Guardian Procedure Calls Reference Manual

• Dynamic memory allocation
Several Guardian procedures support the creation of memory pools and the dynamic allocation
of variable-sized blocks from a pool. The calling program provides the memory area to be
used as the pool and then calls the POOL_DEFINE_ procedure to initialize the pool. The pool
can reside in the user data stack or in an extended data segment. The pool procedures 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 POOL_GETSPACE_ procedure and can release blocks by calling the
POOL_PUTSPACE_ procedure. The program must release one entire block in a
POOL_PUTSPACE_ call; it cannot release part of a block or multiple blocks in one
POOL_PUTSPACE_ call. If the pool is too small or is larger than necessary, the process can
resize the pool by calling the POOL_RESIZE_ procedure. For detecting potential problems
with the pool, the POOL_GETINFO_ procedure returns information about a pool and the
POOL_CHECK_ procedure checks the internal data structures of a pool.
Be careful to use only the currently reserved blocks of the pool. Using blocks that are not
reserved causes pool corruption. If multiple pools are defined, make sure to return reserved
blocks to the correct pool. For debugging purposes, call POOL_GETINFO_ for information
on the pool header and call POOL_CHECK_ to check the pool for 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 in determining the proper size of a pool.
Each block allocated by the POOL_GETSPACE_ procedure has a tag at the beginning of the
block and a tag at the end of the block. A block boundary tag serves three purposes:
◦ It contains the size of each block so that the program does not need to specify the length
of a 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.
• POOL can only be defined on a single segment. It cannot be defined from segment space of
two consecutive logical segments.
The pool space overhead on each block can be substantial if very small blocks are allocated
(in current RVUs, the minimum block size is 32 bytes).
Although pools 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
error := POOL_DEFINE_ ( pool, 2048D );
Related Programming Manual
For programming information about the POOL_DEFINE_ memory-management procedure, see the
Guardian Programmer's Guide.
POOL_DEFINE_ Procedure 941