Guardian Procedure Calls Reference Manual (G06.25+)

Guardian Procedure Calls (D-E)
Guardian Procedure Calls Reference Manual—522629-013
4-30
DEFINEPOOL Procedure
(Superseded by POOL_* Procedures)
initialize a 19-word array, the pool-header, that is used to manage the pool. The
pool and the pool header can reside in the user data stack or in extended memory.
The pool routines accept and return extended addresses that apply to both the
stack and extended memory.
Once the pool is defined, the process can reserve blocks of various sizes from the
pool by calling the GETPOOL procedure and can release blocks by calling the
PUTPOOL procedure. The program must release one entire block using
PUTPOOL; it may not return part of a block or multiple blocks in one PUTPOOL
call.
Be careful to use only the currently reserved blocks of the pool, or the pool
structure is corrupted and unpredictable results occur. If multiple pools are
defined, do not return reserved blocks to the wrong pool. For debugging purposes,
a special call to GETPOOL checks for pool consistency.
•
Pool management methods
The following information is supplied for use in evaluating the appropriateness of
using the Guardian pool routines in user application programs and determining the
proper size of a pool. Application programs should not depend on the pool data
structures, since they are subject to change. The program should use only the
procedural interfaces described on the following pages.
The requested block size is rounded up to a multiple of 4 bytes, at a minimum of
28 bytes. This reduces pool fragmentation, but when the program is allocating
small blocks, it can waste memory space.
One extra word is allocated for a boundary tag at the beginning and end of each
block; thus, the minimum pool block size is 32 bytes. This tag serves three
purposes:
1. It contains the size of each block so that the program does not need to specify
the length of the block when releasing it.
2. It serves as a check to ensure that the program does not erroneously use more
memory than the block contains (although it does not stop the program from
overwriting).
3. It provides for efficient coalescing of adjacent free blocks.
In GETPOOL, the free block list is searched for the first block sufficiently large
enough to satisfy the request. If the free block is at least 32 bytes longer than the
required size, it is split into a reserved block and a new free block. Otherwise, the
entire free block is used for the request.
In summary, the pool space overhead on each block can be substantial if very
small blocks are allocated. An approximate formula is:
ALLOCATED := ($MAX (REQUEST + 7, 32) /4) * 4;
where REQUEST is the original request size in bytes; the allocated blocks are also
measured in bytes.