Ubuntu Manpage: MPI_Testsome - Tests for completion of one or more previously initiated communications in

Provided by: openmpi-doc_4.1.4-3ubuntu2_all

NAME

       MPI_Testsome  - Tests for completion of one or more previously initiated communications in
       a list.

SYNTAX

C Syntax

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

Fortran Syntax

       USE MPI
       ! or the older form: INCLUDE 'mpif.h'
       MPI_TESTSOME(INCOUNT, ARRAY_OF_REQUESTS, OUTCOUNT,
                 ARRAY_OF_INDICES, ARRAY_OF_STATUSES, IERROR)
            INTEGER   INCOUNT, ARRAY_OF_REQUESTS(*)
            INTEGER   OUTCOUNT, ARRAY_OF_INDICES(*)
            INTEGER   ARRAY_OF_STATUSES(MPI_STATUS_SIZE,*), IERROR

Fortran 2008 Syntax

       USE mpi_f08
       MPI_Testsome(incount, array_of_requests, outcount, array_of_indices,
                 array_of_statuses, ierror)
            INTEGER, INTENT(IN) :: incount
            TYPE(MPI_Request), INTENT(INOUT) :: array_of_requests(incount)
            INTEGER, INTENT(OUT) :: outcount, array_of_indices(*)
            TYPE(MPI_Status) :: array_of_statuses(*)
            INTEGER, OPTIONAL, INTENT(OUT) :: ierror

C++ Syntax

       #include <mpi.h>
       static int Request::Testsome(int incount, Request
            array_of_requests[], int array_of_indices[],
            Status array_of_statuses[])

       static int Request::Testsome(int incount, Request
            array_of_requests[], int array_of_indices[])

INPUT PARAMETERS

       incount   Length of array_of_requests (integer).

       array_of_requests
                 Array of requests (array of handles).

OUTPUT PARAMETERS

       outcount  Number of completed requests (integer).

       array_of_indices
                 Array of indices of operations that completed (array of integers).

       array_of_statuses
                 Array of status objects for operations that completed (array of status).

       IERROR    Fortran only: Error status (integer).

DESCRIPTION

Behaves like MPI_Waitsome, except that it returns immediately.

Returns in outcount the number of requests from the list array_of_requests that have
completed. Returns in the first outcount locations of the array array_of_indices the
indices of these operations (index within the array array_of_requests; the array is
indexed from 0 in C and from 1 in Fortran). Returns in the first outcount locations of the
array array_of_status the status for these completed operations. If a request that
completed was allocated by a nonblocking communication call, then it is deallocated, and
the associated handle is set to MPI_REQUEST_NULL.

If no operation has completed it returns outcount = 0. If there is no active handle in the
list, it returns outcount = MPI_UNDEFINED.

MPI_Testsome is a local operation, which returns immediately, whereas MPI_Waitsome blocks
until a communication completes, if it was passed a list that contains at least one active
handle. Both calls fulfill a fairness requirement: If a request for a receive repeatedly
appears in a list of requests passed to MPI_Waitsome or MPI_Testsome, and a matching send
has been posted, then the receive will eventually succeed unless the send is satisfied by
another receive; send requests also fulfill this fairness requirement.

Errors that occur during the execution of MPI_Testsome are handled as for MPI_Waitsome.

If your application does not need to examine the array_of_statuses field, you can save
resources by using the predefined constant MPI_STATUSES_IGNORE can be used as a special
value for the array_of_statuses argument.

NOTES

       The use of MPI_Testsome is likely to be more efficient than the use  of  MPI_Testany.  The
       former returns information on all completed communications; with the latter, a new call is
       required for each communication that completes.

       A server with multiple clients can use MPI_Waitsome  so  as  not  to  starve  any  client.
       Clients  send  messages to the server with service requests. The server calls MPI_Waitsome
       with one receive request for each client, then handles all receives that  have  completed.
       If a call to MPI_Waitany is used instead, then one client could starve while requests from
       another client always sneak in first.

ERRORS

       For each invocation of MPI_Testsome, if one or more requests generate  an  MPI  exception,
       only  the  first  MPI request that caused an exception will be passed to its corresponding
       error handler.  No other error  handlers  will  be  invoked  (even  if  multiple  requests
       generated  exceptions).   However,  all  requests  that  generate an exception will have a
       relevant  error  code  set   in   the   corresponding   status.MPI_ERROR   field   (unless
       MPI_STATUSES_IGNORE was used).

       The  default  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 generated the MPI
       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.

       If the invoked error handler allows MPI_Testsome  to  return  to  the  caller,  the  value
       MPI_ERR_IN_STATUS  will  be  returned  in  the  C  and  Fortran  bindings.  In C++, if the
       predefined   error   handler   MPI::ERRORS_THROW_EXCEPTIONS    is    used,    the    value
       MPI::ERR_IN_STATUS  will  be  contained in the MPI::Exception object.  The MPI_ERROR field
       can then be examined in  the  array  of  returned  statuses  to  determine  exactly  which
       request(s) generated an exception.