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
38extern "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) \
101ple_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/* Obtain definitions such as that of size_t */
119
120#include <stddef.h>
121
122/*----------------------------------------------------------------------------
123 * Basic types used by PLE.
124 * They may be modified here to better map to a given library, with the
125 * following constraints:
126 * - ple_lnum_t must be signed
127 *----------------------------------------------------------------------------*/
128
129#if defined(PLE_HAVE_LONG_LNUM)
130 typedef long ple_lnum_t; /* Local integer index or number */
131#else
132 typedef int ple_lnum_t; /* Local integer index or number */
133#endif
134
135typedef double ple_coord_t; /* Real number (coordinate value) */
136
137/*----------------------------------------------------------------------------
138 * MPI datatypes.
139 *----------------------------------------------------------------------------*/
140
141#if defined(PLE_HAVE_MPI)
142
143#define PLE_MPI_TAG (int)('P'+'L'+'E') /* MPI tag for PLE operations */
144
145#if defined(PLE_HAVE_LONG_LNUM)
146# define PLE_MPI_LNUM MPI_LONG /* MPI type for ple_lnum_t type */
147#else
148# define PLE_MPI_LNUM MPI_INT /* MPI type for ple_lnum_t type */
149#endif
150
151#define PLE_MPI_COORD MPI_DOUBLE /* MPI type for ple_coord_t type */
152
153#endif
154
155/*----------------------------------------------------------------------------
156 * Macro used to silence "unused argument" warnings.
157 *
158 * This is useful when a function must match a given function pointer
159 * type, but does not use all possible arguments.
160 *----------------------------------------------------------------------------*/
161
162#define PLE_UNUSED(x) (void)(x)
163
164/*----------------------------------------------------------------------------
165 * Macros for compilation with a C++ compiler
166 *----------------------------------------------------------------------------*/
167
168#undef PLE_BEGIN_C_DECLS
169#undef PLE_END_C_DECLS
170
171#if defined(__cplusplus)
172# define PLE_BEGIN_C_DECLS extern "C" {
173# define PLE_END_C_DECLS }
174#else
175# define PLE_BEGIN_C_DECLS
176# define PLE_END_C_DECLS
177#endif
178
179/*----------------------------------------------------------------------------
180 * Macros for scoping of examples
181 *----------------------------------------------------------------------------*/
182
183#undef PLE_BEGIN_EXAMPLE_SCOPE
184#undef PLE_END_EXAMPLE_SCOPE
185
186#define PLE_BEGIN_EXAMPLE_SCOPE {
187#define PLE_END_EXAMPLE_SCOPE }
188
189/*----------------------------------------------------------------------------
190 * Function pointer types
191 *----------------------------------------------------------------------------*/
192
193typedef int
194(ple_printf_t) (const char *const format,
195 va_list arg_ptr);
196
197typedef void
198(ple_error_handler_t) (const char *file_name,
199 const int line_num,
200 const int sys_error_code,
201 const char *format,
202 va_list arg_ptr);
203
204typedef void *
205(ple_mem_malloc_t)(size_t ni,
206 size_t size,
207 const char *var_name,
208 const char *file_name,
209 int line_num);
210
211typedef void *
212(ple_mem_realloc_t)(void *ptr,
213 size_t ni,
214 size_t size,
215 const char *var_name,
216 const char *file_name,
217 int line_num);
218
219typedef void *
220(ple_mem_free_t)(void *ptr,
221 const char *var_name,
222 const char *file_name,
223 int line_num);
224
225/*============================================================================
226 * Public function prototypes
227 *============================================================================*/
228
242int
243ple_printf(const char *const format,
244 ...);
245
246/* Returns function associated with the ple_printf() function.
247 *
248 * returns:
249 * pointer to the vprintf() or replacement function.
250 */
251
254
255/*
256 * Associates a vprintf() type function with the ple_printf() function.
257 *
258 * parameters:
259 * f <-- pointer to a vprintf() type function.
260 */
261
262void
264
265/*
266 * Calls the error handler (set by ple_error_handler_set() or default).
267 *
268 * With the default error handler, an error message is output to stderr,
269 * and the current process exits with an EXIT_FAILURE code.
270 *
271 * parameters:
272 * file_name <-- name of source file from which error handler called.
273 * line_num <-- line of source file from which error handler called.
274 * sys_error_code <-- error code if error in system or libc call,
275 * 0 otherwise.
276 * format <-- format string, as printf() and family.
277 * ... <-- variable arguments based on format string.
278 */
279
280void
281ple_error(const char *file_name,
282 const int line_num,
283 const int sys_error_code,
284 const char *format,
285 ...);
286
287/*
288 * Returns the error handler associated with the ple_error() function.
289 *
290 * returns:
291 * pointer to the error handler function.
292 */
293
296
297/*
298 * Associates an error handler with the ple_error() function.
299 *
300 * parameters:
301 * handler <-- pointer to the error handler function.
302 */
303
304void
306
307/*
308 * Allocate memory for ni items of size bytes.
309 *
310 * This function calls malloc(), but adds tracing capabilities, and
311 * automatically calls the ple_error() errorhandler if it fails to
312 * allocate the required memory.
313 *
314 * parameters:
315 * ni <-- number of items.
316 * size <-- element size.
317 * var_name <-- allocated variable name string.
318 * file_name <-- name of calling source file.
319 * line_num <-- line number in calling source file.
320 *
321 * returns:
322 * pointer to allocated memory.
323 */
324
325void *
326ple_mem_malloc(size_t ni,
327 size_t size,
328 const char *var_name,
329 const char *file_name,
330 int line_num);
331
332/*
333 * Reallocate memory for ni items of size bytes.
334 *
335 * This function calls realloc(), but adds tracing capabilities, and
336 * automatically calls the ple_error() errorhandler if it fails to
337 * allocate the required memory.
338 *
339 * parameters:
340 * ptr <-> pointer to previous memory location
341 * (if NULL, ple_alloc() called).
342 * ni <-- number of items.
343 * size <-- element size.
344 * var_name <-- allocated variable name string.
345 * file_name <-- name of calling source file.
346 * line_num -> line number in calling source file
347 *
348 * returns:
349 * pointer to allocated memory.
350 */
351
352void *
353ple_mem_realloc(void *ptr,
354 size_t ni,
355 size_t size,
356 const char *var_name,
357 const char *file_name,
358 int line_num);
359
360/*
361 * Free allocated memory.
362 *
363 * This function calls free(), but adds tracing capabilities, and
364 * automatically calls the ple_error() errorhandler if it fails to
365 * free the corresponding memory. In case of a NULL pointer argument,
366 * the function simply returns.
367 *
368 * parameters:
369 * ptr <-> pointer to previous memory location
370 * (if NULL, ple_alloc() called).
371 * var_name <-- allocated variable name string.
372 * file_name <-- name of calling source file.
373 * line_num <-- line number in calling source file.
374 *
375 * returns:
376 * NULL pointer.
377 */
378
379void *
380ple_mem_free(void *ptr,
381 const char *var_name,
382 const char *file_name,
383 int line_num);
384
385/* Return the function pointers associated with PLE's memory management.
386 *
387 * All arguments are optional.
388 *
389 * parameters:
390 * malloc_func <-- pointer to ple_mem_malloc function pointer (or NULL).
391 * realloc_func <-- pointer to ple_mem_realloc function pointer (or NULL).
392 * free_func <-- pointer to ple_mem_free function pointer (or NULL).
393 */
394
395void
397 ple_mem_realloc_t **realloc_func,
398 ple_mem_free_t **free_func);
399
400/* Associate functions to modifiy PLE's memory management.
401 *
402 * All arguments are optional, so the previously set functions pointers will
403 * not be modified if an argument value is NULL.
404 *
405 * parameters:
406 * malloc_func <-- ple_mem_malloc function pointer (or NULL).
407 * realloc_func <-- ple_mem_realloc function pointer (or NULL).
408 * free_func <-- ple_mem_free function pointer (or NULL).
409 */
410
411void
413 ple_mem_realloc_t *realloc_func,
414 ple_mem_free_t *free_func);
415
416/*
417 * Return Wall clock time
418 *
419 * returns:
420 * elapsed time from first call of a function of the ple_timer_...()
421 * series, or -1 if unable to compute.
422 */
423
424double
425ple_timer_wtime(void);
426
427/*
428 * Return CPU time.
429 *
430 * Note that in the rare case that only the minimal C library clock()
431 * method is available (see ple_timer_cpu_time_method()), at least one of
432 * the ple_timer_...() functions (possibly this one) must be called
433 * upon program start for this function to be used. In addition,
434 * in this case, time may "loop" back to 0 every multiple of
435 * 2^size_t / CLOCKS_PER_SEC seconds.
436 *
437 * returns:
438 * current CPU time usage, or -1 if unable to compute.
439 */
440
441double
443
444/*----------------------------------------------------------------------------*/
445
446#ifdef __cplusplus
447}
448#endif /* __cplusplus */
449
450#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:198
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:205
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_free_t(void *ptr, const char *var_name, const char *file_name, int line_num)
Definition: ple_defs.h:220
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
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_timer_wtime(void)
Return Wall clock time.
Definition: ple_defs.c:609
int ple_lnum_t
Definition: ple_defs.h:132
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_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
double ple_coord_t
Definition: ple_defs.h:135
ple_printf_t * ple_printf_function_get(void)
Returns function associated with the ple_printf() function.
Definition: ple_defs.c:393
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
ple_error_handler_t * ple_error_handler_get(void)
Returns the error handler associated with the ple_error() function.
Definition: ple_defs.c:449
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
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:194
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:212