https://gcc.gnu.org/g:2e247252868310b5e6147985a2988348540dbc9e
commit r17-1837-g2e247252868310b5e6147985a2988348540dbc9e Author: Paul-Antoine Arras <[email protected]> Date: Wed Jun 24 18:46:29 2026 +0200 libgomp.texi: Document new GOMP entry points for OMPT observability libgomp/ChangeLog: * libgomp.texi (Implementing MASKED and MASTER construct): Update pseudocode; describe GOMP_has_masked_thread_num. (Implementing ATOMIC construct): Fix stale function names; note exclusivity to explicit atomic constructs. (Implementing BARRIER construct): Document GOMP_barrier_ext and GOMP_barrier_cancel_ext; describe the kind parameter. (Implementing REDUCTION clause): Document GOMP_reduction_start and GOMP_reduction_end. (Implementing FOR construct): Document GOMP_loop_static_worksharing and GOMP_distribute_static_worksharing. Diff: --- libgomp/libgomp.texi | 64 ++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 55 insertions(+), 9 deletions(-) diff --git a/libgomp/libgomp.texi b/libgomp/libgomp.texi index 05de63e4020c..cb08aa08e2c5 100644 --- a/libgomp/libgomp.texi +++ b/libgomp/libgomp.texi @@ -8023,10 +8023,18 @@ presented by libgomp. Only maintainers should need them. @section Implementing MASKED and MASTER construct @smallexample -if (omp_get_thread_num () == thread_num) +if (GOMP_has_masked_thread_num(thread_num)) block @end smallexample +@code{GOMP_has_masked_thread_num} encapsulates the following check, so that OMPT +can distinguish the compiler-generated code from user-level thread-number +queries: + +@smallexample +omp_get_thread_num() == @var{thread_num} +@end + Hereby, @var{thread_num} has the value of the argument to the @code{filter} clause or zero if not specified. @@ -8070,13 +8078,17 @@ The target should implement the @code{__sync} builtins. Failing that we could add @smallexample - void GOMP_atomic_enter (void) - void GOMP_atomic_exit (void) + void GOMP_atomic_start (void) + void GOMP_atomic_end (void) @end smallexample which reuses the regular lock code, but with yet another lock object private to the library. +Those two functions are used exclusively for explicit @code{atomic} constructs; +reductions use @code{GOMP_reduction_start} and @code{GOMP_reduction_end} instead +(see @ref{Implementing REDUCTION clause}). + @node Implementing FLUSH construct @@ -8090,9 +8102,20 @@ Expands to the @code{__sync_synchronize} builtin. @section Implementing BARRIER construct @smallexample - void GOMP_barrier (void) + void GOMP_barrier_ext (int kind) + void GOMP_barrier_cancel_ext (int kind) @end smallexample +@var{kind} should be @code{GOMP_BARRIER_EXPLICIT}. Other values are for implicit +barriers resulting from parallel or work-sharing constructs. + +@code{GOMP_barrier} and @code{GOMP_barrier_cancel} are kept for backward +compatibility but new code only calls the @code{_ext} variants. + +@code{GOMP_barrier_cancel_ext} should be used when the barrier happens within +a cancellable construct. + + @node Implementing THREADPRIVATE construct @section Implementing THREADPRIVATE construct @@ -8171,6 +8194,17 @@ thread's @var{team_id}. The thread stores its final value into the array, and after the barrier, the primary thread iterates over the array to collect the values. +In cases where an atomic update cannot be used (e.g. for a reduction involving +more than one scalar), a critical section is required. Dedicated entry points +are used rather than @code{GOMP_atomic_start} and @code{GOMP_atomic_end} so that +OMPT can distinguish reduction critical sections from user-level atomic +constructs. The section is bracketed by: + +@smallexample + void GOMP_reduction_start (void) + void GOMP_reduction_end (void) +@end smallexample + @node Implementing PARALLEL construct @section Implementing PARALLEL construct @@ -8281,11 +8315,23 @@ variables. So the expression should remain evaluable in the subfunction. We can also pull it into a local variable if we like, but since its supposed to remain unchanged, we can also not if we like. -If we have SCHEDULE(STATIC), and no ORDERED, then we ought to be -able to get away with no work-sharing context at all, since we can -simply perform the arithmetic directly in each thread to divide up -the iterations. Which would mean that we wouldn't need to call any -of these routines. +For @code{schedule(static)} without @code{ordered}, the compiler uses: + +@smallexample + _Complex int GOMP_loop_static_worksharing (void) +@end + +which returns the thread id in the real part and the thread count in the imaginary +part as a single value, avoiding separate @code{omp_get_thread_num} / +@code{omp_get_num_threads} calls that OMPT cannot distinguish from user queries. + +Similarly, for @code{distribute} constructs: + +@smallexample + _Complex int GOMP_distribute_static_worksharing (void) +@end + +returns the team id and team count. There are separate routines for handling loops with an ORDERED clause. Bookkeeping for that is non-trivial...
