MPIGrequeststart(3OpenMPI) MPIGrequeststart(3OpenMPI)

NAME
       MMPPIIGGrreeqquueessttssttaarrtt  - Starts a generalized request and returns a handle
       to it in request.


SSYYNNTTAAXX
CC SSyynnttaaxx
       #include 
       int MPIGrequeststart(MPIGrequestqueryfunction *queryfn,
            MPIGrequestfreefunction *freefn,
            MPIGrequestcancelfunction *cancelfn, void *extrastate,
            MPIRequest *request)


FFoorrttrraann SSyynnttaaxx ((sseeee FFOORRTTRRAANN 7777 NNOOTTEESS))
       INCLUDE 'mpif.h'
       MPIGREQUESTSTART(QUERYFN, FREEFN, CANCELFN, EXTRASTATE,
            REQUEST, IERROR)
            INTEGER   REQUEST, IERROR
            EXTERNAL QUERYFN, FREEFN, CANCELFN
            INTEGER (KIND=MPIADDRESSKIND) EXTRASTATE


CC++++ SSyynnttaaxx
       #include 
       static MPI::Grequest
                    MPI::Grequest::Start(const MPI::Grequest::Queryfunction
                    queryfn, const MPI::Grequest::Freefunction freefn,
                    const MPI::Grequest::Cancelfunction cancelfn,
                    void *extrastate)


IINNPPUUTT PPAARRAAMMEETTEERRSS
       queryfn  Callback function invoked  when  request  status  is  queried
                 (function).

       freefn   Callback function invoked when request is freed (function).

       cancelfn Callback  function  invoked  when  request is canceled (func-
                 tion).

       extrastate
                 Extra state.


OOUUTTPPUUTT PPAARRAAMMEETTEERRSS
       request   Generalized request (handle).

       IERROR    Fortran only: Error status (integer).


