MPIKeyvalcreate(3OpenMPI) MPIKeyvalcreate(3OpenMPI)

NAME
       MMPPIIKKeeyyvvaallccrreeaattee  -  Generates a new attribute key - use of this rou-
       tine is deprecated.


SSYYNNTTAAXX
CC SSyynnttaaxx
       #include 
       int MPIKeyvalcreate(MPICopyfunction *copyfn,
            MPIDeletefunction *deletefn, int *keyval, void *extrastate)


FFoorrttrraann SSyynnttaaxx
       INCLUDE 'mpif.h'
       MPIKEYVALCREATE(COPYFN, DELETEFN, KEYVAL, EXTRASTATE, IERROR)
            EXTERNAL  COPYFN, DELETEFN
            INTEGER   KEYVAL, EXTRASTATE, IERROR



IINNPPUUTT PPAARRAAMMEETTEERRSS
       copyfn   Copy callback function for keyval.

       deletefn Delete callback function for keyval.

       extrastate
                 Extra state for callback functions.


OOUUTTPPUUTT PPAARRAAMMEETTEERRSS
       keyval    Key value for future access (integer).

       IERROR    Fortran only: Error status (integer).


DESCRIPTION
       Note that use of this routine is deprecated as  of  MPI-2.  Please  use
       MPICommcreatekeyval instead.

       This deprecated routine is not available in C++.

       Generates a new attribute key. Keys are locally unique in a process and
       opaque to the user, though they are explicitly stored in integers. Once
       allocated, the key value can be used to associate attributes and access
       them on any locally defined communicator.

       The copyfn function is invoked when a communicator  is  duplicated  by
       MPICOMMDUP.  copyfn  should  be  of type MPICopyfunction, which is
       defined as follows:

         typedef int MPICopyfunction(MPIComm oldcomm, int keyval,
                                       void *extrastate, void *attributevalin,
                                       void *attributevalout, int *flag)

       A Fortran declaration for such a function is as follows:

         SUBROUTINE COPYFUNCTION(OLDCOMM, KEYVAL, EXTRASTATE, ATTRIBUTEVALIN,
                     ATTRIBUTEVALOUT, FLAG, IERR)
         INTEGER OLDCOMM, KEYVAL, EXTRASTATE,
         ATTRIBUTEVALIN, ATTRIBUTEVALOUT, IERR
         LOGICAL FLAG

       The copy callback function is invoked for each key value in oldcomm  in
       arbitrary  order.  Each  call  to  the copy callback is made with a key
       value and its corresponding attribute. If it returns flag = 0, then the
       attribute is deleted in the duplicated communicator. Otherwise ( flag =
       1),  the  new  attribute  value  is  set  to  the  value  returned   in
       attributevalout.  The  function returns MPISUCCESS on success and an
       error code on failure (in which case MPICommdup will fail).

       copyfn may be specified as MPINULLCOPYFN or MPIDUPFN from  either
       C  or  Fortran;  MPINULLCOPYFN is a function that does nothing other
       than return flag = 0, and MPISUCCESS. MPIDUPFN  is  a  simple-minded
       copy function that sets flag = 1, returns the value of attributevalin
       in attributevalout, and returns MPISUCCESS.


NNOOTTEESS
       Key values are global (available for any and all communicators).

       There are subtle differences between C and Fortran  that  require  that
       the  copyfn  be written in the same language that MPIKeyvalcreate is
       called from. This should not be a problem for  most  users;  only  pro-
       gramers  using  both  Fortran and C in the same program need to be sure
       that they follow this rule.

       Even   though    both    formal    arguments    attributevalin    and
       attributevalout  are  of  type void*, their usage differs. The C copy
       function is  passed  by  MPI  in  attributevalin  the  value  of  the
       attribute, and in attributevalout the address of the attribute, so as
       to allow the function to return the (new) attribute value. The  use  of
       type void* for both is to avoid messy type casts.

       A valid copy function is one that completely duplicates the information
       by making a full duplicate copy of the data structures  implied  by  an
       attribute;  another  might  just  make  another  reference to that data
       structure, while using a  reference-count  mechanism.  Other  types  of
       attributes  might  not  copy  at all (they might be specific to oldcomm
       only).

       Analogous to copyfn is a callback deletion function, defined  as  fol-
       lows.  The deletefn function is invoked when a communicator is deleted
       by MPICommfree or when a call is made explicitly to  MPIAttrdelete.
       deletefn  should  be  of type MPIDeletefunction, which is defined as
       follows:

         typedef int MPIDeletefunction(MPIComm comm, int keyval,
             void *attributeval, void *extrastate);

       A Fortran declaration for such a function is as follows:

         SUBROUTINE DELETEFUNCTION(COMM, KEYVAL,ATTRIBUTEVAL, EXTRASTATE, IERR)
             INTEGER COMM, KEYVAL, ATTRIBUTEVAL, EXTRASTATE, IERR

       This  function  is  called  by  MPICommfree,   MPIAttrdelete,   and
       MPIAttrput to do whatever is needed to remove an attribute. The func-
       tion returns MPISUCCESS on success and an error code  on  failure  (in
       which case MPICOMMFREE will fail).

       deletefn  may be specified as MPINULLDELETEFN from either C or FOR-
       TRAN; MPINULLDELETEFN is a function that does  nothing,  other  than
       returning MPISUCCESS.

       The  special key value MPIKEYVALINVALID is never returned by MPIKey-
       valcreate. Therefore, it can be used for static initialization of  key
       values.


EERRRROORRSS
       Almost  all MPI routines return an error value; C routines as the value
       of the function and Fortran routines in the last  argument.  C++  func-
       tions  do  not  return  errors.  If the default error handler is set to
       MPI::ERRORSTHROWEXCEPTIONS, then on error the C++ exception mechanism
       will be used to throw an MPI:Exception object.

       Before  the  error  value is returned, the current MPI error handler is
       called. By default, this error handler aborts the MPI job,  except  for
       I/O   function   errors.   The   error  handler  may  be  changed  with
       MPICommseterrhandler; the predefined error handler MPIERRORSRETURN
       may  be  used  to cause error values to be returned. Note that MPI does
       not guarantee that an MPI program can continue past an error.


SEE ALSO
       MPIKeyvalfree



Open MPI 1.2                    September 2006     MPIKeyvalcreate(3OpenMPI)