include/memtab.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.1
  11  * Copyright (c) 1991-2001, University of Groningen, The Netherlands
  12  * This program is free software; you can redistribute it and/or
  13  * modify it under the terms of the GNU General Public License
  14  * as published by the Free Software Foundation; either version 2
  15  * of the License, or (at your option) any later version.
  16  *
  17  * If you want to redistribute modifications, please consider that
  18  * scientific software is very special. Version control is crucial -
  19  * bugs must be traceable. We will be happy to consider code for
  20  * inclusion in the official distribution, but derived work must not
  21  * be called official GROMACS. Details are found in the README & COPYING
  22  * files - if they are missing, get the official version at www.gromacs.org.
  23  *
  24  * To help us fund GROMACS development, we humbly ask that you cite
  25  * the papers on the package - you can find them in the top README file.
  26  *
  27  * For more info, check our website at http://www.gromacs.org
  28  *
  29  * And Hey:
  30  * Getting the Right Output Means no Artefacts in Calculating Stuff
  31  */
  32
  33 #ifndef _memtab_h
  34 #define _memtab_h
  35
  36 static char *SRCID_memtab_h = "$Id$";
  37 #ifdef HAVE_CONFIG_H
  38 #include <config.h>
  39 #endif
  40
  41 #ifdef HAVE_IDENT
  42 #ident  "@(#) memtab.h 1.12 12/16/92"
  43 #endif /* HAVE_IDENT */
  44
  45 /*
  46  * This module is intended for alloc(at)ing memory in one contiguous
  47  * block, using only local references. All references within this block
  48  * are made relative to the start of the block. This means that before
  49  * using a pointer in this block, they must be reallocated, simply by
  50  * adding the base address to the pointer value.
  51  */
  52
  53 #define NOENTRY         -1      /* Denotes a NULL pointer reference     */
  54
  55 typedef struct
  56 {
  57   void *ref;            /* The "physical" address of an entry           */
  58   void *handle;         /* The associated handle                        */
  59 } t_mref;
  60
  61 typedef struct
  62 {
  63   int nref;             /* The number of inserted references            */
  64   t_mref *refs;         /* The inserted references and their handles    */
  65   int msize;            /* The total size of the memory allocated sofar */
  66   char *mtab;           /* The allocated memory (one contiguous block)  */
  67 } t_memtab;
  68
  69 extern void init_memtab(t_memtab *mtab);
  70      /*
  71       * Initialises the struct, should be called before any other action
  72       * The function init_memtab() will initialise a struct which can be
  73       * extended by successive invokations of put_memtab().
  74       */
  75
  76 extern void dispose_memtab(t_memtab *mtab);
  77      /*
  78       * Disposes all the memory allocated for the struct. After this
  79       * any reference within the block may become invalid (depends on
  80       * the definition of the free() call).
  81       */
  82
  83 extern void *put_memtab(t_memtab *mtab,int size,void *ref);
  84      /*
  85       * The function put_memtab() returns a handle to the memory block
  86       * specified by pointer ref and size bytes. If the address was inserted
  87       * before in the struct, this (previous) handle will be returned else
  88       * the struct will be extended, a new handle will be created and the
  89       * data will be copied into the struct. Note that the returned handle
  90       * is actually the offset of the copied block within the struct.
  91       * NULL pointers and null sizes will return a handle that will convert
  92       * to NULL after invokation of get_memtab(). Note that after every
  93       * invokation absolute addresses, got before from get_memtab() might
  94       * have changed due to a move within the reallocation.
  95       */
  96
  97 extern void *get_memtab(t_memtab *mtab,void *handle);
  98      /*
  99       * Returns the (physical) address corresponding to the specified handle.
 100       * Handle should be a value returned by put_memtab(). When invoked
 101       * with NULL for handle, get_memtab() returns the base address of
 102       * the allocated block.
 103       */
 104
 105 long wr_memtab(FILE *fp,t_memtab *mtab);
 106      /*
 107       * Writes the referenced contents of the struct to the file specified
 108       * by fp. The function wr_memtab() returnes the number of bytes written.
 109       */
 110
 111 void *rd_memtab(FILE *fp,int size,t_memtab *mtab);
 112      /*
 113       * Extends the struct by reading size bytes from the file specified
 114       * by fp. The function rd_memtab() will return a handle to the read
 115       * block.
 116       */
 117
 118 #endif  /* _memtab_h */