Skip to content

Commit 47654ef

Browse files
jsquyresjsquyres
committed
docs: update status text in MPI_(Test*|Wait*) man pages
Slightly update the text about the output status in MPI_Test* and MPI_Wait* functions: * Link out to the MPI standard (rather than refer to outdated versions of the standard) * Slightly tweak the wording * Minor RST formatting fixes Signed-off-by: Jeff Squyres <jeff@squyres.com>
1 parent 6a0b54b commit 47654ef

File tree

8 files changed

+80
-68
lines changed

8 files changed

+80
-68
lines changed

‎docs/man-openmpi/man3/MPI_Test.3.rst

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -101,12 +101,15 @@ ERRORS
101101

102102
.. include:: ./ERRORS.rst
103103

104-
Note that per MPI-1 section 3.2.5, MPI errors on requests passed to
105-
:ref:`MPI_TEST` do not set the status.MPI_ERROR field in the returned status.
106-
The error code is passed to the back-end error handler and may be passed
107-
back to the caller through the return value of :ref:`MPI_TEST` if the back-end
108-
error handler returns it. The pre-defined MPI error handler
109-
MPI_ERRORS_RETURN exhibits this behavior, for example.
104+
Note that per the "Return Status" section in the "Point-to-Point
105+
Communication" chapter in the `MPI Standard
106+
<https://www.mpi-forum.org/docs/>`_, MPI errors on requests passed to
107+
:ref:`MPI_TEST` do not set the ``status.MPI_ERROR`` field in the
108+
returned *status*. The error code is always passed to the back-end
109+
error handler and may be passed back to the caller through the return
110+
value of :ref:`MPI_TEST` if the back-end error handler returns it.
111+
The pre-defined MPI error handler ``MPI_ERRORS_RETURN`` exhibits this
112+
behavior, for example.
110113

111114

112115
.. seealso::

‎docs/man-openmpi/man3/MPI_Testall.3.rst

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -101,17 +101,17 @@ ERRORS
101101

102102
.. include:: ./ERRORS.rst
103103

104-
For each invocation of :ref:`MPI_Testall`, if one or more requests generate an
105-
MPI error, only the *first* MPI request that caused an error will be
106-
passed to its corresponding error handler. No other error handlers will
107-
be invoked (even if multiple requests generated errors). However, *all*
108-
requests that generate an error will have a relevant error code set in
109-
the corresponding status.MPI_ERROR field (unless MPI_STATUSES_IGNORE was
110-
used).
111-
112-
If the invoked error handler allows :ref:`MPI_Testall` to return to the caller,
113-
the value MPI_ERR_IN_STATUS will be returned in the C and Fortran
114-
bindings.
104+
For each invocation of :ref:`MPI_Testall`, if one or more requests
105+
generate an MPI error, only the *first* MPI request that caused an
106+
error will be passed to its corresponding error handler. No other
107+
error handlers will be invoked (even if multiple requests generated
108+
errors). However, *all* requests that generate an error will have a
109+
relevant error code set in the corresponding ``status.MPI_ERROR``
110+
field (unless ``MPI_STATUSES_IGNORE`` was used).
111+
112+
If the invoked error handler allows :ref:`MPI_Testall` to return to
113+
the caller, the value ``MPI_ERR_IN_STATUS`` will be returned in the C
114+
and Fortran bindings.
115115

116116

117117
.. seealso::

‎docs/man-openmpi/man3/MPI_Testany.3.rst

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -101,12 +101,15 @@ ERRORS
101101

102102
.. include:: ./ERRORS.rst
103103

