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 * check out http://www.gromacs.org for more information.
7 * Copyright (c) 2012,2013, by the GROMACS development team, led by
8 * David van der Spoel, Berk Hess, Erik Lindahl, and including many
9 * others, as listed in the AUTHORS file in the top-level source
10 * directory and at http://www.gromacs.org.
12 * GROMACS is free software; you can redistribute it and/or
13 * modify it under the terms of the GNU Lesser General Public License
14 * as published by the Free Software Foundation; either version 2.1
15 * of the License, or (at your option) any later version.
17 * GROMACS is distributed in the hope that it will be useful,
18 * but WITHOUT ANY WARRANTY; without even the implied warranty of
19 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20 * Lesser General Public License for more details.
22 * You should have received a copy of the GNU Lesser General Public
23 * License along with GROMACS; if not, see
24 * http://www.gnu.org/licenses, or write to the Free Software Foundation,
25 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
27 * If you want to redistribute modifications to GROMACS, please
28 * consider that scientific software is very special. Version
29 * control is crucial - bugs must be traceable. We will be happy to
30 * consider code for inclusion in the official distribution, but
31 * derived work must not be called official GROMACS. Details are found
32 * in the README & COPYING files - if they are missing, get the
33 * official version at http://www.gromacs.org.
35 * To help us fund GROMACS development, we humbly ask that you cite
36 * the research papers on the package. Check out http://www.gromacs.org.
41 #include "visibility.h"
45 * Memory allocation routines in gromacs:
47 * If an allocation fails, the program is halted by means of the
48 * fatal_error routine, which outputs source file and line number
49 * and the name of the variable involved.
51 * Macro's which can be used:
54 * Allocates memory for nelem elements and returns this in ptr.
55 * The allocated memory is initialized to zeros.
58 * Reallocates memory for nelem elements and returns this in ptr.
61 * Allocates memory for size bytes and returns this in ptr.
63 * scalloc(ptr,nelem,elsize)
64 * Allocates memory for nelem elements of size elsize and returns
68 * Reallocates memory for size bytes and returns this in ptr.
71 * Frees memory referenced by ptr.
73 * snew_aligned(ptr,nelem,alignment)
74 * Allocates memory for nelem elements and returns this in ptr.
75 * The allocated memory is initialized to zeroes.
76 * alignment=n will constrain ptr to be n-byte aligned.
77 * This pointer should only be freed with sfree_aligned, since
78 * it may not be the value returned by the underlying malloc.
81 * Frees aligned memory referenced by ptr.
83 ****************************************************************************
85 * Functions which are used by the macro's:
87 * extern void *save_malloc(char *name,char *file,int line,int size);
88 * Like alloc, returns a pointer to the allocated space, uses name, file
89 * and line to generate an error message when allocation failed.
91 * extern void *save_calloc(char *name,char *file,int line,
92 * size_t nelem,size_t elsize);
93 * Like calloc, returns a pointer to the allocated space, uses name, file
94 * and line to generate an error message when allocation failed.
96 * extern void *save_realloc(char *name,char *file,int line,
97 * void *ptr,size_t size);
98 * Like realloc, returns a pointer to the allocated space, uses name, file
99 * and line to generate an error message when allocation failed.
100 * If ptr equals NULL, malloc is called in stead of realloc, in this way
101 * it is possible to combine first and later allocations.
103 * extern void save_free(char *name,char *file,int line, void *ptr);
104 * Like free, uses name, file and line to generate an error message when
107 * extern size_t maxavail();
108 * Returns the maximum available allocation unit, by applying a binary
109 * search on the largest block of memory available. After allocation
110 * it invokes free to restore the original state. So it is important
111 * that free can undo the effect of a malloc.
113 * extern size_t memavail();
114 * Returns the total of available allocation unit, by applying maxavail
115 * until no space is left, it then frees all allocated space and returns
116 * the sum of the previously allocated space. As mentioned with maxavail,
117 * it is important that free can undo the effect of a malloc.
119 * extern void *save_malloc_aligned(char *name,char *file,int line,size_t size,size_t alignment);
120 * Like alloc, returns a pointer to the allocated space, uses name, file
121 * and line to generate an error message when allocation failed.
122 * The returned pointer will be n-byte aligned, where n=alignment.
123 * The pointer should only be freed with a call to save_free.
125 * extern void save_free_aligned(char *name,char *file,int line, void *ptr);
126 * Like free, uses name, file and line to generate an error message when
127 * the free failed. This function is intended to be called for
128 * pointers allocated with save_malloc_aligned, and may not work
129 * on normal pointers.
137 void *save_malloc(const char *name
, const char *file
, int line
, size_t size
);
139 void *save_calloc(const char *name
, const char *file
, int line
,
140 size_t nelem
, size_t elsize
);
142 void *save_realloc(const char *name
, const char *file
, int line
,
143 void *ptr
, size_t nelem
, size_t elsize
);
145 void save_free(const char *name
, const char *file
, int line
, void *ptr
);
146 size_t maxavail(void);
147 size_t memavail(void);
149 /* Aligned-memory counterparts */
152 void *save_malloc_aligned(const char *name
, const char *file
, int line
,
153 unsigned nelem
, size_t elsize
, size_t alignment
);
155 void *save_calloc_aligned(const char *name
, const char *file
, int line
,
156 unsigned nelem
, size_t elsize
, size_t alignment
);
158 void save_free_aligned(const char *name
, const char *file
, int line
, void *ptr
);
163 /* Use of sizeof(T) in _snew() and _srenew() can cause obscure bugs if
164 * several files define distinct data structures with identical names and
165 * allocate memory for them using the macros below.
166 * For this reason, the size of an element is passed as a parameter.
168 * The C versions work fine in such cases, but when compiled with a C++
169 * compiler (and if the compiler does not inline the calls), the linker cannot
170 * tell that data structures with identical names are actually different and
171 * links calls to these template functions incorrectly, which can result in
172 * allocation of an incorrect amount of memory if the element size is computed
173 * within the function. Even with the size passed as a parameter, incorrect
174 * linkage will occur, but as the type is now only present in the cast, it
175 * should not cause problems.
177 template <typename T
>
178 void _snew(const char *name
, const char *file
, int line
,
179 T
* &ptr
, size_t nelem
, size_t elsize
)
181 ptr
= (T
*)save_calloc(name
, file
, line
, nelem
, elsize
);
183 template <typename T
>
184 void _srenew(const char *name
, const char *file
, int line
,
185 T
* &ptr
, size_t nelem
, size_t elsize
)
187 ptr
= (T
*)save_realloc(name
, file
, line
, ptr
, nelem
, elsize
);
189 template <typename T
>
190 void _smalloc(const char *name
, const char *file
, int line
, T
* &ptr
, size_t size
)
192 ptr
= (T
*)save_malloc(name
, file
, line
, size
);
194 template <typename T
>
195 void _srealloc(const char *name
, const char *file
, int line
, T
* &ptr
, size_t size
)
197 ptr
= (T
*)save_realloc(name
, file
, line
, ptr
, size
, sizeof(char));
199 template <typename T
>
200 void _snew_aligned(const char *name
, const char *file
, int line
,
201 T
* &ptr
, size_t nelem
, size_t elsize
, size_t alignment
)
203 ptr
= (T
*)save_calloc_aligned(name
, file
, line
, nelem
, elsize
, alignment
);
206 #define snew(ptr, nelem) _snew(#ptr, __FILE__, __LINE__, (ptr), (nelem), sizeof(*(ptr)))
207 #define srenew(ptr, nelem) _srenew(#ptr, __FILE__, __LINE__, (ptr), (nelem), sizeof(*(ptr)))
208 #define smalloc(ptr, size) _smalloc(#ptr, __FILE__, __LINE__, (ptr), (size))
209 #define srealloc(ptr, size) _srealloc(#ptr, __FILE__, __LINE__, (ptr), (size))
210 #define snew_aligned(ptr, nelem, alignment) _snew_aligned(#ptr, __FILE__, __LINE__, (ptr), (nelem), sizeof(*(ptr)), alignment)
214 /* These macros work in C, not in C++ */
215 #define snew(ptr, nelem) (ptr) = save_calloc(#ptr, __FILE__, __LINE__, \
216 (nelem), sizeof(*(ptr)))
217 #define srenew(ptr, nelem) (ptr) = save_realloc(#ptr, __FILE__, __LINE__, \
218 (ptr), (nelem), sizeof(*(ptr)))
219 #define smalloc(ptr, size) (ptr) = save_malloc(#ptr, __FILE__, __LINE__, size)
220 #define scalloc(ptr, nelem, elsize) \
221 (ptr) = save_calloc(#ptr, __FILE__, __LINE__, nelem, elsize)
222 #define srealloc(ptr, size) (ptr) = save_realloc(#ptr, __FILE__, __LINE__, \
224 #define snew_aligned(ptr, nelem, alignment) (ptr) = save_calloc_aligned(#ptr, __FILE__, __LINE__, (nelem), sizeof(*(ptr)), alignment)
227 #define sfree(ptr) save_free(#ptr, __FILE__, __LINE__, (ptr))
229 /* call this ONLY with a pointer obtained through snew_aligned or
231 #define sfree_aligned(ptr) save_free_aligned(#ptr, __FILE__, __LINE__, (ptr))
233 #endif /* _smalloc_h */