openmp: Add documentation for omp_{get_max, set_num}_threads and omp_{s, g}et_teams_thread_limit

This patch adds documentation for these new OpenMP 5.1 APIs as well as
two new environment variables - OMP_NUM_TEAMS and OMP_TEAMS_THREAD_LIMIT.

2021-10-12  Jakub Jelinek  <jakub@redhat.com>

	* libgomp.texi (omp_get_max_teams, omp_get_teams_thread_limit,
	omp_set_num_teams, omp_set_teams_thread_limit, OMP_NUM_TEAMS,
	OMP_TEAMS_THREAD_LIMIT): Document.

1 files changed, 154 insertions, 0 deletions

diff --git a/libgomp/libgomp.texi b/libgomp/libgomp.texi
index b1bbe8efb3b..bdd7e3ac442 100644
--- a/libgomp/libgomp.texi
+++ b/libgomp/libgomp.texi
@@ -369,6 +369,7 @@ linkage, and do not throw exceptions.
 * omp_get_level::               Number of parallel regions
 * omp_get_max_active_levels::   Current maximum number of active regions
 * omp_get_max_task_priority::   Maximum task priority value that can be set
+* omp_get_max_teams::           Maximum number of teams for teams region
 * omp_get_max_threads::         Maximum number of threads of parallel region
 * omp_get_nested::              Nested parallel regions
 * omp_get_num_devices::         Number of target devices
@@ -380,6 +381,7 @@ linkage, and do not throw exceptions.
 * omp_get_supported_active_levels:: Maximum number of active regions supported
 * omp_get_team_num::            Get team number
 * omp_get_team_size::           Number of threads in a team
+* omp_get_teams_thread_limit::  Maximum number of threads imposed by teams
 * omp_get_thread_limit::        Maximum number of threads
 * omp_get_thread_num::          Current thread ID
 * omp_in_parallel::             Whether a parallel region is active
@@ -389,8 +391,10 @@ linkage, and do not throw exceptions.
 * omp_set_dynamic::             Enable/disable dynamic teams
 * omp_set_max_active_levels::   Limits the number of active parallel regions
 * omp_set_nested::              Enable/disable nested parallel regions
+* omp_set_num_teams::           Set upper teams limit for teams region
 * omp_set_num_threads::         Set upper team size limit
 * omp_set_schedule::            Set the runtime scheduling method
+* omp_set_teams_thread_limit::  Set upper thread limit for teams construct
 
 Initialize, set, test, unset and destroy simple and nested locks.
 
@@ -684,6 +688,32 @@ This function obtains the maximum allowed priority number for tasks.
 @end table
 
 
