* Fix some "MPI:Exception" typos (needs 2 :'s)

* Update exactly how we handle MPI exceptions, particularly with
   respect to MPI-1 section 3.2.5, and how error handlers are only
   invoked for the ''first'' request that generates an exception.
 * Update the "see also" section to be consistent across all 8
   MPI_Test* and MPI_Wait* functions.
 * Fixes trac:560

This commit was SVN r13619.

The following Trac tickets were found above:
  Ticket 560 --> https://svn.open-mpi.org/trac/ompi/ticket/560

ompi/mpi/man/man3/MPI_Errhandler_set.3

@@ -42,7 +42,7 @@ This deprecated routine is not available in C++.
 Associates the new error handler errhandler with communicator comm at the calling process. Note that an error handler is always associated with the communicator. 
 
 .SH ERRORS
-Almost all MPI routines return an error value; C routines as the value of the function and Fortran routines in the last argument. C++ functions do not return errors. If the default error handler is set to MPI::ERRORS_THROW_EXCEPTIONS, then on error the C++ exception mechanism will be used to throw an MPI:Exception object.
+Almost all MPI routines return an error value; C routines as the value of the function and Fortran routines in the last argument. C++ functions do not return errors. If the default error handler is set to MPI::ERRORS_THROW_EXCEPTIONS, then on error the C++ exception mechanism will be used to throw an MPI::Exception object.
 .sp
 Before the error value is returned, the current MPI error handler is
 called. By default, this error handler aborts the MPI job, except for I/O function errors. The error handler may be changed with MPI_Comm_set_errhandler; 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.  

ompi/mpi/man/man3/MPI_Test.3

@@ -1,5 +1,6 @@
 .\"Copyright 2006, Sun Microsystems, Inc.
 .\" Copyright (c) 1996 Thinking Machines Corporation
+.\"Copyright 2007, Cisco Systems, Inc.  All rights reserved.
 .TH MPI_Test 3OpenMPI "September 2006" "Open MPI 1.2" " "
 .SH NAME
 \fBMPI_Test\fP \- Tests for the completion of a specific send or receive.
@@ -61,14 +62,47 @@ receives.
 The use of the nonblocking MPI_Test call allows the user to schedule alternative activities within a single thread of execution. An event-driven thread scheduler can be emulated with periodic calls to MPI_Test. 
 
 .SH ERRORS
-Almost all MPI routines return an error value; C routines as the value of the function and Fortran routines in the last argument. C++ functions do not return errors. If the default error handler is set to MPI::ERRORS_THROW_EXCEPTIONS, then on error the C++ exception mechanism will be used to throw an MPI:Exception object.
+Almost all MPI routines return an error value; C routines as the value of the function and Fortran routines in the last argument. C++ functions do not return errors. If the default error handler is set to MPI::ERRORS_THROW_EXCEPTIONS, then on error the C++ exception mechanism will be used to throw an MPI::Exception object.
 .sp
 Before the error value is returned, the current MPI error handler is
-called. By default, this error handler aborts the MPI job, except for I/O function errors. The error handler may be changed with MPI_Comm_set_errhandler; 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.  
+called. By default, this 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 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.
+.sp
+Note that per MPI-1 section 3.2.5, MPI exceptions on requests passed
+to MPI_TEST do not set the status.MPI_ERROR field in the returned
+status.  The error code is passed to the back-end error handler
+and may be passed back to the caller through the return value of
+MPI_TEST if the back-end error handler returns it.  The
+pre-defined MPI error handler MPI_ERRORS_RETURN exhibits this
+behavior, for example.
 
 .SH SEE ALSO
 .ft R
 .sp
+MPI_Comm_set_errhandler
+.br
+MPI_File_set_errhandler
+.br
+MPI_Testall
+.br
+MPI_Testany
+.br
+MPI_Testsome
+.br
 MPI_Wait
+.br
+MPI_Waitall
+.br
+MPI_Waitany
+.br
+MPI_Waitsome
+.br
+MPI_Win_set_errhandler
+.br
 
 ' @(#)MPI_Test.3 1.20 06/03/09   

ompi/mpi/man/man3/MPI_Testall.3

@@ -67,20 +67,52 @@ Errors that occurred during the execution of MPI_Testall are handled in the same
 and neither \fIarray_of_requests\fP nor \fIarray_of_statuses\fP is modified.
 
 .SH ERRORS
-Almost all MPI routines return an error value; C routines as the value of the function and Fortran routines in the last argument. C++ functions do not return errors. If the default error handler is set to MPI::ERRORS_THROW_EXCEPTIONS, then on error the C++ exception mechanism will be used to throw an MPI:Exception object.
+For each invocation of MPI_Testall, if one or more requests generate
+an MPI exception, only the \fIfirst\fP 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, \fIall\fP 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).
 .sp
