include/smalloc.h

   1 /*
   2  *
   3  *                This source code is part of
   4  *
   5  *                 G   R   O   M   A   C   S
   6  *
   7  *          GROningen MAchine for Chemical Simulations
   8  *
   9  *                        VERSION 3.2.0
  10  * Written by David van der Spoel, Erik Lindahl, Berk Hess, and others.
  11  * Copyright (c) 1991-2000, University of Groningen, The Netherlands.
  12  * Copyright (c) 2001-2004, The GROMACS development team,
  13  * check out http://www.gromacs.org for more information.
  14
  15  * This program is free software; you can redistribute it and/or
  16  * modify it under the terms of the GNU General Public License
  17  * as published by the Free Software Foundation; either version 2
  18  * of the License, or (at your option) any later version.
  19  *
  20  * If you want to redistribute modifications, please consider that
  21  * scientific software is very special. Version control is crucial -
  22  * bugs must be traceable. We will be happy to consider code for
  23  * inclusion in the official distribution, but derived work must not
  24  * be called official GROMACS. Details are found in the README & COPYING
  25  * files - if they are missing, get the official version at www.gromacs.org.
  26  *
  27  * To help us fund GROMACS development, we humbly ask that you cite
  28  * the papers on the package - you can find them in the top README file.
  29  *
  30  * For more info, check our website at http://www.gromacs.org
  31  *
  32  * And Hey:
  33  * Gromacs Runs On Most of All Computer Systems
  34  */
  35
  36 #ifndef _smalloc_h
  37 #define _smalloc_h
  38
  39 #ifdef HAVE_CONFIG_H
  40 #include <config.h>
  41 #endif
  42
  43 #include <stdlib.h>
  44
  45 /*
  46  * Memory allocation routines in gromacs:
  47  *
  48  * If an allocation fails, the program is halted by means of the
  49  * fatal_error routine, which outputs source file and line number
  50  * and the name of the variable involved.
  51  *
  52  * Macro's which can be used:
  53  *
  54  * snew(ptr,nelem)
  55  *    Allocates memory for nelem elements and returns this in ptr.
  56  *    The allocated memory is initialized to zeros.
  57  *
  58  * srenew(ptr,nelem)
  59  *    Reallocates memory for nelem elements and returns this in ptr.
  60  *
  61  * smalloc(ptr,size)
  62  *    Allocates memory for size bytes and returns this in ptr.
  63  *
  64  * scalloc(ptr,nelem,elsize)
  65  *    Allocates memory for nelem elements of size elsize and returns
  66  *    this in ptr.
  67  *
  68  * srealloc(ptr,size)
  69  *    Reallocates memory for size bytes and returns this in ptr.
  70  *
  71  * sfree(ptr)
  72  *    Frees memory referenced by ptr.
  73  *
  74  * snew_aligned(ptr,nelem,alignment)
  75  *    Allocates memory for nelem elements and returns this in ptr.
  76  *    The allocated memory is initialized to zeroes.
  77  *    alignment=n will constrain ptr to be n-byte aligned.
  78  *    This pointer should only be freed with sfree_aligned, since
  79  *    it may not be the value returned by the underlying malloc.
  80  *
  81  * sfree_aligned(ptr)
  82  *    Frees aligned memory referenced by ptr.
  83  *
  84  ****************************************************************************
  85  *
  86  * Functions which are used by the macro's:
  87  *
  88  * extern void *save_malloc(char *name,char *file,int line,int size);
  89  *    Like alloc, returns a pointer to the allocated space, uses name, file
  90  *    and line to generate an error message when allocation failed.
  91  *
  92  * extern void *save_calloc(char *name,char *file,int line,
  93  *                          size_t nelem,size_t elsize);
  94  *    Like calloc, returns a pointer to the allocated space, uses name, file
  95  *    and line to generate an error message when allocation failed.
  96  *
  97  * extern void *save_realloc(char *name,char *file,int line,
  98  *                           void *ptr,size_t size);
  99  *    Like realloc, returns a pointer to the allocated space, uses name, file
 100  *    and line to generate an error message when allocation failed.
 101  *    If ptr equals NULL, malloc is called in stead of realloc, in this way
 102  *    it is possible to combine first and later allocations.
 103  *
 104  * extern void save_free(char *name,char *file,int line, void *ptr);
 105  *    Like free, uses name, file and line to generate an error message when
 106  *    the free failed.
 107  *
 108  * extern size_t maxavail();
 109  *    Returns the maximum available allocation unit, by applying a binary
 110  *    search on the largest block of memory available. After allocation
 111  *    it invokes free to restore the original state. So it is important
 112  *    that free can undo the effect of a malloc.
 113  *
 114  * extern size_t memavail();
 115  *    Returns the total of available allocation unit, by applying maxavail
 116  *    until no space is left, it then frees all allocated space and returns
 117  *    the sum of the previously allocated space. As mentioned with maxavail,
 118  *    it is important that free can undo the effect of a malloc.
 119  *
 120  * extern void *save_malloc_aligned(char *name,char *file,int line,size_t size,size_t alignment);
 121  *    Like alloc, returns a pointer to the allocated space, uses name, file
 122  *    and line to generate an error message when allocation failed.
 123  *    The returned pointer will be n-byte aligned, where n=alignment.
 124  *    The pointer should only be freed with a call to save_free.
 125  *
 126  * extern void save_free_aligned(char *name,char *file,int line, void *ptr);
 127  *    Like free, uses name, file and line to generate an error message when
 128  *    the free failed. This function is intended to be called for
 129  *    pointers allocated with save_malloc_aligned, and may not work
 130  *    on normal pointers.
 131  */
 132
 133 #ifdef __cplusplus
 134 extern "C" {
 135 #endif
 136
 137 void *save_malloc(const char *name,const char *file,int line,size_t size);
 138 void *save_calloc(const char *name,const char *file,int line,
 139                   size_t nelem,size_t elsize);
 140 void *save_realloc(const char *name,const char *file,int line,
 141                    void *ptr,size_t nelem,size_t elsize);
 142 void save_free(const char *name,const char *file,int line, void *ptr);
 143 size_t maxavail(void);
 144 size_t memavail(void);
 145
 146 /* Aligned-memory counterparts */
 147
 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.
 158  * For this reason, the size of an element is passed as a parameter.
 159  *
 160  * The C versions work fine in such cases, but when compiled with a C++
 161  * compiler (and if the compiler does not inline the calls), the linker cannot
 162  * tell that data structures with identical names are actually different and
 163  * links calls to these template functions incorrectly, which can result in
 164  * allocation of an incorrect amount of memory if the element size is computed
 165  * within the function. Even with the size passed as a parameter, incorrect
 166  * linkage will occur, but as the type is now only present in the cast, it
 167  * should not cause problems.
 168  */
 169 template <typename T>
 170 void _snew(const char *name, const char *file, int line,
 171            T *&ptr, size_t nelem, size_t elsize)
 172 {
 173     ptr = (T *)save_calloc(name, file, line, nelem, elsize);
 174 }
 175 template <typename T>
 176 void _srenew(const char *name, const char *file, int line,
 177              T *&ptr, size_t nelem, size_t elsize)
 178 {
 179     ptr = (T *)save_realloc(name, file, line, ptr, nelem, elsize);
 180 }
 181 template <typename T>
 182 void _smalloc(const char *name, const char *file, int line, T *&ptr, size_t size)
 183 {
 184     ptr = (T *)save_malloc(name, file, line, size);
 185 }
 186 template <typename T>
 187 void _srealloc(const char *name, const char *file, int line, T *&ptr, size_t size)
 188 {
 189     ptr = (T *)save_realloc(name, file, line, ptr, size, sizeof(char));
 190 }
 191 template <typename T>
 192 void _snew_aligned(const char *name, const char *file, int line,
 193                    T *&ptr, size_t nelem, size_t elsize,size_t alignment)
 194 {
 195   ptr = (T *)save_calloc_aligned(name, file, line, nelem, elsize, alignment);
 196 }
 197
 198 #define snew(ptr,nelem) _snew(#ptr,__FILE__,__LINE__,(ptr),(nelem),sizeof(*(ptr)))
 199 #define srenew(ptr,nelem) _srenew(#ptr,__FILE__,__LINE__,(ptr),(nelem),sizeof(*(ptr)))
 200 #define smalloc(ptr, size) _smalloc(#ptr,__FILE__,__LINE__,(ptr),(size))
 201 #define srealloc(ptr, size) _srealloc(#ptr,__FILE__,__LINE__,(ptr),(size))
 202 #define snew_aligned(ptr,nelem,alignment) _snew_aligned(#ptr,__FILE__,__LINE__,(ptr),(nelem),sizeof(*(ptr)),alignment)
 203
 204 #else
 205
 206 /* These macros work in C, not in C++ */
 207 #define snew(ptr,nelem) (ptr)=save_calloc(#ptr,__FILE__,__LINE__,\
 208                         (nelem),sizeof(*(ptr)))
 209 #define srenew(ptr,nelem) (ptr)=save_realloc(#ptr,__FILE__,__LINE__,\
 210                         (ptr),(nelem),sizeof(*(ptr)))
 211 #define smalloc(ptr,size) (ptr)=save_malloc(#ptr,__FILE__,__LINE__,size)
 212 #define scalloc(ptr,nelem,elsize)\
 213                 (ptr)=save_calloc(#ptr,__FILE__,__LINE__,nelem,elsize)
 214 #define srealloc(ptr,size) (ptr)=save_realloc(#ptr,__FILE__,__LINE__,\
 215                         (ptr),size,1)
 216 #define snew_aligned(ptr,nelem,alignment) (ptr)=save_calloc_aligned(#ptr,__FILE__,__LINE__,(nelem),sizeof(*(ptr)),alignment)
 217 #endif
 218
 219 #define sfree(ptr) save_free(#ptr,__FILE__,__LINE__,(ptr))
 220
 221 /* call this ONLY with a pointer obtained through snew_aligned or
 222    smalloc_aligned: */
 223 #define sfree_aligned(ptr) save_free_aligned(#ptr,__FILE__,__LINE__,(ptr))
 224
 225 #endif  /* _smalloc_h */