PLE
Parallel Location and Exchange
ple_defs.h
1 #ifndef __PLE_DEFS_H__
2 #define __PLE_DEFS_H__
3 
4 /*============================================================================
5  * Definitions, global variables, and base functions
6  *============================================================================*/
7 
8 /*
9  This file is part of the "Parallel Location and Exchange" library,
10  intended to provide mesh or particle-based code coupling services.
11 
12  Copyright (C) 2005-2018 EDF S.A.
13 
14  This library is free software; you can redistribute it and/or
15  modify it under the terms of the GNU Lesser General Public
16  License as published by the Free Software Foundation; either
17  version 2.1 of the License, or (at your option) any later version.
18 
19  This library is distributed in the hope that it will be useful,
20  but WITHOUT ANY WARRANTY; without even the implied warranty of
21  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
22  Lesser General Public License for more details.
23 
24  You should have received a copy of the GNU Lesser General Public
25  License along with this library; if not, write to the Free Software
26  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
27 */
28 
29 /*----------------------------------------------------------------------------*/
30 
31 #include "ple_config.h"
32 
33 /*----------------------------------------------------------------------------*/
34 
35 #include <stdarg.h>
36 
37 #ifdef __cplusplus
38 extern "C" {
39 #if 0
40 } /* Fake brace to force back Emacs auto-indentation back to column 0 */
41 #endif
42 #endif /* __cplusplus */
43 
44 /*=============================================================================
45  * Macro definitions
46  *============================================================================*/
47 
48 /* Absolute, minimum, and maximum values */
49 
50 #define PLE_ABS(a) ((a) < 0 ? -(a) : (a)) /* Absolute value of a */
51 #define PLE_MIN(a,b) ((a) > (b) ? (b) : (a)) /* Minimum of a et b */
52 #define PLE_MAX(a,b) ((a) < (b) ? (b) : (a)) /* Maximum of a et b */
53 
54 /*
55  * Allocate memory for _ni items of type _type.
56  *
57  * This macro calls ple_mem_malloc(), automatically setting the
58  * allocated variable name and source file name and line arguments.
59  *
60  * parameters:
61  * _ptr --> pointer to allocated memory.
62  * _ni <-- number of items.
63  * _type <-- element type.
64  */
65 
66 #define PLE_MALLOC(_ptr, _ni, _type) \
67 _ptr = (_type *) ple_mem_malloc(_ni, sizeof(_type), \
68  #_ptr, __FILE__, __LINE__)
69 
70 /*
71  * Reallocate memory for _ni items of type _type.
72  *
73  * This macro calls ple_mem_realloc(), automatically setting the
74  * allocated variable name and source file name and line arguments.
75  *
76  * parameters:
77  * _ptr <-> pointer to allocated memory.
78  * _ni <-- number of items.
79  * _type <-- element type.
80  */
81 
82 #define PLE_REALLOC(_ptr, _ni, _type) \
83 _ptr = (_type *) ple_mem_realloc(_ptr, _ni, sizeof(_type), \
84  #_ptr, __FILE__, __LINE__)
85 
86 /*
87  * Free allocated memory.
88  *
89  * This macro calls ple_mem_free(), automatically setting the
90  * allocated variable name and source file name and line arguments.
91  *
92  * The freed pointer is set to NULL to avoid accidental reuse.
93  *
94  * parameters:
95  * _ptr <-> pointer to allocated memory.
96  */
97 
98 #ifdef __cplusplus /* avoid casting from void for C++ */
99 
100 #define PLE_FREE(_ptr) \
101 ple_mem_free(_ptr, #_ptr, __FILE__, __LINE__), _ptr = NULL
102 
103 #else
104 
105 #define PLE_FREE(_ptr) \
106 _ptr = ple_mem_free(_ptr, #_ptr, __FILE__, __LINE__)
107 
108 #endif /* __cplusplus */
109 
110 /*============================================================================
111  * Type definitions
112  *============================================================================*/
113 
114 /*----------------------------------------------------------------------------
115  * General C types such as size_t which should be known
116  *----------------------------------------------------------------------------*/
117 
118 /*
119  * Obtain definitions such as that of size_t through stddef.h (C99 standard)
120  * if available (preferred method), or through stdlib.h (which defines
121  * malloc() and family and so must define size_t some way) otherwise.
122  * This must be done in ple_defs.h in a way independent of the private
123  * configuration files, as size_t is used in many public FVM headers.
124  */
125 
126 #if defined(__STDC_VERSION__)
127 # if (__STDC_VERSION__ >= 199901L)
128 # include <stddef.h>
129 # else
130 # include <stdlib.h>
131 # endif
132 #else
133 # include <stdlib.h>
134 #endif
135 
136 /*----------------------------------------------------------------------------
137  * Basic types used by PLE.
138  * They may be modified here to better map to a given library, with the
139  * following constraints:
140  * - ple_lnum_t must be signed
141  *----------------------------------------------------------------------------*/
142 
143 typedef int ple_lnum_t; /* Local integer index or number */
144 typedef double ple_coord_t; /* Real number (coordinate value) */
145 
146 /*----------------------------------------------------------------------------
147  * MPI datatypes.
148  *----------------------------------------------------------------------------*/
149 
150 #if defined(PLE_HAVE_MPI)
151 
152 #define PLE_MPI_TAG (int)('P'+'L'+'E') /* MPI tag for PLE operations */
153 
154 #define PLE_MPI_LNUM MPI_INT /* MPI type for ple_lnum_t type */
155 #define PLE_MPI_COORD MPI_DOUBLE /* MPI type for ple_coord_t type */
156 
157 #endif
158 
159 /*----------------------------------------------------------------------------
160  * Macro used to silence "unused argument" warnings.
161  *
162  * This is useful when a function must match a given function pointer
163  * type, but does not use all possible arguments.
164  *----------------------------------------------------------------------------*/
165 
166 #define PLE_UNUSED(x) (void)(x)
167 
168 /*----------------------------------------------------------------------------
169  * Macros for compilation with a C++ compiler
170  *----------------------------------------------------------------------------*/
171 
172 #undef PLE_BEGIN_C_DECLS
173 #undef PLE_END_C_DECLS
174 
175 #if defined(__cplusplus)
176 # define PLE_BEGIN_C_DECLS extern "C" {
177 # define PLE_END_C_DECLS }
178 #else
179 # define PLE_BEGIN_C_DECLS
180 # define PLE_END_C_DECLS
181 #endif
182 
183 /*----------------------------------------------------------------------------
184  * Macros for scoping of examples
185  *----------------------------------------------------------------------------*/
186 
187 #undef PLE_BEGIN_EXAMPLE_SCOPE
188 #undef PLE_END_EXAMPLE_SCOPE
189 
190 #define PLE_BEGIN_EXAMPLE_SCOPE {
191 #define PLE_END_EXAMPLE_SCOPE }
192 
193 /*----------------------------------------------------------------------------
194  * Function pointer types
195  *----------------------------------------------------------------------------*/
196 
197 typedef int
198 (ple_printf_t) (const char *const format,
199  va_list arg_ptr);
200 
201 typedef void
202 (ple_error_handler_t) (const char *file_name,
203  const int line_num,
204  const int sys_error_code,
205  const char *format,
206  va_list arg_ptr);
207 
208 typedef void *
209 (ple_mem_malloc_t)(size_t ni,
210  size_t size,
211  const char *var_name,
212  const char *file_name,
213  int line_num);
214 
215 typedef void *
216 (ple_mem_realloc_t)(void *ptr,
217  size_t ni,
218  size_t size,
219  const char *var_name,
220  const char *file_name,
221  int line_num);
222 
223 typedef void *
224 (ple_mem_free_t)(void *ptr,
225  const char *var_name,
226  const char *file_name,
227  int line_num);
228 
229 /*============================================================================
230  * Public function prototypes
231  *============================================================================*/
232 
246 int
247 ple_printf(const char *const format,
248  ...);
249 
250 /* Returns function associated with the ple_printf() function.
251  *
252  * returns:
253  * pointer to the vprintf() or replacement function.
254  */
255 
256 ple_printf_t *
258 
259 /*
260  * Associates a vprintf() type function with the ple_printf() function.
261  *
262  * parameters:
263  * f <-- pointer to a vprintf() type function.
264  */
265 
266 void
267 ple_printf_function_set(ple_printf_t *f);
268 
269 /*
270  * Calls the error handler (set by ple_error_handler_set() or default).
271  *
272  * With the default error handler, an error message is output to stderr,
273  * and the current process exits with an EXIT_FAILURE code.
274  *
275  * parameters:
276  * file_name <-- name of source file from which error handler called.
277  * line_num <-- line of source file from which error handler called.
278  * sys_error_code <-- error code if error in system or libc call,
279  * 0 otherwise.
280  * format <-- format string, as printf() and family.
281  * ... <-- variable arguments based on format string.
282  */
283 
284 void
285 ple_error(const char *file_name,
286  const int line_num,
287  const int sys_error_code,
288  const char *format,
289  ...);
290 
291 /*
292  * Returns the error handler associated with the ple_error() function.
293  *
294  * returns:
295  * pointer to the error handler function.
296  */
297 
298 ple_error_handler_t *
300 
301 /*
302  * Associates an error handler with the ple_error() function.
303  *
304  * parameters:
305  * handler <-- pointer to the error handler function.
306  */
307 
308 void
309 ple_error_handler_set(ple_error_handler_t *handler);
310 
311 /*
312  * Allocate memory for ni items of size bytes.
313  *
314  * This function calls malloc(), but adds tracing capabilities, and
315  * automatically calls the ple_error() errorhandler if it fails to
316  * allocate the required memory.
317  *
318  * parameters:
319  * ni <-- number of items.
320  * size <-- element size.
321  * var_name <-- allocated variable name string.
322  * file_name <-- name of calling source file.
323  * line_num <-- line number in calling source file.
324  *
325  * returns:
326  * pointer to allocated memory.
327  */
328 
329 void *
330 ple_mem_malloc(size_t ni,
331  size_t size,
332  const char *var_name,
333  const char *file_name,
334  int line_num);
335 
336 /*
337  * Reallocate memory for ni items of size bytes.
338  *
339  * This function calls realloc(), but adds tracing capabilities, and
340  * automatically calls the ple_error() errorhandler if it fails to
341  * allocate the required memory.
342  *
343  * parameters:
344  * ptr <-> pointer to previous memory location
345  * (if NULL, ple_alloc() called).
346  * ni <-- number of items.
347  * size <-- element size.
348  * var_name <-- allocated variable name string.
349  * file_name <-- name of calling source file.
350  * line_num -> line number in calling source file
351  *
352  * returns:
353  * pointer to allocated memory.
354  */
355 
356 void *
357 ple_mem_realloc(void *ptr,
358  size_t ni,
359  size_t size,
360  const char *var_name,
361  const char *file_name,
362  int line_num);
363 
364 /*
365  * Free allocated memory.
366  *
367  * This function calls free(), but adds tracing capabilities, and
368  * automatically calls the ple_error() errorhandler if it fails to
369  * free the corresponding memory. In case of a NULL pointer argument,
370  * the function simply returns.
371  *
372  * parameters:
373  * ptr <-> pointer to previous memory location
374  * (if NULL, ple_alloc() called).
375  * var_name <-- allocated variable name string.
376  * file_name <-- name of calling source file.
377  * line_num <-- line number in calling source file.
378  *
379  * returns:
380  * NULL pointer.
381  */
382 
383 void *
384 ple_mem_free(void *ptr,
385  const char *var_name,
386  const char *file_name,
387  int line_num);
388 
389 /* Return the function pointers associated with PLE's memory management.
390  *
391  * All arguments are optional.
392  *
393  * parameters:
394  * malloc_func <-- pointer to ple_mem_malloc function pointer (or NULL).
395  * realloc_func <-- pointer to ple_mem_realloc function pointer (or NULL).
396  * free_func <-- pointer to ple_mem_free function pointer (or NULL).
397  */
398 
399 void
400 ple_mem_functions_get(ple_mem_malloc_t **malloc_func,
401  ple_mem_realloc_t **realloc_func,
402  ple_mem_free_t **free_func);
403 
404 /* Associate functions to modifiy PLE's memory management.
405  *
406  * All arguments are optional, so the previously set functions pointers will
407  * not be modified if an argument value is NULL.
408  *
409  * parameters:
410  * malloc_func <-- ple_mem_malloc function pointer (or NULL).
411  * realloc_func <-- ple_mem_realloc function pointer (or NULL).
412  * free_func <-- ple_mem_free function pointer (or NULL).
413  */
414 
415 void
416 ple_mem_functions_set(ple_mem_malloc_t *malloc_func,
417  ple_mem_realloc_t *realloc_func,
418  ple_mem_free_t *free_func);
419 
420 /*
421  * Return Wall clock time
422  *
423  * returns:
424  * elapsed time from first call of a function of the ple_timer_...()
425  * series, or -1 if unable to compute.
426  */
427 
428 double
429 ple_timer_wtime(void);
430 
431 /*
432  * Return CPU time.
433  *
434  * Note that in the rare case that only the minimal C library clock()
435  * method is available (see ple_timer_cpu_time_method()), at least one of
436  * the ple_timer_...() functions (possibly this one) must be called
437  * upon program start for this function to be used. In addition,
438  * in this case, time may "loop" back to 0 every multiple of
439  * 2^size_t / CLOCKS_PER_SEC seconds.
440  *
441  * returns:
442  * current CPU time usage, or -1 if unable to compute.
443  */
444 
445 double
446 ple_timer_cpu_time(void);
447 
448 /*----------------------------------------------------------------------------*/
449 
450 #ifdef __cplusplus
451 }
452 #endif /* __cplusplus */
453 
454 #endif /* __PLE_DEFS_H__ */
void ple_error_handler_set(ple_error_handler_t *handler)
Associates an error handler with the ple_error() function.
Definition: ple_defs.c:457
void ple_error(const char *const file_name, const int line_num, const int sys_error_code, const char *const format,...)
Calls the error handler (set by ple_error_handler_set() or default).
Definition: ple_defs.c:423
double ple_timer_cpu_time(void)
Return CPU time.
Definition: ple_defs.c:673
ple_error_handler_t * ple_error_handler_get(void)
Returns the error handler associated with the ple_error() function.
Definition: ple_defs.c:445
int ple_printf(const char *const format,...)
Replacement for printf() with modifiable behavior.
Definition: ple_defs.c:367
void * ple_mem_realloc(void *ptr, size_t ni, size_t size, const char *var_name, const char *file_name, int line_num)
Reallocate memory for ni elements of size bytes.
Definition: ple_defs.c:507
ple_printf_t * ple_printf_function_get(void)
Returns function associated with the ple_printf() function.
Definition: ple_defs.c:389
void ple_mem_functions_set(ple_mem_malloc_t *malloc_func, ple_mem_realloc_t *realloc_func, ple_mem_free_t *free_func)
Associate functions to modifiy PLE&#39;s memory management.
Definition: ple_defs.c:583
void * ple_mem_malloc(size_t ni, size_t size, const char *var_name, const char *file_name, int line_num)
Allocate memory for ni elements of size bytes.
Definition: ple_defs.c:479
void ple_mem_functions_get(ple_mem_malloc_t **malloc_func, ple_mem_realloc_t **realloc_func, ple_mem_free_t **free_func)
Return the function pointers associated with PLE&#39;s memory management.
Definition: ple_defs.c:557
void ple_printf_function_set(ple_printf_t *const fct)
Associates a vprintf() type function with the ple_printf() function.
Definition: ple_defs.c:401
void * ple_mem_free(void *ptr, const char *var_name, const char *file_name, int line_num)
Free allocated memory.
Definition: ple_defs.c:535
double ple_timer_wtime(void)
Return Wall clock time.
Definition: ple_defs.c:605