Skip to content

Commit 0639ea7

Browse files
hppritchahppritcha
committed
sessions: add man pages
Signed-off-by: Howard Pritchard <[email protected]>
1 parent 018d488 commit 0639ea7

11 files changed

+806
-1
lines changed

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

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
# Name
2+
3+
`MPI_Comm_create_from_group` - Creates a new communicator from a group and stringtag
4+
5+
# Syntax
6+
7+
## C Syntax
8+
9+
```c
10+
#include <mpi.h>
11+
12+
int MPI_Comm_create_from_group(MPI_Group group, const char *stringtag, MPI_Info info, MPI_Errhandler errhandler, MPI_Comm *newcomm)
13+
```
14+
15+
## Fortran Syntax
16+
17+
```fortran
18+
USE MPI
19+
! or the older form: INCLUDE 'mpif.h'
20+
21+
MPI_COMM_CREATE_FROM_GROUP(GROUP, STRINGTAG, INFO, ERRHANDLER, NEWCOMM, IERROR)
22+
INTEGER GROUP, INFO, ERRHANDLER, NEWCOMM, IERROR
23+
CHARACTER*(*) STRINGTAG
24+
```
25+
26+
## Fortran 2008 Syntax
27+
28+
```fortran
29+
USE mpi_f08
30+
31+
MPI_Comm_create_from_group(group, stringtag, info, errhandler, newcomm, ierror)
32+
TYPE(MPI_Group), INTENT(IN) :: group
33+
CHARACTER(LEN=*), INTENT(IN) :: stringtag
34+
TYPE(MPI_Info), INTENT(IN) :: info
35+
TYPE(MPI_Errhandler), INTENT(IN) :: errhandler
36+
TYPE(MPI_Comm), INTENT(OUT) :: newcomm
37+
INTEGER, OPTIONAL, INTENT(OUT) :: ierror
38+
```
39+
40+
# Input Parameters
41+
42+
* `group` : Group (handler)
43+
* `stringtag` : Unique identifier for this operation (string)
44+
* `info` : info object (handler)
45+
* `errhandler` : error handler to be attached to the new intra-communicator (handle)
46+
47+
# Output Parameters
48+
49+
* `newcomm` : New communicator (handle).
50+
* `IERROR` : Fortran only: Error status (integer).
51+
52+
# Description
53+
54+
`MPI_Comm_create_from_group` is similar to `MPI_Comm_create_group`, except
55+
that the set of MPI processes involved in the creation of the new intra-communicator
56+
is specified by a group argument, rather than the group associated with a pre-existing communicator.
57+
If a non-empty group is specified, then all MPI processes in that group must call
58+
the function and each of these MPI processes must provide the same arguments, including
59+
a `group` that contains the same members with the same ordering, and identical `stringtag`
60+
value. In the event that `MPI_GROUP_EMPTY` is supplied as the group argument, then the
61+
call is a local operation and `MPI_COMM_NULL` is returned as `newcomm`. The `stringtag` argument
62+
is analogous to the `tag` used for `MPI_Comm_create_group`. If multiple threads at
63+
a given MPI process perform concurrent `MPI_Comm_create_from_group` operations,
64+
the user must distinguish these operations by providing different `stringtag` arguments. The
65+
`stringtag` shall not exceed MPI_MAX_STRINGTAG_LEN characters in length. For C, this includes
66+
space for a null terminating character.
67+
68+
# Notes
69+
70+
The `errhandler` argument specifies an error handler to be attached to the new intracommunicator.
71+
The `info` argument provides hints and assertions, possibly MPI implementation dependent, which
72+
indicate desired characteristics and guide communicator creation. MPI_MAX_STRINGTAG_LEN shall have a value
73+
of at least 63.
74+
75+
76+
# Errors
77+
78+
Almost all MPI routines return an error value; C routines as the value
79+
of the function and Fortran routines in the last argument.
80+
Before the error value is returned, the current MPI error handler is
81+
called. By default, this error handler aborts the MPI job, except for
82+
I/O function errors. The error handler may be changed with
83+
`MPI_Comm_set_errhandler`; the predefined error handler `MPI_ERRORS_RETURN`
84+
may be used to cause error values to be returned. Note that MPI does not
85+
guarantee that an MPI program can continue past an error.
86+
87+
# See Also
88+
89+
[`MPI_Comm_create_group`(3)](MPI_Comm_create_group.html)

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

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
# Name
2+
3+
`MPI_Group_from_session_pset` - Creates a group using a provided session handle and process set.
4+
5+
# Syntax
6+
7+
## C Syntax
8+
9+
```c
10+
#include <mpi.h>
11+
12+
int MPI_Group_from_session_pset(MPI_Session session, const char *pset_name, MPI_Group *newgroup)
13+
```
14+
15+
## Fortran Syntax
16+
17+
```fortran
18+
USE MPI
19+
! or the older form: INCLUDE 'mpif.h'
20+
21+
MPI_GROUP_FROM_SESSION_PSET(SESSION, PSET_NAME, NEWGROUP, IERROR)
22+
INTEGER SESSION, NEWGROUP, IERROR
23+
CHARACTER*(*) PSET_NAME
24+
```
25+
26+
## Fortran 2008 Syntax
27+
28+
```fortran
29+
USE mpi_f08
30+
31+
MPI_Group_from_session_pset(session, pset_name, newgroup, ierror)
32+
TYPE(MPI_Session), INTENT(IN) :: session
33+
CHARACTER(LEN=*), INTENT(IN) :: pset_name
34+
TYPE(MPI_Group), INTENT(OUT) :: newgroup
35+
INTEGER, OPTIONAL, INTENT(OUT) :: ierror
36+
```
37+
38+
# Input Parameters
39+
40+
* `session` : Session (handle).
41+
* `pset_name` : name of process set to use to create the new group (string)
42+
43+
# Output Parameters
44+
45+
* `newgroup` : New group derived from supplied session and process set (handle).
46+
* `IERROR` : Fortran only: Error status (integer).
47+
48+
# Description
49+
50+
The function `MPI_Group_from_session_pset` creates a group `newgroup` using the
51+
provided `session` handle and `process set`. The process set name must be one returned from
52+
an invocation of `MPI_Session_get_nth_pset` using the supplied `session` handle. If the
53+
`pset_name` does not exist, MPI_GROUP_NULL will be returned in the `newgroup` argument.
54+
55+
# Note
56+
57+
As with other group constructors, `MPI_Group_from_session_pset` is a local function.
58+
59+
# Errors
60+
61+
Almost all MPI routines return an error value; C routines as the value
62+
of the function and Fortran routines in the last argument.
63+
64+
Before the error value is returned, the current MPI error handler is
65+
called. By default, this error handler aborts the MPI job, except for
66+
I/O function errors. The error handler may be changed with
67+
`MPI_Session_set_errhandler`; the predefined error handler `MPI_ERRORS_RETURN`
68+
may be used to cause error values to be returned. Note that MPI does not
69+
guarantee that an MPI program can continue past an error.
70+
71+
# See Also
72+
73+
[`MPI_Session_init`(3)](MPI_Session_init.html)
74+
[`MPI_Session_get_nth_pset`(3)](MPI_Session_get_nth_pset.html)
75+
[`MPI_Group_free`(3)](MPI_Group_free.html)

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

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
# Name
2+
3+
`MPI_Intercomm_create_from_groups` - Creates a new inter-communicator from a local and remote group and stringtag
4+
5+
# Syntax
6+
7+
## C Syntax
8+
9+
```c
10+
#include <mpi.h>
11+
12+
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)
13+
```
14+
15+
## Fortran Syntax
16+
17+
```fortran
18+
USE MPI
19+
! or the older form: INCLUDE 'mpif.h'
20+
21+
MPI_INTERCOMM_CREATE_FROM_GROUPS(LOCAL_GROUP, LOCAL_LEADER, REMOTE_GROUP, REMOTE_LEADER, STRINGTAG, INFO, ERRHANDLER, NEWINTERCOMM, IERROR)
22+
INTEGER LOCAL_GROUP, LOCAL_LEADER, REMOTE_GROUP, REMOTE_LEADER, INFO, ERRHANDLER, NEWINTERCOMM, IERROR
23+
CHARACTER*(*) STRINGTAG
24+
```
25+
26+
## Fortran 2008 Syntax
27+
28+
```fortran
29+
USE mpi_f08
30+
31+
MPI_Intercomm_create_from_groups(local_group, local_leader, remote_group, remote_leader, stringtag, info, errhandler, newintercomm, ierror)
32+
TYPE(MPI_Group), INTENT(IN) :: local_group, remote_group
33+
INTEGER, INTENT(IN) :: local_leader, remote_leader
34+
CHARACTER(LEN=*), INTENT(IN) :: stringtag
35+
TYPE(MPI_Info), INTENT(IN) :: info
36+
TYPE(MPI_Errhandler), INTENT(IN) :: errhandler
37+
TYPE(MPI_Comm), INTENT(OUT) :: newintercomm
38+
INTEGER, OPTIONAL, INTENT(OUT) :: ierror
39+
```
40+
41+
# Input Parameters
42+
43+
* `local_group` : Local group (handler)
44+
* `local_leader` : rank of local group leader in local_group (integer)
45+
* `remote_group` : Remote group (handler)
46+
* `remote_leader` : rank of remote leader in remote_group, significant only at local_leader (integer)
47+
* `stringtag` : Unique identifier for this operation (string)
48+
* `info` : info object (handler)
49+
* `errhandler` : error handler to be attached to the new inter-communicator (handle)
50+
51+
# Output Parameters
52+
53+
* `newintercomm` : New inter-communicator (handle).
54+
* `IERROR` : Fortran only: Error status (integer).
55+
56+
# Description
57+
58+
`MPI_Intercomm_create_from_groups` creates an inter-communicator. Unlike `MPI_Intercomm_create`, this function
59+
uses as input previously defined, disjoint local and remote groups. The calling MPI
60+
process must be a member of the local group. The call is collective over the union of
61+
the local and remote groups. All involved MPI processes shall provide an identical value
62+
for the `stringtag` argument. Within each group, all MPI processes shall provide identical
63+
`local_group`, `local_leader` arguments. Wildcards are not permitted for the
64+
`remote_leader` or `local_leader` arguments. The `stringtag` argument serves the same purpose
65+
as the `stringtag` used in the `MPI_Comm_create_from_group` function; it differentiates
66+
concurrent calls in a multithreaded environment. The `stringtag` shall not exceed
67+
`MPI_MAX_STRINGTAG_LEN` characters in length. For C, this includes space for a null terminating
68+
character. In the event that MPI_GROUP_EMPTY is supplied as the `local_group` or `remote_group1 or both, then the
69+
call is a local operation and MPI_COMM_NULL is returned as the newintercomm`.
70+
71+
# Notes
72+
73+
The `errhandler` argument specifies an error handler to be attached to the new inter-communicator.
74+
The `info` argument provides hints and assertions, possibly MPI implementation dependent, which
75+
indicate desired characteristics and guide communicator creation. MPI_MAX_STRINGTAG_LEN shall have a value
76+
of at least 63.
77+
78+
79+
# Errors
80+
81+
Almost all MPI routines return an error value; C routines as the value
82+
of the function and Fortran routines in the last argument.
83+
Before the error value is returned, the current MPI error handler is
84+
called. By default, this error handler aborts the MPI job, except for
85+
I/O function errors. The error handler may be changed with
86+
`MPI_Comm_set_errhandler`; the predefined error handler `MPI_ERRORS_RETURN`
87+
may be used to cause error values to be returned. Note that MPI does not
88+
guarantee that an MPI program can continue past an error.
89+
90+
# See Also
91+
92+
[`MPI_Comm_create_from_group`(3)](MPI_Comm_create_from_group.html)

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

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# Name
2+
3+
`MPI_Session_create_errhandler` - Creates an error handler that can be
4+
attached to sessions
5+
6+
# Syntax
7+
8+
## C Syntax
9+
10+
```c
11+
#include <mpi.h>
12+
13+
int MPI_Session_create_errhandler(MPI_Session_errhandler_function *function,
14+
MPI_Errhandler *errhandler)
15+
```
16+
17+
## Fortran Syntax
18+
19+
```fortran
20+
USE MPI
21+
! or the older form: INCLUDE 'mpif.h'
22+
23+
MPI_SESSION_CREATE_ERRHANDLER(FUNCTION, ERRHANDLER, IERROR)
24+
EXTERNAL FUNCTION
25+
INTEGER ERRHANDLER, IERROR
26+
```
27+
28+
## Fortran 2008 Syntax
29+
30+
```fortran
31+
USE mpi_f08
32+
33+
MPI_Session_create_errhandler(session_errhandler_fn, errhandler, ierror)
34+
PROCEDURE(MPI_Session_errhandler_function) :: session_errhandler_fn
35+
TYPE(MPI_Errhandler), INTENT(OUT) :: errhandler
36+
INTEGER, OPTIONAL, INTENT(OUT) :: ierror
37+
```
38+
39+
# Input Parameter
40+
41+
* `function` : User-defined error handling procedure (function).
42+
43+
# Output Parameters
44+
45+
* `errhandler` : MPI error handler (handle).
46+
* `IERROR` : Fortran only: Error status (integer).
47+
48+
# Description
49+
50+
`MPI_Session_create_errhandler` creates an error handler that can be attached
51+
to sessions. This `function` is identical to `MPI_Errhandler_create`,
52+
the use of which is deprecated.
53+
In C, the user routine should be a `function` of type
54+
`MPI_Session_errhandler_function`, which is defined as
55+
```c
56+
typedef void MPI_Session_errhandler_function(MPI_Session *, int *, ...);
57+
```
58+
The first argument is the session in use. The second is the error
59+
code to be returned by the MPI routine that raised the error. This
60+
typedef replaces `MPI_Handler_function`, the use of which is deprecated.
61+
In Fortran, the user routine should be of this form:
62+
```fortran
63+
SUBROUTINE SESSION_ERRHANDLER_FUNCTION(SESSION, ERROR_CODE, ...)
64+
INTEGER SESSION, ERROR_CODE
65+
```
66+
67+
# Errors
68+
69+
Almost all MPI routines return an error value; C routines as the value
70+
of the `function` and Fortran routines in the last argument.
71+
Before the error value is returned, the current MPI error handler is
72+
called. By default, this error handler aborts the MPI job, except for
73+
I/O `function` errors. The error handler may be changed with
74+
`MPI_Session_set_errhandler`; the predefined error handler `MPI_ERRORS_RETURN`
75+
may be used to cause error values to be returned. Note that MPI does not
76+
guarantee that an MPI program can continue past an error.

0 commit comments

Comments
 (0)