Re: [Patch] libgomp.texi: Note to 'Memory allocation' sect and missing mem-memory routines
On 10/12/23 04:53, Tobias Burnus wrote:
libgomp.texi: Note to 'Memory allocation' sect and missing mem-memory routines
This commit completes the documentation of the OpenMP memory-management
routines, except for the unimplemented TR11 additions. It also makes clear
in the 'Memory allocation' section of the 'OpenMP-Implementation Specifics'
chapter under which condition OpenMP managed memory/allocators are used.
libgomp/ChangeLog:
* libgomp.texi: Fix some typos.
(Memory Management Routines): Document remaining 5.x routines.
(Memory allocation): Make clear when the section applies.
libgomp/libgomp.texi | 382 +--
1 file changed, 367 insertions(+), 15 deletions(-)
diff --git a/libgomp/libgomp.texi b/libgomp/libgomp.texi
index 0d965f96d48..3fc9c7dea23 100644
--- a/libgomp/libgomp.texi
+++ b/libgomp/libgomp.texi
@@ -1917,7 +1917,7 @@ is not supported.
@item @emph{Description}:
If the device number is refers to the initial device or to a device with
s/is refers/refers/
memory accessible from the host (shared memory), the @code{omp_get_mapped_ptr}
-routines returnes the value of the passed @var{ptr}. Otherwise, if associated
+routines returns the value of the passed @var{ptr}. Otherwise, if associated
storage to the passed host pointer @var{ptr} exists on device associated with
s/on device/on the device/ (or maybe /on a device/?)
+@node omp_alloc
+@subsection @code{omp_alloc} -- Memory allocation with an allocator
+@table @asis
+@item @emph{Description}:
+Allocate memory with the specified allocator, which can either be a predefined
+allocator, an allocator handle or @code{omp_null_allocator}. If the allocators
+is @code{omp_null_allocator}, the allocator specified by the
Minimally, s/allocators is/allocator is/, or maybe something like /allocator
argument is/, and/or add appropriate markup on allocator here to indicate that
it is an argument.
+@var{def-allocator-var} ICV is used. @var{size} must be a nonnegative number
+denoting the number of bytes to be allocated; if @var{size} is zero,
+@code{omp_alloc} will return a null pointer. If successful, a pointer to the
s/will return/returns/
+allocated memory is returned, otherwise the @code{fallback} trait of the
+allocator determines the behavior. The content of the allocated memory is
+unspecified.
+
+In @code{target} regions, either the @code{dynamic_allocators} clause must
+appear on a @code{requires} directive in the same compilation unit -- or the
s/ -- or/, or/
+@var{allocator} argument may only be a constant expression with the value of
s/may only be/must be/
+@node omp_aligned_alloc
+@subsection @code{omp_aligned_alloc} -- Memory allocation with an allocator
and alignment
+@table @asis
+@item @emph{Description}:
+Allocate memory with the specified allocator, which can either be a predefined
+allocator, an allocator handle or @code{omp_null_allocator}. If the allocators
+is @code{omp_null_allocator}, the allocator specified by the
Ditto above comments re "allocators is".
+@var{def-allocator-var} ICV is used. @var{alignment} must be a positive power
+of two and @var{size} must be a nonnegative number that is a multiple of the
+alignment and denotes the number of bytes to be allocated; if @var{size} is
+zero, @code{omp_aligned_alloc} will return a null pointer. The alignment will
+be at least the maximal value required by @code{alignment} trait of the
s/will return/return/
"The alignment will be" needs to be rewritten to avoid future tense too, but
I'm not sure what you're trying to say here. Is this a requirement on the
alignment argument or a statement about the actual alignment of the allocated
memory?
+allocator and the value of the passed @var{alignment} argument. If
successful,
+a pointer to the allocated memory is returned, otherwise the @code{fallback}
+trait of the allocator determines the behavior. The content of the allocated
+memory is unspecified.
+
+In @code{target} regions, either the @code{dynamic_allocators} clause must
+appear on a @code{requires} directive in the same compilation unit -- or the
+@var{allocator} argument may only be a constant expression with the value of
+one of the predefined allocators and may not be @code{omp_null_allocator}.
Ditto above comments re using comma and "must".
+@node omp_free
+@subsection @code{omp_free} -- Freeing memory allocated with OpenMP routines
+@table @asis
+@item @emph{Description}:
+The @code{omp_free} routine deallocates memory previously allocated by an
+OpenMP memory-management routine. The @var{ptr} argument must point to such
+memory or be a null pointer; if it is a null pointer, no operation is
+performed. If specified, the @var{allocator} argument must be either the
+memory allocator that was used for the allocation or @code{omp_null_allocator};
+if it is @code{omp_null_allocator}, the implementation will determine the value
s/will determine/dete
[Patch] libgomp.texi: Note to 'Memory allocation' sect and missing mem-memory routines
This patch improves the documentation by completing the description of
the remaining so far undocumented OpenMP Memory-Management Routines
(except for the two function added in TR11, which are also unimplmeneted).
Current online version:
https://gcc.gnu.org/onlinedocs/libgomp/Memory-Management-Routines.html
And the patch makes clearer when the OpenMP allocators are actually used;
besides the obvious use via the routines above, it happens when using the
'allocate' directive/clause and the 'allocators' clause. The new note
is added to the beginning of the section
https://gcc.gnu.org/onlinedocs/libgomp/Memory-allocation.html
The new note mostly applies, except that only C supports 'omp allocate';
Fortran has a patch pending a comment by Jakub and for C++ I still need
to complete my daft patch.
I also fixed some typos (albeit 'behaviour' is not really a typo), removed
some 'kind=' for local consistency and to make especially the 'info' output
cleaner.
Comment, remarks, suggestions - before (or after) I apply it?
Tobias
PS: Also general comments and suggestions to the documentation are welcome.
The wording (current patch and current documentation) can surely be improved.
That documentation is missing - e.g. for several routines - is a known
problem.
If someone feels bored, besides reviewing libgomp.texi (6282 LoC),
https://gcc.gnu.org/projects/gomp/ (1281 LoC) and
https://gcc.gnu.org/wiki/Offloading
(+ openmp + OpenACC) can surely be improved :-)
-
Siemens Electronic Design Automation GmbH; Anschrift: Arnulfstraße 201, 80634
München; Gesellschaft mit beschränkter Haftung; Geschäftsführer: Thomas
Heurung, Frank Thürauf; Sitz der Gesellschaft: München; Registergericht
München, HRB 106955
libgomp.texi: Note to 'Memory allocation' sect and missing mem-memory routines
This commit completes the documentation of the OpenMP memory-management
routines, except for the unimplemented TR11 additions. It also makes clear
in the 'Memory allocation' section of the 'OpenMP-Implementation Specifics'
chapter under which condition OpenMP managed memory/allocators are used.
libgomp/ChangeLog:
* libgomp.texi: Fix some typos.
(Memory Management Routines): Document remaining 5.x routines.
(Memory allocation): Make clear when the section applies.
libgomp/libgomp.texi | 382 +--
1 file changed, 367 insertions(+), 15 deletions(-)
diff --git a/libgomp/libgomp.texi b/libgomp/libgomp.texi
index 0d965f96d48..3fc9c7dea23 100644
--- a/libgomp/libgomp.texi
+++ b/libgomp/libgomp.texi
@@ -1917,7 +1917,7 @@ is not supported.
@item @emph{Description}:
If the device number is refers to the initial device or to a device with
memory accessible from the host (shared memory), the @code{omp_get_mapped_ptr}
-routines returnes the value of the passed @var{ptr}. Otherwise, if associated
+routines returns the value of the passed @var{ptr}. Otherwise, if associated
storage to the passed host pointer @var{ptr} exists on device associated with
@var{device_num}, it returns that pointer. In all other cases and in cases of
an error, a null pointer is returned.
@@ -2397,12 +2397,12 @@ They have C linkage and do not throw exceptions.
* omp_destroy_allocator:: Destroy an allocator
* omp_set_default_allocator:: Set the default allocator
* omp_get_default_allocator:: Get the default allocator
-@c * omp_alloc::
-@c * omp_aligned_alloc::
-@c * omp_free::
-@c * omp_calloc::
-@c * omp_aligned_calloc::
-@c * omp_realloc::
+* omp_alloc:: Memory allocation with an allocator
+* omp_aligned_alloc:: Memory allocation with an allocator and alignment
+* omp_free:: Freeing memory allocated with OpenMP routines
+* omp_calloc:: Allocate nullified memory with an allocator
+* omp_aligned_calloc:: Allocate nullified aligned memory with an allocator
+* omp_realloc:: Reallocate memory allocated with OpenMP routines
@c * omp_get_memspace_num_resources:: /TR11
@c * omp_get_submemspace:: /TR11
@end menu
@@ -2434,8 +2434,8 @@ may be used as trait value to specify that the default value should be used.
@item @emph{Fortran}:
@multitable @columnfractions .20 .80
@item @emph{Interface}: @tab @code{function omp_init_allocator(memspace, ntraits, traits)}
-@item @tab @code{integer (kind=omp_allocator_handle_kind) :: omp_init_allocator}
-@item @tab @code{integer (kind=omp_memspace_handle_kind), intent(in) :: memspace}
+@item @tab @code{integer (omp_allocator_handle_kind) :: omp_init_allocator}
+@item @tab @code{integer (omp_memspace_handle_kind), intent(in) :: memspace}
@item @tab @code{integer, intent(in) :: ntraits}
@item @tab @code{type (omp_alloctrait), intent(in) :: traits(*)}
@end multitable
@@ -2467,7 +2467,7 @@ routine is permitted but will have no effect.
@item @emph{Fortran}:
@multitable @columnfractions .20 .80
@item @emph{Interface}: @tab @code{subroutine omp_destroy