-Before the error value is returned, the current MPI error handler is
+The default error handler aborts the MPI job, except for I/O function
-called. By default, this error handler aborts the MPI job, except for I/O function errors. The error handler may be changed with MPI_Comm_set_errhandler; 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.  
+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.
+.sp
+If the invoked error handler allows MPI_Testall 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.
 
 .SH SEE ALSO
 .ft R
 .sp
+MPI_Comm_set_errhandler
+.br
+MPI_File_set_errhandler
+.br
+MPI_Test
+.br
+MPI_Testany
+.br
+MPI_Testsome
+.br
+MPI_Wait
+.br
+MPI_Waitall
+.br
 MPI_Waitany
 .br
 MPI_Waitsome
 .br
-MPI_Testsome
+MPI_Win_set_errhandler
 .br
-MPI_Waitall
 
 ' @(#)MPI_Testall.3 1.20 06/03/09   

ompi/mpi/man/man3/MPI_Testany.3

@@ -67,18 +67,47 @@ MPI_Testany(count, array_of_requests, index, status) has the same effect as the
 If your application does not need to examine the \fIstatus\fP field, you can save resources by using the predefined constant MPI_STATUS_IGNORE as a special value for the \fIstatus\fP argument. 
 
 .SH ERRORS
-Almost all MPI routines return an error value; C routines as the value of the function and Fortran routines in the last argument. C++ functions do not return errors. If the default error handler is set to MPI::ERRORS_THROW_EXCEPTIONS, then on error the C++ exception mechanism will be used to throw an MPI:Exception object.
+Almost all MPI routines return an error value; C routines as the value of the function and Fortran routines in the last argument. C++ functions do not return errors. If the default error handler is set to MPI::ERRORS_THROW_EXCEPTIONS, then on error the C++ exception mechanism will be used to throw an MPI::Exception object.
 .sp
 Before the error value is returned, the current MPI error handler is
-called. By default, this error handler aborts the MPI job, except for I/O function errors. The error handler may be changed with MPI_Comm_set_errhandler; 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.  
+called. By default, this 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 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.
+.sp
+Note that per MPI-1 section 3.2.5, MPI exceptions on requests passed
+to MPI_TESTANY do not set the status.MPI_ERROR field in the returned
+status.  The error code is passed to the back-end error handler and
+may be passed back to the caller through the return value of
+MPI_TESTANY if the back-end error handler returns it.  The pre-defined
+MPI error handler MPI_ERRORS_RETURN exhibits this behavior, for
+example.
 
 .SH SEE ALSO
 .ft R
 .sp
-.nf
+MPI_Comm_set_errhandler
-MPI_Wait
+.br
-MPI_Waitany    
+MPI_File_set_errhandler
-MPI_Waitsome
+.br
 MPI_Test
+.br
+MPI_Testall
+.br
 MPI_Testsome
+.br
+MPI_Wait
+.br
+MPI_Waitall
+.br
+MPI_Waitany
+.br
+MPI_Waitsome
+.br
+MPI_Win_set_errhandler
+.br
+
 ' @(#)MPI_Testany.3 1.20 06/03/09   

ompi/mpi/man/man3/MPI_Testsome.3

@@ -73,18 +73,52 @@ efficient than the use of MPI_Testany. The former returns information on all com
 A server with multiple clients can use MPI_Waitsome so as not to starve any client. Clients send messages to the server with service requests. The server calls MPI_Waitsome with one receive request for each client, then handles all receives that have completed. If a call to MPI_Waitany is used instead, then one client could starve while requests from another client always sneak in first. 
 
 .SH ERRORS
