sessions: add man pages

Signed-off-by: Howard Pritchard <[email protected]>

Author: hppritcha

ompi/mpi/man/man3/MPI_Comm_create_from_group.3.md

@@ -0,0 +1,89 @@
+# Name
+
+`MPI_Comm_create_from_group` - Creates a new communicator from a group and stringtag
+
+# Syntax
+
+## C Syntax
+
+```c
+#include <mpi.h>
+
+int MPI_Comm_create_from_group(MPI_Group group, const char *stringtag, MPI_Info info, MPI_Errhandler errhandler, MPI_Comm *newcomm)
+```
+
+## Fortran Syntax
+
+```fortran
+USE MPI
+! or the older form: INCLUDE 'mpif.h'
+
+MPI_COMM_CREATE_FROM_GROUP(GROUP, STRINGTAG, INFO, ERRHANDLER, NEWCOMM, IERROR)
+    INTEGER	GROUP, INFO, ERRHANDLER, NEWCOMM, IERROR
+    CHARACTER*(*) STRINGTAG
+```
+
+## Fortran 2008 Syntax
+
+```fortran
+USE mpi_f08
+
+MPI_Comm_create_from_group(group, stringtag, info, errhandler, newcomm, ierror)
+    TYPE(MPI_Group), INTENT(IN) :: group
+    CHARACTER(LEN=*), INTENT(IN) :: stringtag
+    TYPE(MPI_Info), INTENT(IN) :: info
+    TYPE(MPI_Errhandler), INTENT(IN) :: errhandler
+    TYPE(MPI_Comm), INTENT(OUT) :: newcomm
+    INTEGER, OPTIONAL, INTENT(OUT) :: ierror
+```
+
+# Input Parameters
+
+* `group` : Group (handler)
+* `stringtag` : Unique identifier for this operation (string)
+* `info` : info object (handler)
+* `errhandler` : error handler to be attached to the new intra-communicator (handle)
+
+# Output Parameters
+
+* `newcomm` : New communicator (handle).
+* `IERROR` : Fortran only: Error status (integer).
+
+# Description
+
+`MPI_Comm_create_from_group` is similar to `MPI_Comm_create_group`, except
+that the set of MPI processes involved in the creation of the new intra-communicator
+is specified by a group argument, rather than the group associated with a pre-existing communicator.
+If a non-empty group is specified, then all MPI processes in that group must call
+the function and each of these MPI processes must provide the same arguments, including
+a `group` that contains the same members with the same ordering, and identical `stringtag`
+value. In the event that `MPI_GROUP_EMPTY` is supplied as the group argument, then the
+call is a local operation and `MPI_COMM_NULL` is returned as `newcomm`. The `stringtag` argument
+is analogous to the `tag` used for `MPI_Comm_create_group`. If multiple threads at
+a given MPI process perform concurrent `MPI_Comm_create_from_group` operations,
+the user must distinguish these operations by providing different `stringtag` arguments. The
+`stringtag` shall not exceed MPI_MAX_STRINGTAG_LEN characters in length. For C, this includes
+space for a null terminating character.
+
+# Notes
+
+The `errhandler` argument specifies an error handler to be attached to the new intracommunicator.
+The `info` argument provides hints and assertions, possibly MPI implementation dependent, which
+indicate desired characteristics and guide communicator creation. MPI_MAX_STRINGTAG_LEN shall have a value
+of at least 63.
+
+
+# Errors
+
+Almost all MPI routines return an error value; C routines as the value
+of the function and Fortran routines in the last argument.
+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.
+
+# See Also
+
+[`MPI_Comm_create_group`(3)](MPI_Comm_create_group.html)

ompi/mpi/man/man3/MPI_Group_from_session_pset.3.md

