src/gromacs/legacyheaders/smalloc.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 1991-2000, University of Groningen, The Netherlands.
   5  * Copyright (c) 2001-2004, The GROMACS development team.
   6  * Copyright (c) 2013, 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.
  10  *
  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.
  15  *
  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.
  20  *
  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.
  25  *
  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.
  33  *
  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.
  36  */
  37
  38 #ifndef _smalloc_h
  39 #define _smalloc_h
  40
  41 #include <stdlib.h>
  42
  43 /*
  44  * Memory allocation routines in gromacs:
  45  *
  46  * If an allocation fails, the program is halted by means of the
  47  * fatal_error routine, which outputs source file and line number
  48  * and the name of the variable involved.
  49  *
  50  * Macro's which can be used:
  51  *
  52  * snew(ptr,nelem)
  53  *    Allocates memory for nelem elements and returns this in ptr.
  54  *    The allocated memory is initialized to zeros.
  55  *
  56  * srenew(ptr,nelem)
  57  *    Reallocates memory for nelem elements and returns this in ptr.
  58  *
  59  * smalloc(ptr,size)
  60  *    Allocates memory for size bytes and returns this in ptr.
  61  *
  62  * scalloc(ptr,nelem,elsize)
  63  *    Allocates memory for nelem elements of size elsize and returns
  64  *    this in ptr.
  65  *
  66  * srealloc(ptr,size)
  67  *    Reallocates memory for size bytes and returns this in ptr.
  68  *
  69  * sfree(ptr)
  70  *    Frees memory referenced by ptr.
  71  *
  72  * snew_aligned(ptr,nelem,alignment)
  73  *    Allocates memory for nelem elements and returns this in ptr.
  74  *    The allocated memory is initialized to zeroes.
  75  *    alignment=n will constrain ptr to be n-byte aligned.
  76  *    This pointer should only be freed with sfree_aligned, since
  77  *    it may not be the value returned by the underlying malloc.
  78  *
  79  * sfree_aligned(ptr)
  80  *    Frees aligned memory referenced by ptr.
  81  *
  82  ****************************************************************************
  83  *
  84  * Functions which are used by the macro's:
  85  *
  86  * extern void *save_malloc(char *name,char *file,int line,int size);
  87  *    Like alloc, returns a pointer to the allocated space, uses name, file
  88  *    and line to generate an error message when allocation failed.
  89  *
  90  * extern void *save_calloc(char *name,char *file,int line,
  91  *                          size_t nelem,size_t elsize);
  92  *    Like calloc, returns a pointer to the allocated space, uses name, file
  93  *    and line to generate an error message when allocation failed.
  94  *
  95  * extern void *save_realloc(char *name,char *file,int line,
  96  *                           void *ptr,size_t size);
  97  *    Like realloc, returns a pointer to the allocated space, uses name, file
  98  *    and line to generate an error message when allocation failed.
  99  *    If ptr equals NULL, malloc is called in stead of realloc, in this way
 100  *    it is possible to combine first and later allocations.
 101  *
 102  * extern void save_free(char *name,char *file,int line, void *ptr);
 103  *    Like free, uses name, file and line to generate an error message when
 104  *    the free failed.
 105  *
 106  * extern size_t maxavail();
 107  *    Returns the maximum available allocation unit, by applying a binary
 108  *    search on the largest block of memory available. After allocation
 109  *    it invokes free to restore the original state. So it is important
 110  *    that free can undo the effect of a malloc.
 111  *
 112  * extern size_t memavail();
 113  *    Returns the total of available allocation unit, by applying maxavail
 114  *    until no space is left, it then frees all allocated space and returns
 115  *    the sum of the previously allocated space. As mentioned with maxavail,
 116  *    it is important that free can undo the effect of a malloc.
 117  *
 118  * extern void *save_malloc_aligned(char *name,char *file,int line,size_t size,size_t alignment);
 119  *    Like alloc, returns a pointer to the allocated space, uses name, file
 120  *    and line to generate an error message when allocation failed.
 121  *    The returned pointer will be n-byte aligned, where n=alignment.
 122  *    The pointer should only be freed with a call to save_free.
 123  *
 124  * extern void save_free_aligned(char *name,char *file,int line, void *ptr);
 125  *    Like free, uses name, file and line to generate an error message when
 126  *    the free failed. This function is intended to be called for
 127  *    pointers allocated with save_malloc_aligned, and may not work
 128  *    on normal pointers.
 129  */
 130
 131 #ifdef __cplusplus
 132 extern "C" {
 133 #endif
 134
 135 void *save_malloc(const char *name, const char *file, int line, size_t size);
 136 void *save_calloc(const char *name, const char *file, int line,
 137                   size_t nelem, size_t elsize);
 138 void *save_realloc(const char *name, const char *file, int line,
 139                    void *ptr, size_t nelem, size_t elsize);
 140 void save_free(const char *name, const char *file, int line, void *ptr);
 141 size_t maxavail(void);
 142 size_t memavail(void);
 143
 144 /* Aligned-memory counterparts */
 145
 146 void *save_malloc_aligned(const char *name, const char *file, int line,
 147                           unsigned nelem, size_t elsize, size_t alignment);
 148 void *save_calloc_aligned(const char *name, const char *file, int line,
 149                           unsigned nelem, size_t elsize, size_t alignment);
 150 void save_free_aligned(const char *name, const char *file, int line, void *ptr);
 151
 152 #ifdef __cplusplus
 153 }
 154
 155 /* Use of sizeof(T) in _snew() and _srenew() can cause obscure bugs if
 156  * several files define distinct data structures with identical names and
 157  * allocate memory for them using the macros below.  Note that by the standard,
 158  * such declarations cause undefined behavior.
 159  * The C versions work fine in such cases, but when compiled with a C++
 160  * compiler (and if the compiler does not inline the calls), the linker cannot
 161  * tell that data structures with identical names are actually different and
 162  * links calls to these template functions incorrectly, which can result in
 163  * allocation of an incorrect amount of memory if the element size is computed
 164  * within the function.
 165  *
 166  * This could be solved by passing the size as a parameter, but this has other
 167  * issues: it provokes warnings from cppcheck for some invokations.
 168  * Even with the size passed as a parameter, incorrect linkage will occur.
 169  * When converting files to C++, locally declared structs should be enclosed in
 170  * anonymous namespaces or some other means taken to ensure they are unique.
 171  */
 172 template <typename T> inline
 173 void _snew(const char *name, const char *file, int line,
 174            T * &ptr, size_t nelem)
 175 {
 176     ptr = (T *)save_calloc(name, file, line, nelem, sizeof(T));
 177 }
 178 template <typename T> inline
 179 void _srenew(const char *name, const char *file, int line,
 180              T * &ptr, size_t nelem)
 181 {
 182     ptr = (T *)save_realloc(name, file, line, ptr, nelem, sizeof(T));
 183 }
 184 template <typename T> inline
 185 void _smalloc(const char *name, const char *file, int line, T * &ptr, size_t size)
 186 {
 187     ptr = (T *)save_malloc(name, file, line, size);
 188 }
 189 template <typename T> inline
 190 void _srealloc(const char *name, const char *file, int line, T * &ptr, size_t size)
 191 {
 192     ptr = (T *)save_realloc(name, file, line, ptr, size, sizeof(char));
 193 }
 194 template <typename T> inline
 195 void _snew_aligned(const char *name, const char *file, int line,
 196                    T * &ptr, size_t nelem, size_t alignment)
 197 {
 198     ptr = (T *)save_calloc_aligned(name, file, line, nelem, sizeof(T), alignment);
 199 }
 200
 201 #define snew(ptr, nelem) _snew(#ptr, __FILE__, __LINE__, (ptr), (nelem))
 202 #define srenew(ptr, nelem) _srenew(#ptr, __FILE__, __LINE__, (ptr), (nelem))
 203 #define smalloc(ptr, size) _smalloc(#ptr, __FILE__, __LINE__, (ptr), (size))
 204 #define srealloc(ptr, size) _srealloc(#ptr, __FILE__, __LINE__, (ptr), (size))
 205 #define snew_aligned(ptr, nelem, alignment) _snew_aligned(#ptr, __FILE__, __LINE__, (ptr), (nelem), alignment)
 206
 207 #else /* __cplusplus */
 208
 209 /* These macros work in C, not in C++ */
 210 #define snew(ptr, nelem) (ptr) = save_calloc(#ptr, __FILE__, __LINE__, \
 211                                              (nelem), sizeof(*(ptr)))
 212 #define srenew(ptr, nelem) (ptr) = save_realloc(#ptr, __FILE__, __LINE__, \
 213                                                 (ptr), (nelem), sizeof(*(ptr)))
 214 #define smalloc(ptr, size) (ptr) = save_malloc(#ptr, __FILE__, __LINE__, size)
 215 #define scalloc(ptr, nelem, elsize) \
 216     (ptr) = save_calloc(#ptr, __FILE__, __LINE__, nelem, elsize)
 217 #define srealloc(ptr, size) (ptr) = save_realloc(#ptr, __FILE__, __LINE__, \
 218                                                  (ptr), size, 1)
 219 #define snew_aligned(ptr, nelem, alignment) (ptr) = save_calloc_aligned(#ptr, __FILE__, __LINE__, (nelem), sizeof(*(ptr)), alignment)
 220 #endif /* __cplusplus */
 221
 222 #define sfree(ptr) save_free(#ptr, __FILE__, __LINE__, (ptr))
 223
 224 /* call this ONLY with a pointer obtained through snew_aligned or
 225    smalloc_aligned: */
 226 #define sfree_aligned(ptr) save_free_aligned(#ptr, __FILE__, __LINE__, (ptr))
 227
 228 #ifdef __cplusplus
 229
 230 #include "../utility/common.h"
 231
 232 namespace gmx
 233 {
 234
 235 /*! \brief
 236  * Stripped-down version of scoped_ptr that uses sfree().
 237  *
 238  * Currently only implements constructor from a pointer value and destructor;
 239  * other operations can be added if they become necessary.
 240  *
 241  * This is currently in smalloc.h, as this header also declares sfree().
 242  * If more flexible guards/smart pointers are needed for C pointers, this class
 243  * should be moved to a separate header under src/gromacs/utility/ together
 244  * with that more flexible implementation.
 245  * Currently, boost::shared_ptr is used in a few locations, but is not suitable
 246  * for all cases.  A scoped_ptr with deleter support would be a general enough
 247  * implementation for all uses.  C++11 unique_ptr has this, but for non-C++11
 248  * suppoer we need something else.
 249  *
 250  * Methods in this class do not throw.
 251  */
 252 class scoped_ptr_sfree
 253 {
 254     public:
 255         /*! \brief
 256          * Initializes a scoped_ptr that frees \p ptr on scope exit.
 257          *
 258          * \param[in] ptr  Pointer to use for initialization.
 259          */
 260         explicit scoped_ptr_sfree(void *ptr) : ptr_(ptr) {}
 261         //! Frees the pointer passed to the constructor.
 262         ~scoped_ptr_sfree() { sfree(ptr_); }
 263
 264     private:
 265         void                   *ptr_;
 266
 267         GMX_DISALLOW_COPY_AND_ASSIGN(scoped_ptr_sfree);
 268 };
 269
 270 }      // namespace gmx
 271 #endif /* __cplusplus */
 272
 273 #endif /* _smalloc_h */