GCALLOC(3R)

NAME
gcalloc, gcfree, gcallocown - garbage compacting memory allocation

SYNOPSIS
#include <dmd.h>

char *gcalloc (nbytes, where)

void gcfree (s)

void gcallocown (s, p)

unsigned long nbytes;
long **where;
char *s;
Proc *p;

DESCRIPTION
The gcalloc function provides a simple garbage-compacting memory allocator. It returns either a pointer to a block of nbytes contiguous bytes of storage or a NULL if unavailable. The storage is not initialized to zeros. The pointer where points to the location where the address of the storage block is to be saved. The contents of where will be updated after each compaction. That is, if garbage collection occurs, your storage will be moved, and your pointer will be changed to point to the new location of your storage area. Therefore, a program using gcalloc should never store the location of gcallocated memory anywhere other than the location handed to the allocator. Typically, this location is contained in a structure such as a Bitmap.

The gcallocown function changes the owning process of the memory returned by gcalloc. If p is zero, the memory will belong to no one and will only be freed by an explicit call to gcfree.

The gcfree function frees the storage block at s, thus making it available for future allocation.

The terminal automatically frees all memory gcalloc'ed and owned by a process when the process terminates or when the window it is running in is deleted. However, it is recommended that a process free its garbage compactable memory when the storage is no longer needed so that other processes will be able to use it.

EXAMPLE
These routines could be used for allocating and freeing space used to store Points in a polygon.

    #include <dmd.h>
    Point *poly;
    Point *
    polyalloc(n)
    {
         char *gcalloc();
    return (poly = (Point *)gcalloc(sizeof(Point)*n, &poly));
    }
    polyfree( )
    {
         void gcfree();
         gcfree (poly);
    }

SEE ALSO
alloc(3R), balloc(3R), structures(3R).

DIAGNOSTICS
When garbage compaction is in effect, a small rectangle flashes on the upper left corner of the terminal's screen.

BUGS
If gcalloc is called to attempt to allocate over 7000000 bytes, it will fail, but it may say it succeeded. If this happens, the memory used by gcalloc is corrupted and may damage other programs running in the terminal.