On 1/14/24 07:26, Tobias Burnus wrote:
This documents two more OpenMP (5.0) routines, omp_pause_resource and
omp_pause_resource_all.
Comments, remarks, suggestions - to the patch or the documentation in general?
I have some minor nits about typos and copy-editing. I assume the formatting
of the interface syntax
is consistent with how it's done elsewhere in the manual.
+@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 ressouces on a device
+* omp_pause_resource_all:: Release OpenMP ressouces on all devices
s/ressouces/resources/g (there are more instances below)
+@end menu
+
+
+
+@node omp_pause_resource
+@subsection @code{omp_pause_resource} -- Release OpenMP ressouces on a device
+@table @asis
+@item @emph{Description}:
+Free resources used by OpenMP programm and runtime library on and for the
s/OpenMP programm/an OpenMP program/g (same mistake below)
+device specified by @var{device_num}; on success, zero is returned and non-zero
+otherwise.
+
+The value of @var{device_num} must be valid device number. The effect when
s/valid device number/a valid device number/
+invoked from within a @code{target} region is unspecified.
+
+@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 ressouces on all
devices
+@table @asis
+@item @emph{Description}:
+Free resources used by OpenMP programm and runtime library on all devices,
including
+the host. On success, zero is returned and non-zero otherwise.
+
+The effect when invoked from within a @code{target} region is unspecified.
+
+@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{omp_pause_resource}
+
+@item @emph{Reference}:
+@uref{https://www.openmp.org, OpenMP specification v5.0}, Section 3.2.44.
+@end table
+
+
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. I
understand this is in the OpenMP spec but if you're going to make users read
the spec anyway I wonder what the purpose of the GCC documentation is. :-S 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.
-Sandra
