home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
High Voltage Shareware
/
high1.zip
/
high1
/
DIR9
/
HEAP20.ZIP
/
HEAP.DOC
next >
Wrap
Text File
|
1993-10-05
|
7KB
|
193 lines
Unfragmenting Heap Library 2.0
By Tom Ledoux
October 5, 1993
WHAT'S NEW IN 2:
================
Improved speed by many times. The size may be a little bit larger, but
speed is increased when using Halloc() and Hfree(). Instead of searching all
internal variables for a specified handle, now each handle is stored as
Heap[handle-1]. So now a handle can be accessed on the fly instead of
searching for it. Other than speed, nothing else changed.
INTRODUCTION:
=============
When you allocate blocks of memory then free a block in the middle,
you're left with a 'hole'. This is called memory fragmentation. You can't
use this 'hole' unless you allocate the same size or smaller, or until all
memory after it is freed. But now you don't have to worry about memory
fragmentation. Just use these functions and all your troubles are over.
This library allocates a base block of memory which all blocks of
memory are contained. Once a block is freed, all the blocks after it are moved
over to cover up the 'hole'. Since memory is beeing moved constantly, pointers
are useless after a long period of time. So communication to the memory blocks
is done by the use of handles. Handles are just numbers which can be 1 to
6000. As the blocks of memory are moved from location to location, the handle
stays the same. You can find out a blocks memory pointer, but once another
block is freed, that pointer might be invalid.
|*| = Blocks of used memory
|-| = Free memory
Without the Heap Library
------------------------
|****|**|*******|****|----|******|***********|****|**|------|
Memory is freed, nothing happens.
Less contiguous memory is available.
With the Heap Library
---------------------
|****|**|*******|****|******|***********|****|**|-----------|
Memory is freed, the rest is moved over.
More contiguous memory is available.
FILES:
======
The Heap Library was compiled using Turbo C 2.0 and is provided for
small, medium, large, compact, and huge memory models. Files included in the
archive are:
HEAP.DOC - Documentation file
HTEST.C - Heap Library example file
HEAP.H - Heap Library include file
HEAPS.LIB - Heap Library library file for the Small memory model
HEAPM.LIB - Medium
HEAPL.LIB - Large
HEAPC.LIB - Compact
HEAPH.LIB - Huge
HEAP20_C.ZIP - Turbo C source code for this library
To compile the example file, type:
TCC -ms htest.c heaps.lib
FUNCTIONS:
==========
unsigned char InitHeap(unsigned int handles, unsigned long bytes);
handles - Number of handles to alloc(). Each handle takes 10 bytes.
Maximum of 6000 handles.
bytes - Total bytes of base memory to alloc() for a heap.
RETURN - 1 if success, 0 if failure.
HeapInitialized flag is set on return.
ERRORS - HeapError = ERR_ALREADYINIT
ERR_TOOMANYHAND
ERR_SIZETOOLARGE
ERR_SIZETOOSMALL
Initializes and allocates an unfragmenting heap. Memory is
alloc()'d only once by this function.
----------------------------------------
void UnInitHeap(void);
ERRORS - HeapError = ERR_NOTINIT
Clears all variables and free()'s memory alloc()'d by InitHeap().
----------------------------------------
unsigned int Halloc(unsigned long bytes);
bytes - Number of bytes to allocate.
RETURN - Handle associated with a block of memory.
0 if failure.
ERRORS - HeapError = ERR_NOTINIT
ERR_SIZETOOLARGE
ERR_SIZETOOSMALL
ERR_TOOMANYHAND
This function doesn't actually use the alloc() function, but just
sets aside a block of memory already alloc()'d by InitHeap().
----------------------------------------
unsigned char Hfree(unsigned int handle);
handle - Handle associated with the block of memory to be freed.
RETURN - 1 if success, 0 if failure.
ERRORS - HeapError = ERR_NOTINIT
ERR_HANDNOTFOUND
After the memory is freed, all memory allocated after it is
moved over to prevent memory fragmentation.
This function doesn't actually use the free() function, but
just gives back the block of memory set aside by Halloc().
----------------------------------------
unsigned long Hsize(unsigned int handle);
handle - Handle associated with a block of memory.
RETURN - Size of the memory allocated by Halloc().
0 if failure.
ERRORS - HeapError = ERR_NOTINIT
ERR_HANDNOTFOUND
Returns the size of memory associated with a handle.
----------------------------------------
char huge *Hpointer(unsigned int handle);
handle - Handle of a block of memory.
RETURN - Pointer to the memory block.
NULL if failure.
ERRORS - HeapError = ERR_NOTINIT
ERR_HANDNOTFOUND
Returns a pointer to the block of memory set aside by Halloc().
Use this pointer right away. The location of the memory
block may change after Hfree() is called.
----------------------------------------
void Hclear(void);
ERRORS - HeapError = ERR_NOTINIT
Frees all memory set aside by Halloc().
All variables are set as if InitHeap() was just called.
----------------------------------------
VARIABLES:
==========
HeapInitialized - Set if InitHeap() was successful or not.
HeapError - Set by all functions to indicate an error.
HeapMaxHandles - Set by InitHeap(). Maximum handles allocatable
by Halloc().
HeapUsedHandles - Total handles allocated by Halloc().
HeapUnused - Total memory available to allocate by Halloc().
HeapUsed - Total memory allocated by Halloc().
*HeapBase - Pointer to the base of memory alloc()'d by
InitHeap().
*HeapVersion - String to indicate the version of this library.
ERRORS:
-------
ERR_NOTINIT - InitHeap() was not called.
ERR_ALREADYINIT - InitHeap() was already called.
ERR_SIZETOOSMALL - Requested size is too small.
ERR_SIZETOOLARGE - Requested size is too large.
ERR_TOOMANYHAND - Too many handles already used.
ERR_HANDNOTFOUND - Requested handle not found.
USE:
====
This library and its source code my be freely distributed and freely
used however and for whatever you want. Think of these files as yours. Do
with them as you please. I just hope someone gets as much use out of them as I
have.