8.3
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-2024 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
77typedef void (cs_base_atexit_t) (void);
78
79/* Function pointers for SIGINT (or similar) handler */
80
81typedef 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
101static inline const char *
102cs_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
126char *
127cs_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
138void
139cs_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
156void
157cs_base_mpi_init(int *argc,
158 char **argv[]);
159
160/*----------------------------------------------------------------------------*/
169/*----------------------------------------------------------------------------*/
170
171MPI_Comm
172cs_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
190MPI_Comm
191cs_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
207void
208cs_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
217void
218cs_base_error_init(bool signal_defaults);
219
220/*----------------------------------------------------------------------------
221 * Initialize management of memory allocated through BFT.
222 *----------------------------------------------------------------------------*/
223
224void
225cs_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
233void
235
236/*----------------------------------------------------------------------------
237 * Restore signal handlers in case they were modified by another application.
238 *----------------------------------------------------------------------------*/
239
240void
242
243/*----------------------------------------------------------------------------
244 * Print summary of running time, including CPU and elapsed times.
245 *----------------------------------------------------------------------------*/
246
247void
249
250/*----------------------------------------------------------------------------*/
259/*----------------------------------------------------------------------------*/
260
261void
262cs_base_update_status(const char *format,
263 ...);
264
265/*----------------------------------------------------------------------------
266 * Set tracing of progress on or off.
267 *
268 * This function should be called before cs_base_bft_printf_set() if tracing
269 * is activated.
270 *
271 * parameters:
272 * trace <-- trace progress to stdout
273 *----------------------------------------------------------------------------*/
274
275void
276cs_base_trace_set(bool trace);
277
278
279/*----------------------------------------------------------------------------
280 * Set output file name and suppression flag for bft_printf().
281 *
282 * This allows redirecting or suppressing logging for different ranks.
283 *
284 * parameters:
285 * log_name <-- base file name for log
286 * rn_log_flag <-- redirection for ranks > 0 log:
287 * false: to "/dev/null" (suppressed)
288 * true: to <log_name>_r*.log" file;
289 *----------------------------------------------------------------------------*/
290
291void
292cs_base_bft_printf_init(const char *log_name,
293 bool rn_log_flag);
294
295/*----------------------------------------------------------------------------
296 * Replace default bft_printf() mechanism with internal mechanism.
297 *
298 * This allows redirecting or suppressing logging for different ranks.
299 *
300 * parameters:
301 * log_name <-- base file name for log
302 * rn_log_flag <-- redirection for ranks > 0 log:
303 * false: to "/dev/null" (suppressed)
304 * true: to <log_name>_r*.log" file;
305 *----------------------------------------------------------------------------*/
306
307void
308cs_base_bft_printf_set(const char *log_name,
309 bool rn_log_flag);
310
311/*----------------------------------------------------------------------------
312 * Return name of default log file.
313 *
314 * cs_base_bft_printf_set or cs_base_c_bft_printf_set() must have
315 * been called before this.
316 *
317 * returns:
318 * name of default log file
319 *----------------------------------------------------------------------------*/
320
321const char *
323
324/*----------------------------------------------------------------------------
325 * Return flag indicating if the default log file output is suppressed.
326 *
327 * cs_base_bft_printf_set or cs_base_c_bft_printf_set() must have
328 * been called before this.
329 *
330 * returns:
331 * output suppression flag
332 *----------------------------------------------------------------------------*/
333
334bool
336
337/*----------------------------------------------------------------------------
338 * Print a warning message header.
339 *
340 * parameters:
341 * file_name <-- name of source file
342 * line_nume <-- line number in source file
343 *----------------------------------------------------------------------------*/
344
345void
346cs_base_warn(const char *file_name,
347 int line_num);
348
349/*----------------------------------------------------------------------------
350 * Define a function to be called when entering cs_exit() or bft_error().
351 *
352 * Compared to the C atexit(), only one function may be called (latest
353 * setting wins), but the function is called slightly before exit,
354 * so it is well adapted to cleanup such as flushing of non-C API logging.
355 *
356 * parameters:
357 * fct <-- pointer tu function to be called
358 *----------------------------------------------------------------------------*/
359
360void
362
363/*----------------------------------------------------------------------------
364 * Set handler function for SIGINT or similar.
365 *
366 * When first encountered, SIGINT will call that handler if present,
367 * then revert to the general handler if encountered again.
368 *
369 * parameters:
370 * h <-- pointer to function to be called
371 *----------------------------------------------------------------------------*/
372
373void
375
376/*----------------------------------------------------------------------------
377 * Clean a string representing options.
378 *
379 * Characters are converted to lowercase, leading and trailing whitespace
380 * is removed, and multiple whitespaces or tabs are replaced by single
381 * spaces.
382 *
383 * parameters:
384 * s <-> string to be cleaned
385 *----------------------------------------------------------------------------*/
386
387void
389
390/*----------------------------------------------------------------------------
391 * Return a string providing locale path information.
392 *
393 * This is normally the path determined upon configuration, but may be
394 * adapted for movable installs using the CS_ROOT_DIR environment variable.
395 *
396 * returns:
397 * locale path
398 *----------------------------------------------------------------------------*/
399
400const char *
402
403/*----------------------------------------------------------------------------
404 * Return a string providing package data path information.
405 *
406 * This is normally the path determined upon configuration, but may be
407 * adapted for movable installs using the CS_ROOT_DIR environment variable.
408 *
409 * returns:
410 * package data path
411 *----------------------------------------------------------------------------*/
412
413const char *
415
416/*----------------------------------------------------------------------------
417 * Return a string providing loadable library path information.
418 *
419 * This is normally the path determined upon configuration, but may be
420 * adapted for movable installs using the CS_ROOT_DIR environment variable.
421 *
422 * returns:
423 * package loadable library (plugin) path
424 *----------------------------------------------------------------------------*/
425
426const char *
428
429/*----------------------------------------------------------------------------
430 * Ensure bool argument has value 0 or 1.
431 *
432 * This allows working around issues with Intel compiler C bindings,
433 * which seem to pass incorrect values in some cases.
434 *
435 * parameters:
436 * b <-> pointer to bool
437 *----------------------------------------------------------------------------*/
438
439void
440cs_base_check_bool(bool *b);
441
442/*----------------------------------------------------------------------------
443 * Open a data file in read mode.
444 *
445 * If a file of the given name in the working directory is found, it
446 * will be opened. Otherwise, it will be searched for in the "data/thch"
447 * subdirectory of pkgdatadir.
448 *
449 * parameters:
450 * base_name <-- base file name
451 *
452 * returns:
453 * pointer to opened file
454 *----------------------------------------------------------------------------*/
455
456FILE *
457cs_base_open_properties_data_file(const char *base_name);
458
459#if defined(HAVE_DLOPEN)
460
461/*----------------------------------------------------------------------------*/
469/*----------------------------------------------------------------------------*/
470
471void*
472cs_base_dlopen(const char *filename);
473
474/*----------------------------------------------------------------------------*/
486/*----------------------------------------------------------------------------*/
487
488void*
489cs_base_dlopen_plugin(const char *name);
490
491/*----------------------------------------------------------------------------*/
497/*----------------------------------------------------------------------------*/
498
499int
501
502/*----------------------------------------------------------------------------*/
508/*----------------------------------------------------------------------------*/
509
510void
511cs_base_dlopen_set_flags(int flags);
512
513/*----------------------------------------------------------------------------*/
525/*----------------------------------------------------------------------------*/
526
527void
528cs_base_dlclose(const char *filename,
529 void *handle);
530
531/*----------------------------------------------------------------------------*/
541/*----------------------------------------------------------------------------*/
542
543void *
545 const char *name,
546 bool errors_are_fatal);
547
548
549#endif /* defined(HAVE_DLOPEN) */
550
551/*----------------------------------------------------------------------------*/
558/*----------------------------------------------------------------------------*/
559
560void
562 int lv_start);
563
564/*----------------------------------------------------------------------------*/
573/*----------------------------------------------------------------------------*/
574
575void
577
578/*----------------------------------------------------------------------------*/
585/*----------------------------------------------------------------------------*/
586
587void
589
590/*----------------------------------------------------------------------------*/
610/*----------------------------------------------------------------------------*/
611
612void
613cs_base_get_run_identity(char **run_id,
614 char **case_name,
615 char **study_name);
616
617/*----------------------------------------------------------------------------*/
618
620
621#endif /* __CS_BASE_H__ */
void cs_base_option_string_clean(char *s)
Definition: cs_base.cpp:2365
const char * cs_base_get_localedir(void)
Definition: cs_base.cpp:2398
const char * cs_base_get_pkgdatadir(void)
Definition: cs_base.cpp:2416
void * cs_base_dlopen_plugin(const char *name)
Load a plugin's dynamic library.
Definition: cs_base.cpp:2565
void cs_base_mpi_init(int *argc, char **argv[])
Definition: cs_base.cpp:1269
void cs_base_dlclose(const char *filename, void *handle)
Unload a dynamic library.
Definition: cs_base.cpp:2630
void cs_base_sigint_handler_set(cs_base_sigint_handler_t *const h)
Definition: cs_base.cpp:2348
int cs_base_dlopen_get_flags(void)
Get flags for dlopen.
Definition: cs_base.cpp:2596
void cs_base_time_summary(void)
Definition: cs_base.cpp:1966
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_exit(int status)
Definition: cs_base.cpp:1545
void cs_base_check_bool(bool *b)
Definition: cs_base.cpp:2452
void cs_base_error_init(bool signal_defaults)
Definition: cs_base.cpp:1587
void cs_base_mem_finalize(void)
Definition: cs_base.cpp:1716
void cs_base_signal_restore(void)
Definition: cs_base.cpp:1930
void cs_base_at_finalize(cs_base_atexit_t *func)
Register a function to be called at the finalization stage.
Definition: cs_base.cpp:2760
char * cs_base_get_app_name(int argc, const char *argv[])
Definition: cs_base.cpp:1114
void cs_base_logfile_head(int argc, char *argv[])
Definition: cs_base.cpp:1173
MPI_Comm cs_base_get_rank_step_comm_recursive(MPI_Comm parent_comm, int rank_step)
Definition: cs_base.cpp:1464
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.cpp:2780
const char * cs_base_get_pkglibdir(void)
Definition: cs_base.cpp:2434
void cs_base_update_status(const char *format,...)
Update status file.
Definition: cs_base.cpp:2046
void cs_base_trace_set(bool trace)
Definition: cs_base.cpp:2123
void cs_base_backtrace_dump(FILE *f, int lv_start)
Dump a stack trace to a file.
Definition: cs_base.cpp:2694
void cs_base_warn(const char *file_name, int line_num)
Definition: cs_base.cpp:2313
void cs_base_mem_init(void)
Definition: cs_base.cpp:1635
void * cs_base_dlopen(const char *filename)
Load a dynamic library.
Definition: cs_base.cpp:2525
const char * cs_base_bft_printf_name(void)
Definition: cs_base.cpp:2283
void cs_base_atexit_set(cs_base_atexit_t *const fct)
Definition: cs_base.cpp:2332
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.cpp:1383
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.cpp:2663
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.cpp:2813
bool cs_base_bft_printf_suppressed(void)
Definition: cs_base.cpp:2299
void cs_base_dlopen_set_flags(int flags)
Set flags for dlopen.
Definition: cs_base.cpp:2610
void cs_base_bft_printf_set(const char *log_name, bool rn_log_flag)
Definition: cs_base.cpp:2220
void cs_base_bft_printf_init(const char *log_name, bool rn_log_flag)
Definition: cs_base.cpp:2142
void() cs_base_atexit_t(void)
Definition: cs_base.h:77
FILE * cs_base_open_properties_data_file(const char *base_name)
Definition: cs_base.cpp:2482
#define BEGIN_C_DECLS
Definition: cs_defs.h:542
#define END_C_DECLS
Definition: cs_defs.h:543
@ h
Definition: cs_field_pointer.h:93