Skip to content

Latest commit

 

History

History
122 lines (86 loc) · 3.59 KB

MPI_Comm_create_keyval.3.rst

File metadata and controls

122 lines (86 loc) · 3.59 KB
Raw

MPI_Comm_create_keyval

MPI_Comm_create_keyval Generates a new attribute key.

SYNTAX

C Syntax

#include <mpi.h>

int MPI_Comm_create_keyval(MPI_Comm_copy_attr_function
    *comm_copy_attr_fn, MPI_Comm_delete_attr_function
    *comm_delete_attr_fn, int *comm_keyval,
    void *extra_state)

Fortran Syntax

USE MPI
! or the older form: INCLUDE 'mpif.h'

MPI_COMM_CREATE_KEYVAL(COMM_COPY_ATTR_FN, COMM_DELETE_ATTR_FN,
    COMM_KEYVAL, EXTRA_STATE, IERROR)
    EXTERNAL COMM_COPY_ATTR_FN, COMM_DELETE_ATTR_FN
    INTEGER COMM_KEYVAL, IERROR

    INTEGER(KIND=MPI_ADDRESS_KIND) EXTRA_STATE

Fortran 2008 Syntax

USE mpi_f08

MPI_Comm_create_keyval(comm_copy_attr_fn, comm_delete_attr_fn, comm_keyval,
        extra_state, ierror)
    PROCEDURE(MPI_Comm_copy_attr_function) :: comm_copy_attr_fn
    PROCEDURE(MPI_Comm_delete_attr_function) :: comm_delete_attr_fn
    INTEGER, INTENT(OUT) :: comm_keyval
    INTEGER(KIND=MPI_ADDRESS_KIND), INTENT(IN) :: extra_state
    INTEGER, OPTIONAL, INTENT(OUT) :: ierror

INPUT PARAMETERS

  • comm_copy_attr_fn : Copy callback function for comm_keyval

    (function).

  • comm_delete_attr_fn : Delete callback function for

    comm_keyval (function).

  • extra_state : Extra state for callback functions.

OUTPUT PARAMETER

  • comm_keyval : Key value for future access (integer).
  • ierror : Fortran only: Error status (integer).

DESCRIPTION

This function replaces MPI_Keyval_create, the use of which is deprecated. The C binding is identical. The Fortran binding differs in that extra_state is an address-sized integer. Also, the copy and delete callback functions have Fortran bindings that are consistent with address-sized attributes. The argument comm_copy_attr_fn may be specified as MPI_COMM_NULL_COPY_FN or MPI_COMM_DUP_FN from C or Fortran. MPI_COMM_NULL_COPY_FN is a function that does nothing more than returning flag = 0 and MPI_SUCCESS. MPI_COMM_DUP_FN is a simple-minded copy function that sets flag = 1, returns the value of attribute_val_in in attribute_val_out, and returns MPI_SUCCESS. These replace the MPI-1 predefined callbacks MPI_NULL_COPY_FN and MPI_DUP_FN, the use of which is deprecated. The two C callback functions are:

typedef int MPI_Comm_copy_attr_function(MPI_Comm oldcomm, int comm_keyval,
             void *extra_state, void *attribute_val_in,
             void *attribute_val_out, int *flag);

typedef int MPI_Comm_delete_attr_function(MPI_Comm comm, int comm_keyval,
             void *attribute_val, void *extra_state);

which are the same as the MPI-1.1 calls but with a new name. The old names are deprecated. The two Fortran callback functions are:

SUBROUTINE COMM_COPY_ATTR_FN(OLDCOMM, COMM_KEYVAL, EXTRA_STATE,
             ATTRIBUTE_VAL_IN, ATTRIBUTE_VAL_OUT, FLAG, IERROR)
    INTEGER OLDCOMM, COMM_KEYVAL, IERROR

    INTEGER(KIND=MPI_ADDRESS_KIND) EXTRA_STATE, ATTRIBUTE_VAL_IN,
        ATTRIBUTE_VAL_OUT
    LOGICAL FLAG

SUBROUTINE COMM_DELETE_ATTR_FN(COMM, COMM_KEYVAL, ATTRIBUTE_VAL, EXTRA_STATE,
             IERROR)
    INTEGER COMM, COMM_KEYVAL, IERROR

    INTEGER(KIND=MPI_ADDRESS_KIND) ATTRIBUTE_VAL, EXTRA_STATE

ERRORS

* MPI_Comm_free_keyval