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-2015 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 /*----------------------------------------------------------------------------
31  * Standard C library headers
32  *----------------------------------------------------------------------------*/
33 
34 /*=============================================================================
35  * Macro definitions
36  *============================================================================*/
37 
38 /* Application type name */
39 
40 #define CS_APP_NAME "Code_Saturne"
41 #define CS_APP_VERSION PACKAGE_VERSION /* PACKAGE_VERSION from autoconf */
42 
43 /* System type name */
44 
45 #if defined(__bg__)
46 #define _CS_ARCH_Blue_Gene
47 
48 #elif defined(__linux__) || defined(__linux) || defined(linux)
49 #define _CS_ARCH_Linux
50 
51 #elif defined(__sun__) || defined(__sun) || defined(sun)
52 #define _CS_ARCH_SunOS
53 
54 #endif
55 
56 /* On certain architectures such as IBM Blue Gene, some operations may
57  * be better optimized on memory-aligned data (if 0 here, no alignment
58  * is leveraged). This alignment is not exploited yet in Code_Saturne. */
59 
60 #if defined(__bgq__)
61 #define CS_MEM_ALIGN 32
62 #else
63 #define CS_MEM_ALIGN 0
64 #endif
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 
77 typedef void (cs_base_atexit_t) (void);
78 
79 /*=============================================================================
80  * Global variable definitions
81  *============================================================================*/
82 
83 /*=============================================================================
84  * Public function prototypes
85  *============================================================================*/
86 
87 /*----------------------------------------------------------------------------
88  * First analysis of the command line to determine an application name.
89  *
90  * If no name is defined by the command line, a name is determined based
91  * on the working directory.
92  *
93  * The caller is responsible for freeing the returned string.
94  *
95  * parameters:
96  * argc <-- number of command line arguments
97  * argv <-- array of command line arguments
98  *
99  * returns:
100  * pointer to character string with application name
101  *----------------------------------------------------------------------------*/
102 
103 char *
104 cs_base_get_app_name(int argc,
105  const char *argv[]);
106 
107 /*----------------------------------------------------------------------------
108  * Print logfile header
109  *
110  * parameters:
111  * argc <-- number of command line arguments
112  * argv <-- array of command line arguments
113  *----------------------------------------------------------------------------*/
114 
115 void
116 cs_base_logfile_head(int argc,
117  char *argv[]);
118 
119 #if defined(HAVE_MPI)
120 
121 /*----------------------------------------------------------------------------
122  * First analysis of the command line and environment variables to determine
123  * if we require MPI, and initialization if necessary.
124  *
125  * parameters:
126  * argc <-> number of command line arguments
127  * argv <-> array of command line arguments
128  *
129  * Global variables `cs_glob_n_ranks' (number of Code_Saturne processes)
130  * and `cs_glob_rank_id' (rank of local process) are set by this function.
131  *----------------------------------------------------------------------------*/
132 
133 void
134 cs_base_mpi_init(int *argc,
135  char **argv[]);
136 
137 #endif /* defined(HAVE_MPI) */
138 
139 /*----------------------------------------------------------------------------
140  * Exit, with handling for both normal and error cases.
141  *
142  * Finalize MPI if necessary.
143  *
144  * parameters:
145  * status <-- value to be returned to the parent:
146  * EXIT_SUCCESS / 0 for the normal case,
147  * EXIT_FAILURE or other nonzero code for error cases.
148  *----------------------------------------------------------------------------*/
149 
150 void
151 cs_exit(int status);
152 
153 /*----------------------------------------------------------------------------
154  * Initialize error and signal handlers.
155  *
156  * parameters:
157  * signal_defaults <-- leave default signal handlers in place if true.
158  *----------------------------------------------------------------------------*/
159 
160 void
161 cs_base_error_init(bool signal_defaults);
162 
163 /*----------------------------------------------------------------------------
164  * Initialize management of memory allocated through BFT.
165  *----------------------------------------------------------------------------*/
166 
167 void
168 cs_base_mem_init(void);
169 
170 /*----------------------------------------------------------------------------
171  * Finalize management of memory allocated through BFT.
172  *
173  * A summary of the consumed memory is given.
174  *----------------------------------------------------------------------------*/
175 
176 void
178 
179 /*----------------------------------------------------------------------------
180  * Print summary of running time, including CPU and elapsed times.
181  *----------------------------------------------------------------------------*/
182 
183 void
185 
186 /*----------------------------------------------------------------------------
187  * Set output file name and suppression flag for bft_printf().
188  *
189  * This allows redirecting or suppressing logging for different ranks.
190  *
191  * parameters:
192  * log_name <-- base file name for log, or NULL for stdout
193  * r0_log_flag <-- redirection for rank 0 log;
194  * 0: not redirected; 1: redirected to <log_name> file
195  * rn_log_flag <-- redirection for ranks > 0 log:
196  * 0: not redirected; 1: redirected to <log_name>_n*" file;
197  * 2: redirected to "/dev/null" (suppressed)
198  *----------------------------------------------------------------------------*/
199 
200 void
201 cs_base_bft_printf_init(const char *log_name,
202  int r0_log_flag,
203  int rn_log_flag);
204 
205 /*----------------------------------------------------------------------------
206  * Replace default bft_printf() mechanism with internal mechanism.
207  *
208  * This allows redirecting or suppressing logging for different ranks.
209  *
210  * parameters:
211  * log_name <-- base file name for log
212  * r0_log_flag <-- redirection for rank 0 log;
213  * 0: not redirected; 1: redirected to "listing" file
214  * rn_log_flag <-- redirection for ranks > 0 log:
215  * 0: not redirected; 1: redirected to "listing_n*" file;
216  * 2: redirected to "/dev/null" (suppressed)
217  *----------------------------------------------------------------------------*/
218 
219 void
220 cs_base_bft_printf_set(const char *log_name,
221  int r0_log_flag,
222  int rn_log_flag);
223 
224 /*----------------------------------------------------------------------------
225  * Return name of default log file.
226  *
227  * cs_base_bft_printf_set or cs_base_c_bft_printf_set() must have
228  * been called before this.
229  *
230  * returns:
231  * name of default log file
232  *----------------------------------------------------------------------------*/
233 
234 const char *
236 
237 /*----------------------------------------------------------------------------
238  * Return flag indicating if the default log file output is suppressed.
239  *
240  * cs_base_bft_printf_set or cs_base_c_bft_printf_set() must have
241  * been called before this.
242  *
243  * returns:
244  * output suppression flag
245  *----------------------------------------------------------------------------*/
246 
247 bool
249 
250 /*----------------------------------------------------------------------------
251  * Print a warning message header.
252  *
253  * parameters:
254  * file_name <-- name of source file
255  * line_nume <-- line number in source file
256  *----------------------------------------------------------------------------*/
257 
258 void
259 cs_base_warn(const char *file_name,
260  int line_num);
261 
262 /*----------------------------------------------------------------------------
263  * Define a function to be called when entering cs_exit() or bft_error().
264  *
265  * Compared to the C atexit(), only one function may be called (latest
266  * setting wins), but the function is called slighty before exit,
267  * so it is well adapted to cleanup such as flushing of non-C API logging.
268  *
269  * parameters:
270  * fct <-- pointer tu function to be called
271  *----------------------------------------------------------------------------*/
272 
273 void
275 
276 /*----------------------------------------------------------------------------
277  * Convert a character string from the Fortran API to the C API.
278  *
279  * Eventual leading and trailing blanks are removed.
280  *
281  * parameters:
282  * f_str <-- Fortran string
283  * f_len <-- Fortran string length
284  *
285  * returns:
286  * pointer to C string
287  *----------------------------------------------------------------------------*/
288 
289 char *
290 cs_base_string_f_to_c_create(const char *f_str,
291  int f_len);
292 
293 /*----------------------------------------------------------------------------
294  * Free a string converted from the Fortran API to the C API.
295  *
296  * parameters:
297  * str <-> pointer to C string
298  *----------------------------------------------------------------------------*/
299 
300 void
301 cs_base_string_f_to_c_free(char **c_str);
302 
303 /*----------------------------------------------------------------------------
304  * Clean a string representing options.
305  *
306  * Characters are converted to lowercase, leading and trailing whitespace
307  * is removed, and multiple whitespaces or tabs are replaced by single
308  * spaces.
309  *
310  * parameters:
311  * s <-> string to be cleaned
312  *----------------------------------------------------------------------------*/
313 
314 void
316 
317 /*----------------------------------------------------------------------------
318  * Return a string providing locale path information.
319  *
320  * This is normally the path determined upon configuration, but may be
321  * adapted for movable installs using the CS_ROOT_DIR environment variable.
322  *
323  * returns:
324  * locale path
325  *----------------------------------------------------------------------------*/
326 
327 const char *
329 
330 /*----------------------------------------------------------------------------
331  * Return a string providing package data path information.
332  *
333  * This is normally the path determined upon configuration, but may be
334  * adapted for movable installs using the CS_ROOT_DIR environment variable.
335  *
336  * returns:
337  * package data path
338  *----------------------------------------------------------------------------*/
339 
340 const char *
342 
343 /*----------------------------------------------------------------------------
344  * Return a string providing loadable library path information.
345  *
346  * This is normally the path determined upon configuration, but may be
347  * adapted for movable installs using the CS_ROOT_DIR environment variable.
348  *
349  * returns:
350  * package loadable library (plugin) path
351  *----------------------------------------------------------------------------*/
352 
353 const char *
355 
356 /*----------------------------------------------------------------------------
357  * Ensure bool argument has value 0 or 1.
358  *
359  * This allows working around issues with Intel compiler C bindings,
360  * which seem to pass incorrect values in some cases.
361  *
362  * parameters:
363  * b <-> pointer to bool
364  *----------------------------------------------------------------------------*/
365 
366 void
367 cs_base_check_bool(bool *b);
368 
369 /*----------------------------------------------------------------------------*/
370 
372 
373 #endif /* __CS_BASE_H__ */
void cs_base_string_f_to_c_free(char **c_str)
Definition: cs_base.c:1876
void cs_base_mem_finalize(void)
Definition: cs_base.c:1430
void cs_base_bft_printf_init(const char *log_name, int r0_log_flag, int rn_log_flag)
Definition: cs_base.c:1643
#define BEGIN_C_DECLS
Definition: cs_defs.h:429
char * cs_base_string_f_to_c_create(const char *f_str, int f_len)
Definition: cs_base.c:1819
const char * cs_base_get_localedir(void)
Definition: cs_base.c:1934
void cs_base_mpi_init(int *argc, char **argv[])
Definition: cs_base.c:1135
const char * cs_base_get_pkglibdir(void)
Definition: cs_base.c:1967
void cs_base_warn(const char *file_name, int line_num)
Definition: cs_base.c:1781
void cs_base_option_string_clean(char *s)
Definition: cs_base.c:1904
void cs_base_mem_init(void)
Definition: cs_base.c:1361
bool cs_base_bft_printf_suppressed(void)
Definition: cs_base.c:1767
void cs_exit(int status)
Definition: cs_base.c:1274
void cs_base_logfile_head(int argc, char *argv[])
Definition: cs_base.c:945
char * cs_base_get_app_name(int argc, const char *argv[])
Definition: cs_base.c:886
void cs_base_check_bool(bool *b)
Definition: cs_base.c:1985
#define END_C_DECLS
Definition: cs_defs.h:430
void cs_base_bft_printf_set(const char *log_name, int r0_log_flag, int rn_log_flag)
Definition: cs_base.c:1704
const char * cs_base_get_pkgdatadir(void)
Definition: cs_base.c:1949
void( cs_base_atexit_t)(void)
Definition: cs_base.h:77
void cs_base_error_init(bool signal_defaults)
Definition: cs_base.c:1316
void cs_base_time_summary(void)
Definition: cs_base.c:1560
void cs_base_atexit_set(cs_base_atexit_t *const fct)
Definition: cs_base.c:1800
double precision, save b
Definition: cs_fuel_incl.f90:146
const char * cs_base_bft_printf_name(void)
Definition: cs_base.c:1751