MAN: updated man-pages for lots of RMA window functions

zerothi · zerothi · commit 962608dda094 · 2021-03-31T09:12:53.000+02:00
The updates adds explanations of different MODES for the
window synchronization routines as well as providing a bit
more context for the baseptr (void *) data-types which are actually
void ** types.

Also added more cross-links.

Finally added explanations of the Win_create_dynamic usage that explicitly
requires attention about address spaces. I.e. the actual address at the target
is necessary for succesfull operation.

Signed-off-by: Nick Papior &lt;nickpapior@gmail.com&gt;
diff --git a/ompi/mpi/man/man3/MPI_Alloc_mem.3in b/ompi/mpi/man/man3/MPI_Alloc_mem.3in
@@ -58,9 +58,13 @@ Fortran only: Error status (integer).
 .SH DESCRIPTION
 .ft R
 MPI_Alloc_mem allocates \fIsize\fP bytes of memory. The starting address
-of this memory is returned in the variable \fIbase\fP.
+of this memory is returned in the variable \fIbaseptr\fP.
 .sp
 
+.SH C NOTES
+.ft R
+While \fIbaseptr\fP is a \fIvoid *\fP type, this is to allow easy use of any pointer object for this parameter. This argument is really a \fIvoid **\fP type.
+
 .SH FORTRAN NOTES
 .ft R
 There is no portable FORTRAN 77 syntax for using MPI_Alloc_mem.
diff --git a/ompi/mpi/man/man3/MPI_Win_allocate.3in b/ompi/mpi/man/man3/MPI_Win_allocate.3in
@@ -100,6 +100,12 @@ 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.
 .sp
+Calling \fBMPI_Win_free\fP will deallocate the memory allocated by \fBMPI_Win_allocate\fP. It will thus be an error to manually free \fIbaseptr\fP.
+
+.SH C NOTES
+.ft R
+While \fIbaseptr\fP is a \fIvoid *\fP type, this is to allow easy use of any pointer object for this parameter. This argument is really a \fIvoid **\fP type.
+.sp
 
 .SH ERRORS
 Almost all MPI routines return an error value; C routines as the value of the function and Fortran routines in the last argument.
@@ -119,3 +125,4 @@ MPI_Alloc_mem
 MPI_Free_mem
 MPI_Win_create
 MPI_Win_allocate_shared
+MPI_Win_free
diff --git a/ompi/mpi/man/man3/MPI_Win_allocate_shared.3in b/ompi/mpi/man/man3/MPI_Win_allocate_shared.3in
@@ -123,6 +123,12 @@ 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.
 .sp
+Calling \fBMPI_Win_free\fP will deallocate the memory allocated by \fBMPI_Win_allocate_shared\fP. It will thus be an error to manually free \fIbaseptr\fP.
+
+.SH C NOTES
+.ft R
+While \fIbaseptr\fP is a \fIvoid *\fP type, this is to allow easy use of any pointer object for this parameter. This argument is really a \fIvoid **\fP type.
+.sp
 
 .SH ERRORS
 Almost all MPI routines return an error value; C routines as the value
@@ -144,3 +150,5 @@ MPI_Free_mem
 MPI_Win_allocate
 MPI_Win_create
 MPI_Win_shared_query
+MPI_Win_free
+
diff --git a/ompi/mpi/man/man3/MPI_Win_create_dynamic.3in b/ompi/mpi/man/man3/MPI_Win_create_dynamic.3in
@@ -53,6 +53,9 @@ Fortran only: Error status (integer).
 .SH DESCRIPTION
 .ft R
 MPI_Win_create_dynamic is a one-sided MPI communication collective call executed by all processes in the group of \fIcomm\fP. It returns a window object without memory attached that can be used by these processes to perform RMA operations.
+.sp
+A window created with MPI_Win_create_dynamic requires the \fItarget_disp\fP argument for all RMA functions to be the actual address at the target.
+
 .sp
 The following info keys are supported:
 .ft R
@@ -80,7 +83,14 @@ If set to \fIsame_op\fP, the implementation will assume that all concurrent
 accumulate calls to the same target address will use the same
 operation.  If set to \fIsame_op_no_op\fP, then the implementation will
 assume that all concurrent accumulate calls to the same target address
