DEFINITION - FUNCTION
    addr& = AllocGPMem&(getSize&, flags&)
                                 -- allocate memory with given options

OPERATION
    This is the memory allocator to be used by applications.  Memory is
    allocated according to the given flags.  AllocGPMem& will search the
    free memory list until a block is found with enough room to satisfy
    the memory request.

ARGUMENTS
    getSize& -- the size of the desired block in bytes  (The GPM system
                will automatically round this number to a multiple of the
                minimum supported memory block size)
    flags&   -- a bit field with any special characteristics (see below)

RESULT
    addr&    -- a pointer to the newly allocated memory block.  If there
                are no free memory regions large enough to satisfy the
                request, zero will be returned.

NOTES
    1.) The result of any memory allocation must be checked, and a viable
        error handling path taken.  Any allocation may fail if memory has
        been filled.
    2.) If the free memory list is corrupt, the GPM system will panic with
        an error.

FLAGS
    The flags& defined in the include file memory.bi are bit-coded values,
    hence they can easily combined by ORing or adding them:

    gpmF_NoAdd& -- Don't try to extend the current GP Memory region, if
                   there is not enough free space to satisfy the request.
    gpmF_Clear& -- The just allocated memory block will be initialized
                   to all zeros.

SEE ALSO
    Allocating GP Memory

                                                 Back to Function Reference