104-
Note that per MPI-1 section 3.2.5, MPI errors on requests passed to
105-
:ref:`MPI_TESTANY` do not set the ``status.MPI_ERROR`` field in the returned
106-
status. The error code is passed to the back-end error handler and may
107-
be passed back to the caller through the return value of :ref:`MPI_TESTANY` if
108-
the back-end error handler returns it. The pre-defined MPI error handler
109-
``MPI_ERRORS_RETURN`` exhibits this behavior, for example.
104+
Note that per the "Return Status" section in the "Point-to-Point
105+
Communication" chapter in the `MPI Standard
106+
<https://www.mpi-forum.org/docs/>`_, MPI errors on requests passed to
107+
:ref:`MPI_TESTANY` do not set the ``status.MPI_ERROR`` field in the
108+
returned *status*. The error code is always passed to the back-end
109+
error handler and may be passed back to the caller through the return
110+
value of :ref:`MPI_TESTANY` if the back-end error handler returns it.
111+
The pre-defined MPI error handler ``MPI_ERRORS_RETURN`` exhibits this
112+
behavior, for example.
110113

111114
.. seealso::
112115
* :ref:`MPI_Comm_set_errhandler`

‎docs/man-openmpi/man3/MPI_Testsome.3.rst

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -124,17 +124,17 @@ ERRORS
124124

125125
.. include:: ./ERRORS.rst
126126

127-
For each invocation of :ref:`MPI_Testsome`, if one or more requests generate an
128-
MPI error, only the *first* MPI request that caused an error will be
129-
passed to its corresponding error handler. No other error handlers will
130-
be invoked (even if multiple requests generated errors). However, *all*
131-
requests that generate an error will have a relevant error code set in
132-
the corresponding status.MPI_ERROR field (unless MPI_STATUSES_IGNORE was
133-
used).
134-
135-
If the invoked error handler allows :ref:`MPI_Testsome` to return to the
136-
caller, the value MPI_ERR_IN_STATUS will be returned in the C and
137-
Fortran bindings.
127+
For each invocation of :ref:`MPI_Testsome`, if one or more requests
128+
generate an MPI error, only the *first* MPI request that caused an
129+
error will be passed to its corresponding error handler. No other
130+
error handlers will be invoked (even if multiple requests generated
131+
errors). However, *all* requests that generate an error will have a
132+
relevant error code set in the corresponding ``status.MPI_ERROR``
133+
field (unless ``MPI_STATUSES_IGNORE`` was used).
134+
135+
If the invoked error handler allows :ref:`MPI_Testsome` to return to
136+
the caller, the value ``MPI_ERR_IN_STATUS`` will be returned in the C
137+
and Fortran bindings.
138138

139139
.. seealso::
140140
* :ref:`MPI_Comm_set_errhandler`

‎docs/man-openmpi/man3/MPI_Wait.3.rst

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -113,12 +113,15 @@ ERRORS
113113

114114
.. include:: ./ERRORS.rst
115115

116-
Note that per MPI-1 section 3.2.5, MPI errors on requests passed to
117-
:ref:`MPI_WAIT` do not set the ``status.MPI_ERROR`` field in the returned status.
118-
The error code is passed to the back-end error handler and may be passed
119-
back to the caller through the return value of :ref:`MPI_WAIT` if the back-end
120-
error handler returns it. The pre-defined MPI error handler
121-
``MPI_ERRORS_RETURN`` exhibits this behavior, for example.
116+
Note that per the "Return Status" section in the "Point-to-Point
117+
Communication" chapter in the `MPI Standard
118+
<https://www.mpi-forum.org/docs/>`_, MPI errors on requests passed to
119+
:ref:`MPI_WAIT` do not set the ``status.MPI_ERROR`` field in the
120+
returned *status*. The error code is always passed to the back-end
121+
error handler and may be passed back to the caller through the return
122+
value of :ref:`MPI_WAIT` if the back-end error handler returns it. The
123+
pre-defined MPI error handler ``MPI_ERRORS_RETURN`` exhibits this
124+
behavior, for example.
122125

123126

124127
.. seealso::

‎docs/man-openmpi/man3/MPI_Waitall.3.rst

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -101,17 +101,17 @@ ERRORS
101101

102102
.. include:: ./ERRORS.rst
103103

