Docs: Document omp::allocator::* and ompx::allocator::* allocators.
Checks
| Context |
Check |
Description |
| linaro-tcwg-bot/tcwg_gcc_build--master-arm |
success
|
Build passed
|
| linaro-tcwg-bot/tcwg_gcc_check--master-arm |
success
|
Test passed
|
Commit Message
Here is a follow up patch for documentation of the omp.h allocators,
I'm not super happy with it but I wanted to get eyes on it before I go
to sleep tonight.
I want the table in there somewhere but I'm not confident that where I
put it was the right place.
Alex
Comments
On 4/15/25 19:11, Alex wrote:
> Here is a follow up patch for documentation of the omp.h allocators,
> I'm not super happy with it but I wanted to get eyes on it before I go
> to sleep tonight.
> > From c8cef447baf16743f7bf0d887d3fd09108d3a607 Mon Sep 17 00:00:00 2001
> From: waffl3x <waffl3x@baylibre.com>
> Date: Tue, 15 Apr 2025 18:50:30 -0600
> Subject: [PATCH] Docs: Document omp::allocator::* and ompx::allocator::*
> allocators.
>
> libgomp/ChangeLog:
>
> * libgomp.texi: Add omp::allocator::* table.
> Add example using omp::allocator::cgroup.
When writing ChangeLogs for .texi files, I recommend using the
associated @node name to identify the part being changed, like
* libgomp.texi (OMP_ALLOCATOR): blah blah...
> @@ -3950,6 +3950,24 @@ value.
> @item ompx_gnu_pinned_mem_alloc @tab omp_default_mem_space (GNU extension)
> @end multitable
>
> +Each predefined allocator, including omp_null_allocator, also corresponds to an
You need to put @code{} markup around all literal identifiers, both in
the running text and in the tables.
> +allocator template. This allows C++ standard library containers to use OpenMP
> +allocation routines.
> +
> +@multitable @columnfractions .45 .45
> +@headitem Predefined allocators @tab Associated allocator template
> +@item omp_null_allocator @tab omp::allocator::null_allocator
> +@item omp_default_mem_alloc @tab omp::allocator::default_mem
> +@item omp_large_cap_mem_alloc @tab omp::allocator::large_cap_mem
> +@item omp_const_mem_alloc @tab omp::allocator::const_mem
> +@item omp_high_bw_mem_alloc @tab omp::allocator::high_bw_mem
> +@item omp_low_lat_mem_alloc @tab omp::allocator::low_lat_mem
> +@item omp_cgroup_mem_alloc @tab omp::allocator::cgroup_mem
> +@item omp_pteam_mem_alloc @tab omp::allocator::pteam_mem
> +@item omp_thread_mem_alloc @tab omp::allocator::thread_mem
> +@item ompx_gnu_pinned_mem_alloc @tab ompx::allocator::gnu_pinned_mem
> +@end multitable
> +
> The predefined allocators use the default values for the traits,
> as listed below. Except that the last three allocators have the
> @code{access} trait set to @code{cgroup}, @code{pteam}, and
> @@ -6758,6 +6776,14 @@ see @ref{OMP_ALLOCATOR}. Predefined allocators without an associated memory
> space use the @code{omp_default_mem_space} memory space. See additionally
> @ref{Offload-Target Specifics}.
>
> +Each predefined allocator, including omp_null_allocator, has a corresponding
> +allocator class template that meet the C++ allocator completeness requirements.
s/meet/meets/
> +These are located in the omp::allocator namespace, and the ompx::allocator
> +namespace for gnu extensions.
s/gnu/GNU/
> +@smallexample
> +std::vector<int, omp::allocator::cgroup_mem<int>> vec;
> +@end smallexample
> +
> For the memory spaces, the following applies:
> @itemize
> @item @code{omp_default_mem_space} is supported
> --
> 2.47.1
>
> I want the table in there somewhere but I'm not confident that where I
> put it was the right place.
It seems reasonable to me.
-Sandra
Alex wrote:
> Here is a follow up patch for documentation of the omp.h allocators,
> I'm not super happy with it but I wanted to get eyes on it before I go
> to sleep tonight.
>
> I want the table in there somewhere but I'm not confident that where I
> put it was the right place.
I think having the C++ template classes listed under the OMP_ALLOCATOR
environment variable feels odd.
I think it is best to move the two tables, the existing one under
"OMP_ALLOCATOR – Set the default allocator",
https://https://gcc.gnu.org/onlinedocs/libgomp/OMP_005fALLOCATOR.html
and the one you added to "11.3 Memory allocation",
https://gcc.gnu.org/onlinedocs/libgomp/Memory-allocation.html
In OMP_ALLOCATOR, I think a sentence such as:
"For the list of available predefined allocators and memory spaces, see
@ref{Memory allocation}."
And then in "Memory Allocator" changing:
"For the available predefined allocators and, as applicable, their
associated predefined memory spaces and for the available traits and
their default values, see "OMP_ALLOCATOR – Set the default allocator."
Predefined allocators without an associated memory space use the
omp_default_mem_space memory space. See additionally Offload-Target
Specifics."
to something like:
"For the available traits and their default values, see ..."
Or we move the traits as well - and then refer to the available traits
and their default in OMP_ALLOCATOR, which seems to be even a bit
cleaner.
And I would add a first bullet point (before the "OpenMP API routines") to
@item The environment variable @ref{OMP_ALLOCATOR}.
(which expands to "OMP_ALLOCATOR" or "OMP_ALLOCATOR – Set the default
allocator") - which seems to be missing from the list.
> These are located in the omp::allocator namespace, […] extensions.
>
> std::vector<int, omp::allocator::cgroup_mem<int>> vec;
I think an intro/lead to the example is missing - like: "For instance"
or "The allocator templates can be used with allocator-aware containers
like".
Otherwise, the example comes a bit sudden and without context.
Except for some additional @code and the other comments by Sandra,
changes LGTM.
Thanks,
Tobias
From c8cef447baf16743f7bf0d887d3fd09108d3a607 Mon Sep 17 00:00:00 2001
From: waffl3x <waffl3x@baylibre.com>
Date: Tue, 15 Apr 2025 18:50:30 -0600
Subject: [PATCH] Docs: Document omp::allocator::* and ompx::allocator::*
allocators.
libgomp/ChangeLog:
* libgomp.texi: Add omp::allocator::* table.
Add example using omp::allocator::cgroup.
Signed-off-by: waffl3x <waffl3x@baylibre.com>
---
libgomp/libgomp.texi | 26 ++++++++++++++++++++++++++
1 file changed, 26 insertions(+)
@@ -3950,6 +3950,24 @@ value.
@item ompx_gnu_pinned_mem_alloc @tab omp_default_mem_space (GNU extension)
@end multitable
+Each predefined allocator, including omp_null_allocator, also corresponds to an
+allocator template. This allows C++ standard library containers to use OpenMP
+allocation routines.
+
+@multitable @columnfractions .45 .45
+@headitem Predefined allocators @tab Associated allocator template
+@item omp_null_allocator @tab omp::allocator::null_allocator
+@item omp_default_mem_alloc @tab omp::allocator::default_mem
+@item omp_large_cap_mem_alloc @tab omp::allocator::large_cap_mem
+@item omp_const_mem_alloc @tab omp::allocator::const_mem
+@item omp_high_bw_mem_alloc @tab omp::allocator::high_bw_mem
+@item omp_low_lat_mem_alloc @tab omp::allocator::low_lat_mem
+@item omp_cgroup_mem_alloc @tab omp::allocator::cgroup_mem
+@item omp_pteam_mem_alloc @tab omp::allocator::pteam_mem
+@item omp_thread_mem_alloc @tab omp::allocator::thread_mem
+@item ompx_gnu_pinned_mem_alloc @tab ompx::allocator::gnu_pinned_mem
+@end multitable
+
The predefined allocators use the default values for the traits,
as listed below. Except that the last three allocators have the
@code{access} trait set to @code{cgroup}, @code{pteam}, and
@@ -6758,6 +6776,14 @@ see @ref{OMP_ALLOCATOR}. Predefined allocators without an associated memory
space use the @code{omp_default_mem_space} memory space. See additionally
@ref{Offload-Target Specifics}.
+Each predefined allocator, including omp_null_allocator, has a corresponding
+allocator class template that meet the C++ allocator completeness requirements.
+These are located in the omp::allocator namespace, and the ompx::allocator
+namespace for gnu extensions.
+@smallexample
+std::vector<int, omp::allocator::cgroup_mem<int>> vec;
+@end smallexample
+
For the memory spaces, the following applies:
@itemize
@item @code{omp_default_mem_space} is supported
--
2.47.1