programmer's 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-2018 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 #if defined(__bgq__)
69 #define CS_MEM_ALIGN 32
70 #else
71 #define CS_MEM_ALIGN 0
72 #endif
73 
74 #define CS_BASE_STRING_LEN 64
75 
76 /*----------------------------------------------------------------------------*/
77 
79 
80 /*============================================================================
81  * Type definitions
82  *============================================================================*/
83 
84 /* Function pointers for extra cleanup operations to be called when
85  entering cs_exit() or bft_error() */
86 
87 typedef void (cs_base_atexit_t) (void);
88 
89 /*=============================================================================
90  * Global variable definitions
91  *============================================================================*/
92 
93 /*=============================================================================
94  * Public function prototypes
95  *============================================================================*/
96 
97 /*----------------------------------------------------------------------------*/
105 /*----------------------------------------------------------------------------*/
106 
107 static inline const char *
108 cs_base_strtf(bool boolean)
109 {
110  if (boolean)
111  return "true";
112  else
113  return "false";
114 }
115 
116 /*----------------------------------------------------------------------------
117  * First analysis of the command line to determine an application name.
118  *
119  * If no name is defined by the command line, a name is determined based
120  * on the working directory.
121  *
122  * The caller is responsible for freeing the returned string.
123  *
124  * parameters:
125  * argc <-- number of command line arguments
126  * argv <-- array of command line arguments
127  *
128  * returns:
129  * pointer to character string with application name
130  *----------------------------------------------------------------------------*/
131 
132 char *
133 cs_base_get_app_name(int argc,
134  const char *argv[]);
135 
136 /*----------------------------------------------------------------------------
137  * Print logfile header
138  *
139  * parameters:
140  * argc <-- number of command line arguments
141  * argv <-- array of command line arguments
142  *----------------------------------------------------------------------------*/
143 
144 void
145 cs_base_logfile_head(int argc,
146  char *argv[]);
147 
148 #if defined(HAVE_MPI)
149 
150 /*----------------------------------------------------------------------------
151  * First analysis of the command line and environment variables to determine
152  * if we require MPI, and initialization if necessary.
153  *
154  * parameters:
155  * argc <-> number of command line arguments
156  * argv <-> array of command line arguments
157  *
158  * Global variables `cs_glob_n_ranks' (number of Code_Saturne processes)
159  * and `cs_glob_rank_id' (rank of local process) are set by this function.
160  *----------------------------------------------------------------------------*/
161 
162 void
163 cs_base_mpi_init(int *argc,
164  char **argv[]);
165 
166 #endif /* defined(HAVE_MPI) */
167 
168 /*----------------------------------------------------------------------------
169  * Exit, with handling for both normal and error cases.
170  *
171  * Finalize MPI if necessary.
172  *
173  * parameters:
174  * status <-- value to be returned to the parent:
175  * EXIT_SUCCESS / 0 for the normal case,
176  * EXIT_FAILURE or other nonzero code for error cases.
177  *----------------------------------------------------------------------------*/
178 
179 void
180 cs_exit(int status);
181 
182 /*----------------------------------------------------------------------------
183  * Initialize error and signal handlers.
184  *
185  * parameters:
186  * signal_defaults <-- leave default signal handlers in place if true.
187  *----------------------------------------------------------------------------*/
188 
189 void
190 cs_base_error_init(bool signal_defaults);
191 
192 /*----------------------------------------------------------------------------
193  * Initialize management of memory allocated through BFT.
194  *----------------------------------------------------------------------------*/
195 
196 void
197 cs_base_mem_init(void);
198 
199 /*----------------------------------------------------------------------------
200  * Finalize management of memory allocated through BFT.
201  *
202  * A summary of the consumed memory is given.
203  *----------------------------------------------------------------------------*/
204 
205 void
207 
208 /*----------------------------------------------------------------------------
209  * Print summary of running time, including CPU and elapsed times.
210  *----------------------------------------------------------------------------*/
211 
212 void
214 
215 /*----------------------------------------------------------------------------
216  * Set output file name and suppression flag for bft_printf().
217  *
218  * This allows redirecting or suppressing logging for different ranks.
219  *
220  * parameters:
221  * log_name <-- base file name for log, or NULL for stdout
222  * r0_log_flag <-- redirection for rank 0 log;
223  * 0: not redirected; 1: redirected to <log_name> file
224  * rn_log_flag <-- redirection for ranks > 0 log:
225  * 0: not redirected; 1: redirected to <log_name>_n*" file;
226  * 2: redirected to "/dev/null" (suppressed)
227  *----------------------------------------------------------------------------*/
228 
229 void
230 cs_base_bft_printf_init(const char *log_name,
231  int r0_log_flag,
232  int rn_log_flag);
233 
234 /*----------------------------------------------------------------------------
235  * Replace default bft_printf() mechanism with internal mechanism.
236  *
237  * This allows redirecting or suppressing logging for different ranks.
238  *
239  * parameters:
240  * log_name <-- base file name for log
241  * r0_log_flag <-- redirection for rank 0 log;
242  * 0: not redirected; 1: redirected to "listing" file
243  * rn_log_flag <-- redirection for ranks > 0 log:
244  * 0: not redirected; 1: redirected to "listing_n*" file;
245  * 2: redirected to "/dev/null" (suppressed)
246  *----------------------------------------------------------------------------*/
247 
248 void
249 cs_base_bft_printf_set(const char *log_name,
250  int r0_log_flag,
251  int rn_log_flag);
252 
253 /*----------------------------------------------------------------------------
254  * Return name of default log file.
255  *
256  * cs_base_bft_printf_set or cs_base_c_bft_printf_set() must have
257  * been called before this.
258  *
259  * returns:
260  * name of default log file
261  *----------------------------------------------------------------------------*/
262 
263 const char *
265 
266 /*----------------------------------------------------------------------------
267  * Return flag indicating if the default log file output is suppressed.
268  *
269  * cs_base_bft_printf_set or cs_base_c_bft_printf_set() must have
270  * been called before this.
271  *
272  * returns:
273  * output suppression flag
274  *----------------------------------------------------------------------------*/
275 
276 bool
278 
279 /*----------------------------------------------------------------------------
280  * Print a warning message header.
281  *
282  * parameters:
283  * file_name <-- name of source file
284  * line_nume <-- line number in source file
285  *----------------------------------------------------------------------------*/
286 
287 void
288 cs_base_warn(const char *file_name,
289  int line_num);
290 
291 /*----------------------------------------------------------------------------
292  * Define a function to be called when entering cs_exit() or bft_error().
293  *
294  * Compared to the C atexit(), only one function may be called (latest
295  * setting wins), but the function is called slighty before exit,
296  * so it is well adapted to cleanup such as flushing of non-C API logging.
297  *
298  * parameters:
299  * fct <-- pointer tu function to be called
300  *----------------------------------------------------------------------------*/
301 
302 void
304 
305 /*----------------------------------------------------------------------------
306  * Convert a character string from the Fortran API to the C API.
307  *
308  * Eventual leading and trailing blanks are removed.
309  *
310  * parameters:
311  * f_str <-- Fortran string
312  * f_len <-- Fortran string length
313  *
314  * returns:
315  * pointer to C string
316  *----------------------------------------------------------------------------*/
317 
318 char *
319 cs_base_string_f_to_c_create(const char *f_str,
320  int f_len);
321 
322 /*----------------------------------------------------------------------------
323  * Free a string converted from the Fortran API to the C API.
324  *
325  * parameters:
326  * str <-> pointer to C string
327  *----------------------------------------------------------------------------*/
328 
329 void
330 cs_base_string_f_to_c_free(char **c_str);
331 
332 /*----------------------------------------------------------------------------
333  * Clean a string representing options.
334  *
335  * Characters are converted to lowercase, leading and trailing whitespace
336  * is removed, and multiple whitespaces or tabs are replaced by single
337  * spaces.
338  *
339  * parameters:
340  * s <-> string to be cleaned
341  *----------------------------------------------------------------------------*/
342 
343 void
345 
346 /*----------------------------------------------------------------------------
347  * Return a string providing locale path information.
348  *
349  * This is normally the path determined upon configuration, but may be
350  * adapted for movable installs using the CS_ROOT_DIR environment variable.
351  *
352  * returns:
353  * locale path
354  *----------------------------------------------------------------------------*/
355 
356 const char *
358 
359 /*----------------------------------------------------------------------------
360  * Return a string providing package data path information.
361  *
362  * This is normally the path determined upon configuration, but may be
363  * adapted for movable installs using the CS_ROOT_DIR environment variable.
364  *
365  * returns:
366  * package data path
367  *----------------------------------------------------------------------------*/
368 
369 const char *
371 
372 /*----------------------------------------------------------------------------
373  * Return a string providing loadable library path information.
374  *
375  * This is normally the path determined upon configuration, but may be
376  * adapted for movable installs using the CS_ROOT_DIR environment variable.
377  *
378  * returns:
379  * package loadable library (plugin) path
380  *----------------------------------------------------------------------------*/
381 
382 const char *
384 
385 /*----------------------------------------------------------------------------
386  * Ensure bool argument has value 0 or 1.
387  *
388  * This allows working around issues with Intel compiler C bindings,
389  * which seem to pass incorrect values in some cases.
390  *
391  * parameters:
392  * b <-> pointer to bool
393  *----------------------------------------------------------------------------*/
394 
395 void
396 cs_base_check_bool(bool *b);
397 
398 /*----------------------------------------------------------------------------
399  * Open a data file in read mode.
400  *
401  * If a file of the given name in the working directory is found, it
402  * will be opened. Otherwise, it will be searched for in the "data/thch"
403  * subdirectory of pkgdatadir.
404  *
405  * parameters:
406  * base_name <-- base file name
407  *
408  * returns:
409  * pointer to opened file
410  *----------------------------------------------------------------------------*/
411 
412 FILE *
413 cs_base_open_properties_data_file(const char *base_name);
414 
415 #if defined(HAVE_DLOPEN)
416 
417 /*----------------------------------------------------------------------------*/
425 /*----------------------------------------------------------------------------*/
426 
427 void*
428 cs_base_dlopen(const char *filename);
429 
430 /*----------------------------------------------------------------------------*/
442 /*----------------------------------------------------------------------------*/
443 
444 void*
445 cs_base_dlopen_plugin(const char *name);
446 
447 /*----------------------------------------------------------------------------*/
453 /*----------------------------------------------------------------------------*/
454 
455 int
457 
458 /*----------------------------------------------------------------------------*/
464 /*----------------------------------------------------------------------------*/
465 
466 void
467 cs_base_dlopen_set_flags(int flags);
468 
469 /*----------------------------------------------------------------------------*/
481 /*----------------------------------------------------------------------------*/
482 
483 void
484 cs_base_dlclose(const char *filename,
485  void *handle);
486 
487 /*----------------------------------------------------------------------------*/
497 /*----------------------------------------------------------------------------*/
498 
499 void *
501  const char *name,
502  bool errors_are_fatal);
503 
504 
505 #endif /* defined(HAVE_DLOPEN) */
506 
507 /*----------------------------------------------------------------------------*/
508 
510 
511 #endif /* __CS_BASE_H__ */
void cs_base_string_f_to_c_free(char **c_str)
Definition: cs_base.c:1871
void cs_base_mem_finalize(void)
Definition: cs_base.c:1425
void cs_base_bft_printf_init(const char *log_name, int r0_log_flag, int rn_log_flag)
Definition: cs_base.c:1638
void() cs_base_atexit_t(void)
Definition: cs_base.h:87
void * cs_base_dlopen_plugin(const char *name)
Load a plugin&#39;s dynamic library.
Definition: cs_base.c:2093
#define BEGIN_C_DECLS
Definition: cs_defs.h:461
char * cs_base_string_f_to_c_create(const char *f_str, int f_len)
Definition: cs_base.c:1814
void * cs_base_dlopen(const char *filename)
Load a dynamic library.
Definition: cs_base.c:2053
const char * cs_base_get_localedir(void)
Definition: cs_base.c:1929
const char * cs_base_get_pkglibdir(void)
Definition: cs_base.c:1962
void cs_base_warn(const char *file_name, int line_num)
Definition: cs_base.c:1776
void cs_base_option_string_clean(char *s)
Definition: cs_base.c:1899
void cs_base_mem_init(void)
Definition: cs_base.c:1356
void cs_base_mpi_init(int *argc, char **argv[])
Definition: cs_base.c:1157
bool cs_base_bft_printf_suppressed(void)
Definition: cs_base.c:1762
int cs_base_dlopen_get_flags(void)
Get flags for dlopen.
Definition: cs_base.c:2124
void cs_exit(int status)
Definition: cs_base.c:1269
void cs_base_logfile_head(int argc, char *argv[])
Definition: cs_base.c:967
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:2191
char * cs_base_get_app_name(int argc, const char *argv[])
Definition: cs_base.c:908
void cs_base_check_bool(bool *b)
Definition: cs_base.c:1980
#define END_C_DECLS
Definition: cs_defs.h:462
void cs_base_bft_printf_set(const char *log_name, int r0_log_flag, int rn_log_flag)
Definition: cs_base.c:1699
void cs_base_dlopen_set_flags(int flags)
Set flags for dlopen.
Definition: cs_base.c:2138
static const char * cs_base_strtf(bool boolean)
Return a string "true" or "false" according to the boolean.
Definition: cs_base.h:108
FILE * cs_base_open_properties_data_file(const char *base_name)
Definition: cs_base.c:2010
const char * cs_base_get_pkgdatadir(void)
Definition: cs_base.c:1944
void cs_base_error_init(bool signal_defaults)
Definition: cs_base.c:1311
void cs_base_time_summary(void)
Definition: cs_base.c:1555
void cs_base_dlclose(const char *filename, void *handle)
Unload a dynamic library.
Definition: cs_base.c:2158
void cs_base_atexit_set(cs_base_atexit_t *const fct)
Definition: cs_base.c:1795
double precision, save b
Definition: cs_fuel_incl.f90:146
const char * cs_base_bft_printf_name(void)
Definition: cs_base.c:1746