8.0
general documentation
Loading...
Searching...
No Matches
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
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 * Print summary of running time, including CPU and elapsed times.
238 *----------------------------------------------------------------------------*/
239
240void
242
243/*----------------------------------------------------------------------------*/
252/*----------------------------------------------------------------------------*/
253
254void
255cs_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
265void
266cs_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
282void
283cs_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
295void
296cs_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
309const 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
322bool
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
333void
334cs_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
348void
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
361void
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
375void
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
388const 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
401const 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
414const 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
427void
428cs_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
444FILE *
445cs_base_open_properties_data_file(const char *base_name);
446
447#if defined(HAVE_DLOPEN)
448
449/*----------------------------------------------------------------------------*/
457/*----------------------------------------------------------------------------*/
458
459void*
460cs_base_dlopen(const char *filename);
461
462/*----------------------------------------------------------------------------*/
474/*----------------------------------------------------------------------------*/
475
476void*
477cs_base_dlopen_plugin(const char *name);
478
479/*----------------------------------------------------------------------------*/
485/*----------------------------------------------------------------------------*/
486
487int
489
490/*----------------------------------------------------------------------------*/
496/*----------------------------------------------------------------------------*/
497
498void
499cs_base_dlopen_set_flags(int flags);
500
501/*----------------------------------------------------------------------------*/
513/*----------------------------------------------------------------------------*/
514
515void
516cs_base_dlclose(const char *filename,
517 void *handle);
518
519/*----------------------------------------------------------------------------*/
529/*----------------------------------------------------------------------------*/
530
531void *
533 const char *name,
534 bool errors_are_fatal);
535
536
537#endif /* defined(HAVE_DLOPEN) */
538
539/*----------------------------------------------------------------------------*/
546/*----------------------------------------------------------------------------*/
547
548void
550 int lv_start);
551
552/*----------------------------------------------------------------------------*/
572/*----------------------------------------------------------------------------*/
573
574void
575cs_base_get_run_identity(char **run_id,
576 char **case_name,
577 char **study_name);
578
579/*----------------------------------------------------------------------------*/
580
582
583#endif /* __CS_BASE_H__ */
void cs_base_option_string_clean(char *s)
Definition cs_base.c:2206
const char * cs_base_get_localedir(void)
Definition cs_base.c:2236
const char * cs_base_get_pkgdatadir(void)
Definition cs_base.c:2251
void * cs_base_dlopen_plugin(const char *name)
Load a plugin's dynamic library.
Definition cs_base.c:2400
void cs_base_sigint_handler_t(int signum)
Definition cs_base.h:81
void cs_base_mpi_init(int *argc, char **argv[])
Definition cs_base.c:1232
void cs_base_dlclose(const char *filename, void *handle)
Unload a dynamic library.
Definition cs_base.c:2465
void cs_base_sigint_handler_set(cs_base_sigint_handler_t *const h)
Definition cs_base.c:2189
int cs_base_dlopen_get_flags(void)
Get flags for dlopen.
Definition cs_base.c:2431
void cs_base_time_summary(void)
Definition cs_base.c:1807
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.c:1504
void cs_base_check_bool(bool *b)
Definition cs_base.c:2287
void cs_base_error_init(bool signal_defaults)
Definition cs_base.c:1546
void cs_base_mem_finalize(void)
Definition cs_base.c:1661
char * cs_base_get_app_name(int argc, const char *argv[])
Definition cs_base.c:1077
void cs_base_logfile_head(int argc, char *argv[])
Definition cs_base.c:1136
MPI_Comm cs_base_get_rank_step_comm_recursive(MPI_Comm parent_comm, int rank_step)
Definition cs_base.c:1420
const char * cs_base_get_pkglibdir(void)
Definition cs_base.c:2269
void cs_base_update_status(const char *format,...)
Update status file.
Definition cs_base.c:1887
void cs_base_trace_set(bool trace)
Definition cs_base.c:1964
void cs_base_backtrace_dump(FILE *f, int lv_start)
Dump a stack trace to a file.
Definition cs_base.c:2529
void cs_base_warn(const char *file_name, int line_num)
Definition cs_base.c:2154
void cs_base_mem_init(void)
Definition cs_base.c:1590
void * cs_base_dlopen(const char *filename)
Load a dynamic library.
Definition cs_base.c:2360
const char * cs_base_bft_printf_name(void)
Definition cs_base.c:2124
void cs_base_atexit_set(cs_base_atexit_t *const fct)
Definition cs_base.c:2173
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:1339
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:2498
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:2606
bool cs_base_bft_printf_suppressed(void)
Definition cs_base.c:2140
void cs_base_dlopen_set_flags(int flags)
Set flags for dlopen.
Definition cs_base.c:2445
void cs_base_bft_printf_set(const char *log_name, bool rn_log_flag)
Definition cs_base.c:2061
void cs_base_bft_printf_init(const char *log_name, bool rn_log_flag)
Definition cs_base.c:1983
FILE * cs_base_open_properties_data_file(const char *base_name)
Definition cs_base.c:2317
void cs_base_atexit_t(void)
Definition cs_base.h:77
#define BEGIN_C_DECLS
Definition cs_defs.h:509
#define END_C_DECLS
Definition cs_defs.h:510
@ h
Definition cs_field_pointer.h:91