@@ -0,0 +1,75 @@
+# Name
+
+`MPI_Group_from_session_pset` - Creates a group using a provided session handle and process set.
+
+# Syntax
+
+## C Syntax
+
+```c
+#include <mpi.h>
+
+int MPI_Group_from_session_pset(MPI_Session session, const char *pset_name, MPI_Group *newgroup)
+```
+
+## Fortran Syntax
+
+```fortran
+USE MPI
+! or the older form: INCLUDE 'mpif.h'
+
+MPI_GROUP_FROM_SESSION_PSET(SESSION, PSET_NAME, NEWGROUP, IERROR)
+    INTEGER	SESSION,  NEWGROUP, IERROR
+    CHARACTER*(*) PSET_NAME
+```
+
+## Fortran 2008 Syntax
+
+```fortran
+USE mpi_f08
+
+MPI_Group_from_session_pset(session, pset_name, newgroup, ierror)
+    TYPE(MPI_Session), INTENT(IN) :: session
+    CHARACTER(LEN=*), INTENT(IN) :: pset_name
+    TYPE(MPI_Group), INTENT(OUT) :: newgroup
+    INTEGER, OPTIONAL, INTENT(OUT) :: ierror
+```
+
+# Input Parameters
+
+* `session` : Session (handle).
+* `pset_name` : name of process set to use to create the new group (string)
+
+# Output Parameters
+
+* `newgroup` : New group derived from supplied session and process set (handle).
+* `IERROR` : Fortran only: Error status (integer).
+
+# Description
+
+The function `MPI_Group_from_session_pset` creates a group `newgroup` using the
+provided `session` handle and `process set`. The process set name must be one returned from
+an invocation of `MPI_Session_get_nth_pset` using the supplied `session` handle. If the
+`pset_name` does not exist, MPI_GROUP_NULL will be returned in the `newgroup` argument.
+
+# Note
+
+As with other group constructors, `MPI_Group_from_session_pset` is a local function.
+
+# Errors
+
+Almost all MPI routines return an error value; C routines as the value
+of the function and Fortran routines in the last argument.
+
+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_Session_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.
+
+# See Also
+
+[`MPI_Session_init`(3)](MPI_Session_init.html)
+[`MPI_Session_get_nth_pset`(3)](MPI_Session_get_nth_pset.html)
+[`MPI_Group_free`(3)](MPI_Group_free.html)

ompi/mpi/man/man3/MPI_Intercomm_create_from_groups.3.md

@@ -0,0 +1,92 @@
+# Name
+
+`MPI_Intercomm_create_from_groups` - Creates a new inter-communicator from a local and remote group and stringtag
+
+# Syntax
+
+## C Syntax
+
+```c
+#include <mpi.h>
+
+int MPI_Intercomm_create_from_groups(MPI_Group local_group, int local_leader, MPI_Group remote_group, int remote_leader, const char *stringtag, MPI_Info info, MPI_Errhandler errhandler, MPI_Comm *newintercomm)
+```
+
+## Fortran Syntax
+
+```fortran
+USE MPI
+! or the older form: INCLUDE 'mpif.h'
+
+MPI_INTERCOMM_CREATE_FROM_GROUPS(LOCAL_GROUP, LOCAL_LEADER, REMOTE_GROUP, REMOTE_LEADER, STRINGTAG, INFO, ERRHANDLER, NEWINTERCOMM, IERROR)
+    INTEGER	LOCAL_GROUP, LOCAL_LEADER, REMOTE_GROUP, REMOTE_LEADER, INFO, ERRHANDLER, NEWINTERCOMM, IERROR
+    CHARACTER*(*) STRINGTAG
+```
+
+## Fortran 2008 Syntax
+
+```fortran
+USE mpi_f08
+
+MPI_Intercomm_create_from_groups(local_group, local_leader, remote_group, remote_leader, stringtag, info, errhandler, newintercomm, ierror)
+    TYPE(MPI_Group), INTENT(IN) :: local_group, remote_group
+    INTEGER, INTENT(IN) :: local_leader, remote_leader
+    CHARACTER(LEN=*), INTENT(IN) :: stringtag
+    TYPE(MPI_Info), INTENT(IN) :: info
+    TYPE(MPI_Errhandler), INTENT(IN) :: errhandler
+    TYPE(MPI_Comm), INTENT(OUT) :: newintercomm
+    INTEGER, OPTIONAL, INTENT(OUT) :: ierror
+```
+
+# Input Parameters
+
+* `local_group` : Local group (handler)
+* `local_leader` : rank of local group leader in local_group (integer)
+* `remote_group` : Remote group (handler)
+* `remote_leader` : rank of remote leader in remote_group, significant only at local_leader (integer)
+* `stringtag` : Unique identifier for this operation (string)
+* `info` : info object (handler)
+* `errhandler` : error handler to be attached to the new inter-communicator (handle)
+
+# Output Parameters
+
+* `newintercomm` : New inter-communicator (handle).
+* `IERROR` : Fortran only: Error status (integer).
+
+# Description
+
+`MPI_Intercomm_create_from_groups` creates an inter-communicator. Unlike `MPI_Intercomm_create`, this function
+uses as input previously defined, disjoint local and remote groups. The calling MPI
+process must be a member of the local group. The call is collective over the union of
+the local and remote groups. All involved MPI processes shall provide an identical value
+for the `stringtag` argument. Within each group, all MPI processes shall provide identical
+`local_group`, `local_leader` arguments. Wildcards are not permitted for the
+`remote_leader` or `local_leader` arguments. The `stringtag` argument serves the same purpose
+as the `stringtag` used in the `MPI_Comm_create_from_group` function; it differentiates
+concurrent calls in a multithreaded environment. The `stringtag` shall not exceed
+`MPI_MAX_STRINGTAG_LEN` characters in length. For C, this includes space for a null terminating
+character. In the event that MPI_GROUP_EMPTY is supplied as the `local_group` or `remote_group1 or both, then the
+call is a local operation and MPI_COMM_NULL is returned as the newintercomm`.
+
+# Notes
+
+The `errhandler` argument specifies an error handler to be attached to the new inter-communicator.
+The `info` argument provides hints and assertions, possibly MPI implementation dependent, which
+indicate desired characteristics and guide communicator creation. MPI_MAX_STRINGTAG_LEN shall have a value
+of at least 63.
+
+
+# Errors
+
+Almost all MPI routines return an error value; C routines as the value
+of the function and Fortran routines in the last argument.
+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.
+
+# See Also
+
+[`MPI_Comm_create_from_group`(3)](MPI_Comm_create_from_group.html)

