PLE
Parallel Location and Exchange
 All Files Functions Pages
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-2015 EDF
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  * Variable value type.
138  *----------------------------------------------------------------------------*/
139 
140 typedef enum {
141 
142  PLE_DATATYPE_NULL, /* empty datatype */
143  PLE_CHAR, /* character values */
144  PLE_FLOAT, /* 4-byte floating point values */
145  PLE_DOUBLE, /* 8-byte floating point values */
146  PLE_INT32, /* 4-byte signed integer values */
147  PLE_INT64, /* 8-byte signed integer values */
148  PLE_UINT32, /* 4-byte unsigned integer values */
149  PLE_UINT64 /* 8-byte unsigned integer values */
150 
151 } ple_datatype_t;
152 
153 /*----------------------------------------------------------------------------
154  * Basic types used by PLE.
155  * They may be modified here to better map to a given library, with the
156  * following constraints:
157  * - ple_lnum_t must be signed
158  *----------------------------------------------------------------------------*/
159 
160 /* Other types */
161 
162 typedef int ple_lnum_t; /* Local integer index or number */
163 typedef double ple_coord_t; /* Real number (coordinate value) */
164 
165 /* Mappings to PLE datatypes */
166 /*---------------------------*/
167 
168 #define PLE_COORD PLE_DOUBLE
169 
170 #if (PLE_SIZEOF_INT == 4)
171  #define PLE_LNUM PLE_INT32
172 #elif (PLE_SIZEOF_INT == 8)
173  #define PLE_LNUM PLE_INT64
174 #else
175  #error
176 #endif
177 
178 /*----------------------------------------------------------------------------
179  * MPI datatypes.
180  *----------------------------------------------------------------------------*/
181 
182 #if defined(PLE_HAVE_MPI)
183 
184 #define PLE_MPI_TAG (int)('P'+'L'+'E') /* MPI tag for PLE operations */
185 
186 #define PLE_MPI_LNUM MPI_INT /* MPI type for ple_lnum_t type */
187 #define PLE_MPI_COORD MPI_DOUBLE /* MPI type for ple_coord_t type */
188 
189 #endif
190 
191 /*----------------------------------------------------------------------------
192  * Macros for compilation with a C++ compiler
193  *----------------------------------------------------------------------------*/
194 
195 #undef PLE_BEGIN_C_DECLS
196 #undef PLE_END_C_DECLS
197 
198 #if defined(__cplusplus)
199 # define PLE_BEGIN_C_DECLS extern "C" {
200 # define PLE_END_C_DECLS }
201 #else
202 # define PLE_BEGIN_C_DECLS
203 # define PLE_END_C_DECLS
204 #endif
205 
206 /*----------------------------------------------------------------------------
207  * Macros for scoping of examples
208  *----------------------------------------------------------------------------*/
209 
210 #undef PLE_BEGIN_EXAMPLE_SCOPE
211 #undef PLE_END_EXAMPLE_SCOPE
212 
213 #define PLE_BEGIN_EXAMPLE_SCOPE {
214 #define PLE_END_EXAMPLE_SCOPE }
215 
216 /*----------------------------------------------------------------------------
217  * Function pointer types
218  *----------------------------------------------------------------------------*/
219 
220 typedef int
221 (ple_printf_t) (const char *const format,
222  va_list arg_ptr);
223 
224 typedef void
225 (ple_error_handler_t) (const char *file_name,
226  const int line_num,
227  const int sys_error_code,
228  const char *format,
229  va_list arg_ptr);
230 
231 typedef void *
232 (ple_mem_malloc_t)(size_t ni,
233  size_t size,
234  const char *var_name,
235  const char *file_name,
236  int line_num);
237 
238 typedef void *
239 (ple_mem_realloc_t)(void *ptr,
240  size_t ni,
241  size_t size,
242  const char *var_name,
243  const char *file_name,
244  int line_num);
245 
246 typedef void *
247 (ple_mem_free_t)(void *ptr,
248  const char *var_name,
249  const char *file_name,
250  int line_num);
251 
252 /*=============================================================================
253  * Static global variables
254  *============================================================================*/
255 
256 /* Sizes and names associated with datatypes */
257 
258 extern const size_t ple_datatype_size[];
259 extern const char *ple_datatype_name[];
260 
261 
262 /*============================================================================
263  * Public function prototypes
264  *============================================================================*/
265 
279 int
280 ple_printf(const char *const format,
281  ...);
282 
283 /* Returns function associated with the ple_printf() function.
284  *
285  * returns:
286  * pointer to the vprintf() or replacement function.
287  */
288 
289 ple_printf_t *
291 
292 /*
293  * Associates a vprintf() type function with the ple_printf() function.
294  *
295  * parameters:
296  * f <-- pointer to a vprintf() type function.
297  */
298 
299 void
300 ple_printf_function_set(ple_printf_t *f);
301 
302 /*
303  * Calls the error handler (set by ple_error_handler_set() or default).
304  *
305  * With the default error handler, an error message is output to stderr,
306  * and the current process exits with an EXIT_FAILURE code.
307  *
308  * parameters:
309  * file_name <-- name of source file from which error handler called.
310  * line_num <-- line of source file from which error handler called.
311  * sys_error_code <-- error code if error in system or libc call,
312  * 0 otherwise.
313  * format <-- format string, as printf() and family.
314  * ... <-- variable arguments based on format string.
315  */
316 
317 void
318 ple_error(const char *file_name,
319  const int line_num,
320  const int sys_error_code,
321  const char *format,
322  ...);
323 
324 /*
325  * Returns the error handler associated with the ple_error() function.
326  *
327  * returns:
328  * pointer to the error handler function.
329  */
330 
331 ple_error_handler_t *
333 
334 /*
335  * Associates an error handler with the ple_error() function.
336  *
337  * parameters:
338  * handler <-- pointer to the error handler function.
339  */
340 
341 void
342 ple_error_handler_set(ple_error_handler_t *handler);
343 
344 /*
345  * Allocate memory for ni items of size bytes.
346  *
347  * This function calls malloc(), but adds tracing capabilities, and
348  * automatically calls the ple_error() errorhandler if it fails to
349  * allocate the required memory.
350  *
351  * parameters:
352  * ni <-- number of items.
353  * size <-- element size.
354  * var_name <-- allocated variable name string.
355  * file_name <-- name of calling source file.
356  * line_num <-- line number in calling source file.
357  *
358  * returns:
359  * pointer to allocated memory.
360  */
361 
362 void *
363 ple_mem_malloc(size_t ni,
364  size_t size,
365  const char *var_name,
366  const char *file_name,
367  int line_num);
368 
369 /*
370  * Reallocate memory for ni items of size bytes.
371  *
372  * This function calls realloc(), but adds tracing capabilities, and
373  * automatically calls the ple_error() errorhandler if it fails to
374  * allocate the required memory.
375  *
376  * parameters:
377  * ptr <-> pointer to previous memory location
378  * (if NULL, ple_alloc() called).
379  * ni <-- number of items.
380  * size <-- element size.
381  * var_name <-- allocated variable name string.
382  * file_name <-- name of calling source file.
383  * line_num -> line number in calling source file
384  *
385  * returns:
386  * pointer to allocated memory.
387  */
388 
389 void *
390 ple_mem_realloc(void *ptr,
391  size_t ni,
392  size_t size,
393  const char *var_name,
394  const char *file_name,
395  int line_num);
396 
397 /*
398  * Free allocated memory.
399  *
400  * This function calls free(), but adds tracing capabilities, and
401  * automatically calls the ple_error() errorhandler if it fails to
402  * free the corresponding memory. In case of a NULL pointer argument,
403  * the function simply returns.
404  *
405  * parameters:
406  * ptr <-> pointer to previous memory location
407  * (if NULL, ple_alloc() called).
408  * var_name <-- allocated variable name string.
409  * file_name <-- name of calling source file.
410  * line_num <-- line number in calling source file.
411  *
412  * returns:
413  * NULL pointer.
414  */
415 
416 void *
417 ple_mem_free(void *ptr,
418  const char *var_name,
419  const char *file_name,
420  int line_num);
421 
422 /* Return the function pointers associated with PLE's memory management.
423  *
424  * All arguments are optional.
425  *
426  * parameters:
427  * malloc_func <-- pointer to ple_mem_malloc function pointer (or NULL).
428  * realloc_func <-- pointer to ple_mem_realloc function pointer (or NULL).
429  * free_func <-- pointer to ple_mem_free function pointer (or NULL).
430  */
431 
432 void
433 ple_mem_functions_get(ple_mem_malloc_t **malloc_func,
434  ple_mem_realloc_t **realloc_func,
435  ple_mem_free_t **free_func);
436 
437 /* Associate functions to modifiy PLE's memory management.
438  *
439  * All arguments are optional, so the previously set functions pointers will
440  * not be modified if an argument value is NULL.
441  *
442  * parameters:
443  * malloc_func <-- ple_mem_malloc function pointer (or NULL).
444  * realloc_func <-- ple_mem_realloc function pointer (or NULL).
445  * free_func <-- ple_mem_free function pointer (or NULL).
446  */
447 
448 void
449 ple_mem_functions_set(ple_mem_malloc_t *malloc_func,
450  ple_mem_realloc_t *realloc_func,
451  ple_mem_free_t *free_func);
452 
453 /*
454  * Return Wall clock time
455  *
456  * returns:
457  * elapsed time from first call of a function of the ple_timer_...()
458  * series, or -1 if unable to compute.
459  */
460 
461 double
462 ple_timer_wtime(void);
463 
464 /*
465  * Return CPU time.
466  *
467  * Note that in the rare case that only the minimal C library clock()
468  * method is available (see ple_timer_cpu_time_method()), at least one of
469  * the ple_timer_...() functions (possibly this one) must be called
470  * upon program start for this function to be used. In addition,
471  * in this case, time may "loop" back to 0 every multiple of
472  * 2^size_t / CLOCKS_PER_SEC seconds.
473  *
474  * returns:
475  * current CPU time usage, or -1 if unable to compute.
476  */
477 
478 double
479 ple_timer_cpu_time(void);
480 
481 /*----------------------------------------------------------------------------*/
482 
483 #ifdef __cplusplus
484 }
485 #endif /* __cplusplus */
486 
487 #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:453
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:419
double ple_timer_cpu_time(void)
Return CPU time.
Definition: ple_defs.c:669
ple_error_handler_t * ple_error_handler_get(void)
Returns the error handler associated with the ple_error() function.
Definition: ple_defs.c:441
int ple_printf(const char *const format,...)
Replacement for printf() with modifiable behavior.
Definition: ple_defs.c:363
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:503
ple_printf_t * ple_printf_function_get(void)
Returns function associated with the ple_printf() function.
Definition: ple_defs.c:385
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:579
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:475
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:553
void ple_printf_function_set(ple_printf_t *const fct)
Associates a vprintf() type function with the ple_printf() function.
Definition: ple_defs.c:397
void * ple_mem_free(void *ptr, const char *var_name, const char *file_name, int line_num)
Free allocated memory.
Definition: ple_defs.c:531
double ple_timer_wtime(void)
Return Wall clock time.
Definition: ple_defs.c:601