-will use the same operation or MPI_NO_OP.  The default is \fIsame_op_no_op\fP.
+will use the same operation or MPI_NO_OP. The default is \fIsame_op_no_op\fP.
+.sp
+
+.SH NOTES
+Since dynamically attaching memory to windows are not collective calls, one have to communicate the actual address at the target using MPI_Get_address and some communication.
+.sp
+Dynamic memory does not have any \fIdisp_unit\fP associated and requires correct offset calculations with proper type handling.
+.sp
 
 .SH ERRORS
 Almost all MPI routines return an error value; C routines as the value of the function and Fortran routines in the last argument.
@@ -89,4 +99,10 @@ 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.
 
 
+.SH SEE ALSO
+MPI_Win_attach
+MPI_Win_detach
+MPI_Get_address
+.br
+
 
diff --git a/ompi/mpi/man/man3/MPI_Win_fence.3in b/ompi/mpi/man/man3/MPI_Win_fence.3in
@@ -54,7 +54,23 @@ MPI_Win_fence synchronizes RMA calls on \fIwin\fP. The call is collective on the
 .sp
 The call completes an RMA access epoch if it was preceded by another fence call and the local process issued RMA communication calls on \fIwin\fP between these two calls. The call completes an RMA exposure epoch if it was preceded by another fence call and the local window was the target of RMA accesses between these two calls. The call starts an RMA access epoch if it is followed by another fence call and by RMA communication calls issued between these two fence calls. The call starts an exposure epoch if it is followed by another fence call and the local window is the target of RMA accesses between these two fence calls. Thus, the fence call is equivalent to calls to a subset of \fIpost, start, complete, wait\fP.
 .sp
-A fence call usually entails a barrier synchronization: a process completes a call to MPI_Win_fence only after all other processes in the group have entered their matching call. However, a call to MPI_Win_fence that is known not to end any epoch (in particular, a call with \fIassert\fP = MPI_MODE_NOPRECEDE) does not necessarily act as a barrier.
+The \fIassert\fP argument is used to provide assertions on the context of the call that may be used for various optimizations. A value of \fIassert\fP = 0 is always valid. The following assertion value is supported:
+.ft R
+.TP 1i
+MPI_MODE_NOPRECEDE
+No locally called RMA calls must be present before this fence. This must be given to all or no members of the window. It may enable faster fence call by bypassing a barrier.
+.sp
+.TP 1i
+MPI_MODE_NOSTORE
+Informs that the local window was not updated by local stores or get calls in the preceding epoch.
+.TP 1i
+MPI_MODE_NOPUT
+Informs that the local window will not be updated by any put or accummulate calls in the ensuing epoch (until next fence call).
+.TP 1i
+MPI_MODE_NOSUCCEED
+No locally called RMA calls must be present after this fence. This must be given to all or no members of the window. It may enable a faster fence call by bypassing a barrier.
+.sp
+
 
 .SH NOTE
 Calls to MPI_Win_fence should both precede and follow calls to put, get or accumulate that are synchronized with fence calls.
diff --git a/ompi/mpi/man/man3/MPI_Win_free.3in b/ompi/mpi/man/man3/MPI_Win_free.3in
@@ -48,6 +48,10 @@ Fortran only: Error status (integer).
 .ft R
 MPI_Win_free frees the window object \fIwin\fP and returns a null handle (equal to MPI_WIN_NULL). This collective call is executed by all processes in the group associated with \fIwin\fP. It can be invoked by a process only after it has completed its involvement in RMA communications on window \fIwin\fP, that is, the process has called MPI_Win_fence, or called MPI_Win_unlock to match a previous call to MPI_Win_lock. When the call returns, the window memory can be freed.
 
+.SH NOTES
+.ft R
+If the window was created through \fBMPI_Win_allocate\fP or \fBMPI_Win_allocate_shared\fP then the memory buffer from that call would be freed when calling \fBMPI_Win_free\fP.
+
 .SH ERRORS
 Almost all MPI routines return an error value; C routines as the value of the function and Fortran routines in the last argument.
 .sp
@@ -56,7 +60,7 @@ called. By default, this error handler aborts the MPI job, except for I/O functi
 
 .SH SEE ALSO
 MPI_Win_create
-MPI_Win_fence
-MPI_Win_unlock
+MPI_Win_allocate
+MPI_Win_allocate_shared
 .br
 
diff --git a/ompi/mpi/man/man3/MPI_Win_lock.3in b/ompi/mpi/man/man3/MPI_Win_lock.3in
@@ -63,8 +63,13 @@ Locks are used to protect accesses to the locked target window effected by RMA c
 Accesses that are protected by an exclusive lock will not be concurrent at the window site with other accesses to the same window that are lock protected. Accesses that are protected by a shared lock will not be concurrent at the window site with accesses protected by an exclusive lock to the same window.
 .sp
 The \fIassert\fP argument is used to provide assertions on the context of the call that may be used for various optimizations. (See Section 6.4.4 of the MPI-2 Standard.) A value of \fIassert\fP = 0 is always valid.
