src/gromacs/utility/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,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.
  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 /*! \file
  38  * \brief
  39  * C memory allocation routines for \Gromacs.
  40  *
  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.
  44  *
  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.
  52  *
  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
  58  * invoke it.
  59  *
  60  * \if internal
  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.
  66  * \endif
  67  *
  68  * \inpublicapi
  69  * \ingroup module_utility
  70  */
  71 #ifndef GMX_UTILITY_SMALLOC_H
  72 #define GMX_UTILITY_SMALLOC_H
  73
  74 #include <stddef.h>
  75
  76 #ifdef __cplusplus
  77 extern "C" {
  78 #endif
  79
  80 /*! \brief
  81  * \Gromacs wrapper for malloc().
  82  *
  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.
  88  *
  89  * This should generally be called through smalloc(), not directly.
  90  */
  91 void *save_malloc(const char *name, const char *file, int line, size_t size);
  92 /*! \brief
  93  * \Gromacs wrapper for calloc().
  94  *
  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.
 101  *
 102  * This should generally be called through snew(), not directly.
 103  */
 104 void *save_calloc(const char *name, const char *file, int line,
 105                   size_t nelem, size_t elsize);
 106 /*! \brief
 107  * \Gromacs wrapper for realloc().
 108  *
 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.
 116  *
 117  * As with realloc(), if \p ptr is NULL, memory is allocated as if malloc() was
 118  * called.
 119  * This should generally be called through srenew(), not directly.
 120  *
 121  * Note that the allocated memory is not initialized to zero.
 122  */
 123 void *save_realloc(const char *name, const char *file, int line,
 124                    void *ptr, size_t nelem, size_t elsize);
 125 /*! \brief
 126  * \Gromacs wrapper for free().
 127  *
 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).
 132  *
 133  * If \p ptr is NULL, does nothing.
 134  * This should generally be called through sfree(), not directly.
 135  * This never fails.
 136  */
 137 void save_free(const char *name, const char *file, int line, void *ptr);
 138
 139 /*! \brief
 140  * \Gromacs wrapper for allocating aligned memory.
 141  *
 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
 149  *     boundary.
 150  *
 151  * There is no macro that invokes this function.
 152  *
 153  * The returned pointer should only be freed with a call to save_free_aligned().
 154  */
 155 void *save_malloc_aligned(const char *name, const char *file, int line,
 156                           size_t nelem, size_t elsize, size_t alignment);
 157 /*! \brief
 158  * \Gromacs wrapper for allocating zero-initialized aligned memory.
 159  *
 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
 167  *     boundary.
 168  *
 169  * This should generally be called through snew_aligned(), not directly.
 170  *
 171  * The returned pointer should only be freed with a call to save_free_aligned().
 172  */
 173 void *save_calloc_aligned(const char *name, const char *file, int line,
 174                           size_t nelem, size_t elsize, size_t alignment);
 175 /*! \brief
 176  * \Gromacs wrapper for freeing aligned memory.
 177  *
 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).
 182  *
 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.
 187  * This never fails.
 188  */
 189 void save_free_aligned(const char *name, const char *file, int line, void *ptr);
 190
 191 #ifdef __cplusplus
 192 }
 193 #endif
 194
 195 #ifdef __cplusplus
 196 /*! \cond internal */
 197 /*! \name Implementation templates for C++ memory allocation macros
 198  *
 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.
 202  *
 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.
 212  *
 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.
 216  */
 217 /*! \{ */
 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)
 222 {
 223     ptr = (T *)save_calloc(name, file, line, nelem, sizeof(T));
 224 }
 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)
 229 {
 230     ptr = (T *)save_realloc(name, file, line, ptr, nelem, sizeof(T));
 231 }
 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)
 236 {
 237     ptr = (T *)save_malloc(name, file, line, size);
 238 }
 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)
 243 {
 244     ptr = (T *)save_calloc_aligned(name, file, line, nelem, sizeof(T), alignment);
 245 }
 246 /*! \] */
 247 /*! \endcond */
 248 #endif /* __cplusplus */
 249
 250 /*! \def snew
 251  * \brief
 252  * Allocates memory for a given number of elements.
 253  *
 254  * \param[out] ptr   Pointer to allocate.
 255  * \param[in]  nelem Number of elements to allocate.
 256  *
 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.
 259  *
 260  * \hideinitializer
 261  */
 262 /*! \def srenew
 263  * \brief
 264  * Reallocates memory for a given number of elements.
 265  *
 266  * \param[in,out] ptr   Pointer to allocate/reallocate.
 267  * \param[in]     nelem Number of elements to allocate.
 268  *
 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().
 274  *
 275  * \hideinitializer
 276  */
 277 /*! \def smalloc
 278  * \brief
 279  * Allocates memory for a given number of bytes.
 280  *
 281  * \param[out] ptr  Pointer to allocate.
 282  * \param[in]  size Number of bytes to allocate.
 283  *
 284  * Allocates memory for \p size bytes and sets this to \p ptr.
 285  * The allocated memory is initialized to zero.
 286  *
 287  * \hideinitializer
 288  */
 289 /*! \def snew_aligned
 290  * \brief
 291  * Allocates aligned memory for a given number of elements.
 292  *
 293  * \param[out] ptr       Pointer to allocate.
 294  * \param[in]  nelem     Number of elements to allocate.
 295  * \param[in]  alignment Requested alignment in bytes.
 296  *
 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.
 300  *
 301  * The returned pointer should only be freed with sfree_aligned().
 302  *
 303  * \hideinitializer
 304  */
 305 #ifdef __cplusplus
 306
 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)
 316
 317 #else
 318
 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)
 328
 329 #endif
 330
 331 /*! \brief
 332  * Frees memory referenced by \p ptr.
 333  *
 334  * \p ptr is allowed to be NULL, in which case nothing is done.
 335  *
 336  * \hideinitializer
 337  */
 338 #define sfree(ptr) save_free(#ptr, __FILE__, __LINE__, (ptr))
 339
 340 /*! \brief
 341  * Frees aligned memory referenced by \p ptr.
 342  *
 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.
 345  *
 346  * \hideinitializer
 347  */
 348 #define sfree_aligned(ptr) save_free_aligned(#ptr, __FILE__, __LINE__, (ptr))
 349
 350 #endif