mdw@git.distorted.org.uk Git - ssr/blob - StraySrc/Libraries/Steel/h/heap

   1 /*
   2  * heap
   3  *
   4  * A heap system in a flex block
   5  *
   6  * © 1993-1998 Straylight
   7  */
   8
   9 /*----- Licensing note ----------------------------------------------------*
  10  *
  11  * This file is part of Straylight's Steel library.
  12  *
  13  * Steel is free software; you can redistribute it and/or modify
  14  * it under the terms of the GNU General Public License as published by
  15  * the Free Software Foundation; either version 2, or (at your option)
  16  * any later version.
  17  *
  18  * Steel is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU General Public License for more details.
  22  *
  23  * You should have received a copy of the GNU General Public License
  24  * along with Steel.  If not, write to the Free Software Foundation,
  25  * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  26  */
  27
  28 #ifndef __heap_h
  29 #define __heap_h
  30
  31 #ifndef __size_t
  32 #define __size_t 1
  33 typedef unsigned int size_t;   /* from <stddef.h> */
  34 #endif
  35
  36 typedef struct heap_infostr
  37 {
  38   int size;                                   /* Size of the whole heap    */
  39   int free;                                   /* Heap space currently free */
  40   int largest;                                /* Size of the largest block */
  41 }
  42 heap_infostr;
  43
  44 /*
  45  * void heap_init(void)
  46  *
  47  * Use
  48  * Initialises the heap system for use.  This must be called before
  49  *  flex_alloc to ensure that the system gets the first block and so it
  50  *  doesn't move around.  heap doesn't mind this, but your data probably will
  51  *  (if it doen't, why don't you use flex?).
  52  */
  53
  54 void heap_init(void);
  55
  56 /*
  57  * heap_infostr heap_info(void)
  58  *
  59  * Use
  60  *  Describes the heap's current status.
  61  *
  62  * Returns
  63  *  Structure type described above.
  64  */
  65
  66 heap_infostr heap_info(void);
  67
  68 /*
  69  * void *heap_alloc(size_t size)
  70  *
  71  * Use
  72  *  Allocates a block of at least a given size from a heap.  If the heap is
  73  *  not big enough, more is claimed from the operating system.  A NULL
  74  *  pointer is returned if a block of suitable size could not be found.
  75  *
  76  * Parameters
  77  *  size_t size == size of block required
  78  *
  79  * Returns
  80  *  Pointer to block
  81  */
  82
  83 void *heap_alloc(size_t size);
  84
  85 /*
  86  * void heap_free(void *block)
  87  *
  88  * Use
  89  *  Frees a block allocated using heap_alloc.  It tries to shrink the heap
  90  *  as much as possible and to coagulate adjacent free blocks together.
  91  *
  92  * Parameters
  93  *  void *block == pointer to the block to free
  94  */
  95
  96 void heap_free(void *block);
  97
  98 /*
  99  * void *heap_realloc(void *block,int newSize)
 100  *
 101  * Use
 102  *  Changes the size of a heap block.  If possible, the block's position is
 103  *  is unchanged, but this may not always be the case.
 104  *
 105  *  Note that changing a block's size to 0 is permitted.  Passing a NULL
 106  *  pointer will probably result in severe heap death.
 107  *
 108  * Parameters
 109  *  void *block == pointer to the block to change
 110  *  int newSize == the new size to make the block
 111  *
 112  * Returns
 113  *   Pointer to where the block has been moved to, or a NULL pointer if the
 114  *   allocation failed.
 115  */
 116
 117 void *heap_realloc(void *block,int newSize);
 118
 119 #endif