MPIWaitsome(3OpenMPI) MPIWaitsome(3OpenMPI)

NAME
       MMPPIIWWaaiittssoommee - Waits for some given communications to complete.


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


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


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

       static int Request::Waitsome(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
       Waits  until at least one of the operations associated with active han-
       dles in the list have completed. Returns  in  outcount  the  number  of
       requests  from  the list arrayofrequests that have completed. Returns
       in the first outcount  locations  of  the  array  arrayofindices  the
       indices  of these operations (index within the array arrayofrequests;
       the array is indexed from 0 in C and from 1 in Fortran). Returns in the
       first  outcount  locations  of the array arrayofstatus 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 MPIREQUESTNULL.

       If the list contains no active handles, then the call  returns  immedi-
       ately with outcount = MPIUNDEFINED.

       When one or more of the communications completed by MPIWaitsome fails,
       then it is desirable to return specific information on each  communica-
       tion.  The  arguments outcount, arrayofindices, and arrayofstatuses
       will be adjusted to indicate completion of all communications that have
       succeeded   or   failed.   The   call   will   return  the  error  code
       MPIERRINSTATUS and the error field of each status returned  will  be
       set  to  indicate  success  or  to  indicate  the  specific  error that
       occurred. The call will return MPISUCCESS if no request resulted in an
       error,  and  will return another error code if it failed for other rea-
       sons (such as invalid arguments). In such cases, it will not update the
       error fields of the statuses.

       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.

       EExxaammppllee:: Same code as the example in  the  MPIWaitany  man  page,  but
       using MPIWaitsome.

           CALL MPICOMMSIZE(comm, size, ierr)
           CALL MPICOMMRANK(comm, rank, ierr)
           IF(rank .GT. 0) THEN         ! client code
               DO WHILE(.TRUE.)
                  CALL MPIISEND(a, n, MPIREAL, 0, tag, comm, request, ierr)
                  CALL MPIWAIT(request, status, ierr)
               END DO
           ELSE         ! rank=0 - server code
               DO i=1, size-1
                  CALL MPIIRECV(a(1,i), n, MPIREAL, i, tag,
                                 comm, requests(i), ierr)
               END DO
               DO WHILE(.TRUE.)
                  CALL MPIWAITSOME(size, requestlist, numdone,
                                   indices, statuses, ierr)
                  DO i=1, numdone
                     CALL DOSERVICE(a(1, indices(i)))
                     CALL MPIIRECV(a(1, indices(i)), n, MPIREAL, 0, tag,
                                  comm, requests(indices(i)), ierr)
                  END DO
               END DO
           END IF


NNOOTTEESS
       The  array  of indices are in the range 0 to incount-1 for C and in the
       range 1 to incount for Fortran.


EERRRROORRSS
       For each invocation of MPIWaitsome, 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  MPIWaitsome  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
       MPITestsome
       MPIWait
       MPIWaitall
       MPIWaitany
       MPIWinseterrhandler




Open MPI 1.2                    September 2006          MPIWaitsome(3OpenMPI)