MPI_TEST, MPI_Test

Purpose

Checks to see if a nonblocking request has completed.

C synopsis

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

C++ synopsis

#include mpi.h
bool MPI::Request::Test();

#include mpi.h
bool MPI::Request::Test(MPI::Status& status);

FORTRAN synopsis

include 'mpif.h' or use mpi
MPI_TEST(INTEGER REQUEST,INTEGER FLAG,INTEGER STATUS(MPI_STATUS_SIZE),
    INTEGER IERROR)

Description

MPI_TEST returns flag = true if the operation identified by request is
complete. The status object is set to contain information on the completed
operation. The request object is deallocated and the request handle is set
to MPI_REQUEST_NULL. Otherwise, flag = false and the status object is
undefined. MPI_TEST is a local operation. The status object can be queried
for information about the operation. (See MPI_WAIT.)

You can call MPI_TEST with a null or inactive request argument. The
operation returns flag = true and empty status.

The error field of MPI_Status is never modified. The success or failure is
indicated by the return code only.

Passing MPI_STATUS_IGNORE for the status argument causes PE MPI to skip
filling in the status fields. By passing this value for status, you can
avoid having to allocate a status object in programs that do not need to
examine the status fields.

When one of the MPI wait or test calls returns status for a nonblocking
operation request and the corresponding blocking operation does not provide
a status argument, the status from this wait or test call does not contain
meaningful source, tag, or message size information.

When you use this subroutine in a threads application, make sure the
request is tested on only one thread. The request does not have to be
tested on the thread that created the request. See IBM Parallel Environment
for AIX: MPI Programming Guide for more information on programming with MPI
in a threads environment.

Parameters

request
     is the operation request (handle) (INOUT)
flag
     is true if the operation completed (logical) (OUT)
status
     is the status object (Status) (INOUT). Note that in FORTRAN a single
     status object is an array of integers.
IERROR
     is the FORTRAN return code. It is always the last argument.

Errors

A GRequest free function returned an error

A GRequest query function returned an error

Invalid status ignore value

Invalid form of status ignore

Invalid request handle

Truncation occurred

MPI not initialized

MPI already finalized

Develop mode error if:

Illegal buffer update (ISEND)

Inconsistent datatype (MPE_I collectives)

Inconsistent message length (MPE_I collectives)

Inconsistent op (MPE_I collectives)

Match of blocking and non-blocking collectives (MPE_I collectives)

Related information

     MPI_TESTALL
     MPI_TESTANY
     MPI_TESTSOME
     MPI_WAIT