From patchwork Tue Oct 12 07:46:37 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jakub Jelinek X-Patchwork-Id: 46120 Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 774393858425 for ; Tue, 12 Oct 2021 07:47:16 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 774393858425 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gcc.gnu.org; s=default; t=1634024836; bh=R8WE8WfhJRuiz/OAMkJ8oaZ2Y2bdJhRDnizhcM++m04=; h=Date:To:Subject:List-Id:List-Unsubscribe:List-Archive:List-Post: List-Help:List-Subscribe:From:Reply-To:Cc:From; b=rC/U1CtsAAjoIpwb4wiFTDhCpnZrK8aL9j82j/1cBoVUwmWS+jJZzI396FAPnKG8s 9jeJA3cq0o6Xv20sxCPjpyb/TFHkoaCii09Ui+iCcb+C3xEC2tRQWMHMt/jW20vX13 jTSe5DrxVZzKHAIaigsP4UUOQ3/z+iV7NOhwGjso= X-Original-To: gcc-patches@gcc.gnu.org Delivered-To: gcc-patches@gcc.gnu.org Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by sourceware.org (Postfix) with ESMTP id 1F4A83858D3C for ; Tue, 12 Oct 2021 07:46:46 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 1F4A83858D3C Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-59-8eJNl9inPOmo0lP8pNatEw-1; Tue, 12 Oct 2021 03:46:42 -0400 X-MC-Unique: 8eJNl9inPOmo0lP8pNatEw-1 Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.phx2.redhat.com [10.5.11.23]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 7E64618125C3; Tue, 12 Oct 2021 07:46:41 +0000 (UTC) Received: from tucnak.zalov.cz (unknown [10.39.193.109]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 2A9B719723; Tue, 12 Oct 2021 07:46:41 +0000 (UTC) Received: from tucnak.zalov.cz (localhost [127.0.0.1]) by tucnak.zalov.cz (8.16.1/8.16.1) with ESMTPS id 19C7kcEM1077550 (version=TLSv1.3 cipher=TLS_AES_256_GCM_SHA384 bits=256 verify=NOT); Tue, 12 Oct 2021 09:46:38 +0200 Received: (from jakub@localhost) by tucnak.zalov.cz (8.16.1/8.16.1/Submit) id 19C7kbB21077548; Tue, 12 Oct 2021 09:46:37 +0200 Date: Tue, 12 Oct 2021 09:46:37 +0200 To: gcc-patches@gcc.gnu.org Subject: [committed] openmp: Add documentation for omp_{get_max, set_num}_threads and omp_{s, g}et_teams_thread_limit Message-ID: <20211012074637.GA304296@tucnak> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.84 on 10.5.11.23 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Disposition: inline X-Spam-Status: No, score=-5.5 required=5.0 tests=BAYES_00, DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, RCVD_IN_DNSWL_LOW, RCVD_IN_MSPIKE_H4, RCVD_IN_MSPIKE_WL, SPF_HELO_NONE, SPF_NONE, TXREP autolearn=ham autolearn_force=no version=3.4.4 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on server2.sourceware.org X-BeenThere: gcc-patches@gcc.gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gcc-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-Patchwork-Original-From: Jakub Jelinek via Gcc-patches From: Jakub Jelinek Reply-To: Jakub Jelinek Cc: Tobias Burnus Errors-To: gcc-patches-bounces+patchwork=sourceware.org@gcc.gnu.org Sender: "Gcc-patches" 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 * 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 --- 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