7.0
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(__bg__)
54 #define _CS_ARCH_Blue_Gene
55 
56 #elif defined(__linux__) || defined(__linux) || defined(linux)
57 #define _CS_ARCH_Linux
58 
59 #elif defined(__sun__) || defined(__sun) || defined(sun)
60 #define _CS_ARCH_SunOS
61 
62 #endif
63 
64 /* On certain architectures such as IBM Blue Gene, some operations may
65  * be better optimized on memory-aligned data (if 0 here, no alignment
66  * is leveraged). This alignment is not exploited yet in Code_Saturne. */
67 
68 #define CS_MEM_ALIGN 0
69 
70 #define CS_BASE_STRING_LEN 80
71 
72 /*----------------------------------------------------------------------------*/
73 
75 
76 /*============================================================================
77  * Type definitions
78  *============================================================================*/
79 
80 /* Function pointers for extra cleanup operations to be called when
81  entering cs_exit() or bft_error() */
82 
83 typedef void (cs_base_atexit_t) (void);
84 
85 /*=============================================================================
86  * Global variable definitions
87  *============================================================================*/
88 
89 /*=============================================================================
90  * Public function prototypes
91  *============================================================================*/
92 
93 /*----------------------------------------------------------------------------*/
101 /*----------------------------------------------------------------------------*/
102 
103 static inline const char *
104 cs_base_strtf(bool boolean)
105 {
106  if (boolean)
107  return "**True**";
108  else
109  return "**False**";
110 }
111 
112 /*----------------------------------------------------------------------------
113  * First analysis of the command line to determine an application name.
114  *
115  * If no name is defined by the command line, a name is determined based
116  * on the working directory.
117  *
118  * The caller is responsible for freeing the returned string.
119  *
120  * parameters:
121  * argc <-- number of command line arguments
122  * argv <-- array of command line arguments
123  *
124  * returns:
125  * pointer to character string with application name
126  *----------------------------------------------------------------------------*/
127 
128 char *
129 cs_base_get_app_name(int argc,
130  const char *argv[]);
131 
132 /*----------------------------------------------------------------------------
133  * Print logfile header
134  *
135  * parameters:
136  * argc <-- number of command line arguments
137  * argv <-- array of command line arguments
138  *----------------------------------------------------------------------------*/
139 
140 void
141 cs_base_logfile_head(int argc,
142  char *argv[]);
143 
144 #if defined(HAVE_MPI)
145 
146 /*----------------------------------------------------------------------------
147  * First analysis of the command line and environment variables to determine
148  * if we require MPI, and initialization if necessary.
149  *
150  * parameters:
151  * argc <-> number of command line arguments
152  * argv <-> array of command line arguments
153  *
154  * Global variables `cs_glob_n_ranks' (number of Code_Saturne processes)
155  * and `cs_glob_rank_id' (rank of local process) are set by this function.
156  *----------------------------------------------------------------------------*/
157 
158 void
159 cs_base_mpi_init(int *argc,
160  char **argv[]);
161 
162 /*----------------------------------------------------------------------------*/
171 /*----------------------------------------------------------------------------*/
172 
173 MPI_Comm
174 cs_base_get_rank_step_comm(int rank_step);
175 
176 #endif /* defined(HAVE_MPI) */
177 
178 /*----------------------------------------------------------------------------
179  * Exit, with handling for both normal and error cases.
180  *
181  * Finalize MPI if necessary.
182  *
183  * parameters:
184  * status <-- value to be returned to the parent:
185  * EXIT_SUCCESS / 0 for the normal case,
186  * EXIT_FAILURE or other nonzero code for error cases.
187  *----------------------------------------------------------------------------*/
188 
189 void
190 cs_exit(int status);
191 
192 /*----------------------------------------------------------------------------
193  * Initialize error and signal handlers.
194  *
195  * parameters:
196  * signal_defaults <-- leave default signal handlers in place if true.
197  *----------------------------------------------------------------------------*/
198 
199 void
200 cs_base_error_init(bool signal_defaults);
201 
202 /*----------------------------------------------------------------------------
203  * Initialize management of memory allocated through BFT.
204  *----------------------------------------------------------------------------*/
205 
206 void
207 cs_base_mem_init(void);
208 
209 /*----------------------------------------------------------------------------
210  * Finalize management of memory allocated through BFT.
211  *
212  * A summary of the consumed memory is given.
213  *----------------------------------------------------------------------------*/
214 
215 void
217 
218 /*----------------------------------------------------------------------------
219  * Print summary of running time, including CPU and elapsed times.
220  *----------------------------------------------------------------------------*/
221 
222 void
224 
225 /*----------------------------------------------------------------------------*/
234 /*----------------------------------------------------------------------------*/
235 
236 void
237 cs_base_update_status(const char *format,
238  ...);
239 
240 /*----------------------------------------------------------------------------
241  * Set tracing of progress on or off.
242  *
243  * parameters:
244  * trace <-- trace progress to stdout
245  *----------------------------------------------------------------------------*/
246 
247 void
248 cs_base_trace_set(bool trace);
249 
250 
251 /*----------------------------------------------------------------------------
252  * Set output file name and suppression flag for bft_printf().
253  *
254  * This allows redirecting or suppressing logging for different ranks.
255  *
256  * parameters:
257  * log_name <-- base file name for log
258  * rn_log_flag <-- redirection for ranks > 0 log:
259  * rn_log_flag <-- redirection for ranks > 0 log:
260  * false: to "/dev/null" (suppressed)
261  * true: to <log_name>_r*.log" file;
262  *----------------------------------------------------------------------------*/
263 
264 void
265 cs_base_bft_printf_init(const char *log_name,
266  bool rn_log_flag);
267 
268 /*----------------------------------------------------------------------------
269  * Replace default bft_printf() mechanism with internal mechanism.
270  *
271  * This allows redirecting or suppressing logging for different ranks.
272  *
273  * parameters:
274  * log_name <-- base file name for log
275  *----------------------------------------------------------------------------*/
276 
277 void
278 cs_base_bft_printf_set(const char *log_name,
279  bool rn_log_flag);
280 
281 /*----------------------------------------------------------------------------
282  * Return name of default log file.
283  *
284  * cs_base_bft_printf_set or cs_base_c_bft_printf_set() must have
285  * been called before this.
286  *
287  * returns:
288  * name of default log file
289  *----------------------------------------------------------------------------*/
290 
291 const char *
293 
294 /*----------------------------------------------------------------------------
295  * Return flag indicating if the default log file output is suppressed.
296  *
297  * cs_base_bft_printf_set or cs_base_c_bft_printf_set() must have
298  * been called before this.
299  *
300  * returns:
301  * output suppression flag
302  *----------------------------------------------------------------------------*/
303 
304 bool
306 
307 /*----------------------------------------------------------------------------
308  * Print a warning message header.
309  *
310  * parameters:
311  * file_name <-- name of source file
312  * line_nume <-- line number in source file
313  *----------------------------------------------------------------------------*/
314 
315 void
316 cs_base_warn(const char *file_name,
317  int line_num);
318 
319 /*----------------------------------------------------------------------------
320  * Define a function to be called when entering cs_exit() or bft_error().
321  *
322  * Compared to the C atexit(), only one function may be called (latest
323  * setting wins), but the function is called slightly before exit,
324  * so it is well adapted to cleanup such as flushing of non-C API logging.
325  *
326  * parameters:
327  * fct <-- pointer tu function to be called
328  *----------------------------------------------------------------------------*/
329 
330 void
332 
333 /*----------------------------------------------------------------------------
334  * Convert a character string from the Fortran API to the C API.
335  *
336  * Eventual leading and trailing blanks are removed.
337  *
338  * parameters:
339  * f_str <-- Fortran string
340  * f_len <-- Fortran string length
341  *
342  * returns:
343  * pointer to C string
344  *----------------------------------------------------------------------------*/
345 
346 char *
347 cs_base_string_f_to_c_create(const char *f_str,
348  int f_len);
349 
350 /*----------------------------------------------------------------------------
351  * Free a string converted from the Fortran API to the C API.
352  *
353  * parameters:
354  * str <-> pointer to C string
355  *----------------------------------------------------------------------------*/
356 
357 void
358 cs_base_string_f_to_c_free(char **c_str);
359 
360 /*----------------------------------------------------------------------------
361  * Clean a string representing options.
362  *
363  * Characters are converted to lowercase, leading and trailing whitespace
364  * is removed, and multiple whitespaces or tabs are replaced by single
365  * spaces.
366  *
367  * parameters:
368  * s <-> string to be cleaned
369  *----------------------------------------------------------------------------*/
370 
371 void
373 
374 /*----------------------------------------------------------------------------
375  * Return a string providing locale 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  * locale path
382  *----------------------------------------------------------------------------*/
383 
384 const char *
386 
387 /*----------------------------------------------------------------------------
388  * Return a string providing package data 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 data path
395  *----------------------------------------------------------------------------*/
396 
397 const char *
399 
400 /*----------------------------------------------------------------------------
401  * Return a string providing loadable library path information.
402  *
403  * This is normally the path determined upon configuration, but may be
404  * adapted for movable installs using the CS_ROOT_DIR environment variable.
405  *
406  * returns:
407  * package loadable library (plugin) path
408  *----------------------------------------------------------------------------*/
409 
410 const char *
412 
413 /*----------------------------------------------------------------------------
414  * Ensure bool argument has value 0 or 1.
415  *
416  * This allows working around issues with Intel compiler C bindings,
417  * which seem to pass incorrect values in some cases.
418  *
419  * parameters:
420  * b <-> pointer to bool
421  *----------------------------------------------------------------------------*/
422 
423 void
424 cs_base_check_bool(bool *b);
425 
426 /*----------------------------------------------------------------------------
427  * Open a data file in read mode.
428  *
429  * If a file of the given name in the working directory is found, it
430  * will be opened. Otherwise, it will be searched for in the "data/thch"
431  * subdirectory of pkgdatadir.
432  *
433  * parameters:
434  * base_name <-- base file name
435  *
436  * returns:
437  * pointer to opened file
438  *----------------------------------------------------------------------------*/
439 
440 FILE *
441 cs_base_open_properties_data_file(const char *base_name);
442 
443 #if defined(HAVE_DLOPEN)
444 
445 /*----------------------------------------------------------------------------*/
453 /*----------------------------------------------------------------------------*/
454 
455 void*
456 cs_base_dlopen(const char *filename);
457 
458 /*----------------------------------------------------------------------------*/
470 /*----------------------------------------------------------------------------*/
471 
472 void*
473 cs_base_dlopen_plugin(const char *name);
474 
475 /*----------------------------------------------------------------------------*/
481 /*----------------------------------------------------------------------------*/
482 
483 int
485 
486 /*----------------------------------------------------------------------------*/
492 /*----------------------------------------------------------------------------*/
493 
494 void
495 cs_base_dlopen_set_flags(int flags);
496 
497 /*----------------------------------------------------------------------------*/
509 /*----------------------------------------------------------------------------*/
510 
511 void
512 cs_base_dlclose(const char *filename,
513  void *handle);
514 
515 /*----------------------------------------------------------------------------*/
525 /*----------------------------------------------------------------------------*/
526 
527 void *
529  const char *name,
530  bool errors_are_fatal);
531 
532 
533 #endif /* defined(HAVE_DLOPEN) */
534 
535 /*----------------------------------------------------------------------------*/
542 /*----------------------------------------------------------------------------*/
543 
544 void
545 cs_base_backtrace_dump(FILE *f,
546  int lv_start);
547 
548 /*----------------------------------------------------------------------------*/
568 /*----------------------------------------------------------------------------*/
569 
570 void
571 cs_base_get_run_identity(char **run_id,
572  char **case_name,
573  char **study_name);
574 
575 /*----------------------------------------------------------------------------*/
576 
578 
579 #endif /* __CS_BASE_H__ */
void cs_base_trace_set(bool trace)
Definition: cs_base.c:1861
void cs_base_string_f_to_c_free(char **c_str)
Definition: cs_base.c:2146
void cs_base_mem_finalize(void)
Definition: cs_base.c:1558
void() cs_base_atexit_t(void)
Definition: cs_base.h:83
void * cs_base_dlopen_plugin(const char *name)
Load a plugin&#39;s dynamic library.
Definition: cs_base.c:2368
#define BEGIN_C_DECLS
Definition: cs_defs.h:495
char * cs_base_string_f_to_c_create(const char *f_str, int f_len)
Definition: cs_base.c:2089
void * cs_base_dlopen(const char *filename)
Load a dynamic library.
Definition: cs_base.c:2328
const char * cs_base_get_localedir(void)
Definition: cs_base.c:2204
const char * cs_base_get_pkglibdir(void)
Definition: cs_base.c:2237
void cs_base_warn(const char *file_name, int line_num)
Definition: cs_base.c:2051
void cs_base_option_string_clean(char *s)
Definition: cs_base.c:2174
void cs_base_mem_init(void)
Definition: cs_base.c:1489
void cs_base_mpi_init(int *argc, char **argv[])
Definition: cs_base.c:1217
void cs_base_bft_printf_init(const char *log_name, bool rn_log_flag)
Definition: cs_base.c:1880
bool cs_base_bft_printf_suppressed(void)
Definition: cs_base.c:2037
int cs_base_dlopen_get_flags(void)
Get flags for dlopen.
Definition: cs_base.c:2399
void cs_exit(int status)
Definition: cs_base.c:1404
void cs_base_logfile_head(int argc, char *argv[])
Definition: cs_base.c:1121
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:2466
char * cs_base_get_app_name(int argc, const char *argv[])
Definition: cs_base.c:1062
void cs_base_backtrace_dump(FILE *f, int lv_start)
Dump a stack trace to a file.
Definition: cs_base.c:2497
void cs_base_check_bool(bool *b)
Definition: cs_base.c:2255
#define END_C_DECLS
Definition: cs_defs.h:496
void cs_base_update_status(const char *format,...)
Update status file.
Definition: cs_base.c:1784
void cs_base_dlopen_set_flags(int flags)
Set flags for dlopen.
Definition: cs_base.c:2413
FILE * cs_base_open_properties_data_file(const char *base_name)
Definition: cs_base.c:2285
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:2574
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:1326
const char * cs_base_get_pkgdatadir(void)
Definition: cs_base.c:2219
void cs_base_bft_printf_set(const char *log_name, bool rn_log_flag)
Definition: cs_base.c:1958
void cs_base_error_init(bool signal_defaults)
Definition: cs_base.c:1446
void cs_base_time_summary(void)
Definition: cs_base.c:1704
void cs_base_dlclose(const char *filename, void *handle)
Unload a dynamic library.
Definition: cs_base.c:2433
void cs_base_atexit_set(cs_base_atexit_t *const fct)
Definition: cs_base.c:2070
double precision, save b
Definition: cs_fuel_incl.f90:146
const char * cs_base_bft_printf_name(void)
Definition: cs_base.c:2021