include/smalloc.h

   1 /*
   2  * $Id$
   3  *
   4  *                This source code is part of
   5  *
   6  *                 G   R   O   M   A   C   S
   7  *
   8  *          GROningen MAchine for Chemical Simulations
   9  *
  10  *                        VERSION 3.0
  11  *
  12  * Copyright (c) 1991-2001
  13  * BIOSON Research Institute, Dept. of Biophysical Chemistry
  14  * University of Groningen, The Netherlands
  15  *
  16  * This program is free software; you can redistribute it and/or
  17  * modify it under the terms of the GNU General Public License
  18  * as published by the Free Software Foundation; either version 2
  19  * of the License, or (at your option) any later version.
  20  *
  21  * If you want to redistribute modifications, please consider that
  22  * scientific software is very special. Version control is crucial -
  23  * bugs must be traceable. We will be happy to consider code for
  24  * inclusion in the official distribution, but derived work must not
  25  * be called official GROMACS. Details are found in the README & COPYING
  26  * files - if they are missing, get the official version at www.gromacs.org.
  27  *
  28  * To help us fund GROMACS development, we humbly ask that you cite
  29  * the papers on the package - you can find them in the top README file.
  30  *
  31  * Do check out http://www.gromacs.org , or mail us at gromacs@gromacs.org .
  32  *
  33  * And Hey:
  34  * Good ROcking Metal Altar for Chronical Sinners
  35  */
  36
  37 #ifndef _smalloc_h
  38 #define _smalloc_h
  39
  40 static char *SRCID_smalloc_h = "$Id$";
  41 #ifdef HAVE_CONFIG_H
  42 #include <config.h>
  43 #endif
  44
  45 #ifdef HAVE_IDENT
  46 #ident  "@(#) smalloc.h 1.14 11/23/92"
  47 #endif /* HAVE_IDENT */
  48
  49 /*
  50  * Memory allocation routines in gromacs:
  51  *
  52  * If an allocation fails, the program is halted by means of the
  53  * fatal_error routine, which outputs source file and line number
  54  * and the name of the variable involved.
  55  *
  56  * Macro's which can be used:
  57  *
  58  * snew(ptr,nelem)
  59  *    Allocates memory for nelem elements and returns this in ptr.
  60  *    The allocated memory is initialized to zeros.
  61  *
  62  * srenew(ptr,nelem)
  63  *    Reallocates memory for nelem elements and returns this in ptr.
  64  *
  65  * smalloc(ptr,size)
  66  *    Allocates memory for size bytes and returns this in ptr.
  67  *
  68  * scalloc(ptr,nelem,elsize)
  69  *    Allocates memory for nelem elements of size elsize and returns
  70  *    this in ptr.
  71  *
  72  * srealloc(ptr,size)
  73  *    Reallocates memory for size bytes and returns this in ptr.
  74  *
  75  * sfree(ptr)
  76  *    Frees memory referenced by ptr.
  77  *
  78  ****************************************************************************
  79  *
  80  * Functions which are used by the macro's:
  81  *
  82  * extern void *save_malloc(char *name,char *file,int line,int size);
  83  *    Like alloc, returns a pointer to the allocated space, uses name, file
  84  *    and line to generate an error message when allocation failed.
  85  *
  86  * extern void *save_calloc(char *name,char *file,int line,
  87  *                          unsigned nelem,unsigned elsize);
  88  *    Like calloc, returns a pointer to the allocated space, uses name, file
  89  *    and line to generate an error message when allocation failed.
  90  *
  91  * extern void *save_realloc(char *name,char *file,int line,
  92  *                           void *ptr,unsigned size);
  93  *    Like realloc, returns a pointer to the allocated space, uses name, file
  94  *    and line to generate an error message when allocation failed.
  95  *    If ptr equals NULL, malloc is called in stead of realloc, in this way
  96  *    it is possible to combine first and later allocations.
  97  *
  98  * extern void save_free(char *name,char *file,int line,void *ptr);
  99  *    Like free, uses name, file and line to generate an error message when
 100  *    the free failed.
 101  *
 102  * extern unsigned maxavail();
 103  *    Returns the maximum available allocation unit, by applying a binary
 104  *    search on the largest block of memory available. After allocation
 105  *    it invokes free to restore the original state. So it is important
 106  *    that free can undo the effect of a malloc.
 107  *
 108  * extern unsigned memavail();
 109  *    Returns the total of available allocation unit, by applying maxavail
 110  *    until no space is left, it then frees all allocated space and returns
 111  *    the sum of the previously allocated space. As mentioned with maxavail,
 112  *    it is important that free can undo the effect of a malloc.
 113  *
 114  */
 115
 116 #define snew(ptr,nelem) (ptr)=save_calloc(#ptr,__FILE__,__LINE__,\
 117                         (nelem),sizeof(*(ptr)))
 118 #define srenew(ptr,nelem) (ptr)=save_realloc(#ptr,__FILE__,__LINE__,\
 119                         (ptr),(nelem)*sizeof(*(ptr)))
 120 #define smalloc(ptr,size) (ptr)=save_malloc(#ptr,__FILE__,__LINE__,size)
 121 #define scalloc(ptr,nelem,elsize)\
 122                 (ptr)=save_calloc(#ptr,__FILE__,__LINE__,nelem,elsize)
 123 #define srealloc(ptr,size) (ptr)=save_realloc(#ptr,__FILE__,__LINE__,\
 124                         (ptr),size)
 125 #define sfree(ptr) save_free(#ptr,__FILE__,__LINE__,(ptr))
 126
 127 #ifdef CPLUSPLUS
 128 extern "C" {
 129 #endif
 130
 131 void *save_malloc(char *name,char *file,int line,int size);
 132 void *save_calloc(char *name,char *file,int line,
 133                   unsigned nelem,unsigned elsize);
 134 void *save_realloc(char *name,char *file,int line,
 135                    void *ptr,unsigned size);
 136 void save_free(char *name,char *file,int line,void *ptr);
 137 unsigned maxavail(void);
 138 unsigned memavail(void);
 139
 140 #ifdef CPLUSPLUS
 141 }
 142 #endif
 143
 144 #endif  /* _smalloc_h */