MPITest(3OpenMPI) MPITest(3OpenMPI)

NAME
       MMPPIITTeesstt - Tests for the completion of a specific send or receive.


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


FFoorrttrraann SSyynnttaaxx
       INCLUDE 'mpif.h'
       MPITEST(REQUEST, FLAG, STATUS, IERROR)
            LOGICAL   FLAG
            INTEGER   REQUEST, STATUS(MPISTATUSSIZE), IERROR


CC++++ SSyynnttaaxx
       #include 
       bool Request::Test(Status& status)

       bool Request::Test()


IINNPPUUTT PPAARRAAMMEETTEERR
       request   Communication request (handle).


OOUUTTPPUUTT PPAARRAAMMEETTEERRSS
       flag      True if operation completed (logical).

       status    Status object (status).

       IERROR    Fortran only: Error status (integer).


DESCRIPTION
       A  call  to MPITest returns flag = true if the operation identified by
       request is complete. In such a case, the status object is set  to  con-
       tain  information  on  the  completed  operation;  if the communication
       object was created by a nonblocking send or receive, then it is deallo-
       cated  and  the  request  handle  is  set to MPIREQUESTNULL. The call
       returns flag = false, otherwise. In this case, the value of the  status
       object is undefined. MPITest is a local operation.

       The  return  status  object for a receive operation carries information
       that can be accessed as described in Section 3.2.5 of the  MPI-1  Stan-
       dard,  "Return  Status." The status object for a send operation carries
       information that can be accessed 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 MPITest with a null or inactive request argu-
       ment. In such a case the operation returns with flag = true  and  empty
       status.

       The  functions MPIWait and MPITest can be used to complete both sends
       and receives.


NNOOTTEESS
       The use of the nonblocking MPITest call allows the  user  to  schedule
       alternative  activities  within a single thread of execution. An event-
       driven  thread  scheduler  can  be  emulated  with  periodic  calls  to
       MPITest.


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
       MPITEST  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 MPITEST if the
       back-end error handler returns it.  The pre-defined MPI  error  handler
       MPIERRORSRETURN exhibits this behavior, for example.


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




Open MPI 1.2                    September 2006              MPITest(3OpenMPI)