Skip to content

Commit 02d183d

Browse files
hjelmnhjelmn
committed
ompi: add missing man pages
This commit adds man pages for the MPI_Win_allocate and MPI_Win_allocated_shared MPI-3 functions. The man page for MPI_Win_create has also been updated to indicate support for the same_size and same_disp_unit info keys Signed-off-by: Nathan Hjelm <[email protected]> (cherry picked from open-mpi/ompi@d6724f2)
1 parent 7b2cc53 commit 02d183d

File tree

5 files changed

+347
-3
lines changed

5 files changed

+347
-3
lines changed

‎ompi/mpi/man/man3/MPI_Win_allocate.3in‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
.\" -*- nroff -*-
2+
.\" Copyright 2015 Los Alamos National Security, LLC. All rights reserved.
3+
.\" Copyright 2010 Cisco Systems, Inc. All rights reserved.
4+
.\" Copyright 2007-2008 Sun Microsystems, Inc.
5+
.\" Copyright (c) 1996 Thinking Machines Corporation
6+
.\" $COPYRIGHT$
7+
.TH MPI_Win_allocate 3 "#OMPI_DATE#" "#PACKAGE_VERSION#" "#PACKAGE_NAME#"
8+
.SH NAME
9+
\fBMPI_Win_allocate\fP \- One-sided MPI call that allocates memory and
10+
returns a window object for RMA operations.
11+
12+
.SH SYNTAX
13+
.ft R
14+
.SH C Syntax
15+
.nf
16+
#include <mpi.h>
17+
int MPI_Win_allocate (MPI_Aint \fIsize\fP, int \fIdisp_unit\fP, MPI_Info \fIinfo\fP,
18+
MPI_Comm \fIcomm\fP, void *\fIbaseptr\fP, MPI_Win *\fIwin\fP)
19+
20+
.fi
21+
.SH Fortran Syntax
22+
.nf
23+
INCLUDE 'mpif.h'
24+
MPI_WIN_ALLOCATE(\fSIZE, DISP_UNIT, INFO, COMM, BASEPTR, WIN, IERROR\fP)
25+
INTEGER(KIND=MPI_ADDRESS_KIND) \fISIZE, BASEPTR\fP
26+
INTEGER \fIDISP_UNIT, INFO, COMM, WIN, IERROR\fP
27+
28+
.fi
29+
.SH INPUT PARAMETERS
30+
.ft R
31+
.TP 1i
32+
size
33+
Size of window in bytes (nonnegative integer).
34+
.TP 1i
35+
disp_unit
36+
Local unit size for displacements, in bytes (positive integer).
37+
.TP 1i
38+
info
39+
Info argument (handle).
40+
.TP 1i
41+
comm
42+
Communicator (handle).
43+
44+
.SH OUTPUT PARAMETERS
45+
.ft R
46+
.TP 1i
47+
baseptr
48+
Initial address of window.
49+
.TP 1i
50+
win
51+
Window object returned by the call (handle).
52+
.TP 1i
53+
IERROR
54+
Fortran only: Error status (integer).
55+
56+
.SH DESCRIPTION
57+
.ft R
58+
\fBMPI_Win_allocate\fP is a collective call executed by all processes
59+
in the group of \fIcomm\fP. On each process, it allocates memory of at
60+
least \fIsize\fP bytes, returns a pointer to it, and returns a window
61+
object that can be used by all processes in \fIcomm\fP to perform RMA
62+
operations. The returned memory consists of \fIsize\fP bytes local to
63+
each process, starting at address \fIbaseptr\fP and is associated with
64+
the window as if the user called \fBMPI_Win_create\fP on existing
65+
memory. The \fIsize\fP argument may be different at each process and
66+
\fIsize\fP = 0 is valid; however, a library might allocate and expose
67+
more memory in order to create a fast, globally symmetric
68+
allocation. The discussion of and rationales for \fBMPI_Alloc_mem\fP and
69+
\fBMPI_Free_mem\fP in MPI-3.1 \[char167] 8.2 also apply to
70+
\fBMPI_Win_allocate\fP; in particular, see the rationale in MPI-3.1
71+
\[char167] 8.2 for an explanation of the type used for \fIbaseptr\fP.
72+
.sp
73+
The displacement unit argument is provided to facilitate address
74+
arithmetic in RMA operations: the target displacement argument of an
75+
RMA operation is scaled by the factor \fIdisp_unit\fP specified by the
76+
target process, at window creation.
77+
.sp
78+
For supported info keys see \fBMPI_Win_create\fI.
79+
.sp
80+
81+
.SH NOTES
82+
Common choices for \fIdisp_unit\fP are 1 (no scaling), and (in C
83+
syntax) \fIsizeof(type)\fP, for a window that consists of an array of
84+
elements of type \fItype\fP. The later choice will allow one to use
85+
array indices in RMA calls, and have those scaled correctly to byte
86+
displacements, even in a heterogeneous environment.
87+
.sp
88+
89+
.SH ERRORS
90+
Almost all MPI routines return an error value; C routines as the value of the function and Fortran routines in the last argument.
91+
.sp
92+
Before the error value is returned, the current MPI error handler is
93+
called. By default, this error handler aborts the MPI job, except for
94+
I/O function errors. The error handler may be changed with
95+
MPI_Comm_set_errhandler; the predefined error handler
96+
MPI_ERRORS_RETURN may be used to cause error values to be
97+
returned. Note that MPI does not guarantee that an MPI program can
98+
continue past an error.
99+
100+
.SH SEE ALSO
101+
.ft R
102+
.sp
103+
MPI_Alloc_mem
104+
MPI_Free_mem
105+
MPI_Win_create
106+
MPI_Win_allocate_shared

