Hi Sandra, hi all,
Sandra Loosemore:
On 1/14/24 07:26, Tobias Burnus wrote:
I have some minor nits about typos and copy-editing.
Thanks. That's the downside of doing editing while being sleepy on a
train. Updated and extended version (documenting also omp_target_memcpy)
is attached. Warning: Still mostly done during a train ride.
I assume the formatting of the interface syntax
is consistent with how it's done elsewhere in the manual.
It should be consistent, but I think it eventually need some cleanup as
the indentation does not work for the continuation lines.
And I think some other improvements are needed, but that's a slow
step-by-step process.
* * *
Re the content, I see no documentation for omp_pause_resource_t or the
equivalent in Fortran, or any hint about what the kind argument is for.
There is actually some Fortran documentation at
https://gcc.gnu.org/onlinedocs/gfortran/OpenMP-Modules-OMP_005fLIB-and-OMP_005fLIB_005fKINDS.html
(gcc/fortran/intrinsic.texi).
But I concur that moving it to libgomp.texi and adding a C version makes
sense; see also PR110364 under "BTW" (2nd paragraph).
If it's to explain implementation-specific
features, then it should at least be documenting whether GCC supports
additional pause kinds as permitted by the spec.
It doesn't - and it lacks the OpenMP 6.0 addition (post-TR12) as well.
Tobiaslibgomp.texi: Document omp_pause_resource{,_all} and omp_target_memcpy*
libgomp/ChangeLog:
* libgomp.texi (Runtime Library Routines): Document
omp_pause_resource, omp_pause_resource_all and
omp_target_memcpy{,_rect}{,_async}.
libgomp/libgomp.texi | 329 ---
1 file changed, 314 insertions(+), 15 deletions(-)
diff --git a/libgomp/libgomp.texi b/libgomp/libgomp.texi
index 74d4ef34c43..d3adfd48545 100644
--- a/libgomp/libgomp.texi
+++ b/libgomp/libgomp.texi
@@ -561,7 +561,7 @@ specification in version 5.2.
* Thread Affinity Routines::
* Teams Region Routines::
* Tasking Routines::
-@c * Resource Relinquishing Routines::
+* Resource Relinquishing Routines::
* Device Information Routines::
* Device Memory Routines::
* Lock Routines::
@@ -1504,16 +1504,78 @@ and @code{false} represent their language-specific counterparts.
-@c @node Resource Relinquishing Routines
-@c @section Resource Relinquishing Routines
-@c
-@c Routines releasing resources used by the OpenMP runtime.
-@c They have C linkage and do not throw exceptions.
-@c
-@c @menu
-@c * omp_pause_resource::
-@c * omp_pause_resource_all::
-@c @end menu
+@node Resource Relinquishing Routines
+@section Resource Relinquishing Routines
+
+Routines releasing resources used by the OpenMP runtime.
+They have C linkage and do not throw exceptions.
+
+@menu
+* omp_pause_resource:: Release OpenMP resources on a device
+* omp_pause_resource_all:: Release OpenMP resources on all devices
+@end menu
+
+
+
+@node omp_pause_resource
+@subsection @code{omp_pause_resource} -- Release OpenMP resources on a device
+@table @asis
+@item @emph{Description}:
+Free resources used by the OpenMP program and the runtime library on and for the
+device specified by @var{device_num}; on success, zero is returned and non-zero
+otherwise.
+
+The value of @var{device_num} must be a conforming device number. The routine
+may not be called from within any explicit region and all explicit threads that
+do not bind to the implicit parallel region have finalized execution.
+
+@item @emph{C/C++}:
+@multitable @columnfractions .20 .80
+@item @emph{Prototype}: @tab @code{int omp_pause_resource(omp_pause_resource_t kind, int device_num);}
+@end multitable
+
+@item @emph{Fortran}:
+@multitable @columnfractions .20 .80
+@item @emph{Interface}: @tab @code{integer function omp_pause_resource(kind, device_num)}
+@item @tab @code{integer (kind=omp_pause_resource_kind) kind}
+@item @tab @code{integer device_num}
+@end multitable
+
+@item @emph{Reference}:
+@uref{https://www.openmp.org, OpenMP specification v5.0}, Section 3.2.43.
+@end table
+
+
+
+@node omp_pause_resource_all
+@subsection @code{omp_pause_resource_all} -- Release OpenMP resources on all devices
+@table @asis
+@item @emph{Description}:
+Free resources used by the OpenMP program and the runtime library on all devices,
+including the host. On success, zero is returned and non-zero otherwise.
+
+The routine may not be called from within any explicit region and all explicit
+threads that do not bind to the implicit parallel region have finalized execution.
+
+@item @emph{C/C++}:
+@multitable @columnfractions .20 .80
+@item @emph{Prototype}: @tab @code{int omp_pause_resource(omp_pause_resource_t kind);}
+@end multitable
+
+@item @emph{Fortran}:
+@multitable @columnfractions .20 .80
+@item @emph{Interface}: @tab @code{integer function omp_pause_resource(kind)}
+@item @tab @code{integer (kind=omp_pause_resource_kind) kind}
+@end multitable
+
+@item @emph{See also}:
+@ref{
