ALLOCATE - a simple garbage collecting storage allocator.

Usage:

B:
   block_pointer = allocate( nwords [, keep ] );

/* C users use "malloc" */

Where:

nwords: is the number of words of storage desired.
keep: indicates how long this block of storage is to be kept.
block_pointer: is a pointer to the storage obtained.

Description:

ALLOCATE obtains a block of storage of the specified size from GETVEC and returns a pointer to the block.

If "keep" is not specified, or if "keep" is zero, the storage obtained from ALLOCATE is automatically released when the current function returns. If a non-zero value is specified for "keep", the block of storage is released when the function "keep" levels down the stack returns to its caller. Thus if "keep" is one, the block is released when the caller of your function returns; if "keep" is two the block is released when the caller's caller returns, and so on.

If "keep" is minus one (-1), the block will be released if the top routine of the current co-routine returns. If this is the main co-routine the vector will never be released but be warned that this only applies to the main co-routine. This allows you to return a vector or data structure in an allocated block.

Several auxiliary functions which are related to ALLOCATE are briefly described below.

freevec( block_pointer );: FREEVEC immediately releases the block of storage beginning at "block_pointer".
keepvec( block_pointer [, keep] );: KEEPVEC marks how long a block of storage is to be kept. The block beginning at "block_pointer" will be released upon the return of the function which is "keep" levels down the stack. If "keep" is not specified, the default value is -1. See the discussion above under "allocate" for the meanings of "keep" values.
lenvec( block_pointer );: LENVEC returns the size of the block of storage beginning at "block_pointer".