8.1
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-2023 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 /* Function pointers for SIGINT (or similar) handler */
80 
81 typedef void (cs_base_sigint_handler_t) (int signum);
82 
83 /*=============================================================================
84  * Global variable definitions
85  *============================================================================*/
86 
87 /*=============================================================================
88  * Public function prototypes
89  *============================================================================*/
90 
91 /*----------------------------------------------------------------------------*/
99 /*----------------------------------------------------------------------------*/
100 
101 static inline const char *
102 cs_base_strtf(bool boolean)
103 {
104  if (boolean)
105  return "*True*";
106  else
107  return "*False*";
108 }
109 
110 /*----------------------------------------------------------------------------
111  * First analysis of the command line to determine an application name.
112  *
113  * If no name is defined by the command line, a name is determined based
114  * on the working directory.
115  *
116  * The caller is responsible for freeing the returned string.
117  *
118  * parameters:
119  * argc <-- number of command line arguments
120  * argv <-- array of command line arguments
121  *
122  * returns:
123  * pointer to character string with application name
124  *----------------------------------------------------------------------------*/
125 
126 char *
127 cs_base_get_app_name(int argc,
128  const char *argv[]);
129 
130 /*----------------------------------------------------------------------------
131  * Print logfile header
132  *
133  * parameters:
134  * argc <-- number of command line arguments
135  * argv <-- array of command line arguments
136  *----------------------------------------------------------------------------*/
137 
138 void
139 cs_base_logfile_head(int argc,
140  char *argv[]);
141 
142 #if defined(HAVE_MPI)
143 
144 /*----------------------------------------------------------------------------
145  * First analysis of the command line and environment variables to determine
146  * if we require MPI, and initialization if necessary.
147  *
148  * parameters:
149  * argc <-> number of command line arguments
150  * argv <-> array of command line arguments
151  *
152  * Global variables `cs_glob_n_ranks' (number of code_saturne processes)
153  * and `cs_glob_rank_id' (rank of local process) are set by this function.
154  *----------------------------------------------------------------------------*/
155 
156 void
157 cs_base_mpi_init(int *argc,
158  char **argv[]);
159 
160 /*----------------------------------------------------------------------------*/
169 /*----------------------------------------------------------------------------*/
170 
171 MPI_Comm
172 cs_base_get_rank_step_comm(int rank_step);
173 
174 /*----------------------------------------------------------------------------
175  * Return a reduced communicator matching a multiple of the total
176  * number of ranks, and given a parent communicator.
177  *
178  * Compared to \ref cs_base_get_rank_step_comm, this function is
179  * collective only on the provided communicator.
180  *
181  * This updates the number of reduced communicators if necessary.
182  *
183  * parameters:
184  * parent_comm <-- associated parent communicator (must be either
185  * cs_glob_mpi_comm or a communicator returned by a
186  * previous
187  * rank_step <-- associated multiple of ranks of parent communicator
188  *----------------------------------------------------------------------------*/
189 
190 MPI_Comm
191 cs_base_get_rank_step_comm_recursive(MPI_Comm parent_comm,
192  int rank_step);
193 
194 #endif /* defined(HAVE_MPI) */
195 
196 /*----------------------------------------------------------------------------
197  * Exit, with handling for both normal and error cases.
198  *
199  * Finalize MPI if necessary.
200  *
201  * parameters:
202  * status <-- value to be returned to the parent:
203  * EXIT_SUCCESS / 0 for the normal case,
204  * EXIT_FAILURE or other nonzero code for error cases.
205  *----------------------------------------------------------------------------*/
206 
207 void
208 cs_exit(int status);
209 
210 /*----------------------------------------------------------------------------
211  * Initialize error and signal handlers.
212  *
213  * parameters:
214  * signal_defaults <-- leave default signal handlers in place if true.
215  *----------------------------------------------------------------------------*/
216 
217 void
218 cs_base_error_init(bool signal_defaults);
219 
220 /*----------------------------------------------------------------------------
221  * Initialize management of memory allocated through BFT.
222  *----------------------------------------------------------------------------*/
223 
224 void
225 cs_base_mem_init(void);
226 
227 /*----------------------------------------------------------------------------
228  * Finalize management of memory allocated through BFT.
229  *
230  * A summary of the consumed memory is given.
231  *----------------------------------------------------------------------------*/
232 
233 void
235 
236 /*----------------------------------------------------------------------------
237  * Print summary of running time, including CPU and elapsed times.
238  *----------------------------------------------------------------------------*/
239 
240 void
242 
243 /*----------------------------------------------------------------------------*/
252 /*----------------------------------------------------------------------------*/
253 
254 void
255 cs_base_update_status(const char *format,
256  ...);
257 
258 /*----------------------------------------------------------------------------
259  * Set tracing of progress on or off.
260  *
261  * parameters:
262  * trace <-- trace progress to stdout
263  *----------------------------------------------------------------------------*/
264 
265 void
266 cs_base_trace_set(bool trace);
267 
268 
269 /*----------------------------------------------------------------------------
270  * Set output file name and suppression flag for bft_printf().
271  *
272  * This allows redirecting or suppressing logging for different ranks.
273  *
274  * parameters:
275  * log_name <-- base file name for log
276  * rn_log_flag <-- redirection for ranks > 0 log:
277  * rn_log_flag <-- redirection for ranks > 0 log:
278  * false: to "/dev/null" (suppressed)
279  * true: to <log_name>_r*.log" file;
280  *----------------------------------------------------------------------------*/
281 
282 void
283 cs_base_bft_printf_init(const char *log_name,
284  bool rn_log_flag);
285 
286 /*----------------------------------------------------------------------------
287  * Replace default bft_printf() mechanism with internal mechanism.
288  *
289  * This allows redirecting or suppressing logging for different ranks.
290  *
291  * parameters:
292  * log_name <-- base file name for log
293  *----------------------------------------------------------------------------*/
294 
295 void
296 cs_base_bft_printf_set(const char *log_name,
297  bool rn_log_flag);
298 
299 /*----------------------------------------------------------------------------
300  * Return name of default log file.
301  *
302  * cs_base_bft_printf_set or cs_base_c_bft_printf_set() must have
303  * been called before this.
304  *
305  * returns:
306  * name of default log file
307  *----------------------------------------------------------------------------*/
308 
309 const char *
311 
312 /*----------------------------------------------------------------------------
313  * Return flag indicating if the default log file output is suppressed.
314  *
315  * cs_base_bft_printf_set or cs_base_c_bft_printf_set() must have
316  * been called before this.
317  *
318  * returns:
319  * output suppression flag
320  *----------------------------------------------------------------------------*/
321 
322 bool
324 
325 /*----------------------------------------------------------------------------
326  * Print a warning message header.
327  *
328  * parameters:
329  * file_name <-- name of source file
330  * line_nume <-- line number in source file
331  *----------------------------------------------------------------------------*/
332 
333 void
334 cs_base_warn(const char *file_name,
335  int line_num);
336 
337 /*----------------------------------------------------------------------------
338  * Define a function to be called when entering cs_exit() or bft_error().
339  *
340  * Compared to the C atexit(), only one function may be called (latest
341  * setting wins), but the function is called slightly before exit,
342  * so it is well adapted to cleanup such as flushing of non-C API logging.
343  *
344  * parameters:
345  * fct <-- pointer tu function to be called
346  *----------------------------------------------------------------------------*/
347 
348 void
350 
351 /*----------------------------------------------------------------------------
352  * Set handler function for SIGINT or similar.
353  *
354  * When first encountered, SIGINT will call that handler if present,
355  * then revert to the general handler if encountered again.
356  *
357  * parameters:
358  * h <-- pointer to function to be called
359  *----------------------------------------------------------------------------*/
360 
361 void
363 
364 /*----------------------------------------------------------------------------
365  * Clean a string representing options.
366  *
367  * Characters are converted to lowercase, leading and trailing whitespace
368  * is removed, and multiple whitespaces or tabs are replaced by single
369  * spaces.
370  *
371  * parameters:
372  * s <-> string to be cleaned
373  *----------------------------------------------------------------------------*/
374 
375 void
377 
378 /*----------------------------------------------------------------------------
379  * Return a string providing locale path information.
380  *
381  * This is normally the path determined upon configuration, but may be
382  * adapted for movable installs using the CS_ROOT_DIR environment variable.
383  *
384  * returns:
385  * locale path
386  *----------------------------------------------------------------------------*/
387 
388 const char *
390 
391 /*----------------------------------------------------------------------------
392  * Return a string providing package data path information.
393  *
394  * This is normally the path determined upon configuration, but may be
395  * adapted for movable installs using the CS_ROOT_DIR environment variable.
396  *
397  * returns:
398  * package data path
399  *----------------------------------------------------------------------------*/
400 
401 const char *
403 
404 /*----------------------------------------------------------------------------
405  * Return a string providing loadable library path information.
406  *
407  * This is normally the path determined upon configuration, but may be
408  * adapted for movable installs using the CS_ROOT_DIR environment variable.
409  *
410  * returns:
411  * package loadable library (plugin) path
412  *----------------------------------------------------------------------------*/
413 
414 const char *
416 
417 /*----------------------------------------------------------------------------
418  * Ensure bool argument has value 0 or 1.
419  *
420  * This allows working around issues with Intel compiler C bindings,
421  * which seem to pass incorrect values in some cases.
422  *
423  * parameters:
424  * b <-> pointer to bool
425  *----------------------------------------------------------------------------*/
426 
427 void
428 cs_base_check_bool(bool *b);
429 
430 /*----------------------------------------------------------------------------
431  * Open a data file in read mode.
432  *
433  * If a file of the given name in the working directory is found, it
434  * will be opened. Otherwise, it will be searched for in the "data/thch"
435  * subdirectory of pkgdatadir.
436  *
437  * parameters:
438  * base_name <-- base file name
439  *
440  * returns:
441  * pointer to opened file
442  *----------------------------------------------------------------------------*/
443 
444 FILE *
445 cs_base_open_properties_data_file(const char *base_name);
446 
447 #if defined(HAVE_DLOPEN)
448 
449 /*----------------------------------------------------------------------------*/
457 /*----------------------------------------------------------------------------*/
458 
459 void*
460 cs_base_dlopen(const char *filename);
461 
462 /*----------------------------------------------------------------------------*/
474 /*----------------------------------------------------------------------------*/
475 
476 void*
477 cs_base_dlopen_plugin(const char *name);
478 
479 /*----------------------------------------------------------------------------*/
485 /*----------------------------------------------------------------------------*/
486 
487 int
489 
490 /*----------------------------------------------------------------------------*/
496 /*----------------------------------------------------------------------------*/
497 
498 void
499 cs_base_dlopen_set_flags(int flags);
500 
501 /*----------------------------------------------------------------------------*/
513 /*----------------------------------------------------------------------------*/
514 
515 void
516 cs_base_dlclose(const char *filename,
517  void *handle);
518 
519 /*----------------------------------------------------------------------------*/
529 /*----------------------------------------------------------------------------*/
530 
531 void *
533  const char *name,
534  bool errors_are_fatal);
535 
536 
537 #endif /* defined(HAVE_DLOPEN) */
538 
539 /*----------------------------------------------------------------------------*/
546 /*----------------------------------------------------------------------------*/
547 
548 void
549 cs_base_backtrace_dump(FILE *f,
550  int lv_start);
551 
552 /*----------------------------------------------------------------------------*/
561 /*----------------------------------------------------------------------------*/
562 
563 void
565 
566 /*----------------------------------------------------------------------------*/
573 /*----------------------------------------------------------------------------*/
574 
575 void
577 
578 /*----------------------------------------------------------------------------*/
598 /*----------------------------------------------------------------------------*/
599 
600 void
601 cs_base_get_run_identity(char **run_id,
602  char **case_name,
603  char **study_name);
604 
605 /*----------------------------------------------------------------------------*/
606 
608 
609 #endif /* __CS_BASE_H__ */
void cs_base_option_string_clean(char *s)
Definition: cs_base.c:2245
const char * cs_base_get_localedir(void)
Definition: cs_base.c:2275
void cs_base_mpi_init(int *argc, char **argv[])
Definition: cs_base.c:1236
void cs_base_dlclose(const char *filename, void *handle)
Unload a dynamic library.
Definition: cs_base.c:2504
void cs_base_sigint_handler_set(cs_base_sigint_handler_t *const h)
Definition: cs_base.c:2228
int cs_base_dlopen_get_flags(void)
Get flags for dlopen.
Definition: cs_base.c:2470
void cs_base_time_summary(void)
Definition: cs_base.c:1846
const char * cs_base_bft_printf_name(void)
Definition: cs_base.c:2163
void cs_exit(int status)
Definition: cs_base.c:1509
void cs_base_check_bool(bool *b)
Definition: cs_base.c:2326
void cs_base_error_init(bool signal_defaults)
Definition: cs_base.c:1551
void cs_base_mem_finalize(void)
Definition: cs_base.c:1665
void * cs_base_dlopen_plugin(const char *name)
Load a plugin's dynamic library.
Definition: cs_base.c:2439
const char * cs_base_get_pkgdatadir(void)
Definition: cs_base.c:2290
void cs_base_at_finalize(cs_base_atexit_t *func)
Register a function to be called at the finalization stage.
Definition: cs_base.c:2634
char * cs_base_get_app_name(int argc, const char *argv[])
Definition: cs_base.c:1081
void * cs_base_dlopen(const char *filename)
Load a dynamic library.
Definition: cs_base.c:2399
void cs_base_logfile_head(int argc, char *argv[])
Definition: cs_base.c:1140
MPI_Comm cs_base_get_rank_step_comm_recursive(MPI_Comm parent_comm, int rank_step)
Definition: cs_base.c:1424
void() cs_base_sigint_handler_t(int signum)
Definition: cs_base.h:81
void cs_base_finalize_sequence(void)
Call sequence of finalization functions.
Definition: cs_base.c:2654
void cs_base_update_status(const char *format,...)
Update status file.
Definition: cs_base.c:1926
static const char * cs_base_strtf(bool boolean)
Return a string "true" or "false" according to the boolean.
Definition: cs_base.h:102
void cs_base_trace_set(bool trace)
Definition: cs_base.c:2003
void cs_base_backtrace_dump(FILE *f, int lv_start)
Dump a stack trace to a file.
Definition: cs_base.c:2568
void cs_base_warn(const char *file_name, int line_num)
Definition: cs_base.c:2193
void cs_base_mem_init(void)
Definition: cs_base.c:1594
const char * cs_base_get_pkglibdir(void)
Definition: cs_base.c:2308
void cs_base_atexit_set(cs_base_atexit_t *const fct)
Definition: cs_base.c:2212
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:1343
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:2687
bool cs_base_bft_printf_suppressed(void)
Definition: cs_base.c:2179
void cs_base_dlopen_set_flags(int flags)
Set flags for dlopen.
Definition: cs_base.c:2484
void cs_base_bft_printf_set(const char *log_name, bool rn_log_flag)
Definition: cs_base.c:2100
void cs_base_bft_printf_init(const char *log_name, bool rn_log_flag)
Definition: cs_base.c:2022
FILE * cs_base_open_properties_data_file(const char *base_name)
Definition: cs_base.c:2356
void() cs_base_atexit_t(void)
Definition: cs_base.h:77
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:2537
#define BEGIN_C_DECLS
Definition: cs_defs.h:514
#define END_C_DECLS
Definition: cs_defs.h:515
@ h
Definition: cs_field_pointer.h:91