Dynamic Memory Allocator

Memory Allocator(MA) is a library of routines that comprises a dynamic memory allocator for use by C, Fortran, or mixed-language applications. Fortran- 77 applications require such a library because the language does not support dynamic memory allocation. C (and Fortran-90) applications can benefit from using MA instead of the ordinary malloc() and free() routines because of the extra features MA provides: MA is designed to be portable across a variety of platforms. The following platforms are currently supported: 
               WIN32 (Windows NT/95)
               SUN (Solaris, SunOS)
               IBM RS6000, SP-2
               HP
               DEC
               SGI
               CRAY T3D, T3E, YMP
               Intel Paragon, Delta, iPSC/860 
               KSR
               CONVEX SPP
               FUJITSU VX/VPP
               LINUX
MA library can be obtained with the Global Arrays distribution package.

Implementation

Memory layout: 
               segment = heap_region stack_region
               region = block block block ...
               block = AD gap1 guard1 client_space guard2 gap2
A segment of memory is obtained from the OS upon initialization. The low end of the segment is managed as a heap; the heap region grows from low addresses to high addresses. The high end of the segment is managed as a stack; the stack region grows from high addresses to low addresses.

Each region consists of a series of contiguous blocks, one per allocation request, and possibly some unused space. Blocks in the heap region are either in use by the client (allocated and not yet deallocated) or not in use by the client (allocated and already deallocated). A block on the rightmost end of the heap region becomes part of the unused space upon deallocation. Blocks in the stack region are always in use by the client, because when a stack block is deallocated, it becomes part of the unused space.

A block consists of the client space, i.e., the range of memory available for use by the application; guard words adjacent to each end of the client space to help detect improper memory access by the client; bookkeeping info (in an "allocation descriptor," AD); and two gaps, each zero or more bytes long, to satisfy alignment constraints (specifically, to ensure that AD and client_space are aligned properly). 

     LIST OF ROUTINES
          All MA routines are shown below, grouped by category and
          listed alphabetically within each category.

          Initialization
               MA_init()
               MA_sizeof()
               MA_sizeof_overhead()
          Allocation
               MA_alloc_get()
               MA_allocate_heap()
               MA_get_index()
               MA_get_pointer()
               MA_inquire_avail()
               MA_inquire_heap()
               MA_inquire_stack()
               MA_push_get()
               MA_push_stack()
          Deallocation
               MA_chop_stack()
               MA_free_heap()
               MA_pop_stack()
          Debugging
               MA_set_auto_verify()
               MA_set_error_print()
               MA_set_hard_fail()
               MA_summarize_allocated_blocks()
               MA_verify_allocator_stuff()
          Iteration Over Allocated Blocks
               MA_get_next_memhandle()
               MA_init_memhandle_iterator()
          Statistics
               MA_print_stats()

     TYPES
          There are three MA-specific types in the public C interface
          to MA:  Integer, Boolean, and Pointer. They are accessible
          by including macdecls.h. Integer is defined in such a way
          that sizeof(Integer) is equal to the number of bytes in a
          FORTRAN integer, which varies according to compiler options
          and platform. Boolean is equivalent to Integer, and Pointer
          is equivalent to char *.

     ERRORS
          Errors considered fatal by MA result in program termination.
          Errors considered nonfatal by MA cause the MA routine to
          return an error value to the caller. For most boolean
          functions, false is returned upon failure and true is
          returned upon success. (The boolean functions for which the
          return value means something other than success or failure
          are MA_set_auto_verify(), MA_set_error_print(), and
          MA_set_hard_fail().) Integer functions return zero upon
          failure; depending on the function, zero may or may not be
          distinguishable as an exceptional value.

          An application can force MA to treat all errors as fatal via
          MA_set_hard_fail().

          If a fatal error occurs, an error message is printed on the
          standard error (stderr). By default, error messages are also
          printed for nonfatal errors. An application can force MA to
          print or not print error messages for nonfatal errors via
          MA_set_error_print().

     FILES
          To access required MA definitions, C applications should
          include macdecls.h and FORTRAN applications should include
          mafdecls.h.


     SEE ALSO
          MA_alloc_get(3), MA_allocate_heap(3), MA_chop_stack(3),
          MA_free_heap(3), MA_get_index(3), MA_get_next_memhandle(3),
          MA_get_pointer(3), MA_init(3),
          MA_init_memhandle_iterator(3), MA_inquire_avail(3),
          MA_inquire_heap(3), MA_inquire_stack(3), MA_pop_stack(3),
          MA_print_stats(3), MA_push_get(3), MA_push_stack(3),
          MA_set_auto_verify(3), MA_set_error_print(3),
          MA_set_hard_fail(3), MA_sizeof(3), MA_sizeof_overhead(3),
          MA_summarize_allocated_blocks(3),
          MA_verify_allocator_stuff(3)

     AUTHOR
          Gregory S. Thomas, Pacific Northwest National Laboratory