MPI_TESTANY, MPI_Testany

Purpose

Tests for the completion of any nonblocking operation.

C synopsis

#include <mpi.h>
int MPI_Testany(int count,MPI_Request *array_of_requests,int *index,
                int *flag,MPI_Status *status);

C++ synopsis

#include mpi.h
bool MPI::Request::Testany(int count, MPI::Request array[],
                           int& index);

#include mpi.h
bool MPI::Request::Testany(int count, MPI::Request array[],
                           int& index, MPI::Status& status);

FORTRAN synopsis

include 'mpif.h' or use mpi
MPI_TESTANY(INTEGER COUNT,INTEGER ARRAY_OF_REQUESTS(*),INTEGER INDEX,INTEGER FLAG,
            INTEGER STATUS(MPI_STATUS_SIZE),INTEGER IERROR)

Description

If one of the operations has completed, MPI_TESTANY returns flag = true and
returns in index the index of this request in the array, and returns in
status the status of the operation. If the request was allocated by a
nonblocking operation, the request is deallocated and the handle is set to
MPI_REQUEST_NULL.

If none of the operations has completed, it returns flag = false and
returns a value of MPI_UNDEFINED in index, and status is undefined. The
array can contain null or inactive handles. When the array contains no
active handles, the call returns immediately with flag = true, index =
MPI_UNDEFINED, and empty status.

MPI_TESTANY(count, array_of_requests, index, flag, status) has the same
effect as the execution of MPI_TEST(array_of_requests[i], flag, status),
for i = 0, 1, ..., count-1, in some arbitrary order, until one call returns
flag = true, or all fail.

The error fields are never modified unless the function gives a return code
of MPI_ERR_IN_STATUS. In which case, the error field of every MPI_Status is
modified to reflect the result of the corresponding request.

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 it. See IBM Parallel Environment for AIX:
MPI Programming Guide for more information on programming with MPI in a
threads environment.

Parameters

count
     is the list length (integer) (IN)
array_of_requests
     is the array of request (array of handles) (INOUT)
index
     is the index of the operation that completed, or MPI_UNDEFINED is no
     operation completed (OUT)
flag
     is true if one of the operations is complete (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.

Notes

The array is indexed from zero (0) in C and from one (1) in FORTRAN.

Errors

Invalid count
     count < 0

Invalid request array

Invalid request(s)

Truncation occurred

A GRequest free function returned an error

A GRequest query function returned an error

Invalid status ignore value

Invalid form of status ignore

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_TEST
     MPI_WAITANY