8.2
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-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 * parameters:
269 * trace <-- trace progress to stdout
270 *----------------------------------------------------------------------------*/
271
272void
273cs_base_trace_set(bool trace);
274
275
276/*----------------------------------------------------------------------------
277 * Set output file name and suppression flag for bft_printf().
278 *
279 * This allows redirecting or suppressing logging for different ranks.
280 *
281 * parameters:
282 * log_name <-- base file name for log
283 * rn_log_flag <-- redirection for ranks > 0 log:
284 * rn_log_flag <-- redirection for ranks > 0 log:
285 * false: to "/dev/null" (suppressed)
286 * true: to <log_name>_r*.log" file;
287 *----------------------------------------------------------------------------*/
288
289void
290cs_base_bft_printf_init(const char *log_name,
291 bool rn_log_flag);
292
293/*----------------------------------------------------------------------------
294 * Replace default bft_printf() mechanism with internal mechanism.
295 *
296 * This allows redirecting or suppressing logging for different ranks.
297 *
298 * parameters:
299 * log_name <-- base file name for log
300 *----------------------------------------------------------------------------*/
301
302void
303cs_base_bft_printf_set(const char *log_name,
304 bool rn_log_flag);
305
306/*----------------------------------------------------------------------------
307 * Return name of default log file.
308 *
309 * cs_base_bft_printf_set or cs_base_c_bft_printf_set() must have
310 * been called before this.
311 *
312 * returns:
313 * name of default log file
314 *----------------------------------------------------------------------------*/
315
316const char *
318
319/*----------------------------------------------------------------------------
320 * Return flag indicating if the default log file output is suppressed.
321 *
322 * cs_base_bft_printf_set or cs_base_c_bft_printf_set() must have
323 * been called before this.
324 *
325 * returns:
326 * output suppression flag
327 *----------------------------------------------------------------------------*/
328
329bool
331
332/*----------------------------------------------------------------------------
333 * Print a warning message header.
334 *
335 * parameters:
336 * file_name <-- name of source file
337 * line_nume <-- line number in source file
338 *----------------------------------------------------------------------------*/
339
340void
341cs_base_warn(const char *file_name,
342 int line_num);
343
344/*----------------------------------------------------------------------------
345 * Define a function to be called when entering cs_exit() or bft_error().
346 *
347 * Compared to the C atexit(), only one function may be called (latest
348 * setting wins), but the function is called slightly before exit,
349 * so it is well adapted to cleanup such as flushing of non-C API logging.
350 *
351 * parameters:
352 * fct <-- pointer tu function to be called
353 *----------------------------------------------------------------------------*/
354
355void
357
358/*----------------------------------------------------------------------------
359 * Set handler function for SIGINT or similar.
360 *
361 * When first encountered, SIGINT will call that handler if present,
362 * then revert to the general handler if encountered again.
363 *
364 * parameters:
365 * h <-- pointer to function to be called
366 *----------------------------------------------------------------------------*/
367
368void
370
371/*----------------------------------------------------------------------------
372 * Clean a string representing options.
373 *
374 * Characters are converted to lowercase, leading and trailing whitespace
375 * is removed, and multiple whitespaces or tabs are replaced by single
376 * spaces.
377 *
378 * parameters:
379 * s <-> string to be cleaned
380 *----------------------------------------------------------------------------*/
381
382void
384
385/*----------------------------------------------------------------------------
386 * Return a string providing locale path information.
387 *
388 * This is normally the path determined upon configuration, but may be
389 * adapted for movable installs using the CS_ROOT_DIR environment variable.
390 *
391 * returns:
392 * locale path
393 *----------------------------------------------------------------------------*/
394
395const char *
397
398/*----------------------------------------------------------------------------
399 * Return a string providing package data path information.
400 *
401 * This is normally the path determined upon configuration, but may be
402 * adapted for movable installs using the CS_ROOT_DIR environment variable.
403 *
404 * returns:
405 * package data path
406 *----------------------------------------------------------------------------*/
407
408const char *
410
411/*----------------------------------------------------------------------------
412 * Return a string providing loadable library path information.
413 *
414 * This is normally the path determined upon configuration, but may be
415 * adapted for movable installs using the CS_ROOT_DIR environment variable.
416 *
417 * returns:
418 * package loadable library (plugin) path
419 *----------------------------------------------------------------------------*/
420
421const char *
423
424/*----------------------------------------------------------------------------
425 * Ensure bool argument has value 0 or 1.
426 *
427 * This allows working around issues with Intel compiler C bindings,
428 * which seem to pass incorrect values in some cases.
429 *
430 * parameters:
431 * b <-> pointer to bool
432 *----------------------------------------------------------------------------*/
433
434void
435cs_base_check_bool(bool *b);
436
437/*----------------------------------------------------------------------------
438 * Open a data file in read mode.
439 *
440 * If a file of the given name in the working directory is found, it
441 * will be opened. Otherwise, it will be searched for in the "data/thch"
442 * subdirectory of pkgdatadir.
443 *
444 * parameters:
445 * base_name <-- base file name
446 *
447 * returns:
448 * pointer to opened file
449 *----------------------------------------------------------------------------*/
450
451FILE *
452cs_base_open_properties_data_file(const char *base_name);
453
454#if defined(HAVE_DLOPEN)
455
456/*----------------------------------------------------------------------------*/
464/*----------------------------------------------------------------------------*/
465
466void*
467cs_base_dlopen(const char *filename);
468
469/*----------------------------------------------------------------------------*/
481/*----------------------------------------------------------------------------*/
482
483void*
484cs_base_dlopen_plugin(const char *name);
485
486/*----------------------------------------------------------------------------*/
492/*----------------------------------------------------------------------------*/
493
494int
496
497/*----------------------------------------------------------------------------*/
503/*----------------------------------------------------------------------------*/
504
505void
506cs_base_dlopen_set_flags(int flags);
507
508/*----------------------------------------------------------------------------*/
520/*----------------------------------------------------------------------------*/
521
522void
523cs_base_dlclose(const char *filename,
524 void *handle);
525
526/*----------------------------------------------------------------------------*/
536/*----------------------------------------------------------------------------*/
537
538void *
540 const char *name,
541 bool errors_are_fatal);
542
543
544#endif /* defined(HAVE_DLOPEN) */
545
546/*----------------------------------------------------------------------------*/
553/*----------------------------------------------------------------------------*/
554
555void
557 int lv_start);
558
559/*----------------------------------------------------------------------------*/
568/*----------------------------------------------------------------------------*/
569
570void
572
573/*----------------------------------------------------------------------------*/
580/*----------------------------------------------------------------------------*/
581
582void
584
585/*----------------------------------------------------------------------------*/
605/*----------------------------------------------------------------------------*/
606
607void
608cs_base_get_run_identity(char **run_id,
609 char **case_name,
610 char **study_name);
611
612/*----------------------------------------------------------------------------*/
613
615
616#endif /* __CS_BASE_H__ */
void cs_base_option_string_clean(char *s)
Definition cs_base.c:2296
const char * cs_base_get_localedir(void)
Definition cs_base.c:2326
const char * cs_base_get_pkgdatadir(void)
Definition cs_base.c:2341
void * cs_base_dlopen_plugin(const char *name)
Load a plugin's dynamic library.
Definition cs_base.c:2490
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:1247
void cs_base_dlclose(const char *filename, void *handle)
Unload a dynamic library.
Definition cs_base.c:2555
void cs_base_sigint_handler_set(cs_base_sigint_handler_t *const h)
Definition cs_base.c:2279
int cs_base_dlopen_get_flags(void)
Get flags for dlopen.
Definition cs_base.c:2521
void cs_base_time_summary(void)
Definition cs_base.c:1897
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:1519
void cs_base_check_bool(bool *b)
Definition cs_base.c:2377
void cs_base_error_init(bool signal_defaults)
Definition cs_base.c:1561
void cs_base_mem_finalize(void)
Definition cs_base.c:1680
void cs_base_signal_restore(void)
Definition cs_base.c:1861
void cs_base_at_finalize(cs_base_atexit_t *func)
Register a function to be called at the finalization stage.
Definition cs_base.c:2685
char * cs_base_get_app_name(int argc, const char *argv[])
Definition cs_base.c:1092
void cs_base_logfile_head(int argc, char *argv[])
Definition cs_base.c:1151
MPI_Comm cs_base_get_rank_step_comm_recursive(MPI_Comm parent_comm, int rank_step)
Definition cs_base.c:1438
void cs_base_finalize_sequence(void)
Call sequence of finalization functions.
Definition cs_base.c:2705
const char * cs_base_get_pkglibdir(void)
Definition cs_base.c:2359
void cs_base_update_status(const char *format,...)
Update status file.
Definition cs_base.c:1977
void cs_base_trace_set(bool trace)
Definition cs_base.c:2054
void cs_base_backtrace_dump(FILE *f, int lv_start)
Dump a stack trace to a file.
Definition cs_base.c:2619
void cs_base_warn(const char *file_name, int line_num)
Definition cs_base.c:2244
void cs_base_mem_init(void)
Definition cs_base.c:1609
void * cs_base_dlopen(const char *filename)
Load a dynamic library.
Definition cs_base.c:2450
const char * cs_base_bft_printf_name(void)
Definition cs_base.c:2214
void cs_base_atexit_set(cs_base_atexit_t *const fct)
Definition cs_base.c:2263
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:1357
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:2588
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:2738
bool cs_base_bft_printf_suppressed(void)
Definition cs_base.c:2230
void cs_base_dlopen_set_flags(int flags)
Set flags for dlopen.
Definition cs_base.c:2535
void cs_base_bft_printf_set(const char *log_name, bool rn_log_flag)
Definition cs_base.c:2151
void cs_base_bft_printf_init(const char *log_name, bool rn_log_flag)
Definition cs_base.c:2073
FILE * cs_base_open_properties_data_file(const char *base_name)
Definition cs_base.c:2407
void cs_base_atexit_t(void)
Definition cs_base.h:77
#define BEGIN_C_DECLS
Definition cs_defs.h:528
#define END_C_DECLS
Definition cs_defs.h:529
@ h
Definition cs_field_pointer.h:91