7.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-2021 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  * Convert a character string from the Fortran API to the C API.
349  *
350  * Eventual leading and trailing blanks are removed.
351  *
352  * parameters:
353  * f_str <-- Fortran string
354  * f_len <-- Fortran string length
355  *
356  * returns:
357  * pointer to C string
358  *----------------------------------------------------------------------------*/
359 
360 char *
361 cs_base_string_f_to_c_create(const char *f_str,
362  int f_len);
363 
364 /*----------------------------------------------------------------------------
365  * Free a string converted from the Fortran API to the C API.
366  *
367  * parameters:
368  * str <-> pointer to C string
369  *----------------------------------------------------------------------------*/
370 
371 void
372 cs_base_string_f_to_c_free(char **c_str);
373 
374 /*----------------------------------------------------------------------------
375  * Clean a string representing options.
376  *
377  * Characters are converted to lowercase, leading and trailing whitespace
378  * is removed, and multiple whitespaces or tabs are replaced by single
379  * spaces.
380  *
381  * parameters:
382  * s <-> string to be cleaned
383  *----------------------------------------------------------------------------*/
384 
385 void
387 
388 /*----------------------------------------------------------------------------
389  * Return a string providing locale path information.
390  *
391  * This is normally the path determined upon configuration, but may be
392  * adapted for movable installs using the CS_ROOT_DIR environment variable.
393  *
394  * returns:
395  * locale path
396  *----------------------------------------------------------------------------*/
397 
398 const char *
400 
401 /*----------------------------------------------------------------------------
402  * Return a string providing package data path information.
403  *
404  * This is normally the path determined upon configuration, but may be
405  * adapted for movable installs using the CS_ROOT_DIR environment variable.
406  *
407  * returns:
408  * package data path
409  *----------------------------------------------------------------------------*/
410 
411 const char *
413 
414 /*----------------------------------------------------------------------------
415  * Return a string providing loadable library path information.
416  *
417  * This is normally the path determined upon configuration, but may be
418  * adapted for movable installs using the CS_ROOT_DIR environment variable.
419  *
420  * returns:
421  * package loadable library (plugin) path
422  *----------------------------------------------------------------------------*/
423 
424 const char *
426 
427 /*----------------------------------------------------------------------------
428  * Ensure bool argument has value 0 or 1.
429  *
430  * This allows working around issues with Intel compiler C bindings,
431  * which seem to pass incorrect values in some cases.
432  *
433  * parameters:
434  * b <-> pointer to bool
435  *----------------------------------------------------------------------------*/
436 
437 void
438 cs_base_check_bool(bool *b);
439 
440 /*----------------------------------------------------------------------------
441  * Open a data file in read mode.
442  *
443  * If a file of the given name in the working directory is found, it
444  * will be opened. Otherwise, it will be searched for in the "data/thch"
445  * subdirectory of pkgdatadir.
446  *
447  * parameters:
448  * base_name <-- base file name
449  *
450  * returns:
451  * pointer to opened file
452  *----------------------------------------------------------------------------*/
453 
454 FILE *
455 cs_base_open_properties_data_file(const char *base_name);
456 
457 #if defined(HAVE_DLOPEN)
458 
459 /*----------------------------------------------------------------------------*/
467 /*----------------------------------------------------------------------------*/
468 
469 void*
470 cs_base_dlopen(const char *filename);
471 
472 /*----------------------------------------------------------------------------*/
484 /*----------------------------------------------------------------------------*/
485 
486 void*
487 cs_base_dlopen_plugin(const char *name);
488 
489 /*----------------------------------------------------------------------------*/
495 /*----------------------------------------------------------------------------*/
496 
497 int
499 
500 /*----------------------------------------------------------------------------*/
506 /*----------------------------------------------------------------------------*/
507 
508 void
509 cs_base_dlopen_set_flags(int flags);
510 
511 /*----------------------------------------------------------------------------*/
523 /*----------------------------------------------------------------------------*/
524 
525 void
526 cs_base_dlclose(const char *filename,
527  void *handle);
528 
529 /*----------------------------------------------------------------------------*/
539 /*----------------------------------------------------------------------------*/
540 
541 void *
543  const char *name,
544  bool errors_are_fatal);
545 
546 
547 #endif /* defined(HAVE_DLOPEN) */
548 
549 /*----------------------------------------------------------------------------*/
556 /*----------------------------------------------------------------------------*/
557 
558 void
559 cs_base_backtrace_dump(FILE *f,
560  int lv_start);
561 
562 /*----------------------------------------------------------------------------*/
582 /*----------------------------------------------------------------------------*/
583 
584 void
585 cs_base_get_run_identity(char **run_id,
586  char **case_name,
587  char **study_name);
588 
589 /*----------------------------------------------------------------------------*/
590 
592 
593 #endif /* __CS_BASE_H__ */
void cs_base_trace_set(bool trace)
Definition: cs_base.c:1974
void cs_base_string_f_to_c_free(char **c_str)
Definition: cs_base.c:2259
void cs_base_mem_finalize(void)
Definition: cs_base.c:1671
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:2481
#define BEGIN_C_DECLS
Definition: cs_defs.h:510
char * cs_base_string_f_to_c_create(const char *f_str, int f_len)
Definition: cs_base.c:2202
MPI_Comm cs_base_get_rank_step_comm_recursive(MPI_Comm parent_comm, int rank_step)
Definition: cs_base.c:1430
void * cs_base_dlopen(const char *filename)
Load a dynamic library.
Definition: cs_base.c:2441
const char * cs_base_get_localedir(void)
Definition: cs_base.c:2317
const char * cs_base_get_pkglibdir(void)
Definition: cs_base.c:2350
void cs_base_warn(const char *file_name, int line_num)
Definition: cs_base.c:2164
void cs_base_option_string_clean(char *s)
Definition: cs_base.c:2287
void cs_base_mem_init(void)
Definition: cs_base.c:1600
void cs_base_mpi_init(int *argc, char **argv[])
Definition: cs_base.c:1240
void cs_base_bft_printf_init(const char *log_name, bool rn_log_flag)
Definition: cs_base.c:1993
bool cs_base_bft_printf_suppressed(void)
Definition: cs_base.c:2150
int cs_base_dlopen_get_flags(void)
Get flags for dlopen.
Definition: cs_base.c:2512
void cs_exit(int status)
Definition: cs_base.c:1515
void cs_base_logfile_head(int argc, char *argv[])
Definition: cs_base.c:1144
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:2579
char * cs_base_get_app_name(int argc, const char *argv[])
Definition: cs_base.c:1085
void cs_base_backtrace_dump(FILE *f, int lv_start)
Dump a stack trace to a file.
Definition: cs_base.c:2610
void cs_base_check_bool(bool *b)
Definition: cs_base.c:2368
#define END_C_DECLS
Definition: cs_defs.h:511
void cs_base_update_status(const char *format,...)
Update status file.
Definition: cs_base.c:1897
void cs_base_dlopen_set_flags(int flags)
Set flags for dlopen.
Definition: cs_base.c:2526
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:2398
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
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:1349
const char * cs_base_get_pkgdatadir(void)
Definition: cs_base.c:2332
void cs_base_bft_printf_set(const char *log_name, bool rn_log_flag)
Definition: cs_base.c:2071
void cs_base_error_init(bool signal_defaults)
Definition: cs_base.c:1557
void cs_base_time_summary(void)
Definition: cs_base.c:1817
void cs_base_dlclose(const char *filename, void *handle)
Unload a dynamic library.
Definition: cs_base.c:2546
void cs_base_atexit_set(cs_base_atexit_t *const fct)
Definition: cs_base.c:2183
double precision, save b
Definition: cs_fuel_incl.f90:146
const char * cs_base_bft_printf_name(void)
Definition: cs_base.c:2134