+The following assertion value is supported:
+.ft R
+.TP 1i
+MPI_MODE_NOCHECK
+No other processes will hold or attempt to acquire a conflicting lock while the caller holds the window.
 .sp
-.ft
+
 .SH NOTES
 .ft R
 In a client/server environment in which clients connect to
diff --git a/ompi/mpi/man/man3/MPI_Win_lock_all.3in b/ompi/mpi/man/man3/MPI_Win_lock_all.3in
@@ -56,8 +56,13 @@ Locks are used to protect accesses to the locked target window effected by RMA c
 Accesses that are protected by an exclusive lock will not be concurrent at the window site with other accesses to the same window that are lock protected. Accesses that are protected by a shared lock will not be concurrent at the window site with accesses protected by an exclusive lock to the same window.
 .sp
 The \fIassert\fP argument is used to provide assertions on the context of the call that may be used for various optimizations. (See Section 6.4.4 of the MPI-2 Standard.) A value of \fIassert\fP = 0 is always valid.
+The following assertion value is supported:
+.ft R
+.TP 1i
+MPI_MODE_NOCHECK
+No other processes will hold or attempt to acquire a conflicting lock while the caller holds the window.
 .sp
-.ft
+
 .SH NOTES
 .ft R
 In a client/server environment in which clients connect to
diff --git a/ompi/mpi/man/man3/MPI_Win_post.3in b/ompi/mpi/man/man3/MPI_Win_post.3in
@@ -55,6 +55,19 @@ Fortran only: Error status (integer).
 .SH DESCRIPTION
 
 Starts an RMA exposure epoch for the local window associated with \fIwin\fP. Only the processes belonging to \fIgroup\fP should access the window with RMA calls on \fIwin\fP during this epoch. Each process in \fIgroup\fP must issue a matching call to MPI_Win_start. MPI_Win_post does not block.
+.sp
+The \fIassert\fP argument is used to provide assertions on the context of the call that may be used for various optimizations. A value of \fIassert\fP = 0 is always valid. The following assertion value is supported:
+.ft R
+.TP 1i
+MPI_MODE_NOCHECK
+The matching call MPI_Win_start have not yet occurred ony any origin processes when this call is made. This assertion must be present for all matching MPI_Win_start calls if used.
+.TP 1i
+MPI_MODE_NOSTORE
+Informs that the local window was not updated by local stores or get calls in the preceding epoch.
+.TP 1i
+MPI_MODE_NOPUT
+Informs that the local window will not be updated by put or accummulate calls until the ensuing wait synchronization.
+.sp
 
 .SH ERRORS
 Almost all MPI routines return an error value; C routines as the value of the function and Fortran routines in the last argument.
diff --git a/ompi/mpi/man/man3/MPI_Win_shared_query.3in b/ompi/mpi/man/man3/MPI_Win_shared_query.3in
@@ -82,6 +82,10 @@ all processes in the group attached to the window specified \fIsize\fP
 = 0, then the call returns \fIsize\fP = 0 and a \fIbaseptr\fP as if
 \fBMPI_Alloc_mem\fP was called with \fIsize\fP = 0.
 
+.SH C NOTES
+.ft R
+While \fIbaseptr\fP is a \fIvoid *\fP type, this is to allow easy use of any pointer object for this parameter. This argument is really a \fIvoid **\fP type.
+
 .SH ERRORS
 Almost all MPI routines return an error value; C routines as the value
 of the function and Fortran routines in the last argument.
diff --git a/ompi/mpi/man/man3/MPI_Win_start.3in b/ompi/mpi/man/man3/MPI_Win_start.3in
@@ -60,7 +60,7 @@ call to MPI_Win_post. MPI_Win_start
 is allowed to block until the corresponding MPI_Win_post calls have been executed, but is not required to.
 .sp
 The \fIassert\fP argument is used to provide assertions on the context of the call that may be used for various optimizations. (See Section 6.4.4 of the MPI-2 Standard.) A value of \fIassert\fP = 0 is always valid. The following assertion value is supported:
-.sp
+.ft R
 .TP 1i
 MPI_MODE_NOCHECK
 When this value is passed in to this call, the library assumes that
