src/bft/bft_mem.h Source File

| programmer's documentation

- Main Page
- Related Pages
- Modules
- Data Structures
- Files

- File List
- Globals

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups 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-2013 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
40 BEGIN_C_DECLS
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) \
97 bft_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 * Public function prototypes
125 *============================================================================*/
126
127 /*
128 * Initialize memory handling.
129 *
130 * This function should be called before any other bft_mem_...()
131 * function. To activate memory allocation logging, a logfile
132 * name should be given as an argument. The resulting file will
133 * be a regular, local file. If this file cannot be opened for
134 * some reason, logging is silently de-activated.
135 *
136 * parameter:
137 * log_file_name <-- name of optional log_file (if NULL, no log).
138 */
139
140 void
141 bft_mem_init(const char *log_file_name);
142
143 /*
144 * End memory handling.
145 *
146 * This function should be called after all other bft_mem_...()
147 * functions. In case of memory allocation logging, it
148 * writes final information to the log file and closes is.
149 */
150
151 void
152 bft_mem_end(void);
153
154 /*
155 * Initialize memory handling.
156 *
157 * This function should be called before any other bft_mem_...()
158 * function. To activate memory allocation logging, a logfile
159 * name should be given as an argument. The resulting file will
160 * be a regular, local file. If this file cannot be opened for
161 * some reason, logging is silently de-activated.
162 *
163 * parameter:
164 * log_file_name <-- name of optional log_file (if NULL, no log).
165 */
166
167 /*
168 * Indicates if bft_mem_...() functions are initialized.
169 *
170 * returns:
171 * 1 if bft_mem_init has been called, 0 otherwise.
172 */
173
174 int
175 bft_mem_initialized(void);
176
177 /*
178 * Allocate memory for ni items of size bytes.
179 *
180 * This function calls malloc(), but adds tracing capabilities, and
181 * automatically calls the bft_error() errorhandler if it fails to
182 * allocate the required memory.
183 *
184 * parameters:
185 * ni <-- number of items.
186 * size <-- element size.
187 * var_name <-- allocated variable name string.
188 * file_name <-- name of calling source file.
189 * line_num <-- line number in calling source file.
190 *
191 * returns:
192 * pointer to allocated memory.
193 */
194
195 void *
196 bft_mem_malloc(size_t ni,
197 size_t size,
198 const char *var_name,
199 const char *file_name,
200 int line_num);
201
202 /*
203 * Reallocate memory for ni items of size bytes.
204 *
205 * This function calls realloc(), but adds tracing capabilities, and
206 * automatically calls the bft_error() errorhandler if it fails to
207 * allocate the required memory.
208 *
209 * parameters:
210 * ptr <-> pointer to previous memory location
211 * (if NULL, bft_alloc() called).
212 * ni <-- number of items.
213 * size <-- element size.
214 * var_name <-- allocated variable name string.
215 * file_name <-- name of calling source file.
216 * line_num -> line number in calling source file
217 *
218 * returns:
219 * pointer to allocated memory.
220 */
221
222 void *
223 bft_mem_realloc(void *ptr,
224 size_t ni,
225 size_t size,
226 const char *var_name,
227 const char *file_name,
228 int line_num);
229
230 /*
231 * Free allocated memory.
232 *
233 * This function calls free(), but adds tracing capabilities, and
234 * automatically calls the bft_error() errorhandler if it fails to
235 * free the corresponding memory. In case of a NULL pointer argument,
236 * the function simply returns.
237 *
238 * parameters:
239 * ptr <-> pointer to previous memory location
240 * (if NULL, bft_alloc() called).
241 * var_name <-- allocated variable name string.
242 * file_name <-- name of calling source file.
243 * line_num <-- line number in calling source file.
244 *
245 * returns:
246 * NULL pointer.
247 */
248
249 void *
250 bft_mem_free(void *ptr,
251 const char *var_name,
252 const char *file_name,
253 int line_num);
254
255 /*
256 * Allocate aligned memory for ni elements of size bytes.
257 *
258 * This function calls posix_memalign() if available, but adds tracing
259 * capabilities, and automatically calls the bft_error() errorhandler if
260 * it fails to allocate the required memory.
261 *
262 * The associated function bft_mem_have_memalign() indicates if this
263 * type of allocation may be used on this system.
264 *
265 * parameters:
266 * alignment <-- alignent.
267 * ni <-- number of items.
268 * size <-- element size.
269 * var_name <-- allocated variable name string.
270 * file_name <-- name of calling source file.
271 * line_num <-- line number in calling source file.
272 *
273 * returns:
274 * pointer to allocated memory.
275 */
276
277 void *
278 bft_mem_memalign(size_t alignment,
279 size_t ni,
280 size_t size,
281 const char *var_name,
282 const char *file_name,
283 int line_num);
284
285 /*
286 * Indicate if a memory aligned allocation variant is available.
287 *
288 * If no such function is available, bft_mem_memalign() will always fail.
289 *
290 * returns:
291 * 1 if memory aligned allocation is possible, 0 otherwise.
292 */
293
294 int
295 bft_mem_have_memalign(void);
296
297 /*
298 * Return current theoretical dynamic memory allocated.
299 *
300 * returns:
301 * current memory handled through bft_mem_...() (in kB).
302 */
303
304 size_t
305 bft_mem_size_current(void);
306
307 /*
308 * Return maximum theoretical dynamic memory allocated.
309 *
310 * returns:
311 * maximum memory handled through bft_mem_...() (in kB).
312 */
313
314 size_t
315 bft_mem_size_max(void);
316
317 /* Returns the error handler associated with the bft_mem_...() functions.
318 *
319 * returns:
320 * pointer to the error handler function.
321 */
322
323 bft_error_handler_t *
324 bft_mem_error_handler_get(void);
325
326 /*
327 * Associates an error handler with the bft_mem_...() functions.
328 *
329 * With the default error handler, an error message is output to stderr,
330 * (after bft_print_flush() is called), and the general error handler used
331 * by bft_error() is then called (which results in the termination of the
332 * current process or process group).
333 *
334 * parameter:
335 * handler <-- pointer to the error handler function.
336 */
337
338 void
339 bft_mem_error_handler_set(bft_error_handler_t *handler);
340
341 /*----------------------------------------------------------------------------*/
342
343 END_C_DECLS
344
345 #endif /* __BFT_MEM_H__ */