-Almost all MPI routines return an error value; C routines as the value of the function and Fortran routines in the last argument. C++ functions do not return errors. If the default error handler is set to MPI::ERRORS_THROW_EXCEPTIONS, then on error the C++ exception mechanism will be used to throw an MPI:Exception object.
+For each invocation of MPI_Testsome, if one or more requests generate
+an MPI exception, only the \fIfirst\fP 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, \fIall\fP 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).
 .sp
-Before the error value is returned, the current MPI error handler is
+The default error handler aborts the MPI job, except for I/O function
-called. By default, this error handler aborts the MPI job, except for I/O function errors. The error handler may be changed with MPI_Comm_set_errhandler; 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.  
+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.
+.sp
+If the invoked error handler allows MPI_Testsome 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.
 
 .SH SEE ALSO
 .ft R
 .sp
-MPI_Waitsome
+MPI_Comm_set_errhandler
+.br
+MPI_File_set_errhandler
+.br
+MPI_Test
+.br
+MPI_Testall
+.br
+MPI_Testany
+.br
+MPI_Wait
+.br
+MPI_Waitall
 .br
 MPI_Waitany
 .br
-MPI_Testany
+MPI_Waitsome
+.br
+MPI_Win_set_errhandler
+.br
 
 ' @(#)MPI_Testsome.3 1.20 06/03/09   

ompi/mpi/man/man3/MPI_Wait.3

@@ -69,14 +69,32 @@ Example: Simple usage of nonblocking operations and  MPI_Wait.
 .ni
 
 .SH ERRORS
-Almost all MPI routines return an error value; C routines as the value of the function and Fortran routines in the last argument. C++ functions do not return errors. If the default error handler is set to MPI::ERRORS_THROW_EXCEPTIONS, then on error the C++ exception mechanism will be used to throw an MPI:Exception object.
+Almost all MPI routines return an error value; C routines as the value of the function and Fortran routines in the last argument. C++ functions do not return errors. If the default error handler is set to MPI::ERRORS_THROW_EXCEPTIONS, then on error the C++ exception mechanism will be used to throw an MPI::Exception object.
 .sp
 Before the error value is returned, the current MPI error handler is
-called. By default, this error handler aborts the MPI job, except for I/O function errors. The error handler may be changed with MPI_Comm_set_errhandler; 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.  
+called. By default, this 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 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.
+.sp
+Note that per MPI-1 section 3.2.5, MPI exceptions on requests passed
+to MPI_WAIT do not set the status.MPI_ERROR field in the returned
+status.  The error code is passed to the back-end error handler
+and may be passed back to the caller through the return value of
+MPI_WAIT if the back-end error handler returns it.  The
+pre-defined MPI error handler MPI_ERRORS_RETURN exhibits this
+behavior, for example.
 
 .SH SEE ALSO
 .ft R
 .sp
+MPI_Comm_set_errhandler
+.br
+MPI_File_set_errhandler
+.br
 MPI_Test
 .br
 MPI_Testall
@@ -91,5 +109,7 @@ MPI_Waitany
 .br
 MPI_Waitsome
 .br
+MPI_Win_set_errhandler
+.br
 
 ' @(#)MPI_Wait.3 1.20 06/03/09

ompi/mpi/man/man3/MPI_Waitall.3

@@ -57,24 +57,52 @@ When one or more of the communications completed by a call to MPI_Waitall fail,
 If your application does not need to examine the \fIarray_of_statuses\fP field, you can save resources by using the predefined constant MPI_STATUSES_IGNORE can be used as a special value for the \fIarray_of_statuses\fP argument. 
 
 .SH ERRORS
-Almost all MPI routines return an error value; C routines as the value of the function and Fortran routines in the last argument. C++ functions do not return errors. If the default error handler is set to MPI::ERRORS_THROW_EXCEPTIONS, then on error the C++ exception mechanism will be used to throw an MPI:Exception object.
+For each invocation of MPI_Waitall, if one or more requests generate
+an MPI exception, only the \fIfirst\fP 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, \fIall\fP 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).
 .sp
