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 /*----------------------------------------------------------------------------
177  * Return a reduced communicator matching a multiple of the total
178  * number of ranks, and given a parent communicator.
179  *
180  * Compared to \ref cs_base_get_rank_step_comm, this function is
181  * collective only on the provided communicator.
182  *
183  * This updates the number of reduced communicators if necessary.
184  *
185  * parameters:
186  * parent_comm <-- associated parent communicator (must be either
187  * cs_glob_mpi_comm or a communicator returned by a
188  * previous
189  * rank_step <-- associated multiple of ranks of parent communicator
190  *----------------------------------------------------------------------------*/
191 
192 MPI_Comm
193 cs_base_get_rank_step_comm_recursive(MPI_Comm parent_comm,
194  int rank_step);
195 
196 #endif /* defined(HAVE_MPI) */
197 
198 /*----------------------------------------------------------------------------
199  * Exit, with handling for both normal and error cases.
200  *
201  * Finalize MPI if necessary.
202  *
203  * parameters:
204  * status <-- value to be returned to the parent:
205  * EXIT_SUCCESS / 0 for the normal case,
206  * EXIT_FAILURE or other nonzero code for error cases.
207  *----------------------------------------------------------------------------*/
208 
209 void
210 cs_exit(int status);
211 
212 /*----------------------------------------------------------------------------
213  * Initialize error and signal handlers.
214  *
215  * parameters:
216  * signal_defaults <-- leave default signal handlers in place if true.
217  *----------------------------------------------------------------------------*/
218 
219 void
220 cs_base_error_init(bool signal_defaults);
221 
222 /*----------------------------------------------------------------------------
223  * Initialize management of memory allocated through BFT.
224  *----------------------------------------------------------------------------*/
225 
226 void
227 cs_base_mem_init(void);
228 
229 /*----------------------------------------------------------------------------
230  * Finalize management of memory allocated through BFT.
231  *
232  * A summary of the consumed memory is given.
233  *----------------------------------------------------------------------------*/
234 
235 void
237 
238 /*----------------------------------------------------------------------------
239  * Print summary of running time, including CPU and elapsed times.
240  *----------------------------------------------------------------------------*/
241 
242 void
244 
245 /*----------------------------------------------------------------------------*/
254 /*----------------------------------------------------------------------------*/
255 
256 void
257 cs_base_update_status(const char *format,
258  ...);
259 
260 /*----------------------------------------------------------------------------
261  * Set tracing of progress on or off.
262  *
263  * parameters:
264  * trace <-- trace progress to stdout
265  *----------------------------------------------------------------------------*/
266 
267 void
268 cs_base_trace_set(bool trace);
269 
270 
271 /*----------------------------------------------------------------------------
272  * Set output file name and suppression flag for bft_printf().
273  *
274  * This allows redirecting or suppressing logging for different ranks.
275  *
276  * parameters:
277  * log_name <-- base file name for log
278  * rn_log_flag <-- redirection for ranks > 0 log:
279  * rn_log_flag <-- redirection for ranks > 0 log:
280  * false: to "/dev/null" (suppressed)
281  * true: to <log_name>_r*.log" file;
282  *----------------------------------------------------------------------------*/
283 
284 void
285 cs_base_bft_printf_init(const char *log_name,
286  bool rn_log_flag);
287 
288 /*----------------------------------------------------------------------------
289  * Replace default bft_printf() mechanism with internal mechanism.
290  *
291  * This allows redirecting or suppressing logging for different ranks.
292  *
293  * parameters:
294  * log_name <-- base file name for log
295  *----------------------------------------------------------------------------*/
296 
297 void
298 cs_base_bft_printf_set(const char *log_name,
299  bool rn_log_flag);
300 
301 /*----------------------------------------------------------------------------
302  * Return name of default log file.
303  *
304  * cs_base_bft_printf_set or cs_base_c_bft_printf_set() must have
305  * been called before this.
306  *
307  * returns:
308  * name of default log file
309  *----------------------------------------------------------------------------*/
310 
311 const char *
313 
314 /*----------------------------------------------------------------------------
315  * Return flag indicating if the default log file output is suppressed.
316  *
317  * cs_base_bft_printf_set or cs_base_c_bft_printf_set() must have
318  * been called before this.
319  *
320  * returns:
321  * output suppression flag
322  *----------------------------------------------------------------------------*/
323 
324 bool
326 
327 /*----------------------------------------------------------------------------
328  * Print a warning message header.
329  *
330  * parameters:
331  * file_name <-- name of source file
332  * line_nume <-- line number in source file
333  *----------------------------------------------------------------------------*/
334 
335 void
336 cs_base_warn(const char *file_name,
337  int line_num);
338 
339 /*----------------------------------------------------------------------------
340  * Define a function to be called when entering cs_exit() or bft_error().
341  *
342  * Compared to the C atexit(), only one function may be called (latest
343  * setting wins), but the function is called slightly before exit,
344  * so it is well adapted to cleanup such as flushing of non-C API logging.
345  *
346  * parameters:
347  * fct <-- pointer tu function to be called
348  *----------------------------------------------------------------------------*/
349 
350 void
352 
353 /*----------------------------------------------------------------------------
354  * Convert a character string from the Fortran API to the C API.
355  *
356  * Eventual leading and trailing blanks are removed.
357  *
358  * parameters:
359  * f_str <-- Fortran string
360  * f_len <-- Fortran string length
361  *
362  * returns:
363  * pointer to C string
364  *----------------------------------------------------------------------------*/
365 
366 char *
367 cs_base_string_f_to_c_create(const char *f_str,
368  int f_len);
369 
370 /*----------------------------------------------------------------------------
371  * Free a string converted from the Fortran API to the C API.
372  *
373  * parameters:
374  * str <-> pointer to C string
375  *----------------------------------------------------------------------------*/
376 
377 void
378 cs_base_string_f_to_c_free(char **c_str);
379 
380 /*----------------------------------------------------------------------------
381  * Clean a string representing options.
382  *
383  * Characters are converted to lowercase, leading and trailing whitespace
384  * is removed, and multiple whitespaces or tabs are replaced by single
385  * spaces.
386  *
387  * parameters:
388  * s <-> string to be cleaned
389  *----------------------------------------------------------------------------*/
390 
391 void
393 
394 /*----------------------------------------------------------------------------
395  * Return a string providing locale path information.
396  *
397  * This is normally the path determined upon configuration, but may be
398  * adapted for movable installs using the CS_ROOT_DIR environment variable.
399  *
400  * returns:
401  * locale path
402  *----------------------------------------------------------------------------*/
403 
404 const char *
406 
407 /*----------------------------------------------------------------------------
408  * Return a string providing package data path information.
409  *
410  * This is normally the path determined upon configuration, but may be
411  * adapted for movable installs using the CS_ROOT_DIR environment variable.
412  *
413  * returns:
414  * package data path
415  *----------------------------------------------------------------------------*/
416 
417 const char *
419 
420 /*----------------------------------------------------------------------------
421  * Return a string providing loadable library path information.
422  *
423  * This is normally the path determined upon configuration, but may be
424  * adapted for movable installs using the CS_ROOT_DIR environment variable.
425  *
426  * returns:
427  * package loadable library (plugin) path
428  *----------------------------------------------------------------------------*/
429 
430 const char *
432 
433 /*----------------------------------------------------------------------------
434  * Ensure bool argument has value 0 or 1.
435  *
436  * This allows working around issues with Intel compiler C bindings,
437  * which seem to pass incorrect values in some cases.
438  *
439  * parameters:
440  * b <-> pointer to bool
441  *----------------------------------------------------------------------------*/
442 
443 void
444 cs_base_check_bool(bool *b);
445 
446 /*----------------------------------------------------------------------------
447  * Open a data file in read mode.
448  *
449  * If a file of the given name in the working directory is found, it
450  * will be opened. Otherwise, it will be searched for in the "data/thch"
451  * subdirectory of pkgdatadir.
452  *
453  * parameters:
454  * base_name <-- base file name
455  *
456  * returns:
457  * pointer to opened file
458  *----------------------------------------------------------------------------*/
459 
460 FILE *
461 cs_base_open_properties_data_file(const char *base_name);
462 
463 #if defined(HAVE_DLOPEN)
464 
465 /*----------------------------------------------------------------------------*/
473 /*----------------------------------------------------------------------------*/
474 
475 void*
476 cs_base_dlopen(const char *filename);
477 
478 /*----------------------------------------------------------------------------*/
490 /*----------------------------------------------------------------------------*/
491 
492 void*
493 cs_base_dlopen_plugin(const char *name);
494 
495 /*----------------------------------------------------------------------------*/
501 /*----------------------------------------------------------------------------*/
502 
503 int
505 
506 /*----------------------------------------------------------------------------*/
512 /*----------------------------------------------------------------------------*/
513 
514 void
515 cs_base_dlopen_set_flags(int flags);
516 
517 /*----------------------------------------------------------------------------*/
529 /*----------------------------------------------------------------------------*/
530 
531 void
532 cs_base_dlclose(const char *filename,
533  void *handle);
534 
535 /*----------------------------------------------------------------------------*/
545 /*----------------------------------------------------------------------------*/
546 
547 void *
549  const char *name,
550  bool errors_are_fatal);
551 
552 
553 #endif /* defined(HAVE_DLOPEN) */
554 
555 /*----------------------------------------------------------------------------*/
562 /*----------------------------------------------------------------------------*/
563 
564 void
565 cs_base_backtrace_dump(FILE *f,
566  int lv_start);
567 
568 /*----------------------------------------------------------------------------*/
588 /*----------------------------------------------------------------------------*/
589 
590 void
591 cs_base_get_run_identity(char **run_id,
592  char **case_name,
593  char **study_name);
594 
595 /*----------------------------------------------------------------------------*/
596 
598 
599 #endif /* __CS_BASE_H__ */
void cs_base_option_string_clean(char *s)
Definition: cs_base.c:2262
const char * cs_base_get_localedir(void)
Definition: cs_base.c:2292
void cs_base_mpi_init(int *argc, char **argv[])
Definition: cs_base.c:1217
void cs_base_dlclose(const char *filename, void *handle)
Unload a dynamic library.
Definition: cs_base.c:2521
int cs_base_dlopen_get_flags(void)
Get flags for dlopen.
Definition: cs_base.c:2487
void cs_base_time_summary(void)
Definition: cs_base.c:1792
const char * cs_base_bft_printf_name(void)
Definition: cs_base.c:2109
void cs_exit(int status)
Definition: cs_base.c:1492
void cs_base_check_bool(bool *b)
Definition: cs_base.c:2343
void cs_base_error_init(bool signal_defaults)
Definition: cs_base.c:1534
void cs_base_mem_finalize(void)
Definition: cs_base.c:1646
void * cs_base_dlopen_plugin(const char *name)
Load a plugin's dynamic library.
Definition: cs_base.c:2456
char * cs_base_string_f_to_c_create(const char *f_str, int f_len)
Definition: cs_base.c:2177
const char * cs_base_get_pkgdatadir(void)
Definition: cs_base.c:2307
char * cs_base_get_app_name(int argc, const char *argv[])
Definition: cs_base.c:1062
void * cs_base_dlopen(const char *filename)
Load a dynamic library.
Definition: cs_base.c:2416
void cs_base_logfile_head(int argc, char *argv[])
Definition: cs_base.c:1121
MPI_Comm cs_base_get_rank_step_comm_recursive(MPI_Comm parent_comm, int rank_step)
Definition: cs_base.c:1407
void cs_base_update_status(const char *format,...)
Update status file.
Definition: cs_base.c:1872
static const char * cs_base_strtf(bool boolean)
Return a string "true" or "false" according to the boolean.
Definition: cs_base.h:104
void cs_base_string_f_to_c_free(char **c_str)
Definition: cs_base.c:2234
void cs_base_trace_set(bool trace)
Definition: cs_base.c:1949
void cs_base_backtrace_dump(FILE *f, int lv_start)
Dump a stack trace to a file.
Definition: cs_base.c:2585
void cs_base_warn(const char *file_name, int line_num)
Definition: cs_base.c:2139
void cs_base_mem_init(void)
Definition: cs_base.c:1577
const char * cs_base_get_pkglibdir(void)
Definition: cs_base.c:2325
void cs_base_atexit_set(cs_base_atexit_t *const fct)
Definition: cs_base.c:2158
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
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:2662
bool cs_base_bft_printf_suppressed(void)
Definition: cs_base.c:2125
void cs_base_dlopen_set_flags(int flags)
Set flags for dlopen.
Definition: cs_base.c:2501
void cs_base_bft_printf_set(const char *log_name, bool rn_log_flag)
Definition: cs_base.c:2046
void cs_base_bft_printf_init(const char *log_name, bool rn_log_flag)
Definition: cs_base.c:1968
FILE * cs_base_open_properties_data_file(const char *base_name)
Definition: cs_base.c:2373
void() cs_base_atexit_t(void)
Definition: cs_base.h:83
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:2554
#define BEGIN_C_DECLS
Definition: cs_defs.h:492
#define END_C_DECLS
Definition: cs_defs.h:493
double precision, save b
Definition: cs_fuel_incl.f90:146