Guardian Procedure Calls Reference Manual (G06.25+)

Guardian Procedure Calls (P)
Guardian Procedure Calls Reference Manual—522629-013
12-14
POOL_DEFINE_ Procedure
Considerations
•
Internal variable-length pool header
The POOL_DEFINE_ procedure creates an internal variable-length pool header at
the beginning of the pool. The length of the header can change between RVUs or
processor types. Information in the header is retrieved by calling the
POOL_GETINFO_ procedure; the header should not be accessed directly, since it
is subject to change.
•
Stack addresses converted to extended addresses
If the pool is in the user data stack, the TAL compiler automatically converts data
stack addresses to extended addresses.
•
Read-only segments
If you specify a pool in an extended data segment that is allocated as a read-only
segment, the POOL_DEFINE_ procedure returns error 3 (bounds error).
•
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
The following 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.
Note. There are additional considerations for privileged callers.