docs: some functions (currently) require mpirun

jsquyres · jsquyres · commit 3e32715144a6 · 2024-12-23T13:09:38.000-05:00
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 &lt;jeff@squyres.com&gt;
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`