+@node omp_get_max_teams
+@section @code{omp_get_max_teams} -- Maximum number of teams of teams region
+@table @asis
+@item @emph{Description}:
+Return the maximum number of teams used for the teams region
+that does not use the clause @code{num_teams}.
+
+@item @emph{C/C++}:
+@multitable @columnfractions .20 .80
+@item @emph{Prototype}: @tab @code{int omp_get_max_teams(void);}
+@end multitable
+
+@item @emph{Fortran}:
+@multitable @columnfractions .20 .80
+@item @emph{Interface}: @tab @code{integer function omp_get_max_teams()}
+@end multitable
+
+@item @emph{See also}:
+@ref{omp_set_num_teams}, @ref{omp_get_num_teams}
+
+@item @emph{Reference}:
+@uref{https://www.openmp.org, OpenMP specification v5.1}, Section 3.4.4.
+@end table
+
+
+
 @node omp_get_max_threads
 @section @code{omp_get_max_threads} -- Maximum number of threads of parallel region
 @table @asis
@@ -988,6 +1018,32 @@ to @code{omp_get_num_threads}.
 
 
 
+@node omp_get_teams_thread_limit
+@section @code{omp_get_teams_thread_limit} -- Maximum number of threads imposed by teams
+@table @asis
+@item @emph{Description}:
+Return the maximum number of threads that will be able to participate in
+each team created by a teams construct.
+
+@item @emph{C/C++}:
+@multitable @columnfractions .20 .80
+@item @emph{Prototype}: @tab @code{int omp_get_teams_thread_limit(void);}
+@end multitable
+
+@item @emph{Fortran}:
+@multitable @columnfractions .20 .80
+@item @emph{Interface}: @tab @code{integer function omp_get_teams_thread_limit()}
+@end multitable
+
+@item @emph{See also}:
+@ref{omp_set_teams_thread_limit}, @ref{OMP_TEAMS_THREAD_LIMIT}
+
+@item @emph{Reference}:
+@uref{https://www.openmp.org, OpenMP specification v5.1}, Section 3.4.6.
+@end table
+
+
+
 @node omp_get_thread_limit
 @section @code{omp_get_thread_limit} -- Maximum number of threads
 @table @asis
@@ -1232,6 +1288,34 @@ regions will set the maximum number of active nested regions to one.
 
 
 
+@node omp_set_num_teams
+@section @code{omp_set_num_teams} -- Set upper teams limit for teams construct
+@table @asis
+@item @emph{Description}:
+Specifies the upper bound for number of teams created by the teams construct
+which does not specify a @code{num_teams} clause.  The
+argument of @code{omp_set_num_teams} shall be a positive integer.
+
+@item @emph{C/C++}:
+@multitable @columnfractions .20 .80
+@item @emph{Prototype}: @tab @code{void omp_set_num_teams(int num_teams);}
+@end multitable
+
+@item @emph{Fortran}:
+@multitable @columnfractions .20 .80
+@item @emph{Interface}: @tab @code{subroutine omp_set_num_teams(num_teams)}
+@item                   @tab @code{integer, intent(in) :: num_teams}
+@end multitable
+
+@item @emph{See also}:
+@ref{OMP_NUM_TEAMS}, @ref{omp_get_num_teams}, @ref{omp_get_max_teams}
+
+@item @emph{Reference}:
+@uref{https://www.openmp.org, OpenMP specification v5.1}, Section 3.4.3.
+@end table
+
+
+
 @node omp_set_num_threads
 @section @code{omp_set_num_threads} -- Set upper team size limit
 @table @asis
@@ -1293,6 +1377,35 @@ For @code{omp_sched_auto} the @var{chunk_size} argument is ignored.
 
 
 
+@node omp_set_teams_thread_limit
+@section @code{omp_set_teams_thread_limit} -- Set upper thread limit for teams construct
+@table @asis
+@item @emph{Description}:
+Specifies the upper bound for number of threads that will be available
+for each team created by the teams construct which does not specify a
+@code{thread_limit} clause.  The argument of
+@code{omp_set_teams_thread_limit} shall be a positive integer.
+
+@item @emph{C/C++}:
+@multitable @columnfractions .20 .80
+@item @emph{Prototype}: @tab @code{void omp_set_teams_thread_limit(int thread_limit);}
+@end multitable
+
+@item @emph{Fortran}:
+@multitable @columnfractions .20 .80
+@item @emph{Interface}: @tab @code{subroutine omp_set_teams_thread_limit(thread_limit)}
+@item                   @tab @code{integer, intent(in) :: thread_limit}
+@end multitable
+
+@item @emph{See also}:
+@ref{OMP_TEAMS_THREAD_LIMIT}, @ref{omp_get_teams_thread_limit}, @ref{omp_get_thread_limit}
+
+@item @emph{Reference}:
+@uref{https://www.openmp.org, OpenMP specification v5.1}, Section 3.4.5.
+@end table
+
+
+
 @node omp_init_lock
 @section @code{omp_init_lock} -- Initialize simple lock
 @table @asis
@@ -1682,12 +1795,14 @@ beginning with @env{GOMP_} are GNU extensions.
 * OMP_MAX_ACTIVE_LEVELS::   Set the maximum number of nested parallel regions
 * OMP_MAX_TASK_PRIORITY::   Set the maximum task priority value
 * OMP_NESTED::              Nested parallel regions
+* OMP_NUM_TEAMS::           Specifies the number of teams to use by teams region
 * OMP_NUM_THREADS::         Specifies the number of threads to use
 * OMP_PROC_BIND::           Whether theads may be moved between CPUs
 * OMP_PLACES::              Specifies on which CPUs the theads should be placed
 * OMP_STACKSIZE::           Set default thread stack size
 * OMP_SCHEDULE::            How threads are scheduled
 * OMP_TARGET_OFFLOAD::      Controls offloading behaviour
+* 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
 * GOMP_CPU_AFFINITY::       Bind threads to specific CPUs
@@ -1840,6 +1955,25 @@ more than one item, otherwise they are disabled by default.
 
 
 
+@node OMP_NUM_TEAMS
+@section @env{OMP_NUM_TEAMS} -- Specifies the number of teams to use by teams region
+@cindex Environment Variable
+@table @asis
+@item @emph{Description}:
+Specifies the upper bound for number of teams to use in teams regions
+without explicit @code{num_teams} clause.  The value of this variable shall
+be a positive integer.  If undefined it defaults to 0 which means
+implementation defined upper bound.
+
+@item @emph{See also}:
+@ref{omp_set_num_teams}
+
+@item @emph{Reference}: 
+@uref{https://www.openmp.org, OpenMP specification v5.1}, Section 6.23
+@end table
+
+
+
 @node OMP_NUM_THREADS
 @section @env{OMP_NUM_THREADS} -- Specifies the number of threads to use
 @cindex Environment Variable
@@ -1998,6 +2132,26 @@ If undefined, then the program will behave as if @code{DEFAULT} was set.
 
 
 
+@node OMP_TEAMS_THREAD_LIMIT
+@section @env{OMP_TEAMS_THREAD_LIMIT} -- Set the maximum number of threads imposed by teams
+@cindex Environment Variable
+@table @asis
+@item @emph{Description}:
+Specifies an upper bound for the number of threads to use by each contention
+group created by a teams construct without explicit @code{thread_limit}
+clause.  The value of this variable shall be a positive integer.  If undefined,
+the value of 0 is used which stands for an implementation defined upper
+limit.
+
+@item @emph{See also}:
+@ref{OMP_THREAD_LIMIT}, @ref{omp_set_teams_thread_limit}
+
+@item @emph{Reference}: 
+@uref{https://www.openmp.org, OpenMP specification v5.1}, Section 6.24
+@end table
+
+
+
 @node OMP_THREAD_LIMIT
 @section @env{OMP_THREAD_LIMIT} -- Set the maximum number of threads
 @cindex Environment Variable