home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 3 / PDCD_3.iso / utilities / utilss / slflex / h / flex
Text File  |  1995-03-25  |  4KB  |  161 lines
  1. /*
  2.  * flex.h
  3.  *
  4.  * A shifting heap
  5.  *
  6.  * © 1994 Straylight
  7.  */
  8.  
  9. #ifndef __flex_h
  10. #define __flex_h
  11.  
  12. /*----- How it all works --------------------------------------------------*
  13.  *
  14.  * In order to allow the blocks to move around, you need to tell flex where
  15.  * your pointer to each block is.  You do this with an anchor pointer (i.e.
  16.  * it points at your anchor for the block).  Flex is quite at liberty to
  17.  * change your anchors at any time it wants to, so if you don't want your
  18.  * blocks to move, don't call flex.  You must ensure that you always access
  19.  * data in flex blocks through the anchor, unless you're really sure the
  20.  * block won't move.
  21.  *
  22.  * Unlike older (Acorn) versions, Straylight flex doesn't ensure that the
  23.  * heap is always as compact as possible.  Instead, calling flex_reduce will
  24.  * attempt to compact the heap a little bit, so if you call it a lot, the
  25.  * heap will eventually become very compact.  It is envisaged that you call
  26.  * flex_reduce every Wimp_Poll.
  27.  *
  28.  * There is another call, flex_compact, which will compact the heap fully.
  29.  * This isn't terribly useful most of the time, since flex compacts itself
  30.  * if it runs out of memory.
  31.  *
  32.  * flex_budge is not currently supported.  If there is a demand for it,
  33.  * it may be added in later.
  34.  */
  35.  
  36. /*
  37.  * A flex anchor pointer
  38.  */
  39.  
  40. typedef void **flex_ptr;
  41.  
  42. /*
  43.  * void flex_init(void)
  44.  *
  45.  * Use
  46.  *  Initialises the flex system.  It doesn't check that any memory is
  47.  *  available.
  48.  */
  49.  
  50. void flex_init(void);
  51.  
  52. /*
  53.  * int flex_alloc(flex_ptr anchor,int size)
  54.  *
  55.  * Use
  56.  *  Allocates size bytes of memory from the flex heap.
  57.  *
  58.  *  Note that if there are no blocks currently allocated prior to making
  59.  *  this call, the block allocated will not be moved by flex.
  60.  *
  61.  * Parameters
  62.  *  flex_ptr anchor == the address of your anchor for this block
  63.  *  int size == size in bytes of the block
  64.  *
  65.  * Returns
  66.  *  0 if it failed.
  67.  */
  68.  
  69. int flex_alloc(flex_ptr anchor,int size);
  70.  
  71. /*
  72.  * void flex_free(flex_ptr anchor)
  73.  *
  74.  * Use
  75.  *  Informs flex that the block pointed to by *anchor isn't useful any
  76.  *  more.
  77.  */
  78.  
  79. void flex_free(flex_ptr anchor);
  80.  
  81. /*
  82.  * int flex_extend(flex_ptr anchor,int newsize)
  83.  *
  84.  * Use
  85.  *  Changes the size of the block pointed to by *anchor.  Note that newsize
  86.  *  is the *NEW SIZE* you want, not an adjustment to the current size as
  87.  *  in flex_midextend.
  88.  *
  89.  * Parameters
  90.  *  flex_ptr anchor == the block to resize
  91.  *  int newsize == the size to make it
  92.  *
  93.  * Returns
  94.  *  0 if it failed
  95.  */
  96.  
  97. int flex_extend(flex_ptr anchor,int newsize);
  98.  
  99. /*
  100.  * int flex_midextend(flex_ptr anchor,int at,int by)
  101.  *
  102.  * Use
  103.  *  Inserts or removes `by' bytes from the block at index `at'.  The insert
  104.  *  or delete is always performed so that the byte that was at `at' is now at
  105.  *  `at'+`by'.  Values of `at' allowable are 0 to flex__size(anchor), and
  106.  *  values of `by' allowable are -flex__size(anchor) to INT_MAX.
  107.  *
  108.  * Parameters
  109.  *  flex_ptr anchor == pointer to the anchor for the block
  110.  *  int at == index at which to extend the block
  111.  *  int by == how much to extend the block by
  112.  *
  113.  * Returns
  114.  *  0 if it failed
  115.  */
  116.  
  117. int flex_midextend(flex_ptr anchor,int at,int by);
  118.  
  119. /*
  120.  * int flex_size(flex_ptr anchor)
  121.  *
  122.  * Use
  123.  *  Tells you how big a flex block is
  124.  *
  125.  * Parameters
  126.  *  flex_ptr anchor == pointer to the block to find size of
  127.  *
  128.  * Returns
  129.  *  Currently allocated size in bytes.
  130.  */
  131.  
  132. int flex_size(flex_ptr anchor);
  133.  
  134. /*
  135.  * void flex_reduce(void)
  136.  *
  137.  * Use
  138.  *  Compacts the heap a bit.  Call it every now and then.
  139.  */
  140.  
  141. void flex_reduce(void);
  142.  
  143. /*
  144.  * void flex_compact(void)
  145.  *
  146.  * Use
  147.  *  Fully compacts the heap.
  148.  */
  149.  
  150. void flex_compact(void);
  151.  
  152. /* --- kernel slot extension functions --- *
  153.  *
  154.  * Only flex_dont_budge is supported at the moment.
  155.  */
  156.  
  157. int flex_dont_budge(int n,void **p);
  158. int flex_budge(int n,void **p);
  159.  
  160. #endif
  161.