Provided by: openmpi-doc_1.6.5-8_all bug

NAME

       MPI_Waitsome - Waits for some given communications to complete.

SYNTAX

C Syntax

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

Fortran Syntax

       INCLUDE 'mpif.h'
       MPI_WAITSOME(INCOUNT, ARRAY_OF_REQUESTS, OUTCOUNT,
                 ARRAY_OF_INDICES, ARRAY_OF_STATUSES, IERROR)
            INTEGER   INCOUNT, ARRAY_OF_REQUESTS(*), OUTCOUNT
            INTEGER   ARRAY_OF_INDICES(*)
            INTEGER   ARRAY_OF_STATUSES(MPI_STATUS_SIZE*)
            INTEGER   IERROR

C++ Syntax

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

       static int Request::Waitsome(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

       Waits until at least one of the operations associated with active handles in the list have
       completed. 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 the list contains no active handles, then the call returns immediately with outcount  =
       MPI_UNDEFINED.

       When  one  or  more  of  the  communications  completed  by MPI_Waitsome fails, then it is
       desirable to return specific information on each communication.  The  arguments  outcount,
       array_of_indices,  and  array_of_statuses  will  be adjusted to indicate completion of all
       communications that have succeeded  or  failed.  The  call  will  return  the  error  code
       MPI_ERR_IN_STATUS  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  MPI_SUCCESS
       if  no  request  resulted in an error, and will return another error code if it failed for
       other reasons (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 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.

       Example: Same code as the example in the MPI_Waitany man page, but using MPI_Waitsome.

           CALL MPI_COMM_SIZE(comm, size, ierr)
           CALL MPI_COMM_RANK(comm, rank, ierr)
           IF(rank .GT. 0) THEN         ! client code
               DO WHILE(.TRUE.)
                  CALL MPI_ISEND(a, n, MPI_REAL, 0, tag, comm, request, ierr)
                  CALL MPI_WAIT(request, status, ierr)
               END DO
           ELSE         ! rank=0 -- server code
               DO i=1, size-1
                  CALL MPI_IRECV(a(1,i), n, MPI_REAL, i, tag,
                                 comm, requests(i), ierr)
               END DO
               DO WHILE(.TRUE.)
                  CALL MPI_WAITSOME(size, request_list, numdone,
                                   indices, statuses, ierr)
                  DO i=1, numdone
                     CALL DO_SERVICE(a(1, indices(i)))
                     CALL MPI_IRECV(a(1, indices(i)), n, MPI_REAL, 0, tag,
                                  comm, requests(indices(i)), ierr)
                  END DO
               END DO
           END IF

NOTES

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

ERRORS

       For each invocation of MPI_Waitsome, 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_Waitsome  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.

SEE ALSO

       MPI_Comm_set_errhandler
       MPI_File_set_errhandler
       MPI_Test
       MPI_Testall
       MPI_Testany
       MPI_Testsome
       MPI_Wait
       MPI_Waitall
       MPI_Waitany
       MPI_Win_set_errhandler