diff mbox series

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

Message ID 20211012074637.GA304296@tucnak
State New
Headers show
Series [committed] openmp: Add documentation for omp_{get_max, set_num}_threads and omp_{s, g}et_teams_thread_limit | expand

Commit Message

Jakub Jelinek Oct. 12, 2021, 7:46 a.m. UTC
Hi!

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.

Bootstrapped/regtested on x86_64-linux and i686-linux, committed to trunk.

We still have a lot of APIs undocumented though:
for i in `sed -n 's,^\t\(omp_.*[^_]\);.*$,\1,p' libgomp.map | sort -u`; do grep -q $i:: libgomp.texi || echo $i; done
omp_aligned_alloc
omp_aligned_calloc
omp_alloc
omp_calloc
omp_capture_affinity
omp_destroy_allocator
omp_display_affinity
omp_display_env
omp_free
omp_get_affinity_format
omp_get_default_allocator
omp_get_num_places
omp_get_partition_num_places
omp_get_partition_place_nums
omp_get_place_num
omp_get_place_num_procs
omp_get_place_proc_ids
omp_init_allocator
omp_pause_resource
omp_pause_resource_all
omp_realloc
omp_set_affinity_format
omp_set_default_allocator
omp_target_alloc
omp_target_associate_ptr
omp_target_disassociate_ptr
omp_target_free
omp_target_is_present
omp_target_memcpy
omp_target_memcpy_rect

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.


	Jakub
diff mbox series

Patch

--- libgomp/libgomp.texi.jj	2021-10-11 17:40:13.339012427 +0200
+++ libgomp/libgomp.texi	2021-10-11 19:51:08.012941074 +0200
@@ -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 allowe
 @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 a
 
 
 
+@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
 
 
 
+@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 exten
 * 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 d
 
 
 
+@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
@@ -1997,6 +2131,26 @@  If undefined, then the program will beha
 @end table
 
 
+
+@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