‎ompi/mpi/man/man3/MPI_Win_allocate_shared.3in‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
.\" -*- nroff -*-
2+
.\" Copyright 2015 Los Alamos National Security, LLC. All rights reserved.
3+
.\" Copyright 2010 Cisco Systems, Inc. All rights reserved.
4+
.\" Copyright 2007-2008 Sun Microsystems, Inc.
5+
.\" Copyright (c) 1996 Thinking Machines Corporation
6+
.\" $COPYRIGHT$
7+
.TH MPI_Win_allocate_shared 3 "#OMPI_DATE#" "#PACKAGE_VERSION#" "#PACKAGE_NAME#"
8+
.SH NAME
9+
\fBMPI_Win_allocate_shared\fP \- One-sided MPI call that allocates
10+
shared memory and returns a window object for RMA operations.
11+
12+
.SH SYNTAX
13+
.ft R
14+
.SH C Syntax
15+
.nf
16+
#include <mpi.h>
17+
int MPI_Win_allocate_shared (MPI_Aint \fIsize\fP, int \fIdisp_unit\fP, MPI_Info \fIinfo\fP,
18+
MPI_Comm \fIcomm\fP, void *\fIbaseptr\fP, MPI_Win *\fIwin\fP)
19+
20+
.fi
21+
.SH Fortran Syntax
22+
.nf
23+
INCLUDE 'mpif.h'
24+
MPI_WIN_ALLOCATE_SHARED(\fSIZE, DISP_UNIT, INFO, COMM, BASEPTR, WIN, IERROR\fP)
25+
INTEGER(KIND=MPI_ADDRESS_KIND) \fISIZE, BASEPTR\fP
26+
INTEGER \fIDISP_UNIT, INFO, COMM, WIN, IERROR\fP
27+
28+
.fi
29+
.SH INPUT PARAMETERS
30+
.ft R
31+
.TP 1i
32+
size
33+
Size of window in bytes (nonnegative integer).
34+
.TP 1i
35+
disp_unit
36+
Local unit size for displacements, in bytes (positive integer).
37+
.TP 1i
38+
info
39+
Info argument (handle).
40+
.TP 1i
41+
comm
42+
Communicator (handle).
43+
44+
.SH OUTPUT PARAMETERS
45+
.ft R
46+
.TP 1i
47+
baseptr
48+
Initial address of window.
49+
.TP 1i
50+
win
51+
Window object returned by the call (handle).
52+
.TP 1i
53+
IERROR
54+
Fortran only: Error status (integer).
55+
56+
.SH DESCRIPTION
57+
.ft R
58+
\fBMPI_Win_allocate_shared\fP is a collective call executed by all
59+
processes in the group of \fIcomm\fP. On each process, it allocates
60+
memory of at least \fIsize\fP bytes that is shared among all processes
61+
in \fIcomm\fP, and returns a pointer to the locally allocated segment
62+
in \fIbaseptr\fP that can be used for load/store accesses on the
63+
calling process. The locally allocated memory can be the target of
64+
load/store accesses by remote processes; the base pointers for other
65+
processes can be queried using the function
66+
\fBMPI_Win_shared_query\fP. The call also returns a window object that
67+
can be used by all processes in \fIcomm\fP to perform RMA
68+
operations. The \fIsize\fP argument may be different at each process
69+
and \fIsize\fP = 0 is valid. It is the user's responsibility to ensure
70+
that the communicator \fIcomm\fP represents a group of processes that
71+
can create a shared memory segment that can be accessed by all
72+
processes in the group. The discussions of rationales for
73+
\fBMPI_Alloc_mem\fP and \fBMPI_Free_mem\fP in MPI-3.1 \[char167] 8.2
74+
also apply to \fBMPI_Win_allocate_shared\fP; in particular, see the
75+
rationale in MPI-3.1 \[char167] 8.2 for an explanation of the type
76+
used for \fIbaseptr\fP. The allocated memory is contiguous across
77+
process ranks unless the info key \fIalloc_shared_noncontig\fP is
78+
specified. Contiguous across process ranks means that the first
79+
address in the memory segment of process i is consecutive with the
80+
last address in the memory segment of process i - 1. This may enable
81+
the user to calculate remote address offsets with local information
82+
only.
83+
.sp
84+
The following info keys are supported:
85+
.ft R
86+
.TP 1i
87+
alloc_shared_noncontig
88+
If not set to \fItrue\fP, the allocation strategy is to allocate
89+
contiguous memory across process ranks. This may limit the performance
90+
on some architectures because it does not allow the implementation to
91+
modify the data layout (e.g., padding to reduce access latency).
92+
.sp
93+
.TP 1i
94+
blocking_fence
95+
If set to \fItrue\fP, the osc/sm component will use \fBMPI_Barrier\FP
96+
for \fBMPI_Win_fence\fP. If set to \fIfalse\fP a condition variable
97+
and counter will be used instead. The default value is
98+
\fIfalse\fP. This info key is Open MPI specific.
99+
.sp
100+
.TP 1i
101+
For additional supported info keys see \fBMPI_Win_create\fP.
102+
.sp
103+
104+
.SH NOTES
105+
Common choices for \fIdisp_unit\fP are 1 (no scaling), and (in C
106+
syntax) \fIsizeof(type)\fP, for a window that consists of an array of
107+
elements of type \fItype\fP. The later choice will allow one to use
108+
array indices in RMA calls, and have those scaled correctly to byte
109+
displacements, even in a heterogeneous environment.
110+
.sp
111+
112+
.SH ERRORS
113+
Almost all MPI routines return an error value; C routines as the value
114+
of the function and Fortran routines in the last argument.
115+
.sp
116+
Before the error value is returned, the current MPI error handler is
117+
called. By default, this error handler aborts the MPI job, except for
118+
I/O function errors. The error handler may be changed with
119+
MPI_Comm_set_errhandler; the predefined error handler
120+
MPI_ERRORS_RETURN may be used to cause error values to be
121+
returned. Note that MPI does not guarantee that an MPI program can
122+
continue past an error.
123+
124+
.SH SEE ALSO
125+
.ft R
126+
.sp
127+
MPI_Alloc_mem
128+
MPI_Free_mem
129+
MPI_Win_allocate
130+
MPI_Win_create

