diff mbox series

libgomp.texi: Document omp_pause_resource{,_all}

Message ID 98216ca7-6a10-4342-b510-1f362127f619@net-b.de
State New
Headers show
Series libgomp.texi: Document omp_pause_resource{,_all} | expand

Commit Message

Tobias Burnus Jan. 14, 2024, 2:26 p.m. UTC 
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?

Tobias

PS: When looking at it, I found an issue in the spec with regards to a 
new constant (post TR12, hence, not added here) and the missing 
unspecified behavior when invoked from within a target region; that's 
now tracked as OpenMP spec issue #3793.

PPS: Still to be documented routines: omp_target_memcpy* and the 
places/affinity routines. (Plus OMPT, interop and TR11/TR12/... but 
those have to be implemented first.)

Comments

Sandra Loosemore Jan. 14, 2024, 4:52 p.m. UTC | #1 
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
diff mbox series

Patch

libgomp.texi: Document omp_pause_resource{,_all}

libgomp/ChangeLog:

	* libgomp.texi (Runtime Library Routines): Document
	omp_pause_resource and omp_pause_resource_all.

 libgomp/libgomp.texi | 82 +++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 71 insertions(+), 11 deletions(-)

diff --git a/libgomp/libgomp.texi b/libgomp/libgomp.texi
index 74d4ef34c43..4946dfe2c84 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,76 @@  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:: <fixme>
-@c * omp_pause_resource_all:: <fixme>
-@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 ressouces on a device
+* omp_pause_resource_all:: Release OpenMP ressouces on all devices
+@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
+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
+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
+
+
 
 @node Device Information Routines
 @section Device Information Routines