Skip to content

Commit b2a15c5

Browse files
jsquyresjsquyres
committed
Merge pull request open-mpi#597 from hjelmn/v2.x_missing_man
Add missing man pages to v2.x
2 parents 2ae0f3b + 02d183d commit b2a15c5

File tree

8 files changed

+496
-3
lines changed

8 files changed

+496
-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_attach.3in‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
.\" -*- nroff -*-
2+
.\" Copyright (c) 2015 Research Organization for Information Science
3+
.\" and Technology (RIST). All rights reserved.
4+
.\" $COPYRIGHT$
5+
.TH MPI_Win_attach 3 "#OMPI_DATE#" "#PACKAGE_VERSION#" "#PACKAGE_NAME#"
6+
.SH NAME
7+
\fBMPI_Win_create, MPI_Win_detach\fP \- One-sided MPI call that attach / detach a window object for RMA operations.
8+
9+
.SH SYNTAX
10+
.ft R
11+
.SH C Syntax
12+
.nf
13+
#include <mpi.h>
14+
MPI_Win_attach(MPI_Win *\fIwin\fP, void *\fIbase\fP, MPI_Aint \fIsize\fP)
15+
16+
MPI_Win_detach(MPI_Win *\fIwin\fP, void *\fIbase\fP)
17+
.fi
18+
.SH Fortran Syntax
19+
.nf
20+
INCLUDE 'mpif.h'
21+
MPI_WIN_ATTACH(\fIWIN, BASE, SIZE, IERROR\fP)
22+
<type> \fIBASE\fP(*)
23+
INTEGER(KIND=MPI_ADDRESS_KIND) \fISIZE\fP
24+
INTEGER \fIWIN, IERROR\fP
25+
26+
.fi
27+
.SH INPUT PARAMETERS
28+
.ft R
29+
.TP 1i
30+
win
31+
A window that was created with
32+
.I MPI_Win_create_dynamic
33+
34+
.TP 1i
35+
base
36+
Initial address of window (choice).
37+
.TP 1i
38+
size
39+
Size of window in bytes (nonnegative integer).
40+
41+
.SH OUTPUT PARAMETERS
42+
.ft R
43+
.TP 1i
44+
win
45+
Window object returned by the call (handle).
46+
.TP 1i
47+
IERROR
48+
Fortran only: Error status (integer).
49+
50+
.SH DESCRIPTION
51+
.ft R
52+
MPI_Win_attach is a one-sided MPI communication collective call executed by all processes in the group of \fIcomm\fP. It returns a window object that can be used by these processes to perform RMA operations. Each process specifies a window of existing memory that it exposes to RMA accesses by the processes in the group of \fIcomm\fP. The window consists of \fIsize\fP bytes, starting at address \fIbase\fP. A process may elect to expose no memory by specifying \fIsize\fP = 0.
53+
.sp
54+
If the \fIbase\fP value used by MPI_Win_create was allocated by MPI_Alloc_mem, the size of the window can be no larger than the value set by the MPI_ALLOC_MEM function.
55+
.sp
56+
57+
.SH NOTES
58+
Use memory allocated by MPI_Alloc_mem to guarantee properly aligned window boundaries (such as word, double-word, cache line, page frame, and so on).
59+
.sp
60+
61+
62+
63+
.SH ERRORS
64+
Almost all MPI routines return an error value; C routines as the value of the function and Fortran routines in the last argument.
65+
.sp
66+
Before the error value is returned, the current MPI error handler is
67+
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.

‎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

0 commit comments

Comments
 (0)