‎ompi/mpi/man/man3/MPI_Win_create.3in‎

Lines changed: 21 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
11
.\" -*- nroff -*-
2+
.\" Copyright 2015 Los Alamos National Security, LLC. All rights
3+
.\" reserved.
24
.\" Copyright 2010 Cisco Systems, Inc. All rights reserved.
35
.\" Copyright 2007-2008 Sun Microsystems, Inc.
46
.\" Copyright (c) 1996 Thinking Machines Corporation
@@ -96,7 +98,18 @@ operation. If set to \fIsame_op_no_op\fP, then the implementation will
9698
assume that all concurrent accumulate calls to the same target address
9799
will use the same operation or MPI_NO_OP. The default is \fIsame_op_no_op\fP.
98100
.sp
99-
101+
.TP 1i
102+
same_size
103+
If set to \fItrue\fP, then the implementation may assume that the argument
104+
\fIsize\fP is identical on all processes, and that all processes have
105+
provided this info key with the same value.
106+
.sp
107+
.TP 1i
108+
same_disp_unit
109+
If set to \fItrue\fP, then the implementation may assume that the argument
110+
\fIdisp_unit\fP is identical on all processes, and that all processes have
111+
provided this info key with the same value.
112+
.sp
100113
.SH NOTES
101114
Common choices for \fIdisp_unit\fP are 1 (no scaling), and (in C syntax) \fIsizeof(type)\fP, for a window that consists of an array of elements of type \fItype\fP. The later choice will allow one to use array indices in RMA calls, and have those scaled correctly to byte displacements, even in a heterogeneous environment.
102115
.sp
@@ -124,5 +137,10 @@ Almost all MPI routines return an error value; C routines as the value of the fu
124137
Before the error value is returned, the current MPI error handler is
125138
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.
126139

