8.0
general documentation
Loading...
Searching...
No Matches
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-2023 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#include "cs_defs.h"
31
32/*----------------------------------------------------------------------------*/
33
34/* BFT headers */
35
36#include "bft_error.h"
37
38/*-----------------------------------------------------------------------------*/
39
41
42/*============================================================================
43 * Public types
44 *============================================================================*/
45
46/*============================================================================
47 * Public macros
48 *============================================================================*/
49
50/*
51 * Allocate memory for _ni items of type _type.
52 *
53 * This macro calls bft_mem_malloc(), automatically setting the
54 * allocated variable name and source file name and line arguments.
55 *
56 * parameters:
57 * _ptr --> pointer to allocated memory.
58 * _ni <-- number of items.
59 * _type <-- element type.
60 */
61
62#define BFT_MALLOC(_ptr, _ni, _type) \
63_ptr = (_type *) bft_mem_malloc(_ni, sizeof(_type), \
64 #_ptr, __FILE__, __LINE__)
65
66/*
67 * Reallocate memory for _ni items of type _type.
68 *
69 * This macro calls bft_mem_realloc(), automatically setting the
70 * allocated variable name and source file name and line arguments.
71 *
72 * parameters:
73 * _ptr <-> pointer to allocated memory.
74 * _ni <-- number of items.
75 * _type <-- element type.
76 */
77
78#define BFT_REALLOC(_ptr, _ni, _type) \
79_ptr = (_type *) bft_mem_realloc(_ptr, _ni, sizeof(_type), \
80 #_ptr, __FILE__, __LINE__)
81
82/*
83 * Free allocated memory.
84 *
85 * This macro calls bft_mem_free(), automatically setting the
86 * allocated variable name and source file name and line arguments.
87 *
88 * The freed pointer is set to NULL to avoid accidental reuse.
89 *
90 * parameters:
91 * _ptr <-> pointer to allocated memory.
92 */
93
94#ifdef __cplusplus /* avoid casting from void for C++ */
95
96#define BFT_FREE(_ptr) \
97bft_mem_free(_ptr, #_ptr, __FILE__, __LINE__), _ptr = NULL
98
99#else
100
101#define BFT_FREE(_ptr) \
102_ptr = bft_mem_free(_ptr, #_ptr, __FILE__, __LINE__)
103
104#endif /* __cplusplus */
105
106/*
107 * Allocate aligned memory for _ni items of type _type.
108 *
109 * This macro calls bft_mem_memalign(), automatically setting the
110 * allocated variable name and source file name and line arguments.
111 *
112 * parameters:
113 * _ptr --> pointer to allocated memory.
114 * _align <-- alignment.
115 * _ni <-- number of items.
116 * _type <-- element type.
117 */
118
119#define BFT_MEMALIGN(_ptr, _align, _ni, _type) \
120_ptr = (_type *) bft_mem_memalign(_align, _ni, sizeof(_type), \
121 #_ptr, __FILE__, __LINE__)
122
123/*----------------------------------------------------------------------------
124 * Function pointer types
125 *----------------------------------------------------------------------------*/
126
127typedef size_t
128(bft_mem_get_size_t)(void *ptr);
129
130typedef void *
131(bft_mem_realloc_t)(void *ptr,
132 size_t ni,
133 size_t size,
134 const char *var_name,
135 const char *file_name,
136 int line_num);
137
138typedef void
139(bft_mem_free_t)(void *ptr,
140 const char *var_name,
141 const char *file_name,
142 int line_num);
143
144/*============================================================================
145 * Public function prototypes
146 *============================================================================*/
147
148/*
149 * Initialize memory handling.
150 *
151 * This function should be called before any other bft_mem_...()
152 * function. To activate memory allocation logging, a logfile
153 * name should be given as an argument. The resulting file will
154 * be a regular, local file. If this file cannot be opened for
155 * some reason, logging is silently de-activated.
156 *
157 * parameter:
158 * log_file_name <-- name of optional log_file (if NULL, no log).
159 */
160
161void
162bft_mem_init(const char *log_file_name);
163
164/*
165 * End memory handling.
166 *
167 * This function should be called after all other bft_mem_...()
168 * functions. In case of memory allocation logging, it
169 * writes final information to the log file and closes is.
170 */
171
172void
173bft_mem_end(void);
174
175/*
176 * Initialize memory handling.
177 *
178 * This function should be called before any other bft_mem_...()
179 * function. To activate memory allocation logging, a logfile
180 * name should be given as an argument. The resulting file will
181 * be a regular, local file. If this file cannot be opened for
182 * some reason, logging is silently de-activated.
183 *
184 * parameter:
185 * log_file_name <-- name of optional log_file (if NULL, no log).
186 */
187
188/*
189 * Indicates if bft_mem_...() functions are initialized.
190 *
191 * returns:
192 * 1 if bft_mem_init has been called, 0 otherwise.
193 */
194
195int
197
198/*
199 * Allocate memory for ni items of size bytes.
200 *
201 * This function calls malloc(), but adds tracing capabilities, and
202 * automatically calls the bft_error() errorhandler if it fails to
203 * allocate the required memory.
204 *
205 * parameters:
206 * ni <-- number of items.
207 * size <-- element size.
208 * var_name <-- allocated variable name string.
209 * file_name <-- name of calling source file.
210 * line_num <-- line number in calling source file.
211 *
212 * returns:
213 * pointer to allocated memory.
214 */
215
216void *
217bft_mem_malloc(size_t ni,
218 size_t size,
219 const char *var_name,
220 const char *file_name,
221 int line_num);
222
223/*
224 * Reallocate memory for ni items of size bytes.
225 *
226 * This function calls realloc(), but adds tracing capabilities, and
227 * automatically calls the bft_error() errorhandler if it fails to
228 * allocate the required memory.
229 *
230 * parameters:
231 * ptr <-> pointer to previous memory location
232 * (if NULL, bft_alloc() called).
233 * ni <-- number of items.
234 * size <-- element size.
235 * var_name <-- allocated variable name string.
236 * file_name <-- name of calling source file.
237 * line_num -> line number in calling source file
238 *
239 * returns:
240 * pointer to allocated memory.
241 */
242
243void *
244bft_mem_realloc(void *ptr,
245 size_t ni,
246 size_t size,
247 const char *var_name,
248 const char *file_name,
249 int line_num);
250
251/*
252 * Free allocated memory.
253 *
254 * This function calls free(), but adds tracing capabilities, and
255 * automatically calls the bft_error() errorhandler if it fails to
256 * free the corresponding memory. In case of a NULL pointer argument,
257 * the function simply returns.
258 *
259 * parameters:
260 * ptr <-> pointer to previous memory location
261 * (if NULL, bft_alloc() called).
262 * var_name <-- allocated variable name string.
263 * file_name <-- name of calling source file.
264 * line_num <-- line number in calling source file.
265 *
266 * returns:
267 * NULL pointer.
268 */
269
270void *
271bft_mem_free(void *ptr,
272 const char *var_name,
273 const char *file_name,
274 int line_num);
275
276/*
277 * Allocate aligned memory for ni elements of size bytes.
278 *
279 * This function calls posix_memalign() if available, but adds tracing
280 * capabilities, and automatically calls the bft_error() errorhandler if
281 * it fails to allocate the required memory.
282 *
283 * The associated function bft_mem_have_memalign() indicates if this
284 * type of allocation may be used on this system.
285 *
286 * parameters:
287 * alignment <-- alignent.
288 * ni <-- number of items.
289 * size <-- element size.
290 * var_name <-- allocated variable name string.
291 * file_name <-- name of calling source file.
292 * line_num <-- line number in calling source file.
293 *
294 * returns:
295 * pointer to allocated memory.
296 */
297
298void *
299bft_mem_memalign(size_t alignment,
300 size_t ni,
301 size_t size,
302 const char *var_name,
303 const char *file_name,
304 int line_num);
305
315
316size_t
317bft_mem_get_block_size(void *ptr);
318
324
325size_t
327
333
334size_t
335bft_mem_size_max(void);
336
337/*
338 * Indicate if a memory aligned allocation variant is available.
339 *
340 * If no such function is available, bft_mem_memalign() will always fail.
341 *
342 * returns:
343 * 1 if memory aligned allocation is possible, 0 otherwise.
344 */
345
346int
348
349/* Returns the error handler associated with the bft_mem_...() functions.
350 *
351 * returns:
352 * pointer to the error handler function.
353 */
354
357
358/*
359 * Associates an error handler with the bft_mem_...() functions.
360 *
361 * With the default error handler, an error message is output to stderr,
362 * (after bft_print_flush() is called), and the general error handler used
363 * by bft_error() is then called (which results in the termination of the
364 * current process or process group).
365 *
366 * parameter:
367 * handler <-- pointer to the error handler function.
368 */
369
370void
372
373/*
374 * Associates alternative functions with the bft_mem_...() functions.
375 *
376 * When memory allocated with another mechanism is reallocated or
377 * freed using a bft_mem_... function, this allows trying the
378 * matching alternative function rather than throwing an error.
379 *
380 * Though using matching methods is recommended, this allows handling
381 * compatibility between methods which might be used in different parts
382 * of the code.
383 *
384 * parameter:
385 * realloc_func <-- pointer to alternative reallocation function.
386 * realloc_func <-- pointer to alternative reallocation function.
387 * free_func <-- pointer to alternative free function.
388 */
389
390void
392 bft_mem_realloc_t *realloc_func,
393 bft_mem_free_t *free_func);
394
395/*----------------------------------------------------------------------------*/
396
398
399#endif /* __BFT_MEM_H__ */
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:52
size_t bft_mem_get_size_t(void *ptr)
Definition bft_mem.h:128
size_t bft_mem_size_current(void)
Return current theoretical dynamic memory allocated.
Definition bft_mem.c:1274
int bft_mem_initialized(void)
Indicates if bft_mem_...() functions are initialized.
Definition bft_mem.c:793
size_t bft_mem_get_block_size(void *ptr)
Return block size associated with a given pointer.
Definition bft_mem.c:1244
void bft_mem_end(void)
End memory handling.
Definition bft_mem.c:719
size_t bft_mem_size_max(void)
Return maximum theoretical dynamic memory allocated.
Definition bft_mem.c:1286
void bft_mem_init(const char *log_file_name)
Initialize memory handling.
Definition bft_mem.c:642
void bft_mem_free_t(void *ptr, const char *var_name, const char *file_name, int line_num)
Definition bft_mem.h:139
bft_error_handler_t * bft_mem_error_handler_get(void)
Returns the error handler associated with the bft_mem_...() functions.
Definition bft_mem.c:1316
void bft_mem_error_handler_set(bft_error_handler_t *handler)
Associates an error handler with the bft_mem_...() functions.
Definition bft_mem.c:1333
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:1145
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:815
int bft_mem_have_memalign(void)
Indicate if a memory aligned allocation variant is available.
Definition bft_mem.c:1300
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:899
void * bft_mem_realloc_t(void *ptr, size_t ni, size_t size, const char *var_name, const char *file_name, int line_num)
Definition bft_mem.h:131
void bft_mem_alternative_set(bft_mem_get_size_t *get_size_func, bft_mem_realloc_t *realloc_func, bft_mem_free_t *free_func)
Definition bft_mem.c:1355
void * bft_mem_free(void *ptr, const char *var_name, const char *file_name, int line_num)
Free allocated memory.
Definition bft_mem.c:1056
#define BEGIN_C_DECLS
Definition cs_defs.h:509
#define END_C_DECLS
Definition cs_defs.h:510