PLE
Parallel Location and Exchange
ple_defs.h
Go to the documentation of this file.
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-2024 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 /*
49  * Allocate memory for _ni items of type _type.
50  *
51  * This macro calls ple_mem_malloc(), automatically setting the
52  * allocated variable name and source file name and line arguments.
53  *
54  * parameters:
55  * _ptr --> pointer to allocated memory.
56  * _ni <-- number of items.
57  * _type <-- element type.
58  */
59 
60 #define PLE_MALLOC(_ptr, _ni, _type) \
61 _ptr = (_type *) ple_mem_malloc(_ni, sizeof(_type), \
62  #_ptr, __FILE__, __LINE__)
63 
64 /*
65  * Reallocate memory for _ni items of type _type.
66  *
67  * This macro calls ple_mem_realloc(), automatically setting the
68  * allocated variable name and source file name and line arguments.
69  *
70  * parameters:
71  * _ptr <-> pointer to allocated memory.
72  * _ni <-- number of items.
73  * _type <-- element type.
74  */
75 
76 #define PLE_REALLOC(_ptr, _ni, _type) \
77 _ptr = (_type *) ple_mem_realloc(_ptr, _ni, sizeof(_type), \
78  #_ptr, __FILE__, __LINE__)
79 
80 /*
81  * Free allocated memory.
82  *
83  * This macro calls ple_mem_free(), automatically setting the
84  * allocated variable name and source file name and line arguments.
85  *
86  * The freed pointer is set to NULL to avoid accidental reuse.
87  *
88  * parameters:
89  * _ptr <-> pointer to allocated memory.
90  */
91 
92 #ifdef __cplusplus /* avoid casting from void for C++ */
93 
94 #define PLE_FREE(_ptr) \
95 ple_mem_free(_ptr, #_ptr, __FILE__, __LINE__), _ptr = NULL
96 
97 #else
98 
99 #define PLE_FREE(_ptr) \
100 _ptr = ple_mem_free(_ptr, #_ptr, __FILE__, __LINE__)
101 
102 #endif /* __cplusplus */
103 
104 /*============================================================================
105  * Type definitions
106  *============================================================================*/
107 
108 /*----------------------------------------------------------------------------
109  * General C types such as size_t which should be known
110  *----------------------------------------------------------------------------*/
111 
112 /* Obtain definitions such as that of size_t */
113 
114 #include <stddef.h>
115 
116 /*----------------------------------------------------------------------------
117  * Basic types used by PLE.
118  * They may be modified here to better map to a given library, with the
119  * following constraints:
120  * - ple_lnum_t must be signed
121  *----------------------------------------------------------------------------*/
122 
123 #if defined(PLE_HAVE_LONG_LNUM)
124  typedef long ple_lnum_t; /* Local integer index or number */
125 #else
126  typedef int ple_lnum_t; /* Local integer index or number */
127 #endif
128 
129 typedef double ple_coord_t; /* Real number (coordinate value) */
130 
131 /*----------------------------------------------------------------------------
132  * MPI datatypes.
133  *----------------------------------------------------------------------------*/
134 
135 #if defined(PLE_HAVE_MPI)
136 
137 #define PLE_MPI_TAG (int)('P'+'L'+'E') /* MPI tag for PLE operations */
138 
139 #if defined(PLE_HAVE_LONG_LNUM)
140 # define PLE_MPI_LNUM MPI_LONG /* MPI type for ple_lnum_t type */
141 #else
142 # define PLE_MPI_LNUM MPI_INT /* MPI type for ple_lnum_t type */
143 #endif
144 
145 #define PLE_MPI_COORD MPI_DOUBLE /* MPI type for ple_coord_t type */
146 
147 #endif
148 
149 /*----------------------------------------------------------------------------
150  * Macro used to silence "unused argument" warnings.
151  *
152  * This is useful when a function must match a given function pointer
153  * type, but does not use all possible arguments.
154  *----------------------------------------------------------------------------*/
155 
156 #define PLE_UNUSED(x) (void)(x)
157 
158 /*----------------------------------------------------------------------------
159  * Macros for compilation with a C++ compiler
160  *----------------------------------------------------------------------------*/
161 
162 #undef PLE_BEGIN_C_DECLS
163 #undef PLE_END_C_DECLS
164 
165 #if defined(__cplusplus)
166 # define PLE_BEGIN_C_DECLS extern "C" {
167 # define PLE_END_C_DECLS }
168 #else
169 # define PLE_BEGIN_C_DECLS
170 # define PLE_END_C_DECLS
171 #endif
172 
173 /*----------------------------------------------------------------------------
174  * Macros for scoping of examples
175  *----------------------------------------------------------------------------*/
176 
177 #undef PLE_BEGIN_EXAMPLE_SCOPE
178 #undef PLE_END_EXAMPLE_SCOPE
179 
180 #define PLE_BEGIN_EXAMPLE_SCOPE {
181 #define PLE_END_EXAMPLE_SCOPE }
182 
183 /*----------------------------------------------------------------------------
184  * Function pointer types
185  *----------------------------------------------------------------------------*/
186 
187 typedef int
188 (ple_printf_t) (const char *const format,
189  va_list arg_ptr);
190 
191 typedef void
192 (ple_error_handler_t) (const char *file_name,
193  const int line_num,
194  const int sys_error_code,
195  const char *format,
196  va_list arg_ptr);
197 
198 typedef void *
199 (ple_mem_malloc_t)(size_t ni,
200  size_t size,
201  const char *var_name,
202  const char *file_name,
203  int line_num);
204 
205 typedef void *
206 (ple_mem_realloc_t)(void *ptr,
207  size_t ni,
208  size_t size,
209  const char *var_name,
210  const char *file_name,
211  int line_num);
212 
213 typedef void *
214 (ple_mem_free_t)(void *ptr,
215  const char *var_name,
216  const char *file_name,
217  int line_num);
218 
219 /*============================================================================
220  * Public function prototypes
221  *============================================================================*/
222 
236 int
237 ple_printf(const char *const format,
238  ...);
239 
240 /* Returns function associated with the ple_printf() function.
241  *
242  * returns:
243  * pointer to the vprintf() or replacement function.
244  */
245 
246 ple_printf_t *
248 
249 /*
250  * Associates a vprintf() type function with the ple_printf() function.
251  *
252  * parameters:
253  * f <-- pointer to a vprintf() type function.
254  */
255 
256 void
258 
259 /*
260  * Calls the error handler (set by ple_error_handler_set() or default).
261  *
262  * With the default error handler, an error message is output to stderr,
263  * and the current process exits with an EXIT_FAILURE code.
264  *
265  * parameters:
266  * file_name <-- name of source file from which error handler called.
267  * line_num <-- line of source file from which error handler called.
268  * sys_error_code <-- error code if error in system or libc call,
269  * 0 otherwise.
270  * format <-- format string, as printf() and family.
271  * ... <-- variable arguments based on format string.
272  */
273 
274 void
275 ple_error(const char *file_name,
276  const int line_num,
277  const int sys_error_code,
278  const char *format,
279  ...);
280 
281 /*
282  * Returns the error handler associated with the ple_error() function.
283  *
284  * returns:
285  * pointer to the error handler function.
286  */
287 
290 
291 /*
292  * Associates an error handler with the ple_error() function.
293  *
294  * parameters:
295  * handler <-- pointer to the error handler function.
296  */
297 
298 void
300 
301 /*
302  * Allocate memory for ni items of size bytes.
303  *
304  * This function calls malloc(), but adds tracing capabilities, and
305  * automatically calls the ple_error() errorhandler if it fails to
306  * allocate the required memory.
307  *
308  * parameters:
309  * ni <-- number of items.
310  * size <-- element size.
311  * var_name <-- allocated variable name string.
312  * file_name <-- name of calling source file.
313  * line_num <-- line number in calling source file.
314  *
315  * returns:
316  * pointer to allocated memory.
317  */
318 
319 void *
320 ple_mem_malloc(size_t ni,
321  size_t size,
322  const char *var_name,
323  const char *file_name,
324  int line_num);
325 
326 /*
327  * Reallocate memory for ni items of size bytes.
328  *
329  * This function calls realloc(), but adds tracing capabilities, and
330  * automatically calls the ple_error() errorhandler if it fails to
331  * allocate the required memory.
332  *
333  * parameters:
334  * ptr <-> pointer to previous memory location
335  * (if NULL, ple_alloc() called).
336  * ni <-- number of items.
337  * size <-- element size.
338  * var_name <-- allocated variable name string.
339  * file_name <-- name of calling source file.
340  * line_num -> line number in calling source file
341  *
342  * returns:
343  * pointer to allocated memory.
344  */
345 
346 void *
347 ple_mem_realloc(void *ptr,
348  size_t ni,
349  size_t size,
350  const char *var_name,
351  const char *file_name,
352  int line_num);
353 
354 /*
355  * Free allocated memory.
356  *
357  * This function calls free(), but adds tracing capabilities, and
358  * automatically calls the ple_error() errorhandler if it fails to
359  * free the corresponding memory. In case of a NULL pointer argument,
360  * the function simply returns.
361  *
362  * parameters:
363  * ptr <-> pointer to previous memory location
364  * (if NULL, ple_alloc() called).
365  * var_name <-- allocated variable name string.
366  * file_name <-- name of calling source file.
367  * line_num <-- line number in calling source file.
368  *
369  * returns:
370  * NULL pointer.
371  */
372 
373 void *
374 ple_mem_free(void *ptr,
375  const char *var_name,
376  const char *file_name,
377  int line_num);
378 
379 /* Return the function pointers associated with PLE's memory management.
380  *
381  * All arguments are optional.
382  *
383  * parameters:
384  * malloc_func <-- pointer to ple_mem_malloc function pointer (or NULL).
385  * realloc_func <-- pointer to ple_mem_realloc function pointer (or NULL).
386  * free_func <-- pointer to ple_mem_free function pointer (or NULL).
387  */
388 
389 void
391  ple_mem_realloc_t **realloc_func,
392  ple_mem_free_t **free_func);
393 
394 /* Associate functions to modifiy PLE's memory management.
395  *
396  * All arguments are optional, so the previously set functions pointers will
397  * not be modified if an argument value is NULL.
398  *
399  * parameters:
400  * malloc_func <-- ple_mem_malloc function pointer (or NULL).
401  * realloc_func <-- ple_mem_realloc function pointer (or NULL).
402  * free_func <-- ple_mem_free function pointer (or NULL).
403  */
404 
405 void
407  ple_mem_realloc_t *realloc_func,
408  ple_mem_free_t *free_func);
409 
410 /*
411  * Return Wall clock time
412  *
413  * returns:
414  * elapsed time from first call of a function of the ple_timer_...()
415  * series, or -1 if unable to compute.
416  */
417 
418 double
419 ple_timer_wtime(void);
420 
421 /*
422  * Return CPU time.
423  *
424  * Note that in the rare case that only the minimal C library clock()
425  * method is available (see ple_timer_cpu_time_method()), at least one of
426  * the ple_timer_...() functions (possibly this one) must be called
427  * upon program start for this function to be used. In addition,
428  * in this case, time may "loop" back to 0 every multiple of
429  * 2^size_t / CLOCKS_PER_SEC seconds.
430  *
431  * returns:
432  * current CPU time usage, or -1 if unable to compute.
433  */
434 
435 double
436 ple_timer_cpu_time(void);
437 
438 /*----------------------------------------------------------------------------*/
439 
440 #ifdef __cplusplus
441 }
442 #endif /* __cplusplus */
443 
444 #endif /* __PLE_DEFS_H__ */
void() ple_error_handler_t(const char *file_name, const int line_num, const int sys_error_code, const char *format, va_list arg_ptr)
Definition: ple_defs.h:192
void *() ple_mem_realloc_t(void *ptr, size_t ni, size_t size, const char *var_name, const char *file_name, int line_num)
Definition: ple_defs.h:206
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's memory management.
Definition: ple_defs.c:561
void *() ple_mem_malloc_t(size_t ni, size_t size, const char *var_name, const char *file_name, int line_num)
Definition: ple_defs.h:199
int ple_printf(const char *const format,...)
Replacement for printf() with modifiable behavior.
Definition: ple_defs.c:371
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's memory management.
Definition: ple_defs.c:587
double ple_timer_wtime(void)
Return Wall clock time.
Definition: ple_defs.c:609
int ple_lnum_t
Definition: ple_defs.h:126
void ple_printf_function_set(ple_printf_t *f)
Associates a vprintf() type function with the ple_printf() function.
Definition: ple_defs.c:405
void ple_error_handler_set(ple_error_handler_t *handler)
Associates an error handler with the ple_error() function.
Definition: ple_defs.c:461
void * ple_mem_free(void *ptr, const char *var_name, const char *file_name, int line_num)
Free allocated memory.
Definition: ple_defs.c:539
double ple_coord_t
Definition: ple_defs.h:129
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:483
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:511
void *() ple_mem_free_t(void *ptr, const char *var_name, const char *file_name, int line_num)
Definition: ple_defs.h:214
void ple_error(const char *file_name, const int line_num, const int sys_error_code, const char *format,...)
Calls the error handler (set by ple_error_handler_set() or default).
Definition: ple_defs.c:427
ple_error_handler_t * ple_error_handler_get(void)
Returns the error handler associated with the ple_error() function.
Definition: ple_defs.c:449
ple_printf_t * ple_printf_function_get(void)
Returns function associated with the ple_printf() function.
Definition: ple_defs.c:393
double ple_timer_cpu_time(void)
Return CPU time.
Definition: ple_defs.c:677
int() ple_printf_t(const char *const format, va_list arg_ptr)
Definition: ple_defs.h:188