-Before the error value is returned, the current MPI error handler is
+The default error handler aborts the MPI job, except for I/O function
-called. By default, this error handler aborts the MPI job, except for I/O function errors. The error handler may be changed with MPI_Comm_set_errhandler; 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.  
+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.
+.sp
+If the invoked error handler allows MPI_Waitall 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.
 
 .SH SEE ALSO
 .ft R
 .sp
+MPI_Comm_set_errhandler
+.br
+MPI_File_set_errhandler
+.br
+MPI_Test
+.br
+MPI_Testall
+.br
+MPI_Testany
+.br
+MPI_Testsome
+.br
 MPI_Wait
 .br
 MPI_Waitany
 .br
 MPI_Waitsome
 .br
-MPI_Test
+MPI_Win_set_errhandler
 .br
-MPI_Testsome
-.br
-MPI_Testall
 
 ' @(#)MPI_Waitall.3 1.20 06/03/09

ompi/mpi/man/man3/MPI_Waitany.3

@@ -88,14 +88,32 @@ If your application does not need to examine the \fIstatus\fP field, you can sav
 .sp
 
 .SH ERRORS
-Almost all MPI routines return an error value; C routines as the value of the function and Fortran routines in the last argument. C++ functions do not return errors. If the default error handler is set to MPI::ERRORS_THROW_EXCEPTIONS, then on error the C++ exception mechanism will be used to throw an MPI:Exception object.
+Almost all MPI routines return an error value; C routines as the value of the function and Fortran routines in the last argument. C++ functions do not return errors. If the default error handler is set to MPI::ERRORS_THROW_EXCEPTIONS, then on error the C++ exception mechanism will be used to throw an MPI::Exception object.
 .sp
 Before the error value is returned, the current MPI error handler is
-called. By default, this error handler aborts the MPI job, except for I/O function errors. The error handler may be changed with MPI_Comm_set_errhandler; 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.  
+called. By default, this 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 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.
+.sp
+Note that per MPI-1 section 3.2.5, MPI exceptions on requests passed
+to MPI_WAITANY do not set the status.MPI_ERROR field in the returned
+status.  The error code is passed to the back-end error handler and
+may be passed back to the caller through the return value of
+MPI_WAITANY if the back-end error handler returns it.  The pre-defined
+MPI error handler MPI_ERRORS_RETURN exhibits this behavior, for
+example.
 
 .SH SEE ALSO
 .ft R
 .sp
+MPI_Comm_set_errhandler
+.br
+MPI_File_set_errhandler
+.br
 MPI_Test
 .br
 MPI_Testall
@@ -110,5 +128,7 @@ MPI_Waitall
 .br
 MPI_Waitsome
 .br
+MPI_Win_set_errhandler
+.br
 
 ' @(#)MPI_Waitany.3 1.22 06/03/09

ompi/mpi/man/man3/MPI_Waitsome.3

@@ -99,14 +99,37 @@ If your application does not need to examine the \fIarray_of_statuses\fP field,
 The array of indices are in the range 0 to incount-1 for C and in the range 1 to incount for Fortran. 
 
 .SH ERRORS
-Almost all MPI routines return an error value; C routines as the value of the function and Fortran routines in the last argument. C++ functions do not return errors. If the default error handler is set to MPI::ERRORS_THROW_EXCEPTIONS, then on error the C++ exception mechanism will be used to throw an MPI:Exception object.
+For each invocation of MPI_Waitsome, if one or more requests generate
+an MPI exception, only the \fIfirst\fP 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, \fIall\fP 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).
 .sp
-Before the error value is returned, the current MPI error handler is
+The default error handler aborts the MPI job, except for I/O function
-called. By default, this error handler aborts the MPI job, except for I/O function errors. The error handler may be changed with MPI_Comm_set_errhandler; 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.  
+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.
+.sp
+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.
 
 .SH SEE ALSO
 .ft R
 .sp
+MPI_Comm_set_errhandler
+.br
+MPI_File_set_errhandler
+.br
 MPI_Test
 .br
 MPI_Testall
@@ -117,9 +140,11 @@ MPI_Testsome
 .br
 MPI_Wait
 .br
+MPI_Waitall
+.br
 MPI_Waitany
 .br
-MPI_Waitall
+MPI_Win_set_errhandler
 .br
 
 ' @(#)MPI_Waitsome.3 1.20 06/03/09