Merge pull request #8744 from zerothi/8680-manpage-win

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

Author: jsquyres

.mailmap

@@ -113,3 +113,7 @@ Anandhi S Jayakumar <anandhi.s.jayakumar@intel.com>
 Mohan Gandhi <mohgan@amazon.com>
 
 Harumi Kuno <harumi.kuno@hpe.com>
+
+Nick Papior <nickpapior@gmail.com>
+Nick Papior <nickpapior@gmail.com> <nicpa@dtu.dk>
+Nick Papior <nickpapior@gmail.com> <zerothi@users.noreply.github.com>

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
+The parameter \fIbaseptr\fP is of type \fIvoid *\fP to allow passing any pointer object for this parameter. The provided argument should be a pointer to a pointer of arbitrary type (e.g., \fIvoid **\fP).
+
 .SH FORTRAN NOTES
 .ft R
 There is no portable FORTRAN 77 syntax for using MPI_Alloc_mem.

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 is thus erroneous 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

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 is thus erroneous 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
+

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

@@ -89,9 +89,9 @@ may allow the implementation to enable certain optimizations.
 .TP 1i
 accumulate_ordering
 By default, accumulate operations from one initiator to one target on
-the same window are strictly ordered.  If the info key
+the same window memory location are strictly ordered. If the info key
 accumulate_ordering is set to \fInone\fP, no ordering of accumulate
-operations guaranteed.  They key can also be a comma-separated list of
+operations guaranteed. They key can also be a comma-separated list of
 required orderings consisting of \fIrar\fP, \fIwar\fP, \fIraw\fP, and \fIwaw\fP for
 read-after-read, write-after-read, read-after-write, and
 write-after-write, respectively.  Looser ordering constraints are

ompi/mpi/man/man3/MPI_Win_create_dynamic.3in

@@ -53,34 +53,44 @@ 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 \fBMPI_Win_create_dynamic\fP requires the \fItarget_disp\fP argument for all RMA communication functions to be the actual address at the target.
+
 .sp
 The following info keys are supported:
 .ft R
 .TP 1i
 no_locks
 If set to \fItrue\fP, then the implementation may assume that the local
 window is never locked (by a call to MPI_Win_lock or
-MPI_Win_lock_all).  Setting this value if only active synchronization
+MPI_Win_lock_all). Setting this value if only active synchronization
 may allow the implementation to enable certain optimizations.
 .sp
 .TP 1i
 accumulate_ordering
 By default, accumulate operations from one initiator to one target on
-the same window are strictly ordered.  If the info key
+the same window memory location are strictly ordered. If the info key
 accumulate_ordering is set to \fInone\fP, no ordering of accumulate
-operations guaranteed.  They key can also be a comma-separated list of
+operations guaranteed. They key can also be a comma-separated list of
 required orderings consisting of \fIrar\fP, \fIwar\fP, \fIraw\fP, and \fIwaw\fP for
 read-after-read, write-after-read, read-after-write, and
-write-after-write, respectively.  Looser ordering constraints are
+write-after-write, respectively. Looser ordering constraints are
 likely to result in improved performance.
 .sp
 .TP 1i
 accumulate_ops
 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
+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 \fBMPI_NO_OP\fP. The default is \fIsame_op_no_op\fP.
+.sp
+
+.SH NOTES
+Since dynamically attaching memory to a window is a local operation, one has to communicate the actual address at the target using \fBMPI_Get_address\fP 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
+
 

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 local RMA calls have been issued before this fence. This assertion must be provided by all or no members of the group of the window. It may enable faster fence call by avoiding unnecessary synchronization.
+.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 local RMA calls will be issued after this fence. This assertion must be provided by all or no members of the group of the window. It may enable faster fence call by avoiding unnecessary synchronization.
+.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.

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 allocated in that call will 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
 

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 lock.
 .sp
-.ft
+
 .SH NOTES
 .ft R
 In a client/server environment in which clients connect to

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 lock.
 .sp
-.ft
+
 .SH NOTES
 .ft R
 In a client/server environment in which clients connect to