MPITestsome(3OpenMPI) MPITestsome(3OpenMPI)

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


SSYYNNTTAAXX
CC SSyynnttaaxx
       #include 
       int MPITestsome(int incount, MPIRequest *arrayofrequests,
            int *outcount, int *arrayofindices, MPIStatus *arrayofstatuses)


FFoorrttrraann SSyynnttaaxx
       INCLUDE 'mpif.h'
       MPITESTSOME(INCOUNT, ARRAYOFREQUESTS, OUTCOUNT,
                 ARRAYOFINDICES, ARRAYOFSTATUSES, IERROR)
            INTEGER   INCOUNT, ARRAYOFREQUESTS(*)
            INTEGER   OUTCOUNT, ARRAYOFINDICES(*)
            INTEGER   ARRAYOFSTATUSES(MPISTATUSSIZE,*), IERROR


CC++++ SSyynnttaaxx
       #include 
       static int Request::Testsome(int incount, Request
            arrayofrequests[], int arrayofindices[], Status arrayofstatuses[])

       static int Request::Testsome(int incount, Request
            arrayofrequests[], int arrayofindices[])


IINNPPUUTT PPAARRAAMMEETTEERRSS
       incount   Length of arrayofrequests (integer).

       arrayofrequests
                 Array of requests (array of handles).


OOUUTTPPUUTT PPAARRAAMMEETTEERRSS
       outcount  Number of completed requests (integer).

       arrayofindices
                 Array of indices of operations that completed (array of inte-
                 gers).

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

       IERROR    Fortran only: Error status (integer).


DESCRIPTION
       Behaves like MPIWaitsome, 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 = MPIUNDEFINED.

       MPITestsome is a local operation, which returns  immediately,  whereas
       MPIWaitsome 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 MPIWaitsome or MPITestsome, and a match-
       ing  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 MPITestsome are handled as
       for MPIWaitsome.

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


NNOOTTEESS
       The  use of MPITestsome is likely to be more efficient than the use of
       MPITestany. 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 MPIWaitsome so as not to starve
       any  client. Clients send messages to the server with service requests.
       The server calls MPIWaitsome with one receive request for each client,
       then handles all receives that have completed. If a call to MPIWaitany
       is used instead, then one  client  could  starve  while  requests  from
       another client always sneak in first.


EERRRROORRSS
       For  each  invocation of MPITestsome, 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.MPIERROR  field  (unless
       MPIIGNORESTATUSES was used).

       The  default  error handler aborts the MPI job, except for I/O function
       errors. The error handler may be changed with  MPICommseterrhandler,
       MPIFileseterrhandler,  or  MPIWinseterrhandler  (depending on the
       type of MPI handle that generated  the  MPI  request);  the  predefined
       error handler MPIERRORSRETURN 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  MPITestsome to return to the
       caller, the value MPIERRINSTATUS will be returned in the C and  For-
       tran   bindings.    In   C++,   if   the   predefined   error   handler
       MPI::ERRORSTHROWEXCEPTIONS is used, the value MPI::ERRINSTATUS will
       be  contained  in  the  MPI::Exception object.  The MPIERROR field can
       then be examined in the array of returned statuses to determine exactly
       which request(s) generated an exception.


SEE ALSO
       MPICommseterrhandler
       MPIFileseterrhandler
       MPITest
       MPITestall
       MPITestany
       MPIWait
       MPIWaitall
       MPIWaitany
       MPIWaitsome
       MPIWinseterrhandler




Open MPI 1.2                    September 2006          MPITestsome(3OpenMPI)