MPIWait(3OpenMPI) MPIWait(3OpenMPI)

NAME
       MMPPIIWWaaiitt - Waits for an MPI send or receive to complete.


SSYYNNTTAAXX
CC SSyynnttaaxx
       #include 
       int MPIWait(MPIRequest *request, MPIStatus *status)


FFoorrttrraann SSyynnttaaxx
       INCLUDE 'mpif.h'
       MPIWAIT(REQUEST, STATUS, IERROR)
            INTEGER   REQUEST, STATUS(MPISTATUSSIZE), IERROR


CC++++ SSyynnttaaxx
       #include 
       void Request::Wait(Status& status)

       void Request::Wait()


IINNPPUUTT PPAARRAAMMEETTEERR
       request   Request (handle).


OOUUTTPPUUTT PPAARRAAMMEETTEERRSS
       status    Status object (status).

       IERROR    Fortran only: Error status (integer).


DESCRIPTION
       A  call to MPIWait returns when the operation identified by request is
       complete. If the communication object associated with this request  was
       created by a nonblocking send or receive call, then the object is deal-
       located by the call to MPIWait  and  the  request  handle  is  set  to
       MPIREQUESTNULL.

       The  call  returns,  in status, information on the completed operation.
       The content of the  status  object  for  a  receive  operation  can  be
       accessed  as  described in Section 3.2.5 of the MPI-1 Standard, "Return
       Status." The status object for a send operation may  be  queried  by  a
       call  to  MPITestcancelled  (see  Section  3.8 of the MPI-1 Standard,
       "Probe and Cancel").

       If your application does not need to examine the status field, you  can
       save  resources by using the predefined constant MPISTATUSIGNORE as a
       special value for the status argument.

       One is allowed to call MPIWait with a null or inactive  request  argu-
       ment. In this case the operation returns immediately with empty status.

       Successful return of MPIWait after an MPIIbsend implies that the user
       send  buffer can be reused  i.e., data has been sent out or copied into
       a buffer attached with MPIBufferattach. Note that, at this point,  we
       can no longer cancel the send (for more information, see Section 3.8 of
       the MPI-1 Standard, "Probe and Cancel"). If a matching receive is never
       posted,  then the buffer cannot be freed. This runs somewhat counter to
       the stated goal of MPICancel (always being able to free program  space
       that was committed to the communication subsystem).

       Example: Simple usage of nonblocking operations and  MPIWait.

           CALL MPICOMMRANK(comm, rank, ierr)
           IF(rank.EQ.0) THEN
               CALL MPIISEND(a(1), 10, MPIREAL, 1, tag, comm, request, ierr)
               **** do some computation ****
               CALL MPIWAIT(request, status, ierr)
           ELSE
               CALL MPIIRECV(a(1), 15, MPIREAL, 0, tag, comm, request, ierr)
               **** do some computation ****
               CALL MPIWAIT(request, status, ierr)
           END IF


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,          MPIFileseterrhandler,           or
       MPIWinseterrhandler (depending on the type of MPI handle that gener-
       ated the request); 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.

       Note that per MPI-1 section 3.2.5, MPI exceptions on requests passed to
       MPIWAIT  do not set the status.MPIERROR field in the returned status.
       The error code is passed to the  back-end  error  handler  and  may  be
       passed  back  to the caller through the return value of MPIWAIT if the
       back-end error handler returns it.  The pre-defined MPI  error  handler
       MPIERRORSRETURN exhibits this behavior, for example.


SEE ALSO
       MPICommseterrhandler
       MPIFileseterrhandler
       MPITest
       MPITestall
       MPITestany
       MPITestsome
       MPIWaitall
       MPIWaitany
       MPIWaitsome
       MPIWinseterrhandler




Open MPI 1.2                      March 2007                MPIWait(3OpenMPI)