Guardian Procedure Calls Reference Manual

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
This 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 these 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:
◦ It contains the size of each block so that the program does not need to specify the length
of the block when releasing it.
◦ 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).
◦ 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.
Although they can also be used to manage the allocation of a collection of equal-sized blocks,
these procedures are not recommended for that purpose, because they can consume more
processor time and pool memory than user-written routines designed for that specific task.
Example
STATUS := DEFINEPOOL ( POOL^HEAD , POOL , 2048D );
Related Programming Manual
For programming information about the DEFINEPOOL memory-management procedure, see the
Guardian Programmer's Guide.
276 Guardian Procedure Calls (D-E)