programmer's documentation
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
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-2017 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 /*----------------------------------------------------------------------------
98  * First analysis of the command line to determine an application name.
99  *
100  * If no name is defined by the command line, a name is determined based
101  * on the working directory.
102  *
103  * The caller is responsible for freeing the returned string.
104  *
105  * parameters:
106  * argc <-- number of command line arguments
107  * argv <-- array of command line arguments
108  *
109  * returns:
110  * pointer to character string with application name
111  *----------------------------------------------------------------------------*/
112 
113 char *
114 cs_base_get_app_name(int argc,
115  const char *argv[]);
116 
117 /*----------------------------------------------------------------------------
118  * Print logfile header
119  *
120  * parameters:
121  * argc <-- number of command line arguments
122  * argv <-- array of command line arguments
123  *----------------------------------------------------------------------------*/
124 
125 void
126 cs_base_logfile_head(int argc,
127  char *argv[]);
128 
129 #if defined(HAVE_MPI)
130 
131 /*----------------------------------------------------------------------------
132  * First analysis of the command line and environment variables to determine
133  * if we require MPI, and initialization if necessary.
134  *
135  * parameters:
136  * argc <-> number of command line arguments
137  * argv <-> array of command line arguments
138  *
139  * Global variables `cs_glob_n_ranks' (number of Code_Saturne processes)
140  * and `cs_glob_rank_id' (rank of local process) are set by this function.
141  *----------------------------------------------------------------------------*/
142 
143 void
144 cs_base_mpi_init(int *argc,
145  char **argv[]);
146 
147 #endif /* defined(HAVE_MPI) */
148 
149 /*----------------------------------------------------------------------------
150  * Exit, with handling for both normal and error cases.
151  *
152  * Finalize MPI if necessary.
153  *
154  * parameters:
155  * status <-- value to be returned to the parent:
156  * EXIT_SUCCESS / 0 for the normal case,
157  * EXIT_FAILURE or other nonzero code for error cases.
158  *----------------------------------------------------------------------------*/
159 
160 void
161 cs_exit(int status);
162 
163 /*----------------------------------------------------------------------------
164  * Initialize error and signal handlers.
165  *
166  * parameters:
167  * signal_defaults <-- leave default signal handlers in place if true.
168  *----------------------------------------------------------------------------*/
169 
170 void
171 cs_base_error_init(bool signal_defaults);
172 
173 /*----------------------------------------------------------------------------
174  * Initialize management of memory allocated through BFT.
175  *----------------------------------------------------------------------------*/
176 
177 void
178 cs_base_mem_init(void);
179 
180 /*----------------------------------------------------------------------------
181  * Finalize management of memory allocated through BFT.
182  *
183  * A summary of the consumed memory is given.
184  *----------------------------------------------------------------------------*/
185 
186 void
188 
189 /*----------------------------------------------------------------------------
190  * Print summary of running time, including CPU and elapsed times.
191  *----------------------------------------------------------------------------*/
192 
193 void
195 
196 /*----------------------------------------------------------------------------
197  * Set output file name and suppression flag for bft_printf().
198  *
199  * This allows redirecting or suppressing logging for different ranks.
200  *
201  * parameters:
202  * log_name <-- base file name for log, or NULL for stdout
203  * r0_log_flag <-- redirection for rank 0 log;
204  * 0: not redirected; 1: redirected to <log_name> file
205  * rn_log_flag <-- redirection for ranks > 0 log:
206  * 0: not redirected; 1: redirected to <log_name>_n*" file;
207  * 2: redirected to "/dev/null" (suppressed)
208  *----------------------------------------------------------------------------*/
209 
210 void
211 cs_base_bft_printf_init(const char *log_name,
212  int r0_log_flag,
213  int rn_log_flag);
214 
215 /*----------------------------------------------------------------------------
216  * Replace default bft_printf() mechanism with internal mechanism.
217  *
218  * This allows redirecting or suppressing logging for different ranks.
219  *
220  * parameters:
221  * log_name <-- base file name for log
222  * r0_log_flag <-- redirection for rank 0 log;
223  * 0: not redirected; 1: redirected to "listing" file
224  * rn_log_flag <-- redirection for ranks > 0 log:
225  * 0: not redirected; 1: redirected to "listing_n*" file;
226  * 2: redirected to "/dev/null" (suppressed)
227  *----------------------------------------------------------------------------*/
228 
229 void
230 cs_base_bft_printf_set(const char *log_name,
231  int r0_log_flag,
232  int rn_log_flag);
233 
234 /*----------------------------------------------------------------------------
235  * Return name of default log file.
236  *
237  * cs_base_bft_printf_set or cs_base_c_bft_printf_set() must have
238  * been called before this.
239  *
240  * returns:
241  * name of default log file
242  *----------------------------------------------------------------------------*/
243 
244 const char *
246 
247 /*----------------------------------------------------------------------------
248  * Return flag indicating if the default log file output is suppressed.
249  *
250  * cs_base_bft_printf_set or cs_base_c_bft_printf_set() must have
251  * been called before this.
252  *
253  * returns:
254  * output suppression flag
255  *----------------------------------------------------------------------------*/
256 
257 bool
259 
260 /*----------------------------------------------------------------------------
261  * Print a warning message header.
262  *
263  * parameters:
264  * file_name <-- name of source file
265  * line_nume <-- line number in source file
266  *----------------------------------------------------------------------------*/
267 
268 void
269 cs_base_warn(const char *file_name,
270  int line_num);
271 
272 /*----------------------------------------------------------------------------
273  * Define a function to be called when entering cs_exit() or bft_error().
274  *
275  * Compared to the C atexit(), only one function may be called (latest
276  * setting wins), but the function is called slighty before exit,
277  * so it is well adapted to cleanup such as flushing of non-C API logging.
278  *
279  * parameters:
280  * fct <-- pointer tu function to be called
281  *----------------------------------------------------------------------------*/
282 
283 void
285 
286 /*----------------------------------------------------------------------------
287  * Convert a character string from the Fortran API to the C API.
288  *
289  * Eventual leading and trailing blanks are removed.
290  *
291  * parameters:
292  * f_str <-- Fortran string
293  * f_len <-- Fortran string length
294  *
295  * returns:
296  * pointer to C string
297  *----------------------------------------------------------------------------*/
298 
299 char *
300 cs_base_string_f_to_c_create(const char *f_str,
301  int f_len);
302 
303 /*----------------------------------------------------------------------------
304  * Free a string converted from the Fortran API to the C API.
305  *
306  * parameters:
307  * str <-> pointer to C string
308  *----------------------------------------------------------------------------*/
309 
310 void
311 cs_base_string_f_to_c_free(char **c_str);
312 
313 /*----------------------------------------------------------------------------
314  * Clean a string representing options.
315  *
316  * Characters are converted to lowercase, leading and trailing whitespace
317  * is removed, and multiple whitespaces or tabs are replaced by single
318  * spaces.
319  *
320  * parameters:
321  * s <-> string to be cleaned
322  *----------------------------------------------------------------------------*/
323 
324 void
326 
327 /*----------------------------------------------------------------------------
328  * Return a string providing locale path information.
329  *
330  * This is normally the path determined upon configuration, but may be
331  * adapted for movable installs using the CS_ROOT_DIR environment variable.
332  *
333  * returns:
334  * locale path
335  *----------------------------------------------------------------------------*/
336 
337 const char *
339 
340 /*----------------------------------------------------------------------------
341  * Return a string providing package data path information.
342  *
343  * This is normally the path determined upon configuration, but may be
344  * adapted for movable installs using the CS_ROOT_DIR environment variable.
345  *
346  * returns:
347  * package data path
348  *----------------------------------------------------------------------------*/
349 
350 const char *
352 
353 /*----------------------------------------------------------------------------
354  * Return a string providing loadable library path information.
355  *
356  * This is normally the path determined upon configuration, but may be
357  * adapted for movable installs using the CS_ROOT_DIR environment variable.
358  *
359  * returns:
360  * package loadable library (plugin) path
361  *----------------------------------------------------------------------------*/
362 
363 const char *
365 
366 /*----------------------------------------------------------------------------
367  * Ensure bool argument has value 0 or 1.
368  *
369  * This allows working around issues with Intel compiler C bindings,
370  * which seem to pass incorrect values in some cases.
371  *
372  * parameters:
373  * b <-> pointer to bool
374  *----------------------------------------------------------------------------*/
375 
376 void
377 cs_base_check_bool(bool *b);
378 
379 /*----------------------------------------------------------------------------
380  * Open a data file in read mode.
381  *
382  * If a file of the given name in the working directory is found, it
383  * will be opened. Otherwise, it will be searched for in the "data/thch"
384  * subdirectory of pkgdatadir.
385  *
386  * parameters:
387  * base_name <-- base file name
388  *
389  * returns:
390  * pointer to opened file
391  *----------------------------------------------------------------------------*/
392 
393 FILE *
394 cs_base_open_properties_data_file(const char *base_name);
395 
396 #if defined(HAVE_DLOPEN)
397 
398 /*----------------------------------------------------------------------------*/
406 /*----------------------------------------------------------------------------*/
407 
408 void*
409 cs_base_dlopen(const char *filename);
410 
411 /*----------------------------------------------------------------------------*/
423 /*----------------------------------------------------------------------------*/
424 
425 void*
426 cs_base_dlopen_plugin(const char *name);
427 
428 /*----------------------------------------------------------------------------*/
440 /*----------------------------------------------------------------------------*/
441 
442 void
443 cs_base_dlclose(const char *filename,
444  void *handle);
445 
446 /*----------------------------------------------------------------------------*/
456 /*----------------------------------------------------------------------------*/
457 
458 void *
460  const char *name,
461  bool errors_are_fatal);
462 
463 
464 #endif /* defined(HAVE_DLOPEN) */
465 
466 /*----------------------------------------------------------------------------*/
467 
469 
470 #endif /* __CS_BASE_H__ */
void cs_base_string_f_to_c_free(char **c_str)
Definition: cs_base.c:1862
void cs_base_mem_finalize(void)
Definition: cs_base.c:1416
void cs_base_bft_printf_init(const char *log_name, int r0_log_flag, int rn_log_flag)
Definition: cs_base.c:1629
void * cs_base_dlopen_plugin(const char *name)
Load a plugin's dynamic library.
Definition: cs_base.c:2074
void( cs_base_atexit_t)(void)
Definition: cs_base.h:87
#define BEGIN_C_DECLS
Definition: cs_defs.h:453
char * cs_base_string_f_to_c_create(const char *f_str, int f_len)
Definition: cs_base.c:1805
void * cs_base_dlopen(const char *filename)
Load a dynamic library.
Definition: cs_base.c:2044
const char * cs_base_get_localedir(void)
Definition: cs_base.c:1920
const char * cs_base_get_pkglibdir(void)
Definition: cs_base.c:1953
void cs_base_warn(const char *file_name, int line_num)
Definition: cs_base.c:1767
void cs_base_option_string_clean(char *s)
Definition: cs_base.c:1890
void cs_base_mem_init(void)
Definition: cs_base.c:1347
void cs_base_mpi_init(int *argc, char **argv[])
Definition: cs_base.c:1148
bool cs_base_bft_printf_suppressed(void)
Definition: cs_base.c:1753
void cs_exit(int status)
Definition: cs_base.c:1260
void cs_base_logfile_head(int argc, char *argv[])
Definition: cs_base.c:958
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:2144
char * cs_base_get_app_name(int argc, const char *argv[])
Definition: cs_base.c:899
void cs_base_check_bool(bool *b)
Definition: cs_base.c:1971
#define END_C_DECLS
Definition: cs_defs.h:454
void cs_base_bft_printf_set(const char *log_name, int r0_log_flag, int rn_log_flag)
Definition: cs_base.c:1690
FILE * cs_base_open_properties_data_file(const char *base_name)
Definition: cs_base.c:2001
const char * cs_base_get_pkgdatadir(void)
Definition: cs_base.c:1935
void cs_base_error_init(bool signal_defaults)
Definition: cs_base.c:1302
void cs_base_time_summary(void)
Definition: cs_base.c:1546
void cs_base_dlclose(const char *filename, void *handle)
Unload a dynamic library.
Definition: cs_base.c:2111
void cs_base_atexit_set(cs_base_atexit_t *const fct)
Definition: cs_base.c:1786
const char * cs_base_bft_printf_name(void)
Definition: cs_base.c:1737