Code_Saturne
CFD tool
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
bft_mem.h
Go to the documentation of this file.
1 #ifndef __BFT_MEM_H__
2 #define __BFT_MEM_H__
3 
4 /*============================================================================
5  * Base memory allocation wrappers with optional tracing
6  *============================================================================*/
7 
8 /*
9  This file is part of Code_Saturne, a general-purpose CFD tool.
10 
11  Copyright (C) 1998-2012 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  * Obtain definitions such as that of size_t through stddef.h (C99 standard)
32  * if available (preferred method), or through stdlib.h (which defines
33  * malloc() and family and so must define size_t some way) otherwise.
34  */
35 
36 #if defined(__STDC_VERSION__)
37 # if (__STDC_VERSION__ == 199901L)
38 # include <stddef.h>
39 # else
40 # include <stdlib.h>
41 # endif
42 #else
43 # include <stdlib.h>
44 #endif
45 
46 /* BFT headers */
47 
48 #include "bft_error.h"
49 
50 /*-----------------------------------------------------------------------------*/
51 
52 #ifdef __cplusplus
53 extern "C" {
54 #if 0
55 } /* Fake brace to force Emacs auto-indentation back to column 0 */
56 #endif
57 #endif /* __cplusplus */
58 
59 /*============================================================================
60  * Public types
61  *============================================================================*/
62 
63 /*============================================================================
64  * Public macros
65  *============================================================================*/
66 
67 /*
68  * Allocate memory for _ni items of type _type.
69  *
70  * This macro calls bft_mem_malloc(), automatically setting the
71  * allocated variable name and source file name and line arguments.
72  *
73  * parameters:
74  * _ptr --> pointer to allocated memory.
75  * _ni <-- number of items.
76  * _type <-- element type.
77  */
78 
79 #define BFT_MALLOC(_ptr, _ni, _type) \
80 _ptr = (_type *) bft_mem_malloc(_ni, sizeof(_type), \
81  #_ptr, __FILE__, __LINE__)
82 
83 /*
84  * Reallocate memory for _ni items of type _type.
85  *
86  * This macro calls bft_mem_realloc(), automatically setting the
87  * allocated variable name and source file name and line arguments.
88  *
89  * parameters:
90  * _ptr <-> pointer to allocated memory.
91  * _ni <-- number of items.
92  * _type <-- element type.
93  */
94 
95 #define BFT_REALLOC(_ptr, _ni, _type) \
96 _ptr = (_type *) bft_mem_realloc(_ptr, _ni, sizeof(_type), \
97  #_ptr, __FILE__, __LINE__)
98 
99 /*
100  * Free allocated memory.
101  *
102  * This macro calls bft_mem_free(), automatically setting the
103  * allocated variable name and source file name and line arguments.
104  *
105  * The freed pointer is set to NULL to avoid accidental reuse.
106  *
107  * parameters:
108  * _ptr <-> pointer to allocated memory.
109  */
110 
111 #ifdef __cplusplus /* avoid casting from void for C++ */
112 
113 #define BFT_FREE(_ptr) \
114 bft_mem_free(_ptr, #_ptr, __FILE__, __LINE__), _ptr = NULL
115 
116 #else
117 
118 #define BFT_FREE(_ptr) \
119 _ptr = bft_mem_free(_ptr, #_ptr, __FILE__, __LINE__)
120 
121 #endif /* __cplusplus */
122 
123 /*
124  * Allocate aligned memory for _ni items of type _type.
125  *
126  * This macro calls bft_mem_memalign(), automatically setting the
127  * allocated variable name and source file name and line arguments.
128  *
129  * parameters:
130  * _ptr --> pointer to allocated memory.
131  * _align <-- alignment.
132  * _ni <-- number of items.
133  * _type <-- element type.
134  */
135 
136 #define BFT_MEMALIGN(_ptr, _align, _ni, _type) \
137 _ptr = (_type *) bft_mem_memalign(_align, _ni, sizeof(_type), \
138  #_ptr, __FILE__, __LINE__)
139 
140 /*============================================================================
141  * Public function prototypes
142  *============================================================================*/
143 
144 /*
145  * Initialize memory handling.
146  *
147  * This function should be called before any other bft_mem_...()
148  * function. To activate memory allocation logging, a logfile
149  * name should be given as an argument. The resulting file will
150  * be a regular, local file. If this file cannot be opened for
151  * some reason, logging is silently de-activated.
152  *
153  * parameter:
154  * log_file_name <-- name of optional log_file (if NULL, no log).
155  */
156 
157 void
158 bft_mem_init(const char *log_file_name);
159 
160 /*
161  * End memory handling.
162  *
163  * This function should be called after all other bft_mem_...()
164  * functions. In case of memory allocation logging, it
165  * writes final information to the log file and closes is.
166  */
167 
168 void
169 bft_mem_end(void);
170 
171 /*
172  * Initialize memory handling.
173  *
174  * This function should be called before any other bft_mem_...()
175  * function. To activate memory allocation logging, a logfile
176  * name should be given as an argument. The resulting file will
177  * be a regular, local file. If this file cannot be opened for
178  * some reason, logging is silently de-activated.
179  *
180  * parameter:
181  * log_file_name <-- name of optional log_file (if NULL, no log).
182  */
183 
184 /*
185  * Indicates if bft_mem_...() functions are initialized.
186  *
187  * returns:
188  * 1 if bft_mem_init has been called, 0 otherwise.
189  */
190 
191 int
192 bft_mem_initialized(void);
193 
194 /*
195  * Allocate memory for ni items of size bytes.
196  *
197  * This function calls malloc(), but adds tracing capabilities, and
198  * automatically calls the bft_error() errorhandler if it fails to
199  * allocate the required memory.
200  *
201  * parameters:
202  * ni <-- number of items.
203  * size <-- element size.
204  * var_name <-- allocated variable name string.
205  * file_name <-- name of calling source file.
206  * line_num <-- line number in calling source file.
207  *
208  * returns:
209  * pointer to allocated memory.
210  */
211 
212 void *
213 bft_mem_malloc(size_t ni,
214  size_t size,
215  const char *var_name,
216  const char *file_name,
217  int line_num);
218 
219 /*
220  * Reallocate memory for ni items of size bytes.
221  *
222  * This function calls realloc(), but adds tracing capabilities, and
223  * automatically calls the bft_error() errorhandler if it fails to
224  * allocate the required memory.
225  *
226  * parameters:
227  * ptr <-> pointer to previous memory location
228  * (if NULL, bft_alloc() called).
229  * ni <-- number of items.
230  * size <-- element size.
231  * var_name <-- allocated variable name string.
232  * file_name <-- name of calling source file.
233  * line_num -> line number in calling source file
234  *
235  * returns:
236  * pointer to allocated memory.
237  */
238 
239 void *
240 bft_mem_realloc(void *ptr,
241  size_t ni,
242  size_t size,
243  const char *var_name,
244  const char *file_name,
245  int line_num);
246 
247 /*
248  * Free allocated memory.
249  *
250  * This function calls free(), but adds tracing capabilities, and
251  * automatically calls the bft_error() errorhandler if it fails to
252  * free the corresponding memory. In case of a NULL pointer argument,
253  * the function simply returns.
254  *
255  * parameters:
256  * ptr <-> pointer to previous memory location
257  * (if NULL, bft_alloc() called).
258  * var_name <-- allocated variable name string.
259  * file_name <-- name of calling source file.
260  * line_num <-- line number in calling source file.
261  *
262  * returns:
263  * NULL pointer.
264  */
265 
266 void *
267 bft_mem_free(void *ptr,
268  const char *var_name,
269  const char *file_name,
270  int line_num);
271 
272 /*
273  * Allocate aligned memory for ni elements of size bytes.
274  *
275  * This function calls posix_memalign() if available, but adds tracing
276  * capabilities, and automatically calls the bft_error() errorhandler if
277  * it fails to allocate the required memory.
278  *
279  * The associated function bft_mem_have_memalign() indicates if this
280  * type of allocation may be used on this system.
281  *
282  * parameters:
283  * alignment <-- alignent.
284  * ni <-- number of items.
285  * size <-- element size.
286  * var_name <-- allocated variable name string.
287  * file_name <-- name of calling source file.
288  * line_num <-- line number in calling source file.
289  *
290  * returns:
291  * pointer to allocated memory.
292  */
293 
294 void *
295 bft_mem_memalign(size_t alignment,
296  size_t ni,
297  size_t size,
298  const char *var_name,
299  const char *file_name,
300  int line_num);
301 
302 /*
303  * Indicate if a memory aligned allocation variant is available.
304  *
305  * If no such function is available, bft_mem_memalign() will always fail.
306  *
307  * returns:
308  * 1 if memory aligned allocation is possible, 0 otherwise.
309  */
310 
311 int
313 
314 /*
315  * Return current theoretical dynamic memory allocated.
316  *
317  * returns:
318  * current memory handled through bft_mem_...() (in kB).
319  */
320 
321 size_t
323 
324 /*
325  * Return maximum theoretical dynamic memory allocated.
326  *
327  * returns:
328  * maximum memory handled through bft_mem_...() (in kB).
329  */
330 
331 size_t
332 bft_mem_size_max(void);
333 
334 /* Returns the error handler associated with the bft_mem_...() functions.
335  *
336  * returns:
337  * pointer to the error handler function.
338  */
339 
342 
343 /*
344  * Associates an error handler with the bft_mem_...() functions.
345  *
346  * With the default error handler, an error message is output to stderr,
347  * (after bft_print_flush() is called), and the general error handler used
348  * by bft_error() is then called (which results in the termination of the
349  * current process or process group).
350  *
351  * parameter:
352  * handler <-- pointer to the error handler function.
353  */
354 
355 void
357 
358 /*----------------------------------------------------------------------------*/
359 
360 #ifdef __cplusplus
361 }
362 #endif /* __cplusplus */
363 
364 #endif /* __BFT_MEM_H__ */
int bft_mem_have_memalign(void)
Indicate if a memory aligned allocation variant is available.
Definition: bft_mem.c:1106
size_t bft_mem_size_current(void)
Return current theoretical dynamic memory allocated.
Definition: bft_mem.c:1051
void bft_mem_end(void)
End memory handling.
Definition: bft_mem.c:639
void * bft_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: bft_mem.c:728
void * bft_mem_memalign(size_t alignment, size_t ni, size_t size, const char *var_name, const char *file_name, int line_num)
Allocate aligned memory for ni elements of size bytes.
Definition: bft_mem.c:969
void bft_mem_error_handler_set(bft_error_handler_t *handler)
Associates an error handler with the bft_mem_...() functions.
Definition: bft_mem.c:1092
void bft_mem_init(const char *log_file_name)
Initialize memory handling.
Definition: bft_mem.c:570
void( bft_error_handler_t)(const char *const file_name, const int line_num, const int sys_error_code, const char *const format, va_list arg_ptr)
Function pointer to opaque error handler.
Definition: bft_error.h:49
void * bft_mem_free(void *ptr, const char *var_name, const char *file_name, int line_num)
Free allocated memory.
Definition: bft_mem.c:907
int bft_mem_initialized(void)
Indicates if bft_mem_...() functions are initialized.
Definition: bft_mem.c:706
void * bft_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: bft_mem.c:799
bft_error_handler_t * bft_mem_error_handler_get(void)
Returns the error handler associated with the bft_mem_...() functions.
Definition: bft_mem.c:1075
size_t bft_mem_size_max(void)
Return maximum theoretical dynamic memory allocated.
Definition: bft_mem.c:1063