DESCRIPTION
       MPIGrequeststart starts a generalized request and returns a handle to
       it in request.

       The  syntax and meaning of the callback functions are listed below. All
       callback functions are passed the extrastate argument that was associ-
       ated with the request by the starting call MPIGrequeststart. This can
       be used to maintain user-defined state for the request. In C, the query
       function is

          typedef int MPIGrequestqueryfunction(void *extrastate,
                       MPIStatus *status);

       In Fortran, it is

          SUBROUTINE GREQUESTQUERYFUNCTION(EXTRASTATE, STATUS, IERROR)
              INTEGER STATUS(MPISTATUSSIZE), IERROR
              INTEGER(KIND=MPIADDRESSKIND) EXTRASTATE

       and in C++, it is

          typedef int MPI::Grequest::Queryfunction(void* extrastate,
                       MPI::Status& status);

       The  queryfn  function computes the status that should be returned for
       the generalized request. The status  also  includes  information  about
       successful/unsuccessful  cancellation  of  the  request  (result  to be
       returned by MPITestcancelled).

       The queryfn function is invoked by  the  MPI{Wait|Test}{any|some|all}
       call  that completed the generalized request associated with this call-
       back.  The  callback   function   is   also   invoked   by   calls   to
       MPIRequestgetstatus if the request is complete when the call occurs.
       In both cases, the callback is passed a reference to the  corresponding
       status  variable  passed  by the user to the MPI call. If the user pro-
       vided MPISTATUSIGNORE or MPISTATUSESIGNORE to the MPI function that
       causes  queryfn to be called, then MPI will pass a valid status object
       to queryfn, and this status will be ignored upon return of  the  call-
       back  function.  Note  that  queryfn  is  invoked  only after MPIGre-
       questcomplete is called on the request;  it  may  be  invoked  several
       times  for  the  same  generalized  request.  Note  also that a call to
       MPI{Wait|Test}{some|all} may cause multiple  invocations  of  queryfn
       callback  functions, one for each generalized request that is completed
       by the MPI call. The order of these invocations  is  not  specified  by
       MPI.

       In C, the free function is

          typedef int MPIGrequestfreefunction(void *extrastate);

       In Fortran, it is

          SUBROUTINE GREQUESTFREEFUNCTION(EXTRASTATE, IERROR)
              INTEGER IERROR
              INTEGER(KIND=MPIADDRESSKIND) EXTRASTATE

       And in C++, it is

          typedef int MPI::Grequest::Freefunction(void* extrastate);

       The  freefn  callback  function  is invoked to clean up user-allocated
       resources when the generalized request is freed.

       The freefn function is invoked  by  the  MPI{Wait|Test}{any|some|all}
       call  that completed the generalized request associated with this call-
       back. freefn is invoked after  the  call  to  queryfn  for  the  same
       request.  However,  if  the  MPI  call  completed  multiple generalized
       requests, the order in which freefn callback functions are invoked  is
       not specified by MPI.

       The  freefn callback is also invoked for generalized requests that are
       freed    by    a    call    to    MPIRequestfree    (no    call    to
       MPI{Wait|Test}{any|some|all}  will  occur for such a request). In this
       case, the callback function will be  called  either  in  the  MPI  call
       MPIRequestfree(request)   or   in   the  MPI  call  MPIGrequestcom-
       plete(request), whichever happens last. In other words,  in  this  case
       the   actual   freeing   code   is  executed  as  soon  as  both  calls
       (MPIRequestfree and MPIGrequestcomplete) have occurred. The request
       is  not  deallocated  until  after freefn completes. Note that freefn
       will be invoked only once per request by a correct program.

       In C, the cancel function is

          typedef int MPIGrequestcancelfunction(void *extrastate, int complete);

       In Fortran, the cancel function is

          SUBROUTINE GREQUESTCANCELFUNCTION(EXTRASTATE, COMPLETE, IERROR)
              INTEGER IERROR
              INTEGER(KIND=MPIADDRESSKIND) EXTRASTATE
              LOGICAL COMPLETE

       In C++, the cancel function is

          typedef in MPI::Grequest::Cancelfunction(void* extrastate,
                      bool complete);

       The cancelfn function is invoked to start the cancelation of a  gener-
       alized request. It is called by MPIRequestcancel(request). MPI passes
       to the callback function  complete=true  if  MPIGrequestcomplete  has
       already been called on the request, and complete=false otherwise.


FFOORRTTRRAANN 7777 NNOOTTEESS
       The MPI standard prescribes portable Fortran syntax for the EXTRASTATE
       argument only for Fortran 90.  FORTRAN 77 users may use the  non-porta-
       ble syntax

            INTEGER*MPIADDRESSKIND EXTRASTATE

       where  MPIADDRESSKIND  is  a constant defined in mpif.h and gives the
       length of the declared integer in bytes.


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.

       All  callback  functions  return an error code. The code is passed back
       and dealt with as appropriate for the error code by  the  MPI  function
       that  invoked  the  callback  function. For example, if error codes are
       returned, then the error code returned by the callback function will be
       returned by the MPI function that invoked the callback function. In the
       case of a  MPI{Wait|Test}any  call  that  invokes  both  queryfn  and
       freefn,  the  MPI call will return the error code returned by the last
       callback, namely freefn. If one or more of the requests in a  call  to
       MPI{Wait|Test}{some|all}  has  failed,  then  the MPI call will return
       MPIERRINSTATUS. In such a case, if the MPI call was passed an  array
       of  statuses,  then MPI will return in each of the statuses that corre-
       spond to a completed generalized request the error code returned by the
       corresponding  invocation of its freefn callback function. However, if
       the MPI function was passed MPISTATUSESIGNORE,  then  the  individual
       error codes returned by each callback function will be lost.

       See the MPI man page for a full list of MPI error codes.






Open MPI 1.2                    September 2006    MPIGrequeststart(3OpenMPI)