docs: some functions (currently) require mpirun

Add a note to several MPI API man pages that they (currently) require being launched via mpirun / mpiexec, and that launching in other environments may result in undefined behavior. Signed-off-by: Jeff Squyres <[email protected]>
open-mpi · Dec 23, 2024 · 3e32715 · 3e32715
1 parent 69dc361
commit 3e32715
Show file tree

Hide file tree

Showing 8 changed files with 21 additions and 0 deletions.
diff --git a/docs/man-openmpi/man3/MPIRUN-ONLY.rst b/docs/man-openmpi/man3/MPIRUN-ONLY.rst
@@ -0,0 +1,7 @@
+.. admonition:: Important
+   :class: error
+
+   In Open MPI, this function only works properly when the MPI job is
+   launched via :ref:`man1-mpirun`.  Using this function in other
+   run-time environments is currently unsupported, and may result in
+   undefined behavior (e.g., the MPI job may hang).
diff --git a/docs/man-openmpi/man3/MPI_Comm_accept.3.rst b/docs/man-openmpi/man3/MPI_Comm_accept.3.rst
@@ -74,6 +74,8 @@ through a call to :ref:`MPI_Open_port` on the root.
 ERRORS
 ------
 
+.. include:: ./MPIRUN-ONLY.rst
+
 .. include:: ./ERRORS.rst
 
 .. seealso::

diff --git a/docs/man-openmpi/man3/MPI_Comm_connect.3.rst b/docs/man-openmpi/man3/MPI_Comm_connect.3.rst
@@ -82,6 +82,8 @@ address of the server. It must be the same as the name returned by
 ERRORS
 ------
 
+.. include:: ./MPIRUN-ONLY.rst
+
 .. include:: ./ERRORS.rst
 
 .. seealso::

diff --git a/docs/man-openmpi/man3/MPI_Comm_create_from_group.3.rst b/docs/man-openmpi/man3/MPI_Comm_create_from_group.3.rst
@@ -94,6 +94,8 @@ shall have a value of at least 63.
 ERRORS
 ------
 
+.. include:: ./MPIRUN-ONLY.rst
+
 .. include:: ./ERRORS.rst
 
 .. seealso::

diff --git a/docs/man-openmpi/man3/MPI_Comm_join.3.rst b/docs/man-openmpi/man3/MPI_Comm_join.3.rst
@@ -91,6 +91,8 @@ mechanisms.
 ERRORS
 ------
 
+.. include:: ./MPIRUN-ONLY.rst
+
 .. include:: ./ERRORS.rst
 
 .. seealso::

diff --git a/docs/man-openmpi/man3/MPI_Comm_spawn.3.rst b/docs/man-openmpi/man3/MPI_Comm_spawn.3.rst
@@ -272,6 +272,8 @@ intercommunicator can be used immediately).
 ERRORS
 ------
 
+.. include:: ./MPIRUN-ONLY.rst
+
 .. include:: ./ERRORS.rst
 
 .. seealso::

diff --git a/docs/man-openmpi/man3/MPI_Comm_spawn_multiple.3.rst b/docs/man-openmpi/man3/MPI_Comm_spawn_multiple.3.rst
@@ -270,6 +270,8 @@ of calling :ref:`MPI_Comm_spawn` several times.
 ERRORS
 ------
 
+.. include:: ./MPIRUN-ONLY.rst
+
 .. include:: ./ERRORS.rst
 
 .. seealso::

diff --git a/docs/man-openmpi/man3/MPI_Intercomm_create_from_groups.3.rst b/docs/man-openmpi/man3/MPI_Intercomm_create_from_groups.3.rst
@@ -99,6 +99,8 @@ shall have a value of at least 63.
 ERRORS
 ------
 
+.. include:: ./MPIRUN-ONLY.rst
+
 .. include:: ./ERRORS.rst
 
 .. seealso:: :ref:`MPI_Comm_create_from_group`
-Original file line number
+Diff line change
@@ Expand Up / @@ -74,6 +74,8 @@ through a call to :ref:`MPI_Open_port` on the root. @@
     ERRORS
     ------
+    .. include:: ./MPIRUN-ONLY.rst
     .. include:: ./ERRORS.rst
     .. seealso::
@@ Expand Down @@