programmer's documentation
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups 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-2013 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(__blrts__) || 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(__blrts__) || defined(__bgp__)
61 #define CS_MEM_ALIGN 16
62 #elif defined(__bgq__)
63 #define CS_MEM_ALIGN 32
64 #else
65 #define CS_MEM_ALIGN 0
66 #endif
67 
68 /*----------------------------------------------------------------------------*/
69 
71 
72 /*============================================================================
73  * Type definitions
74  *============================================================================*/
75 
76 /* Function pointers for extra cleanup operations to be called when
77  entering cs_exit() or bft_error() */
78 
79 typedef void (cs_base_atexit_t) (void);
80 
81 /*=============================================================================
82  * Global variable definitions
83  *============================================================================*/
84 
85 /*=============================================================================
86  * Public function prototypes
87  *============================================================================*/
88 
89 /*----------------------------------------------------------------------------
90  * First analysis of the command line to determine an application name.
91  *
92  * If no name is defined by the command line, a name is determined based
93  * on the working directory.
94  *
95  * The caller is responsible for freeing the returned string.
96  *
97  * parameters:
98  * argc <-- number of command line arguments
99  * argv <-- array of command line arguments
100  *
101  * returns:
102  * pointer to character string with application name
103  *----------------------------------------------------------------------------*/
104 
105 char *
106 cs_base_get_app_name(int argc,
107  const char *argv[]);
108 
109 /*----------------------------------------------------------------------------
110  * Print logfile header
111  *
112  * parameters:
113  * argc <-- number of command line arguments
114  * argv <-- array of command line arguments
115  *----------------------------------------------------------------------------*/
116 
117 void
118 cs_base_logfile_head(int argc,
119  char *argv[]);
120 
121 #if defined(HAVE_MPI)
122 
123 /*----------------------------------------------------------------------------
124  * First analysis of the command line and environment variables to determine
125  * if we require MPI, and initialization if necessary.
126  *
127  * parameters:
128  * argc <-> number of command line arguments
129  * argv <-> array of command line arguments
130  *
131  * Global variables `cs_glob_n_ranks' (number of Code_Saturne processes)
132  * and `cs_glob_rank_id' (rank of local process) are set by this function.
133  *----------------------------------------------------------------------------*/
134 
135 void
136 cs_base_mpi_init(int *argc,
137  char **argv[]);
138 
139 #endif /* defined(HAVE_MPI) */
140 
141 /*----------------------------------------------------------------------------
142  * Exit, with handling for both normal and error cases.
143  *
144  * Finalize MPI if necessary.
145  *
146  * parameters:
147  * status <-- value to be returned to the parent:
148  * EXIT_SUCCESS / 0 for the normal case,
149  * EXIT_FAILURE or other nonzero code for error cases.
150  *----------------------------------------------------------------------------*/
151 
152 void
153 cs_exit(int status);
154 
155 /*----------------------------------------------------------------------------
156  * Initialize error and signal handlers.
157  *----------------------------------------------------------------------------*/
158 
159 void
160 cs_base_error_init(void);
161 
162 /*----------------------------------------------------------------------------
163  * Initialize management of memory allocated through BFT.
164  *----------------------------------------------------------------------------*/
165 
166 void
167 cs_base_mem_init(void);
168 
169 /*----------------------------------------------------------------------------
170  * Finalize management of memory allocated through BFT.
171  *
172  * A summary of the consumed memory is given.
173  *----------------------------------------------------------------------------*/
174 
175 void
177 
178 /*----------------------------------------------------------------------------
179  * Print summary of running time, including CPU and elapsed times.
180  *----------------------------------------------------------------------------*/
181 
182 void
184 
185 /*----------------------------------------------------------------------------
186  * Set output file name and suppression flag for bft_printf().
187  *
188  * This allows redirecting or suppressing logging for different ranks.
189  *
190  * parameters:
191  * log_name <-- base file name for log, or NULL for stdout
192  * r0_log_flag <-- redirection for rank 0 log;
193  * 0: not redirected; 1: redirected to <log_name> file
194  * rn_log_flag <-- redirection for ranks > 0 log:
195  * 0: not redirected; 1: redirected to <log_name>_n*" file;
196  * 2: redirected to "/dev/null" (suppressed)
197  *----------------------------------------------------------------------------*/
198 
199 void
200 cs_base_bft_printf_init(const char *log_name,
201  int r0_log_flag,
202  int rn_log_flag);
203 
204 /*----------------------------------------------------------------------------
205  * Replace default bft_printf() mechanism with internal mechanism.
206  *
207  * This allows redirecting or suppressing logging for different ranks.
208  *
209  * parameters:
210  * log_name <-- base file name for log
211  * r0_log_flag <-- redirection for rank 0 log;
212  * 0: not redirected; 1: redirected to "listing" file
213  * rn_log_flag <-- redirection for ranks > 0 log:
214  * 0: not redirected; 1: redirected to "listing_n*" file;
215  * 2: redirected to "/dev/null" (suppressed)
216  *----------------------------------------------------------------------------*/
217 
218 void
219 cs_base_bft_printf_set(const char *log_name,
220  int r0_log_flag,
221  int rn_log_flag);
222 
223 /*----------------------------------------------------------------------------
224  * Return name of default log file.
225  *
226  * cs_base_bft_printf_set or cs_base_c_bft_printf_set() must have
227  * been called before this.
228  *
229  * returns:
230  * name of default log file
231  *----------------------------------------------------------------------------*/
232 
233 const char *
235 
236 /*----------------------------------------------------------------------------
237  * Return flag indicating if the default log file output is suppressed.
238  *
239  * cs_base_bft_printf_set or cs_base_c_bft_printf_set() must have
240  * been called before this.
241  *
242  * returns:
243  * output suppression flag
244  *----------------------------------------------------------------------------*/
245 
246 bool
248 
249 /*----------------------------------------------------------------------------
250  * Print a warning message header.
251  *
252  * parameters:
253  * file_name <-- name of source file
254  * line_nume <-- line number in source file
255  *----------------------------------------------------------------------------*/
256 
257 void
258 cs_base_warn(const char *file_name,
259  int line_num);
260 
261 /*----------------------------------------------------------------------------
262  * Define a function to be called when entering cs_exit() or bft_error().
263  *
264  * Compared to the C atexit(), only one function may be called (latest
265  * setting wins), but the function is called slighty before exit,
266  * so it is well adapted to cleanup such as flushing of non-C API logging.
267  *
268  * parameters:
269  * fct <-- pointer tu function to be called
270  *----------------------------------------------------------------------------*/
271 
272 void
273 cs_base_atexit_set(cs_base_atexit_t *const fct);
274 
275 /*----------------------------------------------------------------------------
276  * Convert a character string from the Fortran API to the C API.
277  *
278  * Eventual leading and trailing blanks are removed.
279  *
280  * parameters:
281  * f_str <-- Fortran string
282  * f_len <-- Fortran string length
283  *
284  * returns:
285  * pointer to C string
286  *----------------------------------------------------------------------------*/
287 
288 char *
289 cs_base_string_f_to_c_create(const char *f_str,
290  int f_len);
291 
292 /*----------------------------------------------------------------------------
293  * Free a string converted from the Fortran API to the C API.
294  *
295  * parameters:
296  * str <-> pointer to C string
297  *----------------------------------------------------------------------------*/
298 
299 void
300 cs_base_string_f_to_c_free(char **c_str);
301 
302 /*----------------------------------------------------------------------------
303  * Clean a string representing options.
304  *
305  * Characters are converted to lowercase, leading and trailing whitespace
306  * is removed, and multiple whitespaces or tabs are replaced by single
307  * spaces.
308  *
309  * parameters:
310  * s <-> string to be cleaned
311  *----------------------------------------------------------------------------*/
312 
313 void
315 
316 /*----------------------------------------------------------------------------
317  * Return a string providing locale path information.
318  *
319  * This is normally the path determined upon configuration, but may be
320  * adapted for movable installs using the CS_ROOT_DIR environment variable.
321  *
322  * returns:
323  * locale path
324  *----------------------------------------------------------------------------*/
325 
326 const char *
328 
329 /*----------------------------------------------------------------------------
330  * Return a string providing package data path information.
331  *
332  * This is normally the path determined upon configuration, but may be
333  * adapted for movable installs using the CS_ROOT_DIR environment variable.
334  *
335  * returns:
336  * package data path
337  *----------------------------------------------------------------------------*/
338 
339 const char *
341 
342 /*----------------------------------------------------------------------------
343  * Return a string providing loadable library path information.
344  *
345  * This is normally the path determined upon configuration, but may be
346  * adapted for movable installs using the CS_ROOT_DIR environment variable.
347  *
348  * returns:
349  * package loadable library (plugin) path
350  *----------------------------------------------------------------------------*/
351 
352 const char *
354 
355 /*----------------------------------------------------------------------------*/
356 
358 
359 #endif /* __CS_BASE_H__ */