127-
128-
140+
.SH SEE ALSO
141+
.ft R
142+
.sp
143+
MPI_Alloc_mem
144+
MPI_Free_mem
145+
MPI_Win_allocate
146+
MPI_Win_allocate_shared

‎ompi/mpi/man/man3/MPI_Win_shared_query.3in‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
.\" -*- nroff -*-
2+
.\" Copyright 2015 Los Alamos National Security, LLC. All rights reserved.
3+
.\" Copyright 2010 Cisco Systems, Inc. All rights reserved.
4+
.\" Copyright 2007-2008 Sun Microsystems, Inc.
5+
.\" Copyright (c) 1996 Thinking Machines Corporation
6+
.\" $COPYRIGHT$
7+
.TH MPI_Win_shared_query 3 "#OMPI_DATE#" "#PACKAGE_VERSION#" "#PACKAGE_NAME#"
8+
.SH NAME
9+
\fBMPI_Win_shared_query\fP \- Query a shared memory window
10+
11+
.SH SYNTAX
12+
.ft R
13+
.SH C Syntax
14+
.nf
15+
#include <mpi.h>
16+
int MPI_Win_shared_query (MPI_Win \fIwin\fP, int \fIrank\fP, MPI_Aint *\fIsize\fP,
17+
int *\fIdisp_unit\fP, void *\fIbaseptr\fP)
18+
19+
.fi
20+
.SH Fortran Syntax
21+
.nf
22+
INCLUDE 'mpif.h'
23+
MPI_WIN_SHARED_QUERY(WIN, RANK, SIZE, DISP_UNIT, BASEPTR, IERROR)
24+
INTEGER WIN, RANK, DISP_UNIT, IERROR
25+
INTEGER (KIND=MPI_ADDRESS_KIND) SIZE, BASEPTR
26+
27+
.fi
28+
.SH INPUT PARAMETERS
29+
.ft R
30+
.TP 1i
31+
win
32+
Shared memory window object (handle).
33+
.TP 1i
34+
rank
35+
Rank in the group of window \fIwin\fP (non-negative integer)
36+
or MPI_PROC_NULL.
37+
38+
.SH OUTPUT PARAMETERS
39+
.ft R
40+
.TP 1i
41+
size
42+
Size of the window segment (non-negative integer).
43+
.TP 1i
44+
disp_unit
45+
Local unit size for displacements, in bytes (positive integer).
46+
.TP 1i
47+
baseptr
48+
Address for load/store access to window segment
49+
(choice).
50+
.TP 1i
51+
IERROR
52+
Fortran only: Error status (integer).
53+
54+
.SH DESCRIPTION
55+
.ft R
56+
\fBMPI_Win_shared_query\fP queries the process-local address for
57+
remote memory segments created with MPI_Win_allocate_shared. This
58+
function can return different process-local addresses for the same
59+
physical memory on different processes. The returned memory can be
60+
used for load/store accesses subject to the constraints defined in
61+
MPI-3.1 \[char167] 11.7. This function can only be called with windows
62+
of flavor MPI_WIN_FLAVOR_SHARED. If the passed window is not of flavor
63+
MPI_WIN_FLAVOR_SHARED, the error MPI_ERR_RMA_FLAVOR is raised. When
64+
rank is MPI_PROC_NULL, the \fIpointer\fP, \fIdisp_unit\fP, and
65+
\fIsize\fP returned are the pointer, disp_unit, and size of the memory
66+
segment belonging the lowest rank that specified \fIsize\fP > 0. If
67+
all processes in the group attached to the window specified \fIsize\fP
68+
= 0, then the call returns \fIsize\fP = 0 and a \fIbaseptr\fP as if
69+
\fBMPI_Alloc_mem\fP was called with \fIsize\fP = 0.
70+
71+
.SH ERRORS
72+
Almost all MPI routines return an error value; C routines as the value
73+
of the function and Fortran routines in the last argument.
74+
.sp
75+
Before the error value is returned, the current MPI error handler is
76+
called. By default, this error handler aborts the MPI job, except for
77+
I/O function errors. The error handler may be changed with
78+
MPI_Comm_set_errhandler; the predefined error handler
79+
MPI_ERRORS_RETURN may be used to cause error values to be
80+
returned. Note that MPI does not guarantee that an MPI program can
81+
continue past an error.
82+
83+
.SH SEE ALSO
84+
.ft R
85+
.sp
86+
MPI_Alloc_mem
87+
MPI_Win_allocate_shared

‎ompi/mpi/man/man3/Makefile.extra‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -381,6 +381,8 @@ mpi_api_man_pages = \
381381
mpi/man/man3/MPI_Waitall.3 \
382382
mpi/man/man3/MPI_Waitany.3 \
383383
mpi/man/man3/MPI_Waitsome.3 \
384+
mpi/man/man3/MPI_Win_allocate.3 \
385+
mpi/man/man3/MPI_Win_allocate_shared.3 \
384386
mpi/man/man3/MPI_Win_attach.3 \
385387
mpi/man/man3/MPI_Win_c2f.3 \
386388
mpi/man/man3/MPI_Win_call_errhandler.3 \
@@ -411,6 +413,7 @@ mpi_api_man_pages = \
411413
mpi/man/man3/MPI_Win_set_errhandler.3 \
412414
mpi/man/man3/MPI_Win_set_info.3 \
413415
mpi/man/man3/MPI_Win_set_name.3 \
416+
mpi/man/man3/MPI_Win_shared_query.3 \
414417
mpi/man/man3/MPI_Win_start.3 \
415418
mpi/man/man3/MPI_Win_sync.3 \
416419
mpi/man/man3/MPI_Win_test.3 \

0 commit comments

Comments
 (0)