Memory Allocation

Basic Memory Allocation

The basic macros are as follows:

ALLOC( ptr, n_items )

Allocates n_items elements of the correct type, assigning the result to the argument ptr.

FREE( ptr )

Frees the memory pointed to by the argument ptr.

REALLOC( ptr, n_items )

Changes the size of the memory pointed to by ptr to be of size n_items elements, possibly changing the value of ptr in the process.

ALLOC_VAR_SIZED_STRUCT( ptr, element_type, n_elements )

Allocates a variable sized structure, which must be of a specific form. The last element of the structure must be an array of size 1, and this array will constitute the variable-sized part of the structure. The argument element_type must be the type of this last element, and the argument n_elements is the desired number of elements to allocate for this array, in addition to the memory for the first part of the structure. An example of usage is:

{
            struct {  int   a;
                      float b;
                      char  data[1];
                   }                    *ptr;

            ALLOC_VAR_SIZED_STRUCT( ptr, char, 10 );

            ptr->a = 1;
            ptr->b = 2.5;
            ptr->data[0] = 'a';
            ptr->data[9] = 'i';
        }

ALLOC2D( ptr, n1, n2 )
    ALLOC3D( ptr, n1, n2, n3 )
    ALLOC4D( ptr, n1, n2, n3, n4 )
    ALLOC5D( ptr, n1, n2, n3, n4, n5 )

Allocates a 2 to 5 dimensional array of size n1 by n2, etc. and stores the result in the specified pointer, ptr. In the 2 dimensional case, this is accomplished with only 2 memory allocations, one to allocate n1 times n2 elements for the storage, and the second to allocate n1 pointers into the first memory area. In general, there is one memory allocation for each dimension required.

FREE2D( ptr )
    FREE3D( ptr )
    FREE4D( ptr )
    FREE5D( ptr )

Frees the memory associated with the multi-dimensional array.

public  void  set_alloc_checking(
    BOOLEAN state )

Enables or disables allocation checking. It is usually called at the beginning of a program to provide double-checking of allocation. It incurs an extra allocation every time one of the previous allocation macros is invoked. If this function is not called, allocation checking can be turned on by setting the environment variable DEBUG_ALLOC to anything.

Allocation checking detects three types of memory programming errors: freeing a pointer that was not allocated, by checking that memory chunks returned from the system malloc routine do not overlap existing ones, sometimes detects when the system memory has become corrupted, and by recording all memory allocated and printing out what is currently allocated, can detect memory leaks.

public  void  output_alloc_to_file(
    STRING   filename )

If memory checking was enabled, this function can be used to detect memory leaks. At the end of a program, the programmer should free up all memory that is known, then call this function. Any remaining allocated memory is printed out to a file, indicating the file and line number where the memory was allocated.

Higher Level Array Allocation

In addition to the basic memory allocation macros described previously, a set of useful macros for dealing with arrays of dynamically changing size are provided:

SET_ARRAY_SIZE( array, previous_n_elems, new_n_elems,
                    chunk_size )

This macro increases or decreases the size of an array, by specifying the number of elements previously allocated to the array (starts out at zero). The chunk_size argument defines the size of the memory chunks which are allocated. For instance, if chunk_size is 100, then this macro will only reallocate the array if the size change crosses to a different multiple of 100, thus avoiding memory allocation every time it is called. This specification of the granularity of the memory allocation must be consistently specified; if this macro is called with a given variable and chunk size, then subsequent calls to this macro with the same variable must specify the same chunk size. Note also that the number passed in as new_n_elems must be passed in as previous_n_elems on the next call to this macro.

ADD_ELEMENT_TO_ARRAY( array, n_elems,
                          elem_to_add, chunk_size )

Adds the argument elem_to_add to the array at the n_elems'th index, then increments n_elems. The argument chunk_size specifies the granularity of memory allocation.

DELETE_ELEMENT_FROM_ARRAY( array, n_elems, index_to_remove,
                               chunk_size )

Deletes the index_to_remove'th element from the array, decreasing the number of elements in the array (n_elems) and decreasing the memory allocation, if crossing a multiple of chunk_size. Again, chunk_size must be specified the same for all invocations of the previous three macros involving a given pointer.

ADD_ELEMENT_TO_ARRAY_WITH_SIZE( array, n_alloced, n_elems,
                                    elem_to_add, chunk_size )

Adds an element (elem_to_add) to the array, incrementing n_elems. If necessary, the memory is increased by the amount specified in chunk_size and the n_alloced variable is incremented by this amount. The usage of this differs from the use of ADD_ELEMENT_TO_ARRAY in that the number of elements (n_elems) can be decreased arbitrarily, without causing memory to be deallocated.