ompi/mpi/man/man3/MPI_Session_create_errhandler.3.md

@@ -0,0 +1,76 @@
+# Name
+
+`MPI_Session_create_errhandler` - Creates an error handler that can be
+attached to sessions
+
+# Syntax
+
+## C Syntax
+
+```c
+#include <mpi.h>
+
+int MPI_Session_create_errhandler(MPI_Session_errhandler_function *function,
+	MPI_Errhandler *errhandler)
+```
+
+## Fortran Syntax
+
+```fortran
+USE MPI
+! or the older form: INCLUDE 'mpif.h'
+
+MPI_SESSION_CREATE_ERRHANDLER(FUNCTION, ERRHANDLER, IERROR)
+    EXTERNAL	FUNCTION
+    INTEGER	ERRHANDLER, IERROR
+```
+
+## Fortran 2008 Syntax
+
+```fortran
+USE mpi_f08
+
+MPI_Session_create_errhandler(session_errhandler_fn, errhandler, ierror)
+    PROCEDURE(MPI_Session_errhandler_function) :: session_errhandler_fn
+    TYPE(MPI_Errhandler), INTENT(OUT) :: errhandler
+    INTEGER, OPTIONAL, INTENT(OUT) :: ierror
+```
+
+# Input Parameter
+
+* `function` : User-defined error handling procedure (function).
+
+# Output Parameters
+
+* `errhandler` : MPI error handler (handle).
+* `IERROR` : Fortran only: Error status (integer).
+
+# Description
+
+`MPI_Session_create_errhandler` creates an error handler that can be attached
+to sessions. This `function` is identical to `MPI_Errhandler_create`,
+the use of which is deprecated.
+In C, the user routine should be a `function` of type
+`MPI_Session_errhandler_function`, which is defined as
+```c
+typedef void MPI_Session_errhandler_function(MPI_Session *, int *, ...);
+```
+The first argument is the session in use. The second is the error
+code to be returned by the MPI routine that raised the error. This
+typedef replaces `MPI_Handler_function`, the use of which is deprecated.
+In Fortran, the user routine should be of this form:
+```fortran
+SUBROUTINE SESSION_ERRHANDLER_FUNCTION(SESSION, ERROR_CODE, ...)
+   INTEGER SESSION, ERROR_CODE
+```
+
+# Errors
+
+Almost all MPI routines return an error value; C routines as the value
+of the `function` and Fortran routines in the last argument.
+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_Session_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_Session_f2c.3.md

@@ -0,0 +1,43 @@
+# NAME
+
+MPI_Session_c2f, MPI_Session_f2c - Translates a C session handle into a Fortran INTEGER-style session handle, or vice versa.
+
+# SYNTAX
+
+## C Syntax
+
+```c
+#include <mpi.h>
+
+int MPI_Session_f2c(const MPI_Fint *f_session, MPI_Session *c_session)
+int MPI_Session_c2f(const MPI_Session *c_session, MPI_Fint *f_session)
+```
+
+# PARAMETERS
+
+* `f_session`: `mpi`-style `INTEGER` MPI session object
+* `c_session`: C-style MPI session object
+
+# DESCRIPTION
+
+These two procedures are provided in C to convert from a Fortran
+session (which is an array of integers) to a C session (which is a
+structure), and vice versa. The conversion occurs on all the
+information in `session`, including that which is hidden. That is,
+no session information is lost in the conversion.
+
+When using `MPI_Session_f2c()`, if `f_session` is a valid Fortran
+session, then `MPI_Session_f2c()` returns in `c_session` a
+valid C session with the same content. If `f_session` is the Fortran
+value of `MPI_SESSION_NULL`, or if
+`f_session` is not a valid Fortran session, then the call is erroneous.
+
+When using `MPI_Session_c2f()`, the opposite conversion is applied. If
+`c_session` is `MPI_SESSION_NULL`, or if
+`c_session` is not a valid C session, then the call is erroneous.
+
+# NOTES
+
+These functions are only available in C; they are not available in any
+of the Fortran MPI interfaces.
+