[gcc/devel/omp/gcc-16] libgomp.texi: Document new GOMP entry points for OMPT observability

https://gcc.gnu.org/g:90707038b95cc949ac9f854ce2420164046eff4f

commit 90707038b95cc949ac9f854ce2420164046eff4f
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.
    
    (cherry picked from commit 2e247252868310b5e6147985a2988348540dbc9e)

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...