MA_INITIALIZE(3)

NAME
MA_init - initialize the memory allocator

C SYNOPSIS
#include "macdecls.h"
Boolean MA_init(datatype, nominal_stack, nominal_heap)
    Integer     datatype;       /* read-only */
    Integer     nominal_stack;  /* read-only */
    Integer     nominal_heap;   /* read-only */

FORTRAN SYNOPSIS
#include "mafdecls.fh"
logical function MA_init(datatype, nominal_stack, nominal_heap)
    integer     datatype
    integer     nominal_stack
    integer     nominal_heap

DESCRIPTION
MA_init() initializes the memory allocator by requesting from the operating system a single segment of memory that is used to satisfy allocations for both the heap and the stack. The memory segment is large enough to hold nominal_heap elements of type datatype in the heap and nominal_stack elements of type datatype in the stack, plus the overhead for two allocations (one heap and one stack); if more than two allocations will exist concurrently, overhead may be computed using MA_sizeof_overhead() and factored into nominal_heap and nominal_stack. If nominal_heap is less than zero, a default total size for the heap is used. If nominal_stack is less than zero, a default total size for the stack is used. MA_init() must be called before any other MA routine is called, except MA_set_auto_verify(), MA_set_error_print(), MA_set_hard_fail(), MA_sizeof(), or MA_sizeof_overhead().

USAGE
The following FORTRAN code illustrates the use of MA_init() by computing the space required for 100 integers in 5 allocations in the heap, 200 logicals in 4 allocations in the heap, 300 reals in 3 allocations in the stack, and 400 doubles in 2 allocations in the stack.
#include "mafdecls.fh"
    logical ok
    integer heap_bytes_data
    integer heap_bytes_overhead
    integer heap_bytes_total
    integer stack_bytes_data
    integer stack_bytes_overhead
    integer stack_bytes_total
    heap_bytes_data = MA_sizeof(MT_INT, 100, MT_BYTE)
                    + MA_sizeof(MT_LOG, 200, MT_BYTE)
    heap_bytes_overhead = (5 + 4) * MA_sizeof_overhead(MT_BYTE)
    heap_bytes_total = heap_bytes_data + heap_bytes_overhead
    stack_bytes_data = MA_sizeof(MT_REAL, 300, MT_BYTE)
                     + MA_sizeof(MT_DBL, 400, MT_BYTE)
    stack_bytes_overhead = (3 + 2) * MA_sizeof_overhead(MT_BYTE)
    stack_bytes_total = stack_bytes_data + stack_bytes_overhead
    ok = MA_init(MT_BYTE, stack_bytes_total, heap_bytes_total)

DIAGNOSTICS
unable to set sizes of FORTRAN datatypes
This indicates either that the internal state of MA is corrupted or that there is a problem in the C-FORTRAN linkage.
MA already initialized
MA_init() may not be called after it has returned successfully.
invalid datatype: %d
datatype must be one of those listed in macdecls.h or mafdecls.fh.
could not allocate %d bytes
The request for memory to the operating system failed. Recovery may be attempted by calling MA_init() again and requesting less memory.

RETURN VALUE
C: MA_TRUE upon success, MA_FALSE upon failure.
FORTRAN: .true. upon success, .false. upon failure.

FILES
Include files: /msrc/proj/hpctools/ma/release/current/include
Library:       /msrc/proj/hpctools/ma/release/current/lib/platform/libma.a
Man pages:     /msrc/proj/hpctools/ma/release/current/man/man3
Source code:   /msrc/proj/hpctools/ma/release/current/tar/marelease.tar

SEE ALSO
MA(3), MA_initialized(3), MA_sizeof(3), MA_sizeof_overhead(3)

AUTHOR
Gregory S. Thomas, Pacific Northwest National Laboratory