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 LINUXMA library can be obtained with the Global Arrays distribution package.
segment = heap_region stack_region region = block block block ... block = AD gap1 guard1 client_space guard2 gap2A 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