Open MPI logo

MPI_Test(3) man page (version 1.3.4)

  |   Home   |   Support   |   FAQ   |  

« Return to documentation listing



NAME

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

SYNTAX


C Syntax

       #include <mpi.h>
       int MPI_Test(MPI_Request *request, int *flag, MPI_Status *status)

Fortran Syntax

       INCLUDE 'mpif.h'
       MPI_TEST(REQUEST, FLAG, STATUS, IERROR)
            LOGICAL   FLAG
            INTEGER   REQUEST, STATUS(MPI_STATUS_SIZE), IERROR

C++ Syntax

       #include <mpi.h>
       bool Request::Test(Status& status)

       bool Request::Test()

INPUT PARAMETER

       request   Communication request (handle).

OUTPUT PARAMETERS

       flag      True if operation completed (logical).

       status    Status object (status).

       IERROR    Fortran only: Error status (integer).

DESCRIPTION

       A  call  to MPI_Test 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 MPI_REQUEST_NULL. The call
       returns flag = false, otherwise. In this case, the value of the  status
       object is undefined. MPI_Test 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  MPI_Test_cancelled  (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 MPI_STATUS_IGNORE as  a
       special value for the status argument.

       One  is  allowed to call MPI_Test with a null or inactive request argu-
       ment. In such a case the operation returns with flag = true  and  empty
       status.
       driven  thread  scheduler  can  be  emulated  with  periodic  calls  to
       MPI_Test.

ERRORS

       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::ERRORS_THROW_EXCEPTIONS, 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
       MPI_Comm_set_errhandler,          MPI_File_set_errhandler,           or
       MPI_Win_set_errhandler (depending on the type of MPI handle that gener-
       ated the request); the predefined error handler  MPI_ERRORS_RETURN  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
       MPI_TEST  do not set the status.MPI_ERROR 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 MPI_TEST if the
       back-end error handler returns it.  The pre-defined MPI  error  handler
       MPI_ERRORS_RETURN exhibits this behavior, for example.

SEE ALSO

       MPI_Comm_set_errhandler
       MPI_File_set_errhandler
       MPI_Testall
       MPI_Testany
       MPI_Testsome
       MPI_Wait
       MPI_Waitall
       MPI_Waitany
       MPI_Waitsome
       MPI_Win_set_errhandler

1.3.4                            Nov 11, 2009                      MPI_Test(3)

« Return to documentation listing