Examples_allocators.tex

\pagebreak
\section{ Memory Allocators}
\label{sec:allocators}

OpenMP memory allocators can be used to allocate memory with
specific allocator traits.  In the following example an OpenMP allocator is used to
specify an alignment for arrays \plc{x} and \plc{y}. The
general approach for attributing traits to variables allocated by
OpenMP is to create or specify a pre-defined \plc{memory space}, create an
array of \plc{traits}, and then form an \plc{allocator} from the
memory space and trait.
The allocator is then specified
in an OpenMP allocation (using an API \plc{omp\_alloc()} function
for C/C++ code and an \code{allocate} directive for Fortran code
in the allocators.1 example).

In the example below the \plc{xy\_memspace} variable is declared
and assigned the default memory space (\plc{omp\_default\_mem\_space}).
Next, an array for \plc{traits} is created. Since only one
trait will be used, the array size is \plc{1}.
A trait is a structure in C/C++ and a derived type in Fortran,
containing 2 components: a key and a corresponding value (key-value pair).
The trait key used here is \plc{omp\_atk\_alignment} (an enum for C/C++
and a parameter for Fortran)
and the trait value of 64 is specified in the \plc{xy\_traits} declaration.
These declarations are followed by a call to the
\plc{omp\_init\_allocator()} function to combine the memory
space (\plc{xy\_memspace}) and the traits (\plc{xy\_traits})
to form an allocator (\plc{xy\_alloc}).

%In the C/C++ code the API  \plc{omp\_allocate()} function is used 
%to allocate space, similar to \plc{malloc}, except that the allocator 
%is specified as the second argument.  
%In Fortran an API allocation function is not available. 
%An \code{allocate} construct is used (with \plc{x} and \plc{y} 
%listed as the variables to be allocated), along
%with an \code{allocator} clause (specifying the \plc{xy\_alloc} as the allocator)
%for the following Fortran \plc{allocate} statement.

In the C/C++ code the API  \plc{omp\_allocate()} function is used
to allocate space, similar to \plc{malloc}, except that the allocator
is specified as the second argument.
In Fortran an \code{allocate} directive is used to specify an allocator
for a following Fortran \plc{allocate} statement.
A variable list may be supplied if the allocator
is to be applied to a subset of variables in the Fortran allocate
statement. Specifying the complete list is optional.
Here, the \plc{xy\_alloc} allocator is specified
in the \code{allocator} clause,
and the set of all variables used in the allocate statement is specified in the list.

%"for a following Fortran allocation statement" (no using "immediately" here)
% it looks like if you have a list, the allocation statement does not need
% to follow immediately.(?)
% spec5.0 157:19-20 The allocate directive must appear in the same scope as
% the declarations of each of its list items and must follow all such declarations.

%\pagebreak

\cexample[5.0]{allocators}{1}
\ffreeexample[5.0]{allocators}{1}