MPI_WAITSOME(3)					     Open MPI					   MPI_WAITSOME(3)

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
	  USE MPI
	  ! or the older form: 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

   Fortran 2008 Syntax
	  USE mpi_f08
	  MPI_Waitsome(incount, array_of_requests, outcount, array_of_indices,
		       array_of_statuses, ierror)
	       INTEGER, INTENT(IN) :: incount
	       TYPE(MPI_Request), INTENT(INOUT) :: array_of_requests(incount)
	       INTEGER, INTENT(OUT) :: outcount, array_of_indices(*)
	       TYPE(MPI_Status) :: array_of_statuses(*)
	       INTEGER, OPTIONAL, INTENT(OUT) :: ierror

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 <#mpi-waitany> man page, but using MPI_Waitsome.

	  CALL MPI_COMM_SIZE(comm, size, ierr)
	  CALL MPI_COMM_RANK(comm, rank, ierr)
	  IF(rank > 0) THEN	    ! client code
	      DO
		 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
		 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, i, 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
       Almost  all MPI routines return an error value; C routines as the return result of the function and Fortran
       routines in the last argument.

       Before the error value is returned, the current MPI error handler associated with the communication  object
       (e.g.,  communicator, window, file) is called.  If no communication object is associated with the MPI call,
       then the call is considered attached to MPI_COMM_SELF and will call the associated MPI error handler.  When
       MPI_COMM_SELF  is  not  initialized  (i.e., before MPI_Init <#mpi-init>/MPI_Init_thread <#mpi-init-thread>,
       after MPI_Finalize <#mpi-finalize>, or when using the Sessions Model  exclusively)  the	error  raises  the
       initial	error  handler.	 The  initial  error  handler can be changed by calling MPI_Comm_set_errhandler <#
       mpi-comm-set-errhandler> on MPI_COMM_SELF when using the World model,  or  the  mpi_initial_errhandler  CLI
       argument	  to   mpiexec	 or   info  key	 to  MPI_Comm_spawn  <#mpi-comm-spawn>/MPI_Comm_spawn_multiple	<#
       mpi-comm-spawn-multiple>.  If no other appropriate error handler has been set, then  the	 MPI_ERRORS_RETURN
       error  handler  is  called  for	MPI I/O functions and the MPI_ERRORS_ABORT error handler is called for all
       other MPI functions.

       Open MPI includes three predefined error handlers that can be used:

       • MPI_ERRORS_ARE_FATAL Causes the program to abort all connected MPI processes.

       • MPI_ERRORS_ABORT An error handler that can be invoked on a communicator, window, file, or  session.  When
	 called on a communicator, it acts as if MPI_Abort <#mpi-abort> was called on that communicator. If called
	 on  a window or file, acts as if MPI_Abort <#mpi-abort> was called on a communicator containing the group
	 of processes in the corresponding window or file. If called on a session, aborts only the local process.

       • MPI_ERRORS_RETURN Returns an error code to the application.

       MPI applications can also implement their own error handlers by calling:

       • MPI_Comm_create_errhandler	<#mpi-comm-create-errhandler>	  then	   MPI_Comm_set_errhandler	<#
	 mpi-comm-set-errhandler>

       • MPI_File_create_errhandler	 <#mpi-file-create-errhandler>	   then	    MPI_File_set_errhandler	<#
	 mpi-file-set-errhandler>

       • MPI_Session_create_errhandler	 <#mpi-session-create-errhandler>   then   MPI_Session_set_errhandler	<#
	 mpi-session-set-errhandler> or at MPI_Session_init <#mpi-session-init>

       • MPI_Win_create_errhandler	<#mpi-win-create-errhandler>	  then	    MPI_Win_set_errhandler	<#
	 mpi-win-set-errhandler>

       Note that MPI does not guarantee that an MPI program can continue past an error.

       See the MPI man page <#open-mpi> for a full list of MPI error codes <#open-mpi-errors>.

       See the Error Handling section of the MPI-3.1 standard for more information.

       For each invocation of MPI_Waitsome, if one or more requests generate an MPI  error,  only  the	first  MPI
       request	that  caused  an  error will be passed to its corresponding error handler. No other error handlers
       will be invoked (even if multiple requests generated errors). However, all requests that generate an  error
       will have a relevant error code set in the corresponding status.MPI_ERROR field (unless MPI_STATUSES_IGNORE
       was used).

       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.

       See also:

	  • MPI_Comm_set_errhandler <#mpi-comm-set-errhandler>

	  • MPI_File_set_errhandler <#mpi-file-set-errhandler>

	  • MPI_Test <#mpi-test>

	  • MPI_Testall <#mpi-testall>

	  • MPI_Testany <#mpi-testany>

	  • MPI_Testsome <#mpi-testsome>

	  • MPI_Wait <#mpi-wait>

	  • MPI_Waitall <#mpi-waitall>

	  • MPI_Waitany <#mpi-waitany>

	  • MPI_Win_set_errhandler <#mpi-win-set-errhandler>

Copyright
       2003-2026, The Open MPI Community

						   Mar 05, 2026					   MPI_WAITSOME(3)
