Code_Saturne
CFD tool
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros
ecs_mem.h
Go to the documentation of this file.
1 #ifndef __ECS_MEM_H__
2 #define __ECS_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 #include "ecs_def.h"
31 
32 /*----------------------------------------------------------------------------*/
33 
35 
36 /*============================================================================
37  * Public types
38  *============================================================================*/
39 
40 /*============================================================================
41  * Public macros
42  *============================================================================*/
43 
44 /*
45  * Allocate memory for _ni items of type _type.
46  *
47  * This macro calls ecs_mem_malloc(), automatically setting the
48  * allocated variable name and source file name and line arguments.
49  *
50  * parameters:
51  * _ptr --> pointer to allocated memory.
52  * _ni <-- number of items.
53  * _type <-- element type.
54  */
55 
56 #define ECS_MALLOC(_ptr, _ni, _type) \
57 _ptr = (_type *) ecs_mem_malloc(_ni, sizeof(_type), \
58  #_ptr, __FILE__, __LINE__)
59 
60 /*
61  * Reallocate memory for _ni items of type _type.
62  *
63  * This macro calls ecs_mem_realloc(), automatically setting the
64  * allocated variable name and source file name and line arguments.
65  *
66  * parameters:
67  * _ptr <-> pointer to allocated memory.
68  * _ni <-- number of items.
69  * _type <-- element type.
70  */
71 
72 #define ECS_REALLOC(_ptr, _ni, _type) \
73 _ptr = (_type *) ecs_mem_realloc(_ptr, _ni, sizeof(_type), \
74  #_ptr, __FILE__, __LINE__)
75 
76 /*
77  * Free allocated memory.
78  *
79  * This macro calls ecs_mem_free(), automatically setting the
80  * allocated variable name and source file name and line arguments.
81  *
82  * The freed pointer is set to NULL to avoid accidental reuse.
83  *
84  * parameters:
85  * _ptr <-> pointer to allocated memory.
86  */
87 
88 #ifdef __cplusplus /* avoid casting from void for C++ */
89 
90 #define ECS_FREE(_ptr) \
91 ecs_mem_free(_ptr, #_ptr, __FILE__, __LINE__), _ptr = NULL
92 
93 #else
94 
95 #define ECS_FREE(_ptr) \
96 _ptr = ecs_mem_free(_ptr, #_ptr, __FILE__, __LINE__)
97 
98 #endif /* __cplusplus */
99 
100 /*
101  * Allocate aligned memory for _ni items of type _type.
102  *
103  * This macro calls ecs_mem_memalign(), automatically setting the
104  * allocated variable name and source file name and line arguments.
105  *
106  * parameters:
107  * _ptr --> pointer to allocated memory.
108  * _align <-- alignment.
109  * _ni <-- number of items.
110  * _type <-- element type.
111  */
112 
113 #define ECS_MEMALIGN(_ptr, _align, _ni, _type) \
114 _ptr = (_type *) ecs_mem_memalign(_align, _ni, sizeof(_type), \
115  #_ptr, __FILE__, __LINE__)
116 
117 /*============================================================================
118  * Public function prototypes
119  *============================================================================*/
120 
121 /*
122  * Initialize memory handling.
123  *
124  * This function should be called before any other ecs_mem_...()
125  * function. To activate memory allocation logging, a logfile
126  * name should be given as an argument. The resulting file will
127  * be a regular, local file. If this file cannot be opened for
128  * some reason, logging is silently de-activated.
129  *
130  * parameter:
131  * log_file_name <-- name of optional log_file (if NULL, no log).
132  */
133 
134 void
135 ecs_mem_init(const char *log_file_name);
136 
137 /*
138  * End memory handling.
139  *
140  * This function should be called after all other ecs_mem_...()
141  * functions. In case of memory allocation logging, it
142  * writes final information to the log file and closes is.
143  */
144 
145 void
146 ecs_mem_end(void);
147 
148 /*
149  * Initialize memory handling.
150  *
151  * This function should be called before any other ecs_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 
161 /*
162  * Indicates if ecs_mem_...() functions are initialized.
163  *
164  * returns:
165  * 1 if ecs_mem_init has been called, 0 otherwise.
166  */
167 
168 int
169 ecs_mem_initialized(void);
170 
171 /*
172  * Allocate memory for ni items of size bytes.
173  *
174  * This function calls malloc(), but adds tracing capabilities, and
175  * automatically calls the ecs_error() errorhandler if it fails to
176  * allocate the required memory.
177  *
178  * parameters:
179  * ni <-- number of items.
180  * size <-- element size.
181  * var_name <-- allocated variable name string.
182  * file_name <-- name of calling source file.
183  * line_num <-- line number in calling source file.
184  *
185  * returns:
186  * pointer to allocated memory.
187  */
188 
189 void *
190 ecs_mem_malloc(size_t ni,
191  size_t size,
192  const char *var_name,
193  const char *file_name,
194  int line_num);
195 
196 /*
197  * Reallocate memory for ni items of size bytes.
198  *
199  * This function calls realloc(), but adds tracing capabilities, and
200  * automatically calls the ecs_error() errorhandler if it fails to
201  * allocate the required memory.
202  *
203  * parameters:
204  * ptr <-> pointer to previous memory location
205  * (if NULL, ecs_alloc() called).
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 
216 void *
217 ecs_mem_realloc(void *ptr,
218  size_t ni,
219  size_t size,
220  const char *var_name,
221  const char *file_name,
222  int line_num);
223 
224 /*
225  * Free allocated memory.
226  *
227  * This function calls free(), but adds tracing capabilities, and
228  * automatically calls the ecs_error() errorhandler if it fails to
229  * free the corresponding memory. In case of a NULL pointer argument,
230  * the function simply returns.
231  *
232  * parameters:
233  * ptr <-> pointer to previous memory location
234  * (if NULL, ecs_alloc() called).
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  * NULL pointer.
241  */
242 
243 void *
244 ecs_mem_free(void *ptr,
245  const char *var_name,
246  const char *file_name,
247  int line_num);
248 
249 /*
250  * Return current theoretical dynamic memory allocated.
251  *
252  * returns:
253  * current memory handled through ecs_mem_...() (in kB).
254  */
255 
256 size_t
258 
259 /*
260  * Return maximum theoretical dynamic memory allocated.
261  *
262  * returns:
263  * maximum memory handled through ecs_mem_...() (in kB).
264  */
265 
266 size_t
267 ecs_mem_size_max(void);
268 
269 /*----------------------------------------------------------------------------*/
270 
272 
273 #endif /* __ECS_MEM_H__ */
size_t ecs_mem_size_current(void)
Return current theoretical dynamic memory allocated.
Definition: ecs_mem.c:834
void ecs_mem_init(const char *log_file_name)
Initialize memory handling.
Definition: ecs_mem.c:444
#define BEGIN_C_DECLS
Definition: ecs_def.h:234
void * ecs_mem_free(void *ptr, const char *var_name, const char *file_name, int line_num)
Free allocated memory.
Definition: ecs_mem.c:786
void * ecs_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: ecs_mem.c:677
void * ecs_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: ecs_mem.c:605
int ecs_mem_initialized(void)
Indicates if ecs_mem_...() functions are initialized.
Definition: ecs_mem.c:583
size_t ecs_mem_size_max(void)
Return maximum theoretical dynamic memory allocated.
Definition: ecs_mem.c:846
void ecs_mem_end(void)
End memory handling.
Definition: ecs_mem.c:515
#define END_C_DECLS
Definition: ecs_def.h:235