2 * This file is part of the GROMACS molecular simulation package.
4 * Copyright (c) 1991-2000, University of Groningen, The Netherlands.
5 * Copyright (c) 2001-2004, The GROMACS development team.
6 * Copyright (c) 2013,2014, by the GROMACS development team, led by
7 * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
8 * and including many others, as listed in the AUTHORS file in the
9 * top-level source directory and at http://www.gromacs.org.
11 * GROMACS is free software; you can redistribute it and/or
12 * modify it under the terms of the GNU Lesser General Public License
13 * as published by the Free Software Foundation; either version 2.1
14 * of the License, or (at your option) any later version.
16 * GROMACS is distributed in the hope that it will be useful,
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 * Lesser General Public License for more details.
21 * You should have received a copy of the GNU Lesser General Public
22 * License along with GROMACS; if not, see
23 * http://www.gnu.org/licenses, or write to the Free Software Foundation,
24 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
26 * If you want to redistribute modifications to GROMACS, please
27 * consider that scientific software is very special. Version
28 * control is crucial - bugs must be traceable. We will be happy to
29 * consider code for inclusion in the official distribution, but
30 * derived work must not be called official GROMACS. Details are found
31 * in the README & COPYING files - if they are missing, get the
32 * official version at http://www.gromacs.org.
34 * To help us fund GROMACS development, we humbly ask that you cite
35 * the research papers on the package. Check out http://www.gromacs.org.
39 * C memory allocation routines for \Gromacs.
41 * This header provides macros snew(), srenew(), smalloc(), and sfree() for
42 * C memory management. Additionally, snew_aligned() and sfree_aligned() are
43 * provided for managing memory with a specified byte alignment.
45 * If an allocation fails, the program is halted by calling gmx_fatal(), which
46 * outputs source file and line number and the name of the variable involved.
47 * This frees calling code from the trouble of checking the result of the
48 * allocations everywhere. It also provides a location for centrally logging
49 * memory allocations for diagnosing memory usage (currently can only enabled
50 * by changing the source code). Additionally, sfree() works also with a
51 * `NULL` parameter, which standard free() does not.
53 * The macros forward the calls to functions save_malloc(), save_calloc(),
54 * save_realloc(), save_free(), save_calloc_aligned(), and save_free_aligned().
55 * There are a few low-level locations in \Gromacs that call these directly,
56 * but generally the macros should be used.
57 * save_malloc_aligned() exists for this purpose, although there is no macro to
61 * As an implementation detail, the macros need a different internal
62 * implementation for C and C++ code. This is because C accepts conversions
63 * from `void *` to any pointer type, but C++ doesn't. And in order to cast
64 * the returned pointer to a correct type, a C++ template needs to be used to
65 * get access to the type.
69 * \ingroup module_utility
71 #ifndef GMX_UTILITY_SMALLOC_H
72 #define GMX_UTILITY_SMALLOC_H
81 * \Gromacs wrapper for malloc().
83 * \param[in] name Variable name identifying the allocation.
84 * \param[in] file Source code file where the allocation originates from.
85 * \param[in] line Source code line where the allocation originates from.
86 * \param[in] size Number of bytes to allocate.
87 * \returns Pointer to the allocated space.
89 * This should generally be called through smalloc(), not directly.
91 void *save_malloc(const char *name, const char *file, int line, size_t size);
93 * \Gromacs wrapper for calloc().
95 * \param[in] name Variable name identifying the allocation.
96 * \param[in] file Source code file where the allocation originates from.
97 * \param[in] line Source code line where the allocation originates from.
98 * \param[in] nelem Number of elements to allocate.
99 * \param[in] elsize Number of bytes per element.
100 * \returns Pointer to the allocated space.
102 * This should generally be called through snew(), not directly.
104 void *save_calloc(const char *name, const char *file, int line,
105 size_t nelem, size_t elsize);
107 * \Gromacs wrapper for realloc().
109 * \param[in] name Variable name identifying the allocation.
110 * \param[in] file Source code file where the allocation originates from.
111 * \param[in] line Source code line where the allocation originates from.
112 * \param[in] ptr Pointer to the previously allocated memory (can be NULL).
113 * \param[in] nelem Number of elements to allocate.
114 * \param[in] elsize Number of bytes per element.
115 * \returns Pointer to the allocated space.
117 * As with realloc(), if \p ptr is NULL, memory is allocated as if malloc() was
119 * This should generally be called through srenew(), not directly.
121 * Note that the allocated memory is not initialized to zero.
123 void *save_realloc(const char *name, const char *file, int line,
124 void *ptr, size_t nelem, size_t elsize);
126 * \Gromacs wrapper for free().
128 * \param[in] name Variable name identifying the deallocation.
129 * \param[in] file Source code file where the deallocation originates from.
130 * \param[in] line Source code line where the deallocation originates from.
131 * \param[in] ptr Pointer to the allocated memory (can be NULL).
133 * If \p ptr is NULL, does nothing.
134 * This should generally be called through sfree(), not directly.
137 void save_free(const char *name, const char *file, int line, void *ptr);
140 * \Gromacs wrapper for allocating aligned memory.
142 * \param[in] name Variable name identifying the allocation.
143 * \param[in] file Source code file where the allocation originates from.
144 * \param[in] line Source code line where the allocation originates from.
145 * \param[in] nelem Number of elements to allocate.
146 * \param[in] elsize Number of bytes per element.
147 * \param[in] alignment Requested alignment in bytes.
148 * \returns Pointer to the allocated space, aligned at `alignment`-byte
151 * There is no macro that invokes this function.
153 * The returned pointer should only be freed with a call to save_free_aligned().
155 void *save_malloc_aligned(const char *name, const char *file, int line,
156 size_t nelem, size_t elsize, size_t alignment);
158 * \Gromacs wrapper for allocating zero-initialized aligned memory.
160 * \param[in] name Variable name identifying the allocation.
161 * \param[in] file Source code file where the allocation originates from.
162 * \param[in] line Source code line where the allocation originates from.
163 * \param[in] nelem Number of elements to allocate.
164 * \param[in] elsize Number of bytes per element.
165 * \param[in] alignment Requested alignment in bytes.
166 * \returns Pointer to the allocated space, aligned at `alignment`-byte
169 * This should generally be called through snew_aligned(), not directly.
171 * The returned pointer should only be freed with a call to save_free_aligned().
173 void *save_calloc_aligned(const char *name, const char *file, int line,
174 size_t nelem, size_t elsize, size_t alignment);
176 * \Gromacs wrapper for freeing aligned memory.
178 * \param[in] name Variable name identifying the deallocation.
179 * \param[in] file Source code file where the deallocation originates from.
180 * \param[in] line Source code line where the deallocation originates from.
181 * \param[in] ptr Pointer to the allocated memory (can be NULL).
183 * If \p ptr is NULL, does nothing.
184 * \p ptr should have been allocated with save_malloc_aligned() or
185 * save_calloc_aligned().
186 * This should generally be called through sfree_aligned(), not directly.
189 void save_free_aligned(const char *name, const char *file, int line, void *ptr);
196 /*! \cond internal */
197 /*! \name Implementation templates for C++ memory allocation macros
199 * These templates are used to implement the snew() etc. macros for C++, where
200 * an explicit cast is needed from `void *` (the return value of the allocation
201 * wrapper functions) to the thpe of \p ptr.
203 * Having these as `static` avoid some obscure bugs if several files define
204 * distinct data structures with identical names and allocate memory for them
205 * using snew(). By the C++ standard, such declarations cause undefined
206 * behavior, but can be difficult to spot in the existing C code.
207 * Without the `static` (and if the compiler does not inline the calls), the
208 * linker cannot that data structures with identical names are actually
209 * different and links calls to these template functions incorrectly, which can
210 * result in allocation of an incorrect amount of memory if the element size is
211 * computed within the function.
213 * The size cannot be passed as a parameter to the function either, since that
214 * provokes warnings from cppcheck for some invocations, where a complex
215 * expression is passed as \p ptr.
218 /** C++ helper for snew(). */
219 template <typename T> static inline
220 void gmx_snew_impl(const char *name, const char *file, int line,
221 T * &ptr, size_t nelem)
223 ptr = (T *)save_calloc(name, file, line, nelem, sizeof(T));
225 /** C++ helper for srenew(). */
226 template <typename T> static inline
227 void gmx_srenew_impl(const char *name, const char *file, int line,
228 T * &ptr, size_t nelem)
230 ptr = (T *)save_realloc(name, file, line, ptr, nelem, sizeof(T));
232 /** C++ helper for smalloc(). */
233 template <typename T> static inline
234 void gmx_smalloc_impl(const char *name, const char *file, int line,
235 T * &ptr, size_t size)
237 ptr = (T *)save_malloc(name, file, line, size);
239 /** C++ helper for snew_aligned(). */
240 template <typename T> static inline
241 void gmx_snew_aligned_impl(const char *name, const char *file, int line,
242 T * &ptr, size_t nelem, size_t alignment)
244 ptr = (T *)save_calloc_aligned(name, file, line, nelem, sizeof(T), alignment);
248 #endif /* __cplusplus */
252 * Allocates memory for a given number of elements.
254 * \param[out] ptr Pointer to allocate.
255 * \param[in] nelem Number of elements to allocate.
257 * Allocates memory for \p nelem elements of type \p *ptr and sets this to
258 * \p ptr. The allocated memory is initialized to zeros.
264 * Reallocates memory for a given number of elements.
266 * \param[in,out] ptr Pointer to allocate/reallocate.
267 * \param[in] nelem Number of elements to allocate.
269 * (Re)allocates memory for \p ptr such that it can hold \p nelem elements of
270 * type \p *ptr, and sets the new pointer to \p ptr.
271 * If \p ptr is `NULL`, memory is allocated as if it was new.
272 * If \p nelem is zero, \p ptr is freed (if not `NULL`).
273 * Note that the allocated memory is not initialized, unlike with snew().
279 * Allocates memory for a given number of bytes.
281 * \param[out] ptr Pointer to allocate.
282 * \param[in] size Number of bytes to allocate.
284 * Allocates memory for \p size bytes and sets this to \p ptr.
285 * The allocated memory is initialized to zero.
289 /*! \def snew_aligned
291 * Allocates aligned memory for a given number of elements.
293 * \param[out] ptr Pointer to allocate.
294 * \param[in] nelem Number of elements to allocate.
295 * \param[in] alignment Requested alignment in bytes.
297 * Allocates memory for \p nelem elements of type \p *ptr and sets this to
298 * \p ptr. The returned pointer is `alignment`-byte aligned.
299 * The allocated memory is initialized to zeros.
301 * The returned pointer should only be freed with sfree_aligned().
307 /* C++ implementation */
308 #define snew(ptr, nelem) \
309 gmx_snew_impl(#ptr, __FILE__, __LINE__, (ptr), (nelem))
310 #define srenew(ptr, nelem) \
311 gmx_srenew_impl(#ptr, __FILE__, __LINE__, (ptr), (nelem))
312 #define smalloc(ptr, size) \
313 gmx_smalloc_impl(#ptr, __FILE__, __LINE__, (ptr), (size))
314 #define snew_aligned(ptr, nelem, alignment) \
315 gmx_snew_aligned_impl(#ptr, __FILE__, __LINE__, (ptr), (nelem), alignment)
319 /* C implementation */
320 #define snew(ptr, nelem) \
321 (ptr) = save_calloc(#ptr, __FILE__, __LINE__, (nelem), sizeof(*(ptr)))
322 #define srenew(ptr, nelem) \
323 (ptr) = save_realloc(#ptr, __FILE__, __LINE__, (ptr), (nelem), sizeof(*(ptr)))
324 #define smalloc(ptr, size) \
325 (ptr) = save_malloc(#ptr, __FILE__, __LINE__, size)
326 #define snew_aligned(ptr, nelem, alignment) \
327 (ptr) = save_calloc_aligned(#ptr, __FILE__, __LINE__, (nelem), sizeof(*(ptr)), alignment)
332 * Frees memory referenced by \p ptr.
334 * \p ptr is allowed to be NULL, in which case nothing is done.
338 #define sfree(ptr) save_free(#ptr, __FILE__, __LINE__, (ptr))
341 * Frees aligned memory referenced by \p ptr.
343 * This must only be called with a pointer obtained through snew_aligned().
344 * \p ptr is allowed to be NULL, in which case nothing is done.
348 #define sfree_aligned(ptr) save_free_aligned(#ptr, __FILE__, __LINE__, (ptr))