MPI_WAITSOME, MPI_Waitsome

Purpose

Waits for at least one of a list of nonblocking operations to complete.

C synopsis

#include <mpi.h>
int MPI_Waitsome(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::Waitsome(int incount, MPI::Request req_array[],
                           int array_of_indices[]);

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

FORTRAN synopsis

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

Description

This subroutine waits for at least one of a list of nonblocking operations
associated with active handles in the list to complete. The number of
completed requests from the list of array_of_requests is returned in
outcount. Returns in the first outcount locations of the array
array_of_indices the indices of these operations.

The status for the completed operations is returned in the first outcount
locations of the array array_of_statuses. When a completed request is
allocated by a nonblocking operation, it is deallocated and the associated
handle is set to MPI_REQUEST_NULL.

When the list contains no active handles, then the call returns immediately
with outcount = MPI_UNDEFINED.

When a request for a receive repeatedly appears in a list of requests
passed to MPI_WAITSOME and a matching send was 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 that the
wait for a given request is done on only one thread. The wait does not have
to be done 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, array_of_indices, and
     array_of_statuses (integer) (IN)
array_of_requests
     is an 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.

Notes

In C, the index within the array array_of_requests, is indexed from zero
and from one in FORTRAN.

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 count
     count < 0

Invalid request(s)

Invalid index array

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_TESTSOME
     MPI_WAIT