In some systems, message-passing and remote-memory-access ( RMA) operations run faster when accessing specially allocated memory (e.g., memory that is shared by the other processes in the communicating group on an SMP). MPI provides a mechanism for allocating and freeing such special memory. The use of such memory for message-passing or RMA is not mandatory, and this memory can be used without restrictions as any other dynamically allocated memory. However, implementations may restrict the use of some RMA functionality as defined in Section Lock.
| MPI_ALLOC_MEM(size, info, baseptr) | |
| IN size | size of memory segment in bytes (non-negative integer) |
| IN info | info argument (handle) |
| OUT baseptr | pointer to beginning of memory segment allocated |
If the Fortran compiler provides TYPE(C_PTR), then the following generic interface must be provided in the mpi module and should be provided in the (deprecated) mpif.h include file through overloading, i.e., with the same routine name as the routine with INTEGER(KIND=MPI_ADDRESS_KIND) BASEPTR, but with a different specific procedure name:
INTERFACE MPI_ALLOC_MEM
SUBROUTINE MPI_ALLOC_MEM(SIZE, INFO, BASEPTR, IERROR)
IMPORT :: MPI_ADDRESS_KIND
INTEGER :: INFO, IERROR
INTEGER(KIND=MPI_ADDRESS_KIND) :: SIZE, BASEPTR
END SUBROUTINE
SUBROUTINE MPI_ALLOC_MEM_CPTR(SIZE, INFO, BASEPTR, IERROR)
USE, INTRINSIC :: ISO_C_BINDING, ONLY : C_PTR
IMPORT :: MPI_ADDRESS_KIND
INTEGER :: INFO, IERROR
INTEGER(KIND=MPI_ADDRESS_KIND) :: SIZE
TYPE(C_PTR) :: BASEPTR
END SUBROUTINE
END INTERFACE
The base procedure name of this overloaded function is MPI_ALLOC_MEM_CPTR. The implied specific procedure names
are described in Section Interface Specifications, Procedure Names, and the Profiling Interface.
By default, the allocated memory shall be aligned to at least the alignment required for load/store accesses of any datatype corresponding to a predefined MPI datatype. The info argument may be used to specify a desired alternative minimum alignment in bytes for the allocated memory by setting the value of the key mpi_minimum_memory_alignment to an integral number equal to a power of two. An implementation may ignore values smaller than the default required alignment. The info argument can also be used to provide directives that control the desired location of the allocated memory. Such a directive does not affect the semantics of the call. The corresponding info values are implementation-dependent. A null directive value of info = MPI_INFO_NULL is always valid.
The function MPI_ALLOC_MEM may raise an error of class MPI_ERR_NO_MEM to indicate it failed because memory is exhausted.
| MPI_FREE_MEM(base) | |
| IN base | initial address of memory segment allocated by MPI_ALLOC_MEM (choice) |
The function MPI_FREE_MEM may raise an error of class MPI_ERR_BASE to indicate an invalid base argument.
Rationale.
The C bindings of MPI_ALLOC_MEM and
MPI_FREE_MEM are similar to the bindings for the
malloc and free C library calls:
a call to
MPI_Alloc_mem(..., &base) should be paired with a call to
MPI_Free_mem(base) (one less
level of indirection). Both arguments are declared to
be of same type void* so as to facilitate type casting.
The Fortran binding is consistent with the C bindings:
the Fortran MPI_ALLOC_MEM call returns in
baseptr the TYPE(C_PTR) pointer or
the (integer valued) address
of the allocated memory.
The base argument of MPI_FREE_MEM is a choice
argument, which passes (a reference to) the variable stored at that location.
( End of rationale.)
Advice
to implementors.
If MPI_ALLOC_MEM allocates special memory, then a design similar to the design of C malloc and free functions has to be used, in order to find out the size of a memory segment, when the segment is freed. If no special memory is used, MPI_ALLOC_MEM simply invokes malloc, and MPI_FREE_MEM invokes free.
A call to MPI_ALLOC_MEM can be used in shared memory
systems to allocate memory in a shared memory segment.
( End of advice to implementors.)
Example
Example of use of MPI_ALLOC_MEM, in Fortran with
TYPE(C_PTR) pointers. We assume 4-byte REALs.
Example
Example of use of MPI_ALLOC_MEM, in Fortran with
nonstandard Cray-pointers.
We assume 4-byte REALs, and assume that these pointers
are address-sized.
This code is not Fortran 77 or Fortran 90 code. Some compilers may not support this code or need a special option, e.g., the GNU gFortran compiler needs -fcray-pointer.
Advice
to implementors.
Some compilers map Cray-pointers to address-sized integers,
some to TYPE(C_PTR) pointers (e.g., Cray Fortran, version 7.3.3).
From the user's viewpoint, this mapping is irrelevant
because Examples Memory Allocation should work correctly with
an MPI-3.0 (or later) library if Cray-pointers are available.
( End of advice to implementors.)
Example
Same example, in C.
