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/determines/
+@node omp_calloc
+@subsection @code{omp_calloc} -- Allocate nullified memory with an allocator
+@table @asis
+@item @emph{Description}:
+Allocate zero-initialized 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
"allocators is" problem, again.
+@var{def-allocator-var} ICV is used. The to-be allocated memory is for an
+array with @var{nmemb} elements, each having a size of @var{size} bytes. Both
+@var{nmemb} and @var{size} must be nonnegative numbers; if either of them is
+zero, @code{omp_calloc} will return a null pointer. If successful, a pointer
to
s/will return/returns/
+the zero-initialized allocated memory is returned, otherwise the
@code{fallback}
+trait of the allocator determines the behavior.
+
+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}.
Same problems here as with similar text above.
+@node omp_aligned_calloc
+@subsection @code{omp_aligned_calloc} -- Allocate aligned nullified memory
with an allocator
+@table @asis
+@item @emph{Description}:
+Allocate zero-initialized 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
Same issue with "allocators is".
+@var{def-allocator-var} ICV is used. The to-be allocated memory is for an
+array with @var{nmemb} elements, each having a size of @var{size} bytes. Both
+@var{nmemb} and @var{size} must be nonnegative numbers; if either of them is
+zero, @code{omp_aligned_calloc} will return a null pointer. @var{alignment}
s/will return/returns/
+must be a positive power of two and @var{size} must be a multiple of the
+alignment; the alignment will be at least the maximal value required by
Same issue with "the alignment will be".
+@code{alignment} trait of the allocator and the value of the passed
+@var{alignment} argument. If successful, a pointer to the zero-initialized
+allocated memory is returned, otherwise the @code{fallback} trait of the
+allocator determines the behavior.
+
+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}.
Same issues here as previously noted.
+The @var{size} must be a nonnegative number denoting the number of bytes to be
+allocated; if @var{size} is zero, @code{omp_realloc} will return free the
s/will return free/frees/ (I think?)
+memory and return a null pointer. When @var{size} is nonzero: if successful,
s/return/returns/
s/: if successful/ and the operation is successful
+a pointer to the allocated memory is returned, otherwise the @code{fallback}
+trait of the allocator determines the behavior.
+
+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{free_allocator} and @var{allocator} arguments may only be a constant
+expression with the value of one of the predefined allocators and may not be
+@code{omp_null_allocator}.
Same issues with this text as noted above.
+
+Memory allocated by @code{omp_realloc} must be freed using @code{omp_free}.
+Calling @code{omp_free} invokes undefined behavior if the memory
+was already deallocated or when the used allocator has already been destroyed.
s/omp_free/omp_realloc/ ??? (You already covered the undefined behavior of
omp_free in the section for that function.)
+
+@item @emph{C}:
+@multitable @columnfractions .20 .80
+@item @emph{Prototype}: @tab @code{void* omp_realloc(void *ptr, size_t size,}
+@item @tab @code{ omp_allocator_handle_t allocator,}
+@item @tab @code{ omp_allocator_handle_t free_allocator)}
+@end multitable
+
+@item @emph{C++}:
+@multitable @columnfractions .20 .80
+@item @emph{Prototype}: @tab @code{void* omp_realloc(void *ptr, size_t size,}
+@item @tab @code{ omp_allocator_handle_t
allocator=omp_null_allocator,}
+@item @tab @code{ omp_allocator_handle_t
free_allocator=omp_null_allocator)}
+@end multitable
+
+@item @emph{Fortran}:
+@multitable @columnfractions .20 .80
+@item @emph{Interface}: @tab @code{type(c_ptr) function omp_realloc(ptr, size,
allocator, free_allocator) bind(C)}
+@item @tab @code{use, intrinsic :: iso_c_binding, only :
c_ptr, c_size_t}
+@item @tab @code{type(C_ptr), value :: ptr}
+@item @tab @code{integer (c_size_t), value :: size}
+@item @tab @code{integer (omp_allocator_handle_kind), value
:: allocator, free_allocator}
+@end multitable
+
+@item @emph{See also}:
+@ref{OMP_ALLOCATOR}, @ref{Memory allocation}, @ref{omp_set_default_allocator},
+@ref{omp_free}, @ref{omp_init_allocator}
+
+@item @emph{Reference}:
+@uref{https://www.openmp.org, OpenMP specification v5.0}, Section 3.7.9
+@end table
+
+
+
@c @node Tool Control Routine
@c
@c FIXME
@@ -2591,7 +2922,7 @@ variable is not set.
* OMP_PLACES:: Specifies on which CPUs the threads should be
placed
* OMP_STACKSIZE:: Set default thread stack size
* OMP_SCHEDULE:: How threads are scheduled
-* OMP_TARGET_OFFLOAD:: Controls offloading behaviour
+* OMP_TARGET_OFFLOAD:: Controls offloading behavior
* OMP_TEAMS_THREAD_LIMIT:: Set the maximum number of threads imposed by teams
* OMP_THREAD_LIMIT:: Set the maximum number of threads
* OMP_WAIT_POLICY:: How waiting threads are handled
@@ -3121,14 +3452,14 @@ dynamic scheduling and a chunk size of 1 is used.
@node OMP_TARGET_OFFLOAD
-@section @env{OMP_TARGET_OFFLOAD} -- Controls offloading behaviour
+@section @env{OMP_TARGET_OFFLOAD} -- Controls offloading behavior
@cindex Environment Variable
@cindex Implementation specific setting
@table @asis
@item @emph{ICV:} @var{target-offload-var}
@item @emph{Scope:} global
@item @emph{Description}:
-Specifies the behaviour with regard to offloading code to a device. This
+Specifies the behavior with regard to offloading code to a device. This
variable can be set to one of three values - @code{MANDATORY}, @code{DISABLED}
or @code{DEFAULT}.
@@ -5282,6 +5613,27 @@ on more architectures, GCC currently does not match any @code{arch} or
@node Memory allocation
@section Memory allocation
+The description below applies to:
+
+@itemize
+@item Explicit use of the OpenMP API routines, see
+ @ref{Memory Management Routines}.
+@item The @code{allocate} clause, except when the @code{allocator} modifier is
a
+ constant expression with value @code{omp_default_mem_alloc} and no
+ @code{align} modifier has been specified. (In that case, the normal
+ @code{malloc} allocation is used.)
+@item Using the @code{allocate} directive for automatic/stack variables, except
+ when the @code{allocator} clause is a constant expression with value
+ @code{omp_default_mem_alloc} and no @code{align} clause has been
+ specified. (In that case, the normal allocation is used: stack allocation
+ and, sometimes for Fortran, also @code{malloc} [depending on flags such
as
+ @option{-fstack-arrays}].)
I don't think we use square brackets like this in other GCC documentation. I
think you could just make this less contorted, like:
(In that case, stack allocation is used, except Fortran may also use
@code{malloc} allocation depending on flags such as @option{-fstack-arrays}.)
+@item Using the @code{allocate} directive for variable in static memory is
s/variable/variables/
+ currently not supported (compile time error).
s/compile time error/compile-time error/
+@item Using the @code{allocators} directive for Fortran pointers and
+ allocatables is currently not supported (compile time error).
Same here.
I didn't check the function prototypes for either technical correctness or
consistent formatting with the rest of this document. If you're happy with how
they look, that's fine with me.
-Sandra
