Normally, a program uses the FUNCTION AllocGPMem& to ask for memory:

    addr& = AllocGPMem&(getSize&, flags&)

The getSize& argument is the amount of memory the program needs and flags&
is a bit field which specifies any special characteristics (see reference).
If AllocGPMem& is successful, it returns an address pointer to a block of
memory.  The memory allocation will fail if the GPM system cannot find a
big enough block.  If AllocGPMem& fails, it returns zero.

Because the GP Memory system only keeps track of how much free memory is
available and not how much is in use, it has no idea what memory has been
allocated so far.  This means the program has to explicitly return, or
deallocate, any memory it has allocated so the GPM system can return that
memory to the free memory list.  If the program does not return a block of
memory, then the GPM system will not be able to reallocate that memory for
later reuse.  That block of memory will be lost until the program ends.
If you are using AllocGPMem& to allocate memory, a call to FreeGPMem will
return that memory to the GP Memory system:

    FreeGPMem addr&, freeSize&

Here addr& is the address pointer to the memory block the program is about
to return to the GPM system and freeSize& is the same size that was passed
when the memory was allocated with AllocGPMem&.

The GP Memory system allocation functions will always return memory blocks
that are at least LONG LONG (_INTEGER64) aligned.  This means that the
allocated memory will always start on an address which is at least evenly
divisible by eight.  This alignment makes the memory suitable for any type
of structures or buffers and also provides optimal alignment for stacks
and memory copying.

The following examples show how to allocate memory.

    apointer& = AllocGPMem&(100&, 0&)
    IF apointer& = 0 THEN
        PRINT "couldn't get memory, exiting..."
        GOTO exitProgram
    END IF

In this example AllocGPMem& returns the address of the first byte of a
memory block that is at least 100 bytes in size or zero if there is not
that much free memory.

    anotherptr& = AllocGPMem&(1000&, gpmF_Clear&)
    IF anotherptr& = 0 THEN
        PRINT "couldn't get memory, exiting..."
        GOTO exitProgram
    END IF

The example above allocates 1000 bytes of memory, which the GPM system
fills with zeros before it lets the program use the memory.  If the GPM
system free memory list does not contain enough contiguous memory bytes,
then AllocGPMem& returns a zero.  You must check for this condition and
do a suitable error handling, if needed.

If you're tired remembering the sizes of all memory blocks your program
has allocated, then you can also use the FUNCTION AllocGPMVec& to make
memory allocations.  In addition to allocating a block of memory, this
function keeps track of the size of the memory block, so the program
doesn't have to remember it when it deallocates that memory block.  The
AllocGPMVec& function allocates a little more memory to store the size
of the memory allocation request.

    yap& = AllocGPMVec&(512&, gpmF_Clear&)
    IF yap& = 0 THEN
        PRINT "couldn't get memory, exiting..."
        GOTO exitProgram
    END IF

  Make Sure You Have Memory.
  --------------------------
  Always check the result of any memory allocation to be sure the
  amount of memory requested is available.  Failure to do so will
  lead to trying to use an non-valid pointer.

                                                      Back to GPM Functions