104-
For each invocation of :ref:`MPI_Waitall`, if one or more requests generate an
105-
MPI error, only the *first* MPI request that caused an error will be
106-
passed to its corresponding error handler. No other error handlers will
107-
be invoked (even if multiple requests generated errors). However, *all*
108-
requests that generate an error will have a relevant error code set in
109-
the corresponding status.MPI_ERROR field (unless MPI_STATUSES_IGNORE was
110-
used).
111-
112-
If the invoked error handler allows :ref:`MPI_Waitall` to return to the caller,
113-
the value MPI_ERR_IN_STATUS will be returned in the C and Fortran
114-
bindings.
104+
For each invocation of :ref:`MPI_Waitall`, if one or more requests
105+
generate an MPI error, only the *first* MPI request that caused an
106+
error will be passed to its corresponding error handler. No other
107+
error handlers will be invoked (even if multiple requests generated
108+
errors). However, *all* requests that generate an error will have a
109+
relevant error code set in the corresponding ``status.MPI_ERROR``
110+
field (unless ``MPI_STATUSES_IGNORE`` was used).
111+
112+
If the invoked error handler allows :ref:`MPI_Waitall` to return to
113+
the caller, the value ``MPI_ERR_IN_STATUS`` will be returned in the C
114+
and Fortran bindings.
115115

116116

117117
.. seealso::

‎docs/man-openmpi/man3/MPI_Waitany.3.rst

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -112,12 +112,15 @@ ERRORS
112112

113113
.. include:: ./ERRORS.rst
114114

115-
Note that per MPI-1 section 3.2.5, MPI errors on requests passed to
116-
:ref:`MPI_WAITANY` do not set the ``status.MPI_ERROR`` field in the returned
117-
status. The error code is passed to the back-end error handler and may
118-
be passed back to the caller through the return value of :ref:`MPI_WAITANY` if
119-
the back-end error handler returns it. The pre-defined MPI error handler
120-
``MPI_ERRORS_RETURN`` exhibits this behavior, for example.
115+
Note that per the "Return Status" section in the "Point-to-Point
116+
Communication" chapter in the `MPI Standard
117+
<https://www.mpi-forum.org/docs/>`_, MPI errors on requests passed to
118+
:ref:`MPI_WAITANY` do not set the ``status.MPI_ERROR`` field in the
119+
returned *status*. The error code is always passed to the back-end
120+
error handler and may be passed back to the caller through the return
121+
value of :ref:`MPI_WAITANY` if the back-end error handler returns it.
122+
The pre-defined MPI error handler ``MPI_ERRORS_RETURN`` exhibits this
123+
behavior, for example.
121124

122125

123126
.. seealso::

‎docs/man-openmpi/man3/MPI_Waitsome.3.rst

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -142,17 +142,17 @@ ERRORS
142142

143143
.. include:: ./ERRORS.rst
144144

145-
For each invocation of :ref:`MPI_Waitsome`, if one or more requests generate an
146-
MPI error, only the *first* MPI request that caused an error will be
147-
passed to its corresponding error handler. No other error handlers will
148-
be invoked (even if multiple requests generated errors). However, *all*
149-
requests that generate an error will have a relevant error code set in
150-
the corresponding status.MPI_ERROR field (unless MPI_STATUSES_IGNORE was
151-
used).
152-
153-
If the invoked error handler allows :ref:`MPI_Waitsome` to return to the
154-
caller, the value MPI_ERR_IN_STATUS will be returned in the C and
155-
Fortran bindings.
145+
For each invocation of :ref:`MPI_Waitsome`, if one or more requests
146+
generate an MPI error, only the *first* MPI request that caused an
147+
error will be passed to its corresponding error handler. No other
148+
error handlers will be invoked (even if multiple requests generated
149+
errors). However, *all* requests that generate an error will have a
150+
relevant error code set in the corresponding ``status.MPI_ERROR``
151+
field (unless ``MPI_STATUSES_IGNORE`` was used).
152+
153+
If the invoked error handler allows :ref:`MPI_Waitsome` to return to
154+
the caller, the value ``MPI_ERR_IN_STATUS`` will be returned in the C
155+
and Fortran bindings.
156156

157157

158158
.. seealso::

0 commit comments

Comments
 (0)