199. Memory Allocation

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 .

int MPI_Alloc_mem(MPI_Aint size, MPI_Info info, void *baseptr)

MPI_Alloc_mem(size, info, baseptr, ierror)
USE, INTRINSIC :: ISO_C_BINDING, ONLY : C_PTR
INTEGER(KIND=MPI_ADDRESS_KIND), INTENT(IN) :: size
TYPE(MPI_Info), INTENT(IN) :: info
TYPE(C_PTR), INTENT(OUT) :: baseptr
INTEGER, OPTIONAL, INTENT(OUT) :: ierror
MPI_ALLOC_MEM(SIZE, INFO, BASEPTR, IERROR)
INTEGER INFO, IERROR
INTEGER(KIND=MPI_ADDRESS_KIND) SIZE, BASEPTR

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 mpif.h 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 info argument can 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. Valid info values are implementation-dependent; a null directive value of info = MPI_INFO_NULL is always valid.

The function MPI_ALLOC_MEM may return an error code of class MPI_ERR_NO_MEM to indicate it failed because memory is exhausted.

int MPI_Free_mem(void *base)

MPI_Free_mem(base, ierror)
TYPE(*), DIMENSION(..), INTENT(IN), ASYNCHRONOUS :: base
INTEGER, OPTIONAL, INTENT(OUT) :: ierror
MPI_FREE_MEM(BASE, IERROR)
<type> BASE(*)
INTEGER IERROR

The function MPI_FREE_MEM may return an error code 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.

  USE mpi_f08   !  or  USE mpi      (not guaranteed with INCLUDE 'mpif.h') 
  USE, INTRINSIC :: ISO_C_BINDING 
  TYPE(C_PTR) :: p 
  REAL, DIMENSION(:,:), POINTER :: a            ! no memory is allocated 
  INTEGER, DIMENSION(2) :: shape 
  INTEGER(KIND=MPI_ADDRESS_KIND) :: size 
  shape = (/100,100/) 
  size = 4 * shape(1) * shape(2)                ! assuming 4 bytes per REAL 
  CALL MPI_Alloc_mem(size,MPI_INFO_NULL,p,ierr) ! memory is allocated and 
  CALL C_F_POINTER(p, a, shape) ! intrinsic     ! now accessible via a(i,j) 
  ...                           ! in ISO_C_BINDING 
  a(3,5) = 2.71; 
  ... 
  CALL MPI_Free_mem(a, ierr)                    ! memory is freed 

Example Example of use of MPI_ALLOC_MEM, in Fortran with non-standard Cray-pointers. We assume 4-byte REALs, and assume that these pointers are address-sized.

  REAL A 
  POINTER (P, A(100,100))   ! no memory is allocated 
  INTEGER(KIND=MPI_ADDRESS_KIND) SIZE 
  SIZE = 4*100*100  
  CALL MPI_ALLOC_MEM(SIZE, MPI_INFO_NULL, P, IERR) 
  ! memory is allocated 
  ... 
  A(3,5) = 2.71; 
  ... 
  CALL MPI_FREE_MEM(A, IERR) ! memory is freed 

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.

  float  (* f)[100][100]; 
  /* no memory is allocated */ 
  MPI_Alloc_mem(sizeof(float)*100*100, MPI_INFO_NULL, &f); 
  /* memory allocated */ 
  ... 
  (*f)[5][3] = 2.71; 
  ... 
  MPI_Free_mem(f);