Hardware manual

Alloc -- A Basic Storage Allocator
The Alloc package contains a small and efficient non-relocating storage allocator. It doesn’t do much, but
what it does it does very well. Initially the user gives the allocator one (or several) blocks of storage by calls
on InitializeZone. The user can later add storage to a zone by calling AddToZone. The function Allocate
returns a pointer to a block allocated from a given zone. Calling Free returns a previously-allocated block
to a given zone.
Argument lists given below are decorated with default settings. An argument followed by [exp] will default
if omitted or zero to the value exp; an argument followed by [...exp] will default if omitted to exp.
InitializeZone, AddToZone
The function zone = InitializeZone(Zone, Length, OutOfSpaceRoutine [...SysErr], MalFormedRoutine
[...SysErr]) initializes the block of storage beginning at address Zone and containing Length words to be a
free storage zone. OutOfSpaceRoutine is taken to be an error handling routine that will be called whenever
a requested allocation cannot be satisfied. MalFormedRoutine is an error printing routine that is called
whenever the Alloc package detects an error in the consistency of the zone data structure. InitializeZone
builds the zone data structure, and returns a pointer to a "zone," which is used for all subsequent calls to
Allocate and Free for the zone.
The function AddToZone(Zone, Block, Length) adds the block of storage beginning at Block and
containing Length words to the zone pointed to by Zone.
Alloc restricts the maximum size of the blocks it will allocate and of the "Length" arguments for
InitializeZone and AddToZone to 32K-1.
Allocate, Free
The function Allocate(Zone, Length, returnOnNoSpace [...0], Even [...0]) allocates a block of Length words
from Zone and returns a pointer to that block. If the allocation cannot be done, one of two cases pertains:
(1) returnOnNoSpace is non-zero or the OutOfSpaceRoutine provided for the zone is 0: Allocate returns
the value 0; if returnOnNoSpace is not -1, the size of the largest available block is stored in
@returnOnNoSpace; (2) otherwise, the value returned to the caller is the result of
OutOfSpaceRoutine(Zone, ecOutOfSpace, Length).
If the optional parameter Even is true, the block allocated will be guaranteed to begin on an even word
boundary. This is useful when allocating display buffers.
The procedure Free(Zone, Block) gives a previously-allocated block of storage back to the zone pointed to
by Zone. Block must have been the value of a call on Allocate.
CheckZone
The Alloc package contains considerable facilities for debugging. Conditional compilation will enable
various levels of consistency checking; the remainder of this paragraph assumes that the checking is
enabled. Users should consult the source file (Alloc.Bcpl) for details concerning the conditional
compilation.
The procedure CheckZone(zone), which may be called conveniently from Swat, will perform a fairly
exhaustive consistency check of the zone (provided that conditional compilation has caused the code to be
present!).
In addition, certain checking will be performed on the various calls to the package, provided that the
MalFormedRoutine parameter supplied for the zone is non-zero.
Alloc February 19, 1979 7:23 PM 48
For Xerox Internal Use Only -- December 15, 1980