How to use dynmem.h:

1) dynmem.h now depends on debug.h to print debugging messages.  To enable
debugging messages, set the global variable debugging_level to one of the
following:

 NO_DEBUGGING: No debug functions are provided, no error messages are
printed.  This is the recommended value for a production release.  This is
also the same as not defining DYNMEM_DEBUG.

 DEBUG_CRITICAL: Debugging functions are provided, as well as critical error
messages.  This is the same as defining DYNMEM_DEBUG with no value.

 DEBUG_WARNING: Debugging functions, critical error messages, and warnings
are provided.

 DEBUG_TRACE: Debugging functions, critical error messages, warnings, and
function traces are provided.

It is reccommended that DEBUG_WARN be used while writing programs, but that
NO_DEBUGGING be used for production releases.

Because debugging_level is a variable, it is possible (and recommended) to
use DEBUG_WARNING as the standard level, and to increase it in a section of
code that shows errors.  This will prevent the screen from being overloaded
with error messages.

2) If you desire, set the constant DYNMEM_SIZE before you include dynmem.h.
This will set the amount of memory that dynmem uses to allocate, unless you
are under glulx.  If you do not declare this, it will default to 5120 (5 *
1024, or 5 k), which may or may not be enough space, depending on what you're
doing.  Don't forget, if you do increase this, that you also need to change
the $MAX_STATIC_DATA compiler flag!

3) Include dynmem.h.  (That one was easy, huh? :)

4) Declare as many MemController objects as you want.  There are two optional
properties you can set.  dynmem.h is now set to find its own memory, so there
is no need to declare any arrays.

Properties:
a) obj.block_size - If set, this MemController object will only allocate
blocks of one size.  Why would this be useful?  There's a definite savings in
memory with this, which only increases as the size of the array increases.
This is useful for custom structures, linked lists, etc.  If this is not set
explicitly, the object will allocate blocks of any requested size (except 0).

b) obj.gc_percent - This property, which can be changed during the course of
the program, controlls how often the MemController cleans up memory which has
been freed.  This property defaults to a value of 75% full.

5) Use the public functions provided by the MemController object.  There are5 
regular functions, and 2 debugging functions that are only included if
the debugging level is not NO_DEBUGGING.

Regular:
a) obj.alloc_ptr - If the object has not been set to allocate fixed size
blocks, alloc must be supplied with the length of the block requested.  It is
possible for alloc to return NULL, for example if the array is out of space.
It is reccommended to always check the value of the returned pounter before
using it.  Any memory allocated by alloc is guaranteed to be initialized to 0.

b) obj.realloc_ptr - Realloc takes a previously allocated pointer and a new
length as arguments.  If the pointer is NULL, realloc will behave as alloc.
Realloc will attempt to resize the block to the new length.  Realloc may
simply expand the current block, or it may allocate a new block.  In either
case, realloc guarantees that any data present in the block will be unchanged,
unless the block has shrunk.  Any new memory will be initialized to 0.  As
with alloc, realloc can return NULL in certain circumstances.  Always check
the return value of realloc.

c) obj.free_ptr - Free takes a pointer previously allocated by alloc or
realloc, and returns it to the pool for future use.  Any use of a block after
it is freed is an error, and may cause severe problems.

d) obj.force_collect - This function forces the object to collect freed
memory, wether gc_percent is met or not.

e) obj.check_ptr - This function will examine the pointer passed to it, and
return true if the pointer was allocated from this object.  otherwise, it
returns false.

Debugging:
f) obj.profile - Profile will present several staistics about the object,
including the size of its array, the amount of memory in use, etc.

g) obj.check_mem - Check_mem will print the entire array of memory, a block at
a time, with its status and length.  Possible values for status are:

Ready - The block is ready to be allocated.
InUse - The block has been allocated to the program.
Freed - The block has been freed.
End   - This block marks the end of the array.

Good Luck!
John 'katre' Cater
katre@rice.edu