manpagez: man pages & more
man MPI_Waitsome(3)
Home | html | info | man
MPI_Waitsome(3OpenMPI)                                  MPI_Waitsome(3OpenMPI)




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

       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 han-
       dles 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  immedi-
       ately 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  communica-
       tion.  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 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 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.

       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 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_Waitsome  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(3), MPI_File_set_errhandler(3), MPI_Test(3),
       MPI_Testall(3), MPI_Testany(3), MPI_Testsome(3), MPI_Wait(3),
       MPI_Waitall(3), MPI_Waitany(3), MPI_Win_set_errhandler(3)




Open MPI 1.2                    September 2006          MPI_Waitsome(3OpenMPI)

Mac OS X 10.6 - Generated Thu Sep 17 20:13:22 CDT 2009
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.