7.2
general 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-2022 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 #include "cs_defs.h"
31 
32 /*----------------------------------------------------------------------------
33  * Standard C library headers
34  *----------------------------------------------------------------------------*/
35 
36 #include <stdio.h>
37 
38 /*----------------------------------------------------------------------------
39  * Local headers
40  *----------------------------------------------------------------------------*/
41 
42 /*=============================================================================
43  * Macro definitions
44  *============================================================================*/
45 
46 /* Application type name */
47 
48 #define CS_APP_NAME "Code_Saturne"
49 #define CS_APP_VERSION PACKAGE_VERSION /* PACKAGE_VERSION from autoconf */
50 
51 /* System type name */
52 
53 #if defined(__linux__) || defined(__linux) || defined(linux)
54 #define _CS_ARCH_Linux
55 
56 #endif
57 
58 /* On certain architectures such as IBM Blue Gene, some operations may
59  * be better optimized on memory-aligned data (if 0 here, no alignment
60  * is leveraged). This alignment is not exploited yet in code_saturne. */
61 
62 #define CS_MEM_ALIGN 0
63 
64 #define CS_BASE_STRING_LEN 80
65 
66 /*----------------------------------------------------------------------------*/
67 
69 
70 /*============================================================================
71  * Type definitions
72  *============================================================================*/
73 
74 /* Function pointers for extra cleanup operations to be called when
75  entering cs_exit() or bft_error() */
76 
77 typedef void (cs_base_atexit_t) (void);
78 
79 /*=============================================================================
80  * Global variable definitions
81  *============================================================================*/
82 
83 /*=============================================================================
84  * Public function prototypes
85  *============================================================================*/
86 
87 /*----------------------------------------------------------------------------*/
95 /*----------------------------------------------------------------------------*/
96 
97 static inline const char *
98 cs_base_strtf(bool boolean)
99 {
100  if (boolean)
101  return "*True*";
102  else
103  return "*False*";
104 }
105 
106 /*----------------------------------------------------------------------------
107  * First analysis of the command line to determine an application name.
108  *
109  * If no name is defined by the command line, a name is determined based
110  * on the working directory.
111  *
112  * The caller is responsible for freeing the returned string.
113  *
114  * parameters:
115  * argc <-- number of command line arguments
116  * argv <-- array of command line arguments
117  *
118  * returns:
119  * pointer to character string with application name
120  *----------------------------------------------------------------------------*/
121 
122 char *
123 cs_base_get_app_name(int argc,
124  const char *argv[]);
125 
126 /*----------------------------------------------------------------------------
127  * Print logfile header
128  *
129  * parameters:
130  * argc <-- number of command line arguments
131  * argv <-- array of command line arguments
132  *----------------------------------------------------------------------------*/
133 
134 void
135 cs_base_logfile_head(int argc,
136  char *argv[]);
137 
138 #if defined(HAVE_MPI)
139 
140 /*----------------------------------------------------------------------------
141  * First analysis of the command line and environment variables to determine
142  * if we require MPI, and initialization if necessary.
143  *
144  * parameters:
145  * argc <-> number of command line arguments
146  * argv <-> array of command line arguments
147  *
148  * Global variables `cs_glob_n_ranks' (number of code_saturne processes)
149  * and `cs_glob_rank_id' (rank of local process) are set by this function.
150  *----------------------------------------------------------------------------*/
151 
152 void
153 cs_base_mpi_init(int *argc,
154  char **argv[]);
155 
156 /*----------------------------------------------------------------------------*/
165 /*----------------------------------------------------------------------------*/
166 
167 MPI_Comm
168 cs_base_get_rank_step_comm(int rank_step);
169 
170 /*----------------------------------------------------------------------------
171  * Return a reduced communicator matching a multiple of the total
172  * number of ranks, and given a parent communicator.
173  *
174  * Compared to \ref cs_base_get_rank_step_comm, this function is
175  * collective only on the provided communicator.
176  *
177  * This updates the number of reduced communicators if necessary.
178  *
179  * parameters:
180  * parent_comm <-- associated parent communicator (must be either
181  * cs_glob_mpi_comm or a communicator returned by a
182  * previous
183  * rank_step <-- associated multiple of ranks of parent communicator
184  *----------------------------------------------------------------------------*/
185 
186 MPI_Comm
187 cs_base_get_rank_step_comm_recursive(MPI_Comm parent_comm,
188  int rank_step);
189 
190 #endif /* defined(HAVE_MPI) */
191 
192 /*----------------------------------------------------------------------------
193  * Exit, with handling for both normal and error cases.
194  *
195  * Finalize MPI if necessary.
196  *
197  * parameters:
198  * status <-- value to be returned to the parent:
199  * EXIT_SUCCESS / 0 for the normal case,
200  * EXIT_FAILURE or other nonzero code for error cases.
201  *----------------------------------------------------------------------------*/
202 
203 void
204 cs_exit(int status);
205 
206 /*----------------------------------------------------------------------------
207  * Initialize error and signal handlers.
208  *
209  * parameters:
210  * signal_defaults <-- leave default signal handlers in place if true.
211  *----------------------------------------------------------------------------*/
212 
213 void
214 cs_base_error_init(bool signal_defaults);
215 
216 /*----------------------------------------------------------------------------
217  * Initialize management of memory allocated through BFT.
218  *----------------------------------------------------------------------------*/
219 
220 void
221 cs_base_mem_init(void);
222 
223 /*----------------------------------------------------------------------------
224  * Finalize management of memory allocated through BFT.
225  *
226  * A summary of the consumed memory is given.
227  *----------------------------------------------------------------------------*/
228 
229 void
231 
232 /*----------------------------------------------------------------------------
233  * Print summary of running time, including CPU and elapsed times.
234  *----------------------------------------------------------------------------*/
235 
236 void
238 
239 /*----------------------------------------------------------------------------*/
248 /*----------------------------------------------------------------------------*/
249 
250 void
251 cs_base_update_status(const char *format,
252  ...);
253 
254 /*----------------------------------------------------------------------------
255  * Set tracing of progress on or off.
256  *
257  * parameters:
258  * trace <-- trace progress to stdout
259  *----------------------------------------------------------------------------*/
260 
261 void
262 cs_base_trace_set(bool trace);
263 
264 
265 /*----------------------------------------------------------------------------
266  * Set output file name and suppression flag for bft_printf().
267  *
268  * This allows redirecting or suppressing logging for different ranks.
269  *
270  * parameters:
271  * log_name <-- base file name for log
272  * rn_log_flag <-- redirection for ranks > 0 log:
273  * rn_log_flag <-- redirection for ranks > 0 log:
274  * false: to "/dev/null" (suppressed)
275  * true: to <log_name>_r*.log" file;
276  *----------------------------------------------------------------------------*/
277 
278 void
279 cs_base_bft_printf_init(const char *log_name,
280  bool rn_log_flag);
281 
282 /*----------------------------------------------------------------------------
283  * Replace default bft_printf() mechanism with internal mechanism.
284  *
285  * This allows redirecting or suppressing logging for different ranks.
286  *
287  * parameters:
288  * log_name <-- base file name for log
289  *----------------------------------------------------------------------------*/
290 
291 void
292 cs_base_bft_printf_set(const char *log_name,
293  bool rn_log_flag);
294 
295 /*----------------------------------------------------------------------------
296  * Return name of default log file.
297  *
298  * cs_base_bft_printf_set or cs_base_c_bft_printf_set() must have
299  * been called before this.
300  *
301  * returns:
302  * name of default log file
303  *----------------------------------------------------------------------------*/
304 
305 const char *
307 
308 /*----------------------------------------------------------------------------
309  * Return flag indicating if the default log file output is suppressed.
310  *
311  * cs_base_bft_printf_set or cs_base_c_bft_printf_set() must have
312  * been called before this.
313  *
314  * returns:
315  * output suppression flag
316  *----------------------------------------------------------------------------*/
317 
318 bool
320 
321 /*----------------------------------------------------------------------------
322  * Print a warning message header.
323  *
324  * parameters:
325  * file_name <-- name of source file
326  * line_nume <-- line number in source file
327  *----------------------------------------------------------------------------*/
328 
329 void
330 cs_base_warn(const char *file_name,
331  int line_num);
332 
333 /*----------------------------------------------------------------------------
334  * Define a function to be called when entering cs_exit() or bft_error().
335  *
336  * Compared to the C atexit(), only one function may be called (latest
337  * setting wins), but the function is called slightly before exit,
338  * so it is well adapted to cleanup such as flushing of non-C API logging.
339  *
340  * parameters:
341  * fct <-- pointer tu function to be called
342  *----------------------------------------------------------------------------*/
343 
344 void
346 
347 /*----------------------------------------------------------------------------
348  * Clean a string representing options.
349  *
350  * Characters are converted to lowercase, leading and trailing whitespace
351  * is removed, and multiple whitespaces or tabs are replaced by single
352  * spaces.
353  *
354  * parameters:
355  * s <-> string to be cleaned
356  *----------------------------------------------------------------------------*/
357 
358 void
360 
361 /*----------------------------------------------------------------------------
362  * Return a string providing locale path information.
363  *
364  * This is normally the path determined upon configuration, but may be
365  * adapted for movable installs using the CS_ROOT_DIR environment variable.
366  *
367  * returns:
368  * locale path
369  *----------------------------------------------------------------------------*/
370 
371 const char *
373 
374 /*----------------------------------------------------------------------------
375  * Return a string providing package data path information.
376  *
377  * This is normally the path determined upon configuration, but may be
378  * adapted for movable installs using the CS_ROOT_DIR environment variable.
379  *
380  * returns:
381  * package data path
382  *----------------------------------------------------------------------------*/
383 
384 const char *
386 
387 /*----------------------------------------------------------------------------
388  * Return a string providing loadable library path information.
389  *
390  * This is normally the path determined upon configuration, but may be
391  * adapted for movable installs using the CS_ROOT_DIR environment variable.
392  *
393  * returns:
394  * package loadable library (plugin) path
395  *----------------------------------------------------------------------------*/
396 
397 const char *
399 
400 /*----------------------------------------------------------------------------
401  * Ensure bool argument has value 0 or 1.
402  *
403  * This allows working around issues with Intel compiler C bindings,
404  * which seem to pass incorrect values in some cases.
405  *
406  * parameters:
407  * b <-> pointer to bool
408  *----------------------------------------------------------------------------*/
409 
410 void
411 cs_base_check_bool(bool *b);
412 
413 /*----------------------------------------------------------------------------
414  * Open a data file in read mode.
415  *
416  * If a file of the given name in the working directory is found, it
417  * will be opened. Otherwise, it will be searched for in the "data/thch"
418  * subdirectory of pkgdatadir.
419  *
420  * parameters:
421  * base_name <-- base file name
422  *
423  * returns:
424  * pointer to opened file
425  *----------------------------------------------------------------------------*/
426 
427 FILE *
428 cs_base_open_properties_data_file(const char *base_name);
429 
430 #if defined(HAVE_DLOPEN)
431 
432 /*----------------------------------------------------------------------------*/
440 /*----------------------------------------------------------------------------*/
441 
442 void*
443 cs_base_dlopen(const char *filename);
444 
445 /*----------------------------------------------------------------------------*/
457 /*----------------------------------------------------------------------------*/
458 
459 void*
460 cs_base_dlopen_plugin(const char *name);
461 
462 /*----------------------------------------------------------------------------*/
468 /*----------------------------------------------------------------------------*/
469 
470 int
472 
473 /*----------------------------------------------------------------------------*/
479 /*----------------------------------------------------------------------------*/
480 
481 void
482 cs_base_dlopen_set_flags(int flags);
483 
484 /*----------------------------------------------------------------------------*/
496 /*----------------------------------------------------------------------------*/
497 
498 void
499 cs_base_dlclose(const char *filename,
500  void *handle);
501 
502 /*----------------------------------------------------------------------------*/
512 /*----------------------------------------------------------------------------*/
513 
514 void *
516  const char *name,
517  bool errors_are_fatal);
518 
519 
520 #endif /* defined(HAVE_DLOPEN) */
521 
522 /*----------------------------------------------------------------------------*/
529 /*----------------------------------------------------------------------------*/
530 
531 void
532 cs_base_backtrace_dump(FILE *f,
533  int lv_start);
534 
535 /*----------------------------------------------------------------------------*/
555 /*----------------------------------------------------------------------------*/
556 
557 void
558 cs_base_get_run_identity(char **run_id,
559  char **case_name,
560  char **study_name);
561 
562 /*----------------------------------------------------------------------------*/
563 
565 
566 #endif /* __CS_BASE_H__ */
void cs_base_trace_set(bool trace)
Definition: cs_base.c:1957
void cs_base_mem_finalize(void)
Definition: cs_base.c:1654
void() cs_base_atexit_t(void)
Definition: cs_base.h:77
void * cs_base_dlopen_plugin(const char *name)
Load a plugin&#39;s dynamic library.
Definition: cs_base.c:2377
#define BEGIN_C_DECLS
Definition: cs_defs.h:510
MPI_Comm cs_base_get_rank_step_comm_recursive(MPI_Comm parent_comm, int rank_step)
Definition: cs_base.c:1413
void * cs_base_dlopen(const char *filename)
Load a dynamic library.
Definition: cs_base.c:2337
const char * cs_base_get_localedir(void)
Definition: cs_base.c:2213
const char * cs_base_get_pkglibdir(void)
Definition: cs_base.c:2246
void cs_base_warn(const char *file_name, int line_num)
Definition: cs_base.c:2147
void cs_base_option_string_clean(char *s)
Definition: cs_base.c:2183
void cs_base_mem_init(void)
Definition: cs_base.c:1583
void cs_base_mpi_init(int *argc, char **argv[])
Definition: cs_base.c:1225
void cs_base_bft_printf_init(const char *log_name, bool rn_log_flag)
Definition: cs_base.c:1976
bool cs_base_bft_printf_suppressed(void)
Definition: cs_base.c:2133
int cs_base_dlopen_get_flags(void)
Get flags for dlopen.
Definition: cs_base.c:2408
void cs_exit(int status)
Definition: cs_base.c:1498
void cs_base_logfile_head(int argc, char *argv[])
Definition: cs_base.c:1129
void * cs_base_get_dl_function_pointer(void *handle, const char *name, bool errors_are_fatal)
Get a shared library function pointer.
Definition: cs_base.c:2475
char * cs_base_get_app_name(int argc, const char *argv[])
Definition: cs_base.c:1070
void cs_base_backtrace_dump(FILE *f, int lv_start)
Dump a stack trace to a file.
Definition: cs_base.c:2506
void cs_base_check_bool(bool *b)
Definition: cs_base.c:2264
#define END_C_DECLS
Definition: cs_defs.h:511
void cs_base_update_status(const char *format,...)
Update status file.
Definition: cs_base.c:1880
void cs_base_dlopen_set_flags(int flags)
Set flags for dlopen.
Definition: cs_base.c:2422
static const char * cs_base_strtf(bool boolean)
Return a string "true" or "false" according to the boolean.
Definition: cs_base.h:98
FILE * cs_base_open_properties_data_file(const char *base_name)
Definition: cs_base.c:2294
void cs_base_get_run_identity(char **run_id, char **case_name, char **study_name)
Query run-time directory info, using working directory names.
Definition: cs_base.c:2583
MPI_Comm cs_base_get_rank_step_comm(int rank_step)
Return a reduced communicator matching a multiple of the total number of ranks.
Definition: cs_base.c:1332
const char * cs_base_get_pkgdatadir(void)
Definition: cs_base.c:2228
void cs_base_bft_printf_set(const char *log_name, bool rn_log_flag)
Definition: cs_base.c:2054
void cs_base_error_init(bool signal_defaults)
Definition: cs_base.c:1540
void cs_base_time_summary(void)
Definition: cs_base.c:1800
void cs_base_dlclose(const char *filename, void *handle)
Unload a dynamic library.
Definition: cs_base.c:2442
void cs_base_atexit_set(cs_base_atexit_t *const fct)
Definition: cs_base.c:2166
double precision, save b
Definition: cs_fuel_incl.f90:146
const char * cs_base_bft_printf_name(void)
Definition: cs_base.c:2117