MPI_TESTSOME, MPI_Testsome

Purpose

Tests a collection of nonblocking operations for completion.

C synopsis

#include <mpi.h>
int MPI_Testsome(int incount,MPI_Request *array_of_requests,
                 int *outcount,int *array_of_indices,
                 MPI_Status *array_of_statuses);

C++ synopsis

#include mpi.h
int MPI::Request::Testsome(int incount, MPI::Request req_array[],
                           int array_of_indices[]);

#include mpi.h
int MPI::Request::Testsome(int incount, MPI::Request req_array[],
                           int array_of_indices[],
                           MPI::Status stat_array[]);

FORTRAN synopsis

include 'mpif.h' or use mpi
MPI_TESTSOME(INTEGER INCOUNT,INTEGER ARRAY_OF_REQUESTS(*),
             INTEGER OUTCOUNT,INTEGER ARRAY_OF_INDICES(*),
             INTEGER ARRAY_OF_STATUSES(MPI_STATUS_SIZE,*),INTEGER IERROR)

Description

This subroutine tests a collection of nonblocking operations for
completion. MPI_TESTSOME behaves like MPI_WAITSOME except that MPI_TESTSOME
is a local operation and returns immediately. outcount = 0 is returned when
no operation has completed.

When a request for a receive repeatedly appears in a list of requests
passed to MPI_TESTSOME and a matching send is posted, then the receive
eventually succeeds unless the send is satisfied by another receive. This
fairness requirement also applies to send requests and to I/O requests.

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_STATUSES_IGNORE for the array_of_statuses argument causes PE
MPI to skip filling in the status fields. By passing this value for
array_of_statuses, you can avoid having to allocate a status object array
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

incount
     is the length of array_of_requests (integer) (IN)
array_of_requests
     is the array of requests (array of handles) (INOUT)
outcount
     is the number of completed requests (integer) (OUT)
array_of_indices
     is the array of indices of operations that completed (array of
     integers) (OUT)
array_of_statuses
     is the array of status objects for operations that completed (array of
     status) (INOUT). Note that in FORTRAN a status object is itself an
     array.
IERROR
     is the FORTRAN return code. It is always the last argument.

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_WAITSOME