programmer's documentation
cs_base.h
Go to the documentation of this file.
1 #ifndef __CS_BASE_H__
2 #define __CS_BASE_H__
3 
4 /*============================================================================
5  * Definitions, global variables, and base functions
6  *============================================================================*/
7 
8 /*
9  This file is part of Code_Saturne, a general-purpose CFD tool.
10 
11  Copyright (C) 1998-2016 EDF S.A.
12 
13  This program is free software; you can redistribute it and/or modify it under
14  the terms of the GNU General Public License as published by the Free Software
15  Foundation; either version 2 of the License, or (at your option) any later
16  version.
17 
18  This program is distributed in the hope that it will be useful, but WITHOUT
19  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
20  FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
21  details.
22 
23  You should have received a copy of the GNU General Public License along with
24  this program; if not, write to the Free Software Foundation, Inc., 51 Franklin
25  Street, Fifth Floor, Boston, MA 02110-1301, USA.
26 */
27 
28 /*----------------------------------------------------------------------------*/
29 
30 /*----------------------------------------------------------------------------
31  * Standard C library headers
32  *----------------------------------------------------------------------------*/
33 
34 /*=============================================================================
35  * Macro definitions
36  *============================================================================*/
37 
38 /* Application type name */
39 
40 #define CS_APP_NAME "Code_Saturne"
41 #define CS_APP_VERSION PACKAGE_VERSION /* PACKAGE_VERSION from autoconf */
42 
43 /* System type name */
44 
45 #if defined(__bg__)
46 #define _CS_ARCH_Blue_Gene
47 
48 #elif defined(__linux__) || defined(__linux) || defined(linux)
49 #define _CS_ARCH_Linux
50 
51 #elif defined(__sun__) || defined(__sun) || defined(sun)
52 #define _CS_ARCH_SunOS
53 
54 #endif
55 
56 /* On certain architectures such as IBM Blue Gene, some operations may
57  * be better optimized on memory-aligned data (if 0 here, no alignment
58  * is leveraged). This alignment is not exploited yet in Code_Saturne. */
59 
60 #if defined(__bgq__)
61 #define CS_MEM_ALIGN 32
62 #else
63 #define CS_MEM_ALIGN 0
64 #endif
65 
66 #define CS_BASE_STRING_LEN 64
67 
68 /*----------------------------------------------------------------------------*/
69 
71 
72 /*============================================================================
73  * Type definitions
74  *============================================================================*/
75 
76 /* Function pointers for extra cleanup operations to be called when
77  entering cs_exit() or bft_error() */
78 
79 typedef void (cs_base_atexit_t) (void);
80 
81 /*=============================================================================
82  * Global variable definitions
83  *============================================================================*/
84 
85 /*=============================================================================
86  * Public function prototypes
87  *============================================================================*/
88 
89 /*----------------------------------------------------------------------------
90  * First analysis of the command line to determine an application name.
91  *
92  * If no name is defined by the command line, a name is determined based
93  * on the working directory.
94  *
95  * The caller is responsible for freeing the returned string.
96  *
97  * parameters:
98  * argc <-- number of command line arguments
99  * argv <-- array of command line arguments
100  *
101  * returns:
102  * pointer to character string with application name
103  *----------------------------------------------------------------------------*/
104 
105 char *
106 cs_base_get_app_name(int argc,
107  const char *argv[]);
108 
109 /*----------------------------------------------------------------------------
110  * Print logfile header
111  *
112  * parameters:
113  * argc <-- number of command line arguments
114  * argv <-- array of command line arguments
115  *----------------------------------------------------------------------------*/
116 
117 void
118 cs_base_logfile_head(int argc,
119  char *argv[]);
120 
121 #if defined(HAVE_MPI)
122 
123 /*----------------------------------------------------------------------------
124  * First analysis of the command line and environment variables to determine
125  * if we require MPI, and initialization if necessary.
126  *
127  * parameters:
128  * argc <-> number of command line arguments
129  * argv <-> array of command line arguments
130  *
131  * Global variables `cs_glob_n_ranks' (number of Code_Saturne processes)
132  * and `cs_glob_rank_id' (rank of local process) are set by this function.
133  *----------------------------------------------------------------------------*/
134 
135 void
136 cs_base_mpi_init(int *argc,
137  char **argv[]);
138 
139 #endif /* defined(HAVE_MPI) */
140 
141 /*----------------------------------------------------------------------------
142  * Exit, with handling for both normal and error cases.
143  *
144  * Finalize MPI if necessary.
145  *
146  * parameters:
147  * status <-- value to be returned to the parent:
148  * EXIT_SUCCESS / 0 for the normal case,
149  * EXIT_FAILURE or other nonzero code for error cases.
150  *----------------------------------------------------------------------------*/
151 
152 void
153 cs_exit(int status);
154 
155 /*----------------------------------------------------------------------------
156  * Initialize error and signal handlers.
157  *
158  * parameters:
159  * signal_defaults <-- leave default signal handlers in place if true.
160  *----------------------------------------------------------------------------*/
161 
162 void
163 cs_base_error_init(bool signal_defaults);
164 
165 /*----------------------------------------------------------------------------
166  * Initialize management of memory allocated through BFT.
167  *----------------------------------------------------------------------------*/
168 
169 void
170 cs_base_mem_init(void);
171 
172 /*----------------------------------------------------------------------------
173  * Finalize management of memory allocated through BFT.
174  *
175  * A summary of the consumed memory is given.
176  *----------------------------------------------------------------------------*/
177 
178 void
180 
181 /*----------------------------------------------------------------------------
182  * Print summary of running time, including CPU and elapsed times.
183  *----------------------------------------------------------------------------*/
184 
185 void
187 
188 /*----------------------------------------------------------------------------
189  * Set output file name and suppression flag for bft_printf().
190  *
191  * This allows redirecting or suppressing logging for different ranks.
192  *
193  * parameters:
194  * log_name <-- base file name for log, or NULL for stdout
195  * r0_log_flag <-- redirection for rank 0 log;
196  * 0: not redirected; 1: redirected to <log_name> file
197  * rn_log_flag <-- redirection for ranks > 0 log:
198  * 0: not redirected; 1: redirected to <log_name>_n*" file;
199  * 2: redirected to "/dev/null" (suppressed)
200  *----------------------------------------------------------------------------*/
201 
202 void
203 cs_base_bft_printf_init(const char *log_name,
204  int r0_log_flag,
205  int rn_log_flag);
206 
207 /*----------------------------------------------------------------------------
208  * Replace default bft_printf() mechanism with internal mechanism.
209  *
210  * This allows redirecting or suppressing logging for different ranks.
211  *
212  * parameters:
213  * log_name <-- base file name for log
214  * r0_log_flag <-- redirection for rank 0 log;
215  * 0: not redirected; 1: redirected to "listing" file
216  * rn_log_flag <-- redirection for ranks > 0 log:
217  * 0: not redirected; 1: redirected to "listing_n*" file;
218  * 2: redirected to "/dev/null" (suppressed)
219  *----------------------------------------------------------------------------*/
220 
221 void
222 cs_base_bft_printf_set(const char *log_name,
223  int r0_log_flag,
224  int rn_log_flag);
225 
226 /*----------------------------------------------------------------------------
227  * Return name of default log file.
228  *
229  * cs_base_bft_printf_set or cs_base_c_bft_printf_set() must have
230  * been called before this.
231  *
232  * returns:
233  * name of default log file
234  *----------------------------------------------------------------------------*/
235 
236 const char *
238 
239 /*----------------------------------------------------------------------------
240  * Return flag indicating if the default log file output is suppressed.
241  *
242  * cs_base_bft_printf_set or cs_base_c_bft_printf_set() must have
243  * been called before this.
244  *
245  * returns:
246  * output suppression flag
247  *----------------------------------------------------------------------------*/
248 
249 bool
251 
252 /*----------------------------------------------------------------------------
253  * Print a warning message header.
254  *
255  * parameters:
256  * file_name <-- name of source file
257  * line_nume <-- line number in source file
258  *----------------------------------------------------------------------------*/
259 
260 void
261 cs_base_warn(const char *file_name,
262  int line_num);
263 
264 /*----------------------------------------------------------------------------
265  * Define a function to be called when entering cs_exit() or bft_error().
266  *
267  * Compared to the C atexit(), only one function may be called (latest
268  * setting wins), but the function is called slighty before exit,
269  * so it is well adapted to cleanup such as flushing of non-C API logging.
270  *
271  * parameters:
272  * fct <-- pointer tu function to be called
273  *----------------------------------------------------------------------------*/
274 
275 void
277 
278 /*----------------------------------------------------------------------------
279  * Convert a character string from the Fortran API to the C API.
280  *
281  * Eventual leading and trailing blanks are removed.
282  *
283  * parameters:
284  * f_str <-- Fortran string
285  * f_len <-- Fortran string length
286  *
287  * returns:
288  * pointer to C string
289  *----------------------------------------------------------------------------*/
290 
291 char *
292 cs_base_string_f_to_c_create(const char *f_str,
293  int f_len);
294 
295 /*----------------------------------------------------------------------------
296  * Free a string converted from the Fortran API to the C API.
297  *
298  * parameters:
299  * str <-> pointer to C string
300  *----------------------------------------------------------------------------*/
301 
302 void
303 cs_base_string_f_to_c_free(char **c_str);
304 
305 /*----------------------------------------------------------------------------
306  * Clean a string representing options.
307  *
308  * Characters are converted to lowercase, leading and trailing whitespace
309  * is removed, and multiple whitespaces or tabs are replaced by single
310  * spaces.
311  *
312  * parameters:
313  * s <-> string to be cleaned
314  *----------------------------------------------------------------------------*/
315 
316 void
318 
319 /*----------------------------------------------------------------------------
320  * Return a string providing locale path information.
321  *
322  * This is normally the path determined upon configuration, but may be
323  * adapted for movable installs using the CS_ROOT_DIR environment variable.
324  *
325  * returns:
326  * locale path
327  *----------------------------------------------------------------------------*/
328 
329 const char *
331 
332 /*----------------------------------------------------------------------------
333  * Return a string providing package data path information.
334  *
335  * This is normally the path determined upon configuration, but may be
336  * adapted for movable installs using the CS_ROOT_DIR environment variable.
337  *
338  * returns:
339  * package data path
340  *----------------------------------------------------------------------------*/
341 
342 const char *
344 
345 /*----------------------------------------------------------------------------
346  * Return a string providing loadable library path information.
347  *
348  * This is normally the path determined upon configuration, but may be
349  * adapted for movable installs using the CS_ROOT_DIR environment variable.
350  *
351  * returns:
352  * package loadable library (plugin) path
353  *----------------------------------------------------------------------------*/
354 
355 const char *
357 
358 /*----------------------------------------------------------------------------
359  * Ensure bool argument has value 0 or 1.
360  *
361  * This allows working around issues with Intel compiler C bindings,
362  * which seem to pass incorrect values in some cases.
363  *
364  * parameters:
365  * b <-> pointer to bool
366  *----------------------------------------------------------------------------*/
367 
368 void
369 cs_base_check_bool(bool *b);
370 
371 /*----------------------------------------------------------------------------*/
372 
374 
375 #endif /* __CS_BASE_H__ */
void cs_base_string_f_to_c_free(char **c_str)
Definition: cs_base.c:1883
void cs_base_mem_finalize(void)
Definition: cs_base.c:1437
void cs_base_bft_printf_init(const char *log_name, int r0_log_flag, int rn_log_flag)
Definition: cs_base.c:1650
void() cs_base_atexit_t(void)
Definition: cs_base.h:79
#define BEGIN_C_DECLS
Definition: cs_defs.h:448
char * cs_base_string_f_to_c_create(const char *f_str, int f_len)
Definition: cs_base.c:1826
const char * cs_base_get_localedir(void)
Definition: cs_base.c:1941
void cs_base_mpi_init(int *argc, char **argv[])
Definition: cs_base.c:1142
const char * cs_base_get_pkglibdir(void)
Definition: cs_base.c:1974
void cs_base_warn(const char *file_name, int line_num)
Definition: cs_base.c:1788
void cs_base_option_string_clean(char *s)
Definition: cs_base.c:1911
void cs_base_mem_init(void)
Definition: cs_base.c:1368
bool cs_base_bft_printf_suppressed(void)
Definition: cs_base.c:1774
void cs_exit(int status)
Definition: cs_base.c:1281
void cs_base_logfile_head(int argc, char *argv[])
Definition: cs_base.c:952
char * cs_base_get_app_name(int argc, const char *argv[])
Definition: cs_base.c:893
void cs_base_check_bool(bool *b)
Definition: cs_base.c:1992
#define END_C_DECLS
Definition: cs_defs.h:449
void cs_base_bft_printf_set(const char *log_name, int r0_log_flag, int rn_log_flag)
Definition: cs_base.c:1711
const char * cs_base_get_pkgdatadir(void)
Definition: cs_base.c:1956
void cs_base_error_init(bool signal_defaults)
Definition: cs_base.c:1323
void cs_base_time_summary(void)
Definition: cs_base.c:1567
void cs_base_atexit_set(cs_base_atexit_t *const fct)
Definition: cs_base.c:1807
double precision, save b
Definition: cs_fuel_incl.f90:146
const char * cs_base_bft_printf_name(void)
Definition: cs_base.c:1758