Open MPI logo

MPI_Testsome(3) man page (version 1.3.4)

  |   Home   |   Support   |   FAQ   |  

« Return to documentation listing



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

       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

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 inte-
                 gers).

       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.  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
       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_STA-
       TUSES_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 communica-
       tions;  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 han-
       dlers 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_IGNORE_STATUSES 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 con-
       tinue 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  For-
       tran   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.

SEE ALSO

       MPI_Comm_set_errhandler
       MPI_File_set_errhandler
       MPI_Test
       MPI_Testall
       MPI_Testany
       MPI_Wait
       MPI_Waitall
       MPI_Waitany
       MPI_Waitsome

« Return to documentation listing