home *** CD-ROM | disk | FTP | other *** search
/ High Voltage Shareware / high1.zip / high1 / DIR9 / HEAP20.ZIP / HEAP.DOC next >
Text File  |  1993-10-05  |  7KB  |  193 lines
  1.                         Unfragmenting Heap Library 2.0
  2.                                 By Tom Ledoux
  3.                                October 5, 1993
  4.  
  5.  
  6. WHAT'S NEW IN 2:
  7. ================
  8.         Improved speed by many times.  The size may be a little bit larger, but
  9. speed is increased when using Halloc() and Hfree().  Instead of searching all
  10. internal variables for a specified handle, now each handle is stored as
  11. Heap[handle-1].  So now a handle can be accessed on the fly instead of
  12. searching for it.  Other than speed, nothing else changed.
  13.  
  14.  
  15. INTRODUCTION:
  16. =============
  17.         When you allocate blocks of memory then free a block in the middle,
  18. you're left with a 'hole'.  This is called memory fragmentation.  You can't
  19. use this 'hole' unless you allocate the same size or smaller, or until all
  20. memory after it is freed.  But now you don't have to worry about memory
  21. fragmentation.  Just use these functions and all your troubles are over.
  22.         This library allocates a base block of memory which all blocks of
  23. memory are contained.  Once a block is freed, all the blocks after it are moved
  24. over to cover up the 'hole'.  Since memory is beeing moved constantly, pointers
  25. are useless after a long period of time.  So communication to the memory blocks
  26. is done by the use of handles.  Handles are just numbers which can be 1 to
  27. 6000.  As the blocks of memory are moved from location to location, the handle
  28. stays the same.  You can find out a blocks memory pointer, but once another
  29. block is freed, that pointer might be invalid.
  30.  
  31. |*| = Blocks of used memory
  32. |-| = Free memory
  33.  
  34. Without the Heap Library
  35. ------------------------
  36. |****|**|*******|****|----|******|***********|****|**|------|
  37.                       Memory is freed, nothing happens.
  38.                       Less contiguous memory is available.
  39.  
  40. With the Heap Library
  41. ---------------------
  42. |****|**|*******|****|******|***********|****|**|-----------|
  43.                       Memory is freed, the rest is moved over.
  44.                       More contiguous memory is available.
  45.  
  46.  
  47. FILES:
  48. ======
  49.         The Heap Library was compiled using Turbo C 2.0 and is provided for
  50. small, medium, large, compact, and huge memory models.  Files included in the
  51. archive are:
  52.          HEAP.DOC - Documentation file
  53.         HTEST.C   - Heap Library example file
  54.          HEAP.H   - Heap Library include file
  55.         HEAPS.LIB - Heap Library library file for the Small memory model
  56.         HEAPM.LIB - Medium
  57.         HEAPL.LIB - Large
  58.         HEAPC.LIB - Compact
  59.         HEAPH.LIB - Huge
  60.      HEAP20_C.ZIP - Turbo C source code for this library
  61.  
  62. To compile the example file, type:
  63.         TCC -ms htest.c heaps.lib
  64.  
  65.  
  66. FUNCTIONS:
  67. ==========
  68. unsigned char  InitHeap(unsigned int handles, unsigned long bytes);
  69.  
  70.    handles - Number of handles to alloc().  Each handle takes 10 bytes.
  71.              Maximum of 6000 handles.
  72.      bytes - Total bytes of base memory to alloc() for a heap.
  73.     RETURN - 1 if success, 0 if failure.
  74.              HeapInitialized flag is set on return.
  75.     ERRORS - HeapError = ERR_ALREADYINIT
  76.                          ERR_TOOMANYHAND
  77.                          ERR_SIZETOOLARGE
  78.                          ERR_SIZETOOSMALL
  79.  
  80.         Initializes and allocates an unfragmenting heap.  Memory is
  81.         alloc()'d only once by this function.
  82.  
  83. ----------------------------------------
  84. void           UnInitHeap(void);
  85.  
  86.     ERRORS - HeapError = ERR_NOTINIT
  87.  
  88.         Clears all variables and free()'s memory alloc()'d by InitHeap().
  89.  
  90. ----------------------------------------
  91. unsigned int   Halloc(unsigned long bytes);
  92.  
  93.      bytes - Number of bytes to allocate.
  94.     RETURN - Handle associated with a block of memory.
  95.              0 if failure.
  96.     ERRORS - HeapError = ERR_NOTINIT
  97.                          ERR_SIZETOOLARGE
  98.                          ERR_SIZETOOSMALL
  99.                          ERR_TOOMANYHAND
  100.  
  101.         This function doesn't actually use the alloc() function, but just
  102.         sets aside a block of memory already alloc()'d by InitHeap().
  103.  
  104. ----------------------------------------
  105. unsigned char  Hfree(unsigned int handle);
  106.  
  107.     handle - Handle associated with the block of memory to be freed.
  108.     RETURN - 1 if success, 0 if failure.
  109.     ERRORS - HeapError = ERR_NOTINIT
  110.                          ERR_HANDNOTFOUND
  111.  
  112.         After the memory is freed, all memory allocated after it is
  113.         moved over to prevent memory fragmentation.
  114.         This function doesn't actually use the free() function, but
  115.         just gives back the block of memory set aside by Halloc().
  116.  
  117. ----------------------------------------
  118. unsigned long  Hsize(unsigned int handle);
  119.  
  120.     handle - Handle associated with a block of memory.
  121.     RETURN - Size of the memory allocated by Halloc().
  122.              0 if failure.
  123.     ERRORS - HeapError = ERR_NOTINIT
  124.                          ERR_HANDNOTFOUND
  125.  
  126.         Returns the size of memory associated with a handle.
  127.  
  128. ----------------------------------------
  129. char huge     *Hpointer(unsigned int handle);
  130.  
  131.     handle - Handle of a block of memory.
  132.     RETURN - Pointer to the memory block.
  133.              NULL if failure.
  134.     ERRORS - HeapError = ERR_NOTINIT
  135.                          ERR_HANDNOTFOUND
  136.  
  137.         Returns a pointer to the block of memory set aside by Halloc().
  138.         Use this pointer right away.  The location of the memory
  139.         block may change after Hfree() is called.
  140.  
  141. ----------------------------------------
  142. void           Hclear(void);
  143.  
  144.     ERRORS - HeapError = ERR_NOTINIT
  145.  
  146.         Frees all memory set aside by Halloc().
  147.         All variables are set as if InitHeap() was just called.
  148.  
  149. ----------------------------------------
  150.  
  151.  
  152. VARIABLES:
  153. ==========
  154.         HeapInitialized - Set if InitHeap() was successful or not.
  155.  
  156.         HeapError       - Set by all functions to indicate an error.
  157.  
  158.         HeapMaxHandles  - Set by InitHeap().  Maximum handles allocatable
  159.                           by Halloc().
  160.  
  161.         HeapUsedHandles - Total handles allocated by Halloc().
  162.  
  163.         HeapUnused      - Total memory available to allocate by Halloc().
  164.  
  165.         HeapUsed        - Total memory allocated by Halloc().
  166.  
  167.        *HeapBase        - Pointer to the base of memory alloc()'d by
  168.                           InitHeap().
  169.  
  170.        *HeapVersion     - String to indicate the version of this library.
  171.  
  172. ERRORS:
  173. -------
  174.        ERR_NOTINIT      - InitHeap() was not called.
  175.  
  176.        ERR_ALREADYINIT  - InitHeap() was already called.
  177.  
  178.        ERR_SIZETOOSMALL - Requested size is too small.
  179.  
  180.        ERR_SIZETOOLARGE - Requested size is too large.
  181.  
  182.        ERR_TOOMANYHAND  - Too many handles already used.
  183.  
  184.        ERR_HANDNOTFOUND - Requested handle not found.
  185.  
  186.  
  187. USE:
  188. ====
  189.         This library and its source code my be freely distributed and freely
  190. used however and for whatever you want.  Think of these files as yours.  Do
  191. with them as you please.  I just hope someone gets as much use out of them as I
  192. have.
  193.