8.2
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-2024 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
49
62
63/*
64 * Structure defining an allocated memory block
65 */
66
67typedef struct
68{
69 void *host_ptr;
70#if defined(HAVE_ACCEL)
71 void *device_ptr;
72#endif
73
74 size_t size;
75#if defined(HAVE_ACCEL)
76 cs_alloc_mode_t mode;
77#endif
78
80
81/*============================================================================
82 * Public macros
83 *============================================================================*/
84
85/*
86 * Allocate memory for _ni items of type _type.
87 *
88 * This macro calls bft_mem_malloc(), automatically setting the
89 * allocated variable name and source file name and line arguments.
90 *
91 * parameters:
92 * _ptr --> pointer to allocated memory.
93 * _ni <-- number of items.
94 * _type <-- element type.
95 */
96
97#define BFT_MALLOC(_ptr, _ni, _type) \
98_ptr = (_type *) bft_mem_malloc(_ni, sizeof(_type), \
99 #_ptr, __FILE__, __LINE__)
100
101/*
102 * Reallocate memory for _ni items of type _type.
103 *
104 * This macro calls bft_mem_realloc(), automatically setting the
105 * allocated variable name and source file name and line arguments.
106 *
107 * parameters:
108 * _ptr <-> pointer to allocated memory.
109 * _ni <-- number of items.
110 * _type <-- element type.
111 */
112
113#define BFT_REALLOC(_ptr, _ni, _type) \
114_ptr = (_type *) bft_mem_realloc(_ptr, _ni, sizeof(_type), \
115 #_ptr, __FILE__, __LINE__)
116
117/*
118 * Free allocated memory.
119 *
120 * This macro calls bft_mem_free(), automatically setting the
121 * allocated variable name and source file name and line arguments.
122 *
123 * The freed pointer is set to NULL to avoid accidental reuse.
124 *
125 * parameters:
126 * _ptr <-> pointer to allocated memory.
127 */
128
129#ifdef __cplusplus /* avoid casting from void for C++ */
130
131#define BFT_FREE(_ptr) \
132bft_mem_free(_ptr, #_ptr, __FILE__, __LINE__), _ptr = NULL
133
134#else
135
136#define BFT_FREE(_ptr) \
137_ptr = bft_mem_free(_ptr, #_ptr, __FILE__, __LINE__)
138
139#endif /* __cplusplus */
140
141/*
142 * Allocate aligned memory for _ni items of type _type.
143 *
144 * This macro calls bft_mem_memalign(), automatically setting the
145 * allocated variable name and source file name and line arguments.
146 *
147 * parameters:
148 * _ptr --> pointer to allocated memory.
149 * _align <-- alignment.
150 * _ni <-- number of items.
151 * _type <-- element type.
152 */
153
154#define BFT_MEMALIGN(_ptr, _align, _ni, _type) \
155_ptr = (_type *) bft_mem_memalign(_align, _ni, sizeof(_type), \
156 #_ptr, __FILE__, __LINE__)
157
158/*----------------------------------------------------------------------------
159 * Function pointer types
160 *----------------------------------------------------------------------------*/
161
162typedef size_t
163(bft_mem_get_size_t)(void *ptr);
164
165typedef void *
166(bft_mem_realloc_t)(void *ptr,
167 size_t ni,
168 size_t size,
169 const char *var_name,
170 const char *file_name,
171 int line_num);
172
173typedef void
174(bft_mem_free_t)(void *ptr,
175 const char *var_name,
176 const char *file_name,
177 int line_num);
178
179/*============================================================================
180 * Semi private function definitions
181 *============================================================================*/
182
184
185#ifdef __cplusplus /* only for C++ API */
186
187/*----------------------------------------------------------------------------*/
188
189/*
190 * Return the cs_mem_block structure corresponding to a given
191 * allocated block.
192 *
193 * parameters:
194 * p_get: <-- allocated block's start adress.
195 *
196 * returns:
197 * corresponding cs_mem_block structure.
198 */
199
201bft_mem_get_block_info(const void *p_get);
202
203/*
204 * Return the cs_mem_block structure corresponding to a given
205 * allocated block if available.
206 *
207 * If no block info is available, return block with null pointers
208 * and zero size.
209 *
210 * parameters:
211 * p_get: <-- allocated block's start adress.
212 *
213 * returns:
214 * pointer tocorresponding cs_mem_block structure.
215 */
216
218bft_mem_get_block_info_try(const void *p_get);
219
220/*
221 * \brief Update block information map if enabled.
222 *
223 * parameters
224 * var_name <-- allocated variable name string.
225 * file_name <-- name of calling source file.
226 * line_num <-- line number in calling source file.
227 * old_block <-- pointer to old block info, if present
228 * new_block <-- pointer to new block info, if present
229 */
230
231void
232bft_mem_update_block_info(const char *var_name,
233 const char *file_name,
234 int line_num,
235 const cs_mem_block_t *old_block,
236 const cs_mem_block_t *new_block);
237
238/*----------------------------------------------------------------------------*/
239
240#endif // __cplusplus
241
243
244/*============================================================================
245 * Public function prototypes
246 *============================================================================*/
247
248/*
249 * Initialize memory handling.
250 *
251 * This function should be called before any other bft_mem_...()
252 * function. To activate memory allocation logging, a logfile
253 * name should be given as an argument. The resulting file will
254 * be a regular, local file. If this file cannot be opened for
255 * some reason, logging is silently de-activated.
256 *
257 * parameter:
258 * log_file_name <-- name of optional log_file (if NULL, no log).
259 */
260
261void
262bft_mem_init(const char *log_file_name);
263
264/*
265 * End memory handling.
266 *
267 * This function should be called after all other bft_mem_...()
268 * functions. In case of memory allocation logging, it
269 * writes final information to the log file and closes is.
270 */
271
272void
273bft_mem_end(void);
274
275/*
276 * Initialize memory handling.
277 *
278 * This function should be called before any other bft_mem_...()
279 * function. To activate memory allocation logging, a logfile
280 * name should be given as an argument. The resulting file will
281 * be a regular, local file. If this file cannot be opened for
282 * some reason, logging is silently de-activated.
283 *
284 * parameter:
285 * log_file_name <-- name of optional log_file (if NULL, no log).
286 */
287
288/*
289 * Indicates if bft_mem_...() functions are initialized.
290 *
291 * returns:
292 * 1 if bft_mem_init has been called, 0 otherwise.
293 */
294
295int
297
298/*
299 * Allocate memory for ni items of size bytes.
300 *
301 * This function calls malloc(), but adds tracing capabilities, and
302 * automatically calls the bft_error() errorhandler if it fails to
303 * allocate the required memory.
304 *
305 * Allocation couting and logging to trace file will be done if
306 * both required by the bft_mem_init options and if file_name != nullptr.
307 * If required but file_name == nullptr, it must be handled by the caller,
308 * using `bft_mem_log_mem_op`.
309 *
310 * parameters:
311 * ni <-- number of items.
312 * size <-- element size.
313 * var_name <-- allocated variable name string.
314 * file_name <-- name of calling source file.
315 * line_num <-- line number in calling source file.
316 *
317 * returns:
318 * pointer to allocated memory.
319 */
320
321void *
322bft_mem_malloc(size_t ni,
323 size_t size,
324 const char *var_name,
325 const char *file_name,
326 int line_num);
327
328/*
329 * Reallocate memory for ni items of size bytes.
330 *
331 * This function calls realloc(), but adds tracing capabilities, and
332 * automatically calls the bft_error() errorhandler if it fails to
333 * allocate the required memory.
334 *
335 * parameters:
336 * ptr <-> pointer to previous memory location
337 * (if NULL, bft_alloc() called).
338 * ni <-- number of items.
339 * size <-- element size.
340 * var_name <-- allocated variable name string.
341 * file_name <-- name of calling source file.
342 * line_num -> line number in calling source file
343 *
344 * returns:
345 * pointer to allocated memory.
346 */
347
348void *
349bft_mem_realloc(void *ptr,
350 size_t ni,
351 size_t size,
352 const char *var_name,
353 const char *file_name,
354 int line_num);
355
356/*
357 * Free allocated memory.
358 *
359 * This function calls free(), but adds tracing capabilities, and
360 * automatically calls the bft_error() errorhandler if it fails to
361 * free the corresponding memory. In case of a NULL pointer argument,
362 * the function simply returns.
363 *
364 * parameters:
365 * ptr <-> pointer to previous memory location
366 * (if NULL, bft_alloc() called).
367 * var_name <-- allocated variable name string.
368 * file_name <-- name of calling source file.
369 * line_num <-- line number in calling source file.
370 *
371 * returns:
372 * NULL pointer.
373 */
374
375void *
376bft_mem_free(void *ptr,
377 const char *var_name,
378 const char *file_name,
379 int line_num);
380
381/*
382 * Allocate aligned memory for ni elements of size bytes.
383 *
384 * This function calls posix_memalign() if available, but adds tracing
385 * capabilities, and automatically calls the bft_error() errorhandler if
386 * it fails to allocate the required memory.
387 *
388 * The associated function bft_mem_have_memalign() indicates if this
389 * type of allocation may be used on this system.
390 *
391 * parameters:
392 * alignment <-- alignent.
393 * ni <-- number of items.
394 * size <-- element size.
395 * var_name <-- allocated variable name string.
396 * file_name <-- name of calling source file.
397 * line_num <-- line number in calling source file.
398 *
399 * returns:
400 * pointer to allocated memory.
401 */
402
403void *
404bft_mem_memalign(size_t alignment,
405 size_t ni,
406 size_t size,
407 const char *var_name,
408 const char *file_name,
409 int line_num);
410
416
417size_t
419
425
426size_t
427bft_mem_size_max(void);
428
429/*
430 * Indicate if a memory aligned allocation variant is available.
431 *
432 * If no such function is available, bft_mem_memalign() will always fail.
433 *
434 * returns:
435 * 1 if memory aligned allocation is possible, 0 otherwise.
436 */
437
438int
440
441/* Returns the error handler associated with the bft_mem_...() functions.
442 *
443 * returns:
444 * pointer to the error handler function.
445 */
446
449
450/*
451 * Associates an error handler with the bft_mem_...() functions.
452 *
453 * With the default error handler, an error message is output to stderr,
454 * (after bft_print_flush() is called), and the general error handler used
455 * by bft_error() is then called (which results in the termination of the
456 * current process or process group).
457 *
458 * parameter:
459 * handler <-- pointer to the error handler function.
460 */
461
462void
464
465/*
466 * Associates alternative functions with the bft_mem_...() functions.
467 *
468 * When memory allocated with another mechanism is reallocated or
469 * freed using a bft_mem_... function, this allows trying the
470 * matching alternative function rather than throwing an error.
471 *
472 * Though using matching methods is recommended, this allows handling
473 * compatibility between methods which might be used in different parts
474 * of the code.
475 *
476 * parameter:
477 * realloc_func <-- pointer to alternative reallocation function.
478 * free_func <-- pointer to alternative free function.
479 */
480
481void
483 bft_mem_free_t *free_func);
484
485/*----------------------------------------------------------------------------*/
486
488
489#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
void bft_mem_update_block_info(const char *var_name, const char *file_name, int line_num, const cs_mem_block_t *old_block, const cs_mem_block_t *new_block)
Log matching memory operation if logging is enabled.
Definition bft_mem.cpp:514
cs_mem_block_t bft_mem_get_block_info(const void *p_get)
Return the cs_mem_block structure corresponding to a given allocated block.
Definition bft_mem.cpp:459
cs_mem_block_t bft_mem_get_block_info_try(const void *p_get)
Return the cs_mem_block structure corresponding to a given allocated block if available.
Definition bft_mem.cpp:482
void bft_mem_alternative_set(bft_mem_realloc_t *realloc_func, bft_mem_free_t *free_func)
Definition bft_mem.cpp:1187
size_t bft_mem_get_size_t(void *ptr)
Definition bft_mem.h:163
size_t bft_mem_size_current(void)
Return current theoretical dynamic memory allocated.
Definition bft_mem.cpp:1106
int bft_mem_initialized(void)
Indicates if bft_mem_...() functions are initialized.
Definition bft_mem.cpp:802
void bft_mem_end(void)
End memory handling.
Definition bft_mem.cpp:741
size_t bft_mem_size_max(void)
Return maximum theoretical dynamic memory allocated.
Definition bft_mem.cpp:1118
void bft_mem_init(const char *log_file_name)
Initialize memory handling.
Definition bft_mem.cpp:658
void bft_mem_free_t(void *ptr, const char *var_name, const char *file_name, int line_num)
Definition bft_mem.h:174
bft_error_handler_t * bft_mem_error_handler_get(void)
Returns the error handler associated with the bft_mem_...() functions.
Definition bft_mem.cpp:1148
void bft_mem_error_handler_set(bft_error_handler_t *handler)
Associates an error handler with the bft_mem_...() functions.
Definition bft_mem.cpp:1165
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.cpp:1037
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.cpp:829
int bft_mem_have_memalign(void)
Indicate if a memory aligned allocation variant is available.
Definition bft_mem.cpp:1132
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.cpp:886
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:166
cs_alloc_mode_t
Definition bft_mem.h:50
@ CS_ALLOC_HOST
Definition bft_mem.h:52
@ CS_ALLOC_HOST_DEVICE_PINNED
Definition bft_mem.h:54
@ CS_ALLOC_HOST_DEVICE_SHARED
Definition bft_mem.h:57
@ CS_ALLOC_HOST_DEVICE
Definition bft_mem.h:53
@ CS_ALLOC_DEVICE
Definition bft_mem.h:59
void * bft_mem_free(void *ptr, const char *var_name, const char *file_name, int line_num)
Free allocated memory.
Definition bft_mem.cpp:977
#define BEGIN_C_DECLS
Definition cs_defs.h:528
#define END_C_DECLS
Definition cs_defs.h:529
Definition bft_mem.h:68
size_t size
Definition bft_mem.h:74
void * host_ptr
host pointer
Definition bft_mem.h:69