1 \input texinfo @c -*-texinfo-*-
4 @setfilename libgomp.info
10 Copyright @copyright{} 2006-2014 Free Software Foundation, Inc.
12 Permission is granted to copy, distribute and/or modify this document
13 under the terms of the GNU Free Documentation License, Version 1.3 or
14 any later version published by the Free Software Foundation; with the
15 Invariant Sections being ``Funding Free Software'', the Front-Cover
16 texts being (a) (see below), and with the Back-Cover Texts being (b)
17 (see below). A copy of the license is included in the section entitled
18 ``GNU Free Documentation License''.
20 (a) The FSF's Front-Cover Text is:
24 (b) The FSF's Back-Cover Text is:
26 You have freedom to copy and modify this GNU Manual, like GNU
27 software. Copies published by the Free Software Foundation raise
28 funds for GNU development.
32 @dircategory GNU Libraries
34 * libgomp: (libgomp). GNU OpenACC and OpenMP runtime library
37 This manual documents the GNU implementation of the OpenACC API for
38 offloading of code to accelerator devices in C/C++ and Fortran and
39 the GNU implementation of the OpenMP API for
40 multi-platform shared-memory parallel programming in C/C++ and Fortran.
42 Published by the Free Software Foundation
43 51 Franklin Street, Fifth Floor
44 Boston, MA 02110-1301 USA
50 @setchapternewpage odd
53 @title The GNU OpenACC and OpenMP Implementation
55 @vskip 0pt plus 1filll
56 @comment For the @value{version-GCC} Version*
58 Published by the Free Software Foundation @*
59 51 Franklin Street, Fifth Floor@*
60 Boston, MA 02110-1301, USA@*
74 This manual documents the usage of libgomp, the GNU implementation of the
75 @uref{http://www.openacc.org/, OpenACC} Application Programming Interface (API)
76 for offloading of code to accelerator devices in C/C++ and Fortran, and
77 the GNU implementation of the
78 @uref{http://www.openmp.org, OpenMP} Application Programming Interface (API)
79 for multi-platform shared-memory parallel programming in C/C++ and Fortran.
84 @comment When you add a new menu item, please keep the right hand
85 @comment aligned to the same column. Do not use tabs. This provides
86 @comment better formatting.
89 * Enabling OpenACC:: How to enable OpenACC for your
91 * OpenACC Runtime Library Routines:: The OpenACC runtime application
92 programming interface.
93 * OpenACC Environment Variables:: Influencing OpenACC runtime behavior with
94 environment variables.
95 * OpenACC Library Interoperability:: OpenACC library interoperability with the
96 NVIDIA CUBLAS library.
97 * Enabling OpenMP:: How to enable OpenMP for your
99 * OpenMP Runtime Library Routines: Runtime Library Routines.
100 The OpenMP runtime application programming
102 * OpenMP Environment Variables: Environment Variables.
103 Influencing OpenMP runtime behavior with
104 environment variables.
105 * The libgomp ABI:: Notes on the external libgomp ABI.
106 * Reporting Bugs:: How to report bugs.
107 * Copying:: GNU general public license says how you
108 can copy and share libgomp.
109 * GNU Free Documentation License:: How you can copy and share this manual.
110 * Funding:: How to help assure continued work for free
112 * Library Index:: Index of this documentation.
117 @c ---------------------------------------------------------------------
119 @c ---------------------------------------------------------------------
121 @node Enabling OpenACC
122 @chapter Enabling OpenACC
124 To activate the OpenACC extensions for C/C++ and Fortran, the compile-time
125 flag @command{-fopenacc} must be specified. This enables the OpenACC directive
126 @code{#pragma acc} in C/C++ and @code{!$accp} directives in free form,
127 @code{c$acc}, @code{*$acc} and @code{!$acc} directives in fixed form,
128 @code{!$} conditional compilation sentinels in free form and @code{c$},
129 @code{*$} and @code{!$} sentinels in fixed form, for Fortran. The flag also
130 arranges for automatic linking of the OpenACC runtime library
131 (@ref{OpenACC Runtime Library Routines}).
133 A complete description of all OpenACC directives accepted may be found in
134 the @uref{http://www.openacc.org/, OpenMP Application Programming
135 Interface} manual, version 2.0.
138 @c ---------------------------------------------------------------------
139 @c OpenACC Runtime Library Routines
140 @c ---------------------------------------------------------------------
142 @node OpenACC Runtime Library Routines
143 @chapter OpenACC Runtime Library Routines
145 The runtime routines described here are defined by section 3 of the OpenACC
146 specifications in version 2.0.
147 They have C linkage, and do not throw exceptions.
148 Generally, they are available only for the host, with the exception of
149 @code{acc_on_device}, which is available for both the host and the
153 * acc_get_num_devices:: Get number of devices for the given device type
154 * acc_set_device_type::
155 * acc_get_device_type::
156 * acc_set_device_num::
157 * acc_get_device_num::
160 * acc_on_device:: Whether executing on a particular device
164 * acc_present_or_copyin::
166 * acc_present_or_create::
169 * acc_update_device::
176 * acc_memcpy_to_device::
177 * acc_memcpy_from_device::
179 API routines for target platforms.
181 * acc_get_current_cuda_device::
182 * acc_get_current_cuda_context::
183 * acc_get_cuda_stream::
184 * acc_set_cuda_stream::
189 @node acc_get_num_devices
190 @section @code{acc_get_num_devices} -- Get number of devices for given device type
192 @item @emph{Description}
193 This routine returns a value indicating the
194 number of devices available for the given device type. It determines
195 the number of devices in a @emph{passive} manner. In other words, it
196 does not alter the state within the runtime environment aside from
197 possibly initializing an uninitialized device. This aspect allows
198 the routine to be called without concern for altering the interaction
199 with an attached accelerator device.
201 @item @emph{Reference}:
202 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
208 @node acc_set_device_type
209 @section @code{acc_set_device_type}
211 @item @emph{Reference}:
212 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
218 @node acc_get_device_type
219 @section @code{acc_get_device_type}
221 @item @emph{Reference}:
222 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
228 @node acc_set_device_num
229 @section @code{acc_set_device_num}
231 @item @emph{Reference}:
232 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
238 @node acc_get_device_num
239 @section @code{acc_get_device_num}
241 @item @emph{Reference}:
242 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
249 @section @code{acc_init}
251 @item @emph{Reference}:
252 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
259 @section @code{acc_shutdown}
261 @item @emph{Reference}:
262 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
269 @section @code{acc_on_device} -- Whether executing on a particular device
271 @item @emph{Description}:
272 This routine tells the program whether it is executing on a particular
273 device. Based on the argument passed, GCC tries to evaluate this to a
274 constant at compile time, but library functions are also provided, for
275 both the host and the acceleration device.
277 @item @emph{Reference}:
278 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
285 @section @code{acc_malloc}
287 @item @emph{Reference}:
288 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
295 @section @code{acc_free}
297 @item @emph{Reference}:
298 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
305 @section @code{acc_copyin}
307 @item @emph{Reference}:
308 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
314 @node acc_present_or_copyin
315 @section @code{acc_present_or_copyin}
317 @item @emph{Reference}:
318 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
325 @section @code{acc_create}
327 @item @emph{Reference}:
328 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
334 @node acc_present_or_create
335 @section @code{acc_present_or_create}
337 @item @emph{Reference}:
338 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
345 @section @code{acc_copyout}
347 @item @emph{Reference}:
348 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
355 @section @code{acc_delete}
357 @item @emph{Reference}:
358 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
364 @node acc_update_device
365 @section @code{acc_update_device}
367 @item @emph{Reference}:
368 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
374 @node acc_update_self
375 @section @code{acc_update_self}
377 @item @emph{Reference}:
378 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
385 @section @code{acc_map_data}
387 @item @emph{Reference}:
388 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
395 @section @code{acc_unmap_data}
397 @item @emph{Reference}:
398 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
405 @section @code{acc_deviceptr}
407 @item @emph{Reference}:
408 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
415 @section @code{acc_hostptr}
417 @item @emph{Reference}:
418 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
425 @section @code{acc_is_present}
427 @item @emph{Reference}:
428 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
434 @node acc_memcpy_to_device
435 @section @code{acc_memcpy_to_device}
437 @item @emph{Reference}:
438 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
444 @node acc_memcpy_from_device
445 @section @code{acc_memcpy_from_device}
447 @item @emph{Reference}:
448 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
454 @node acc_get_current_cuda_device
455 @section @code{acc_get_current_cuda_device}
457 @item @emph{Reference}:
458 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
464 @node acc_get_current_cuda_context
465 @section @code{acc_get_current_cuda_context}
467 @item @emph{Reference}:
468 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
474 @node acc_get_cuda_stream
475 @section @code{acc_get_cuda_stream}
477 @item @emph{Reference}:
478 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
484 @node acc_set_cuda_stream
485 @section @code{acc_set_cuda_stream}
487 @item @emph{Reference}:
488 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
494 @c ---------------------------------------------------------------------
495 @c OpenACC Environment Variables
496 @c ---------------------------------------------------------------------
498 @node OpenACC Environment Variables
499 @chapter OpenACC Environment Variables
501 The variables @env{ACC_DEVICE_TYPE} and @env{ACC_DEVICE_NUM}
502 are defined by section 4 of the OpenACC specification in version 2.0.
503 The variable @env{GCC_ACC_NOTIFY} is used for diagnostic purposes.
513 @node ACC_DEVICE_TYPE
514 @section @code{ACC_DEVICE_TYPE}
516 @item @emph{Reference}:
517 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
524 @section @code{ACC_DEVICE_NUM}
526 @item @emph{Reference}:
527 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
534 @section @code{GCC_ACC_NOTIFY}
536 @item @emph{Description}:
537 Print debug information pertaining to the accelerator.
541 @c ---------------------------------------------------------------------
542 @c OpenACC Library Interoperability
543 @c ---------------------------------------------------------------------
545 @node OpenACC Library Interoperability
546 @chapter OpenACC Library Interoperability
548 @section Introduction
550 As the OpenACC library is built using the CUDA Driver API, the question has
551 arisen on what impact does using the OpenACC library have on a program that
552 uses the Runtime library, or a library based on the Runtime library, e.g.,
553 CUBLAS@footnote{Seee section 2.26, "Interactions with the CUDA Driver API" in
554 "CUDA Runtime API", Version 5.5, July 2013 and section 2.27, "VDPAU
555 Interoperability", in "CUDA Driver API", TRM-06703-001, Version 5.5,
556 July 2013, for additional information on library interoperability.}.
557 This chapter will describe the use cases and what changes are
558 required in order to use both the OpenACC library and the CUBLAS and Runtime
559 libraries within a program.
561 @section First invocation: NVIDIA CUBLAS library API
563 In this first use case (see below), a function in the CUBLAS library is called
564 prior to any of the functions in the OpenACC library. More specifically, the
565 function @code{cublasCreate()}.
567 When invoked, the function will initialize the library and allocate the
568 hardware resources on the host and the device on behalf of the caller. Once
569 the initialization and allocation has completed, a handle is returned to the
570 caller. The OpenACC library also requires initialization and allocation of
571 hardware resources. Since the CUBLAS library has already allocated the
572 hardware resources for the device, all that is left to do is to initialize
573 the OpenACC library and acquire the hardware resources on the host.
575 Prior to calling the OpenACC function that will initialize the library and
576 allocate the host hardware resources, one needs to acquire the device number
577 that was allocated during the call to @code{cublasCreate()}. The invoking of the
578 runtime library function @code{cudaGetDevice()} will accomplish this. Once
579 acquired, the device number is passed along with the device type as
580 parameters to the OpenACC library function @code{acc_set_device_num()}.
582 Once the call to @code{acc_set_device_num()} has completed, the OpenACC
583 library will be using the context that was created during the call to
584 @code{cublasCreate()}. In other words, both libraries will be sharing the
588 /* Create the handle */
589 s = cublasCreate(&h);
590 if (s != CUBLAS_STATUS_SUCCESS)
592 fprintf(stderr, "cublasCreate failed %d\n", s);
596 /* Get the device number */
597 e = cudaGetDevice(&dev);
598 if (e != cudaSuccess)
600 fprintf(stderr, "cudaGetDevice failed %d\n", e);
604 /* Initialize OpenACC library and use device 'dev' */
605 acc_set_device_num(dev, acc_device_nvidia);
610 @section First invocation: OpenACC library API
612 In this second use case (see below), a function in the OpenACC library is
613 called prior to any of the functions in the CUBLAS library. More specificially,
614 the function acc_set_device_num().
616 In the use case presented here, the function @code{acc_set_device_num()}
617 is used to both initialize the OpenACC library and allocate the hardware
618 resources on the host and the device. In the call to the function, the
619 call parameters specify which device to use, i.e., 'dev', and what device
620 type to use, i.e., @code{acc_device_nvidia}. It should be noted that this
621 is but one method to initialize the OpenACC library and allocate the
622 appropriate hardware resources. Other methods are available through the
623 use of environment variables and these will be discussed in the next section.
625 Once the call to @code{acc_set_device_num()} has completed, other OpenACC
626 functions can be called as seen with multiple calls being made to
627 @code{acc_copyin()}. In addition, calls can be made to functions in the
628 CUBLAS library. In the use case a call to @code{cublasCreate()} is made
629 subsequent to the calls to @code{acc_copyin()}.
630 As seen in the previous use case, a call to @code{cublasCreate()} will
631 initialize the CUBLAS library and allocate the hardware resources on the
632 host and the device. However, since the device has already been allocated,
633 @code{cublasCreate()} will only initialize the CUBLAS library and allocate
634 the appropriate hardware resources on the host. The context that was created
635 as part of the OpenACC initialization will be shared with the CUBLAS library,
636 similarly to the first use case.
641 acc_set_device_num(dev, acc_device_nvidia);
643 /* Copy the first set to the device */
644 d_X = acc_copyin(&h_X[0], N * sizeof (float));
647 fprintf(stderr, "copyin error h_X\n");
651 /* Copy the second set to the device */
652 d_Y = acc_copyin(&h_Y1[0], N * sizeof (float));
655 fprintf(stderr, "copyin error h_Y1\n");
659 /* Create the handle */
660 s = cublasCreate(&h);
661 if (s != CUBLAS_STATUS_SUCCESS)
663 fprintf(stderr, "cublasCreate failed %d\n", s);
667 /* Perform saxpy using CUBLAS library function */
668 s = cublasSaxpy(h, N, &alpha, d_X, 1, d_Y, 1);
669 if (s != CUBLAS_STATUS_SUCCESS)
671 fprintf(stderr, "cublasSaxpy failed %d\n", s);
675 /* Copy the results from the device */
676 acc_memcpy_from_device(&h_Y1[0], d_Y, N * sizeof (float));
682 @section OpenACC library and environment variables
684 There are two environment variables associated with the OpenACC library that
685 may be used to control the device type and device number.
686 Namely, @env{ACC_DEVICE_TYPE} and @env{ACC_DEVICE_NUM}. In the second
687 use case, the device type and device number were specified using
688 @code{acc_set_device_num()}. However, @env{ACC_DEVICE_TYPE} and
689 @env{ACC_DEVICE_NUM} could have been defined and the call to
690 @code{acc_set_device_num()} would be not be required. At the time of the
691 call to @code{acc_copyin()}, these two environment variables would be
692 sampled and their values used.
694 The use of the environment variables is only relevant when an OpenACC function
695 is called prior to a call to @code{cudaCreate()}. If @code{cudaCreate()}
696 is called prior to a call to an OpenACC function, then a call to
697 @code{acc_set_device_num()}, must be done@footnote{More complete information
698 about @env{ACC_DEVICE_TYPE} and @env{ACC_DEVICE_NUM} can be found in
699 sections 4.1 and 4.2 of the “The OpenACC
700 Application Programming Interface”, Version 2.0, June, 2013.}.
704 @c ---------------------------------------------------------------------
706 @c ---------------------------------------------------------------------
708 @node Enabling OpenMP
709 @chapter Enabling OpenMP
711 To activate the OpenMP extensions for C/C++ and Fortran, the compile-time
712 flag @command{-fopenmp} must be specified. This enables the OpenMP directive
713 @code{#pragma omp} in C/C++ and @code{!$omp} directives in free form,
714 @code{c$omp}, @code{*$omp} and @code{!$omp} directives in fixed form,
715 @code{!$} conditional compilation sentinels in free form and @code{c$},
716 @code{*$} and @code{!$} sentinels in fixed form, for Fortran. The flag also
717 arranges for automatic linking of the OpenMP runtime library
718 (@ref{Runtime Library Routines}).
720 A complete description of all OpenMP directives accepted may be found in
721 the @uref{http://www.openmp.org, OpenMP Application Program Interface} manual,
725 @c ---------------------------------------------------------------------
726 @c OpenMP Runtime Library Routines
727 @c ---------------------------------------------------------------------
729 @node Runtime Library Routines
730 @chapter OpenMP Runtime Library Routines
732 The runtime routines described here are defined by Section 3 of the OpenMP
733 specification in version 4.0. The routines are structured in following
737 Control threads, processors and the parallel environment. They have C
738 linkage, and do not throw exceptions.
740 * omp_get_active_level:: Number of active parallel regions
741 * omp_get_ancestor_thread_num:: Ancestor thread ID
742 * omp_get_cancellation:: Whether cancellation support is enabled
743 * omp_get_default_device:: Get the default device for target regions
744 * omp_get_dynamic:: Dynamic teams setting
745 * omp_get_level:: Number of parallel regions
746 * omp_get_max_active_levels:: Maximum number of active regions
747 * omp_get_max_threads:: Maximum number of threads of parallel region
748 * omp_get_nested:: Nested parallel regions
749 * omp_get_num_devices:: Number of target devices
750 * omp_get_num_procs:: Number of processors online
751 * omp_get_num_teams:: Number of teams
752 * omp_get_num_threads:: Size of the active team
753 * omp_get_proc_bind:: Whether theads may be moved between CPUs
754 * omp_get_schedule:: Obtain the runtime scheduling method
755 * omp_get_team_num:: Get team number
756 * omp_get_team_size:: Number of threads in a team
757 * omp_get_thread_limit:: Maximum number of threads
758 * omp_get_thread_num:: Current thread ID
759 * omp_in_parallel:: Whether a parallel region is active
760 * omp_in_final:: Whether in final or included task region
761 * omp_is_initial_device:: Whether executing on the host device
762 * omp_set_default_device:: Set the default device for target regions
763 * omp_set_dynamic:: Enable/disable dynamic teams
764 * omp_set_max_active_levels:: Limits the number of active parallel regions
765 * omp_set_nested:: Enable/disable nested parallel regions
766 * omp_set_num_threads:: Set upper team size limit
767 * omp_set_schedule:: Set the runtime scheduling method
769 Initialize, set, test, unset and destroy simple and nested locks.
771 * omp_init_lock:: Initialize simple lock
772 * omp_set_lock:: Wait for and set simple lock
773 * omp_test_lock:: Test and set simple lock if available
774 * omp_unset_lock:: Unset simple lock
775 * omp_destroy_lock:: Destroy simple lock
776 * omp_init_nest_lock:: Initialize nested lock
777 * omp_set_nest_lock:: Wait for and set simple lock
778 * omp_test_nest_lock:: Test and set nested lock if available
779 * omp_unset_nest_lock:: Unset nested lock
780 * omp_destroy_nest_lock:: Destroy nested lock
782 Portable, thread-based, wall clock timer.
784 * omp_get_wtick:: Get timer precision.
785 * omp_get_wtime:: Elapsed wall clock time.
790 @node omp_get_active_level
791 @section @code{omp_get_active_level} -- Number of parallel regions
793 @item @emph{Description}:
794 This function returns the nesting level for the active parallel blocks,
795 which enclose the calling call.
798 @multitable @columnfractions .20 .80
799 @item @emph{Prototype}: @tab @code{int omp_get_active_level(void);}
802 @item @emph{Fortran}:
803 @multitable @columnfractions .20 .80
804 @item @emph{Interface}: @tab @code{integer function omp_get_active_level()}
807 @item @emph{See also}:
808 @ref{omp_get_level}, @ref{omp_get_max_active_levels}, @ref{omp_set_max_active_levels}
810 @item @emph{Reference}:
811 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.2.20.
816 @node omp_get_ancestor_thread_num
817 @section @code{omp_get_ancestor_thread_num} -- Ancestor thread ID
819 @item @emph{Description}:
820 This function returns the thread identification number for the given
821 nesting level of the current thread. For values of @var{level} outside
822 zero to @code{omp_get_level} -1 is returned; if @var{level} is
823 @code{omp_get_level} the result is identical to @code{omp_get_thread_num}.
826 @multitable @columnfractions .20 .80
827 @item @emph{Prototype}: @tab @code{int omp_get_ancestor_thread_num(int level);}
830 @item @emph{Fortran}:
831 @multitable @columnfractions .20 .80
832 @item @emph{Interface}: @tab @code{integer function omp_get_ancestor_thread_num(level)}
833 @item @tab @code{integer level}
836 @item @emph{See also}:
837 @ref{omp_get_level}, @ref{omp_get_thread_num}, @ref{omp_get_team_size}
839 @item @emph{Reference}:
840 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.2.18.
845 @node omp_get_cancellation
846 @section @code{omp_get_cancellation} -- Whether cancellation support is enabled
848 @item @emph{Description}:
849 This function returns @code{true} if cancellation is activated, @code{false}
850 otherwise. Here, @code{true} and @code{false} represent their language-specific
851 counterparts. Unless @env{OMP_CANCELLATION} is set true, cancellations are
855 @multitable @columnfractions .20 .80
856 @item @emph{Prototype}: @tab @code{int omp_get_cancellation(void);}
859 @item @emph{Fortran}:
860 @multitable @columnfractions .20 .80
861 @item @emph{Interface}: @tab @code{logical function omp_get_cancellation()}
864 @item @emph{See also}:
865 @ref{OMP_CANCELLATION}
867 @item @emph{Reference}:
868 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.2.9.
873 @node omp_get_default_device
874 @section @code{omp_get_default_device} -- Get the default device for target regions
876 @item @emph{Description}:
877 Get the default device for target regions without device clause.
880 @multitable @columnfractions .20 .80
881 @item @emph{Prototype}: @tab @code{int omp_get_default_device(void);}
884 @item @emph{Fortran}:
885 @multitable @columnfractions .20 .80
886 @item @emph{Interface}: @tab @code{integer function omp_get_default_device()}
889 @item @emph{See also}:
890 @ref{OMP_DEFAULT_DEVICE}, @ref{omp_set_default_device}
892 @item @emph{Reference}:
893 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.2.24.
898 @node omp_get_dynamic
899 @section @code{omp_get_dynamic} -- Dynamic teams setting
901 @item @emph{Description}:
902 This function returns @code{true} if enabled, @code{false} otherwise.
903 Here, @code{true} and @code{false} represent their language-specific
906 The dynamic team setting may be initialized at startup by the
907 @env{OMP_DYNAMIC} environment variable or at runtime using
908 @code{omp_set_dynamic}. If undefined, dynamic adjustment is
912 @multitable @columnfractions .20 .80
913 @item @emph{Prototype}: @tab @code{int omp_get_dynamic(void);}
916 @item @emph{Fortran}:
917 @multitable @columnfractions .20 .80
918 @item @emph{Interface}: @tab @code{logical function omp_get_dynamic()}
921 @item @emph{See also}:
922 @ref{omp_set_dynamic}, @ref{OMP_DYNAMIC}
924 @item @emph{Reference}:
925 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.2.8.
931 @section @code{omp_get_level} -- Obtain the current nesting level
933 @item @emph{Description}:
934 This function returns the nesting level for the parallel blocks,
935 which enclose the calling call.
938 @multitable @columnfractions .20 .80
939 @item @emph{Prototype}: @tab @code{int omp_get_level(void);}
942 @item @emph{Fortran}:
943 @multitable @columnfractions .20 .80
944 @item @emph{Interface}: @tab @code{integer function omp_level()}
947 @item @emph{See also}:
948 @ref{omp_get_active_level}
950 @item @emph{Reference}:
951 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.2.17.
956 @node omp_get_max_active_levels
957 @section @code{omp_get_max_active_levels} -- Maximum number of active regions
959 @item @emph{Description}:
960 This function obtains the maximum allowed number of nested, active parallel regions.
963 @multitable @columnfractions .20 .80
964 @item @emph{Prototype}: @tab @code{int omp_get_max_active_levels(void);}
967 @item @emph{Fortran}:
968 @multitable @columnfractions .20 .80
969 @item @emph{Interface}: @tab @code{integer function omp_get_max_active_levels()}
972 @item @emph{See also}:
973 @ref{omp_set_max_active_levels}, @ref{omp_get_active_level}
975 @item @emph{Reference}:
976 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.2.16.
981 @node omp_get_max_threads
982 @section @code{omp_get_max_threads} -- Maximum number of threads of parallel region
984 @item @emph{Description}:
985 Return the maximum number of threads used for the current parallel region
986 that does not use the clause @code{num_threads}.
989 @multitable @columnfractions .20 .80
990 @item @emph{Prototype}: @tab @code{int omp_get_max_threads(void);}
993 @item @emph{Fortran}:
994 @multitable @columnfractions .20 .80
995 @item @emph{Interface}: @tab @code{integer function omp_get_max_threads()}
998 @item @emph{See also}:
999 @ref{omp_set_num_threads}, @ref{omp_set_dynamic}, @ref{omp_get_thread_limit}
1001 @item @emph{Reference}:
1002 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.2.3.
1007 @node omp_get_nested
1008 @section @code{omp_get_nested} -- Nested parallel regions
1010 @item @emph{Description}:
1011 This function returns @code{true} if nested parallel regions are
1012 enabled, @code{false} otherwise. Here, @code{true} and @code{false}
1013 represent their language-specific counterparts.
1015 Nested parallel regions may be initialized at startup by the
1016 @env{OMP_NESTED} environment variable or at runtime using
1017 @code{omp_set_nested}. If undefined, nested parallel regions are
1018 disabled by default.
1021 @multitable @columnfractions .20 .80
1022 @item @emph{Prototype}: @tab @code{int omp_get_nested(void);}
1025 @item @emph{Fortran}:
1026 @multitable @columnfractions .20 .80
1027 @item @emph{Interface}: @tab @code{logical function omp_get_nested()}
1030 @item @emph{See also}:
1031 @ref{omp_set_nested}, @ref{OMP_NESTED}
1033 @item @emph{Reference}:
1034 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.2.11.
1039 @node omp_get_num_devices
1040 @section @code{omp_get_num_devices} -- Number of target devices
1042 @item @emph{Description}:
1043 Returns the number of target devices.
1046 @multitable @columnfractions .20 .80
1047 @item @emph{Prototype}: @tab @code{int omp_get_num_devices(void);}
1050 @item @emph{Fortran}:
1051 @multitable @columnfractions .20 .80
1052 @item @emph{Interface}: @tab @code{integer function omp_get_num_devices()}
1055 @item @emph{Reference}:
1056 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.2.25.
1061 @node omp_get_num_procs
1062 @section @code{omp_get_num_procs} -- Number of processors online
1064 @item @emph{Description}:
1065 Returns the number of processors online on that device.
1068 @multitable @columnfractions .20 .80
1069 @item @emph{Prototype}: @tab @code{int omp_get_num_procs(void);}
1072 @item @emph{Fortran}:
1073 @multitable @columnfractions .20 .80
1074 @item @emph{Interface}: @tab @code{integer function omp_get_num_procs()}
1077 @item @emph{Reference}:
1078 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.2.5.
1083 @node omp_get_num_teams
1084 @section @code{omp_get_num_teams} -- Number of teams
1086 @item @emph{Description}:
1087 Returns the number of teams in the current team region.
1090 @multitable @columnfractions .20 .80
1091 @item @emph{Prototype}: @tab @code{int omp_get_num_teams(void);}
1094 @item @emph{Fortran}:
1095 @multitable @columnfractions .20 .80
1096 @item @emph{Interface}: @tab @code{integer function omp_get_num_teams()}
1099 @item @emph{Reference}:
1100 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.2.26.
1105 @node omp_get_num_threads
1106 @section @code{omp_get_num_threads} -- Size of the active team
1108 @item @emph{Description}:
1109 Returns the number of threads in the current team. In a sequential section of
1110 the program @code{omp_get_num_threads} returns 1.
1112 The default team size may be initialized at startup by the
1113 @env{OMP_NUM_THREADS} environment variable. At runtime, the size
1114 of the current team may be set either by the @code{NUM_THREADS}
1115 clause or by @code{omp_set_num_threads}. If none of the above were
1116 used to define a specific value and @env{OMP_DYNAMIC} is disabled,
1117 one thread per CPU online is used.
1120 @multitable @columnfractions .20 .80
1121 @item @emph{Prototype}: @tab @code{int omp_get_num_threads(void);}
1124 @item @emph{Fortran}:
1125 @multitable @columnfractions .20 .80
1126 @item @emph{Interface}: @tab @code{integer function omp_get_num_threads()}
1129 @item @emph{See also}:
1130 @ref{omp_get_max_threads}, @ref{omp_set_num_threads}, @ref{OMP_NUM_THREADS}
1132 @item @emph{Reference}:
1133 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.2.2.
1138 @node omp_get_proc_bind
1139 @section @code{omp_get_proc_bind} -- Whether theads may be moved between CPUs
1141 @item @emph{Description}:
1142 This functions returns the currently active thread affinity policy, which is
1143 set via @env{OMP_PROC_BIND}. Possible values are @code{omp_proc_bind_false},
1144 @code{omp_proc_bind_true}, @code{omp_proc_bind_master},
1145 @code{omp_proc_bind_close} and @code{omp_proc_bind_spread}.
1148 @multitable @columnfractions .20 .80
1149 @item @emph{Prototype}: @tab @code{omp_proc_bind_t omp_get_proc_bind(void);}
1152 @item @emph{Fortran}:
1153 @multitable @columnfractions .20 .80
1154 @item @emph{Interface}: @tab @code{integer(kind=omp_proc_bind_kind) function omp_get_proc_bind()}
1157 @item @emph{See also}:
1158 @ref{OMP_PROC_BIND}, @ref{OMP_PLACES}, @ref{GOMP_CPU_AFFINITY},
1160 @item @emph{Reference}:
1161 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.2.22.
1166 @node omp_get_schedule
1167 @section @code{omp_get_schedule} -- Obtain the runtime scheduling method
1169 @item @emph{Description}:
1170 Obtain the runtime scheduling method. The @var{kind} argument will be
1171 set to the value @code{omp_sched_static}, @code{omp_sched_dynamic},
1172 @code{omp_sched_guided} or @code{omp_sched_auto}. The second argument,
1173 @var{modifier}, is set to the chunk size.
1176 @multitable @columnfractions .20 .80
1177 @item @emph{Prototype}: @tab @code{void omp_get_schedule(omp_sched_t *kind, int *modifier);}
1180 @item @emph{Fortran}:
1181 @multitable @columnfractions .20 .80
1182 @item @emph{Interface}: @tab @code{subroutine omp_get_schedule(kind, modifier)}
1183 @item @tab @code{integer(kind=omp_sched_kind) kind}
1184 @item @tab @code{integer modifier}
1187 @item @emph{See also}:
1188 @ref{omp_set_schedule}, @ref{OMP_SCHEDULE}
1190 @item @emph{Reference}:
1191 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.2.13.
1196 @node omp_get_team_num
1197 @section @code{omp_get_team_num} -- Get team number
1199 @item @emph{Description}:
1200 Returns the team number of the calling thread.
1203 @multitable @columnfractions .20 .80
1204 @item @emph{Prototype}: @tab @code{int omp_get_team_num(void);}
1207 @item @emph{Fortran}:
1208 @multitable @columnfractions .20 .80
1209 @item @emph{Interface}: @tab @code{integer function omp_get_team_num()}
1212 @item @emph{Reference}:
1213 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.2.27.
1218 @node omp_get_team_size
1219 @section @code{omp_get_team_size} -- Number of threads in a team
1221 @item @emph{Description}:
1222 This function returns the number of threads in a thread team to which
1223 either the current thread or its ancestor belongs. For values of @var{level}
1224 outside zero to @code{omp_get_level}, -1 is returned; if @var{level} is zero,
1225 1 is returned, and for @code{omp_get_level}, the result is identical
1226 to @code{omp_get_num_threads}.
1229 @multitable @columnfractions .20 .80
1230 @item @emph{Prototype}: @tab @code{int omp_get_team_size(int level);}
1233 @item @emph{Fortran}:
1234 @multitable @columnfractions .20 .80
1235 @item @emph{Interface}: @tab @code{integer function omp_get_team_size(level)}
1236 @item @tab @code{integer level}
1239 @item @emph{See also}:
1240 @ref{omp_get_num_threads}, @ref{omp_get_level}, @ref{omp_get_ancestor_thread_num}
1242 @item @emph{Reference}:
1243 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.2.19.
1248 @node omp_get_thread_limit
1249 @section @code{omp_get_thread_limit} -- Maximum number of threads
1251 @item @emph{Description}:
1252 Return the maximum number of threads of the program.
1255 @multitable @columnfractions .20 .80
1256 @item @emph{Prototype}: @tab @code{int omp_get_thread_limit(void);}
1259 @item @emph{Fortran}:
1260 @multitable @columnfractions .20 .80
1261 @item @emph{Interface}: @tab @code{integer function omp_get_thread_limit()}
1264 @item @emph{See also}:
1265 @ref{omp_get_max_threads}, @ref{OMP_THREAD_LIMIT}
1267 @item @emph{Reference}:
1268 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.2.14.
1273 @node omp_get_thread_num
1274 @section @code{omp_get_thread_num} -- Current thread ID
1276 @item @emph{Description}:
1277 Returns a unique thread identification number within the current team.
1278 In a sequential parts of the program, @code{omp_get_thread_num}
1279 always returns 0. In parallel regions the return value varies
1280 from 0 to @code{omp_get_num_threads}-1 inclusive. The return
1281 value of the master thread of a team is always 0.
1284 @multitable @columnfractions .20 .80
1285 @item @emph{Prototype}: @tab @code{int omp_get_thread_num(void);}
1288 @item @emph{Fortran}:
1289 @multitable @columnfractions .20 .80
1290 @item @emph{Interface}: @tab @code{integer function omp_get_thread_num()}
1293 @item @emph{See also}:
1294 @ref{omp_get_num_threads}, @ref{omp_get_ancestor_thread_num}
1296 @item @emph{Reference}:
1297 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.2.4.
1302 @node omp_in_parallel
1303 @section @code{omp_in_parallel} -- Whether a parallel region is active
1305 @item @emph{Description}:
1306 This function returns @code{true} if currently running in parallel,
1307 @code{false} otherwise. Here, @code{true} and @code{false} represent
1308 their language-specific counterparts.
1311 @multitable @columnfractions .20 .80
1312 @item @emph{Prototype}: @tab @code{int omp_in_parallel(void);}
1315 @item @emph{Fortran}:
1316 @multitable @columnfractions .20 .80
1317 @item @emph{Interface}: @tab @code{logical function omp_in_parallel()}
1320 @item @emph{Reference}:
1321 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.2.6.
1326 @section @code{omp_in_final} -- Whether in final or included task region
1328 @item @emph{Description}:
1329 This function returns @code{true} if currently running in a final
1330 or included task region, @code{false} otherwise. Here, @code{true}
1331 and @code{false} represent their language-specific counterparts.
1334 @multitable @columnfractions .20 .80
1335 @item @emph{Prototype}: @tab @code{int omp_in_final(void);}
1338 @item @emph{Fortran}:
1339 @multitable @columnfractions .20 .80
1340 @item @emph{Interface}: @tab @code{logical function omp_in_final()}
1343 @item @emph{Reference}:
1344 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.2.21.
1349 @node omp_is_initial_device
1350 @section @code{omp_is_initial_device} -- Whether executing on the host device
1352 @item @emph{Description}:
1353 This function returns @code{true} if currently running on the host device,
1354 @code{false} otherwise. Here, @code{true} and @code{false} represent
1355 their language-specific counterparts.
1358 @multitable @columnfractions .20 .80
1359 @item @emph{Prototype}: @tab @code{int omp_is_initial_device(void);}
1362 @item @emph{Fortran}:
1363 @multitable @columnfractions .20 .80
1364 @item @emph{Interface}: @tab @code{logical function omp_is_initial_device()}
1367 @item @emph{Reference}:
1368 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.2.28.
1373 @node omp_set_default_device
1374 @section @code{omp_set_default_device} -- Set the default device for target regions
1376 @item @emph{Description}:
1377 Set the default device for target regions without device clause. The argument
1378 shall be a nonnegative device number.
1381 @multitable @columnfractions .20 .80
1382 @item @emph{Prototype}: @tab @code{void omp_set_default_device(int device_num);}
1385 @item @emph{Fortran}:
1386 @multitable @columnfractions .20 .80
1387 @item @emph{Interface}: @tab @code{subroutine omp_set_default_device(device_num)}
1388 @item @tab @code{integer device_num}
1391 @item @emph{See also}:
1392 @ref{OMP_DEFAULT_DEVICE}, @ref{omp_get_default_device}
1394 @item @emph{Reference}:
1395 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.2.23.
1400 @node omp_set_dynamic
1401 @section @code{omp_set_dynamic} -- Enable/disable dynamic teams
1403 @item @emph{Description}:
1404 Enable or disable the dynamic adjustment of the number of threads
1405 within a team. The function takes the language-specific equivalent
1406 of @code{true} and @code{false}, where @code{true} enables dynamic
1407 adjustment of team sizes and @code{false} disables it.
1410 @multitable @columnfractions .20 .80
1411 @item @emph{Prototype}: @tab @code{void omp_set_dynamic(int dynamic_threads);}
1414 @item @emph{Fortran}:
1415 @multitable @columnfractions .20 .80
1416 @item @emph{Interface}: @tab @code{subroutine omp_set_dynamic(dynamic_threads)}
1417 @item @tab @code{logical, intent(in) :: dynamic_threads}
1420 @item @emph{See also}:
1421 @ref{OMP_DYNAMIC}, @ref{omp_get_dynamic}
1423 @item @emph{Reference}:
1424 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.2.7.
1429 @node omp_set_max_active_levels
1430 @section @code{omp_set_max_active_levels} -- Limits the number of active parallel regions
1432 @item @emph{Description}:
1433 This function limits the maximum allowed number of nested, active
1437 @multitable @columnfractions .20 .80
1438 @item @emph{Prototype}: @tab @code{void omp_set_max_active_levels(int max_levels);}
1441 @item @emph{Fortran}:
1442 @multitable @columnfractions .20 .80
1443 @item @emph{Interface}: @tab @code{subroutine omp_set_max_active_levels(max_levels)}
1444 @item @tab @code{integer max_levels}
1447 @item @emph{See also}:
1448 @ref{omp_get_max_active_levels}, @ref{omp_get_active_level}
1450 @item @emph{Reference}:
1451 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.2.15.
1456 @node omp_set_nested
1457 @section @code{omp_set_nested} -- Enable/disable nested parallel regions
1459 @item @emph{Description}:
1460 Enable or disable nested parallel regions, i.e., whether team members
1461 are allowed to create new teams. The function takes the language-specific
1462 equivalent of @code{true} and @code{false}, where @code{true} enables
1463 dynamic adjustment of team sizes and @code{false} disables it.
1466 @multitable @columnfractions .20 .80
1467 @item @emph{Prototype}: @tab @code{void omp_set_nested(int nested);}
1470 @item @emph{Fortran}:
1471 @multitable @columnfractions .20 .80
1472 @item @emph{Interface}: @tab @code{subroutine omp_set_nested(nested)}
1473 @item @tab @code{logical, intent(in) :: nested}
1476 @item @emph{See also}:
1477 @ref{OMP_NESTED}, @ref{omp_get_nested}
1479 @item @emph{Reference}:
1480 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.2.10.
1485 @node omp_set_num_threads
1486 @section @code{omp_set_num_threads} -- Set upper team size limit
1488 @item @emph{Description}:
1489 Specifies the number of threads used by default in subsequent parallel
1490 sections, if those do not specify a @code{num_threads} clause. The
1491 argument of @code{omp_set_num_threads} shall be a positive integer.
1494 @multitable @columnfractions .20 .80
1495 @item @emph{Prototype}: @tab @code{void omp_set_num_threads(int num_threads);}
1498 @item @emph{Fortran}:
1499 @multitable @columnfractions .20 .80
1500 @item @emph{Interface}: @tab @code{subroutine omp_set_num_threads(num_threads)}
1501 @item @tab @code{integer, intent(in) :: num_threads}
1504 @item @emph{See also}:
1505 @ref{OMP_NUM_THREADS}, @ref{omp_get_num_threads}, @ref{omp_get_max_threads}
1507 @item @emph{Reference}:
1508 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.2.1.
1513 @node omp_set_schedule
1514 @section @code{omp_set_schedule} -- Set the runtime scheduling method
1516 @item @emph{Description}:
1517 Sets the runtime scheduling method. The @var{kind} argument can have the
1518 value @code{omp_sched_static}, @code{omp_sched_dynamic},
1519 @code{omp_sched_guided} or @code{omp_sched_auto}. Except for
1520 @code{omp_sched_auto}, the chunk size is set to the value of
1521 @var{modifier} if positive, or to the default value if zero or negative.
1522 For @code{omp_sched_auto} the @var{modifier} argument is ignored.
1525 @multitable @columnfractions .20 .80
1526 @item @emph{Prototype}: @tab @code{void omp_set_schedule(omp_sched_t kind, int modifier);}
1529 @item @emph{Fortran}:
1530 @multitable @columnfractions .20 .80
1531 @item @emph{Interface}: @tab @code{subroutine omp_set_schedule(kind, modifier)}
1532 @item @tab @code{integer(kind=omp_sched_kind) kind}
1533 @item @tab @code{integer modifier}
1536 @item @emph{See also}:
1537 @ref{omp_get_schedule}
1540 @item @emph{Reference}:
1541 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.2.12.
1547 @section @code{omp_init_lock} -- Initialize simple lock
1549 @item @emph{Description}:
1550 Initialize a simple lock. After initialization, the lock is in
1554 @multitable @columnfractions .20 .80
1555 @item @emph{Prototype}: @tab @code{void omp_init_lock(omp_lock_t *lock);}
1558 @item @emph{Fortran}:
1559 @multitable @columnfractions .20 .80
1560 @item @emph{Interface}: @tab @code{subroutine omp_init_lock(svar)}
1561 @item @tab @code{integer(omp_lock_kind), intent(out) :: svar}
1564 @item @emph{See also}:
1565 @ref{omp_destroy_lock}
1567 @item @emph{Reference}:
1568 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.3.1.
1574 @section @code{omp_set_lock} -- Wait for and set simple lock
1576 @item @emph{Description}:
1577 Before setting a simple lock, the lock variable must be initialized by
1578 @code{omp_init_lock}. The calling thread is blocked until the lock
1579 is available. If the lock is already held by the current thread,
1583 @multitable @columnfractions .20 .80
1584 @item @emph{Prototype}: @tab @code{void omp_set_lock(omp_lock_t *lock);}
1587 @item @emph{Fortran}:
1588 @multitable @columnfractions .20 .80
1589 @item @emph{Interface}: @tab @code{subroutine omp_set_lock(svar)}
1590 @item @tab @code{integer(omp_lock_kind), intent(inout) :: svar}
1593 @item @emph{See also}:
1594 @ref{omp_init_lock}, @ref{omp_test_lock}, @ref{omp_unset_lock}
1596 @item @emph{Reference}:
1597 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.3.3.
1603 @section @code{omp_test_lock} -- Test and set simple lock if available
1605 @item @emph{Description}:
1606 Before setting a simple lock, the lock variable must be initialized by
1607 @code{omp_init_lock}. Contrary to @code{omp_set_lock}, @code{omp_test_lock}
1608 does not block if the lock is not available. This function returns
1609 @code{true} upon success, @code{false} otherwise. Here, @code{true} and
1610 @code{false} represent their language-specific counterparts.
1613 @multitable @columnfractions .20 .80
1614 @item @emph{Prototype}: @tab @code{int omp_test_lock(omp_lock_t *lock);}
1617 @item @emph{Fortran}:
1618 @multitable @columnfractions .20 .80
1619 @item @emph{Interface}: @tab @code{logical function omp_test_lock(svar)}
1620 @item @tab @code{integer(omp_lock_kind), intent(inout) :: svar}
1623 @item @emph{See also}:
1624 @ref{omp_init_lock}, @ref{omp_set_lock}, @ref{omp_set_lock}
1626 @item @emph{Reference}:
1627 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.3.5.
1632 @node omp_unset_lock
1633 @section @code{omp_unset_lock} -- Unset simple lock
1635 @item @emph{Description}:
1636 A simple lock about to be unset must have been locked by @code{omp_set_lock}
1637 or @code{omp_test_lock} before. In addition, the lock must be held by the
1638 thread calling @code{omp_unset_lock}. Then, the lock becomes unlocked. If one
1639 or more threads attempted to set the lock before, one of them is chosen to,
1640 again, set the lock to itself.
1643 @multitable @columnfractions .20 .80
1644 @item @emph{Prototype}: @tab @code{void omp_unset_lock(omp_lock_t *lock);}
1647 @item @emph{Fortran}:
1648 @multitable @columnfractions .20 .80
1649 @item @emph{Interface}: @tab @code{subroutine omp_unset_lock(svar)}
1650 @item @tab @code{integer(omp_lock_kind), intent(inout) :: svar}
1653 @item @emph{See also}:
1654 @ref{omp_set_lock}, @ref{omp_test_lock}
1656 @item @emph{Reference}:
1657 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.3.4.
1662 @node omp_destroy_lock
1663 @section @code{omp_destroy_lock} -- Destroy simple lock
1665 @item @emph{Description}:
1666 Destroy a simple lock. In order to be destroyed, a simple lock must be
1667 in the unlocked state.
1670 @multitable @columnfractions .20 .80
1671 @item @emph{Prototype}: @tab @code{void omp_destroy_lock(omp_lock_t *lock);}
1674 @item @emph{Fortran}:
1675 @multitable @columnfractions .20 .80
1676 @item @emph{Interface}: @tab @code{subroutine omp_destroy_lock(svar)}
1677 @item @tab @code{integer(omp_lock_kind), intent(inout) :: svar}
1680 @item @emph{See also}:
1683 @item @emph{Reference}:
1684 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.3.2.
1689 @node omp_init_nest_lock
1690 @section @code{omp_init_nest_lock} -- Initialize nested lock
1692 @item @emph{Description}:
1693 Initialize a nested lock. After initialization, the lock is in
1694 an unlocked state and the nesting count is set to zero.
1697 @multitable @columnfractions .20 .80
1698 @item @emph{Prototype}: @tab @code{void omp_init_nest_lock(omp_nest_lock_t *lock);}
1701 @item @emph{Fortran}:
1702 @multitable @columnfractions .20 .80
1703 @item @emph{Interface}: @tab @code{subroutine omp_init_nest_lock(nvar)}
1704 @item @tab @code{integer(omp_nest_lock_kind), intent(out) :: nvar}
1707 @item @emph{See also}:
1708 @ref{omp_destroy_nest_lock}
1710 @item @emph{Reference}:
1711 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.3.1.
1715 @node omp_set_nest_lock
1716 @section @code{omp_set_nest_lock} -- Wait for and set nested lock
1718 @item @emph{Description}:
1719 Before setting a nested lock, the lock variable must be initialized by
1720 @code{omp_init_nest_lock}. The calling thread is blocked until the lock
1721 is available. If the lock is already held by the current thread, the
1722 nesting count for the lock is incremented.
1725 @multitable @columnfractions .20 .80
1726 @item @emph{Prototype}: @tab @code{void omp_set_nest_lock(omp_nest_lock_t *lock);}
1729 @item @emph{Fortran}:
1730 @multitable @columnfractions .20 .80
1731 @item @emph{Interface}: @tab @code{subroutine omp_set_nest_lock(nvar)}
1732 @item @tab @code{integer(omp_nest_lock_kind), intent(inout) :: nvar}
1735 @item @emph{See also}:
1736 @ref{omp_init_nest_lock}, @ref{omp_unset_nest_lock}
1738 @item @emph{Reference}:
1739 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.3.3.
1744 @node omp_test_nest_lock
1745 @section @code{omp_test_nest_lock} -- Test and set nested lock if available
1747 @item @emph{Description}:
1748 Before setting a nested lock, the lock variable must be initialized by
1749 @code{omp_init_nest_lock}. Contrary to @code{omp_set_nest_lock},
1750 @code{omp_test_nest_lock} does not block if the lock is not available.
1751 If the lock is already held by the current thread, the new nesting count
1752 is returned. Otherwise, the return value equals zero.
1755 @multitable @columnfractions .20 .80
1756 @item @emph{Prototype}: @tab @code{int omp_test_nest_lock(omp_nest_lock_t *lock);}
1759 @item @emph{Fortran}:
1760 @multitable @columnfractions .20 .80
1761 @item @emph{Interface}: @tab @code{logical function omp_test_nest_lock(nvar)}
1762 @item @tab @code{integer(omp_nest_lock_kind), intent(inout) :: nvar}
1766 @item @emph{See also}:
1767 @ref{omp_init_lock}, @ref{omp_set_lock}, @ref{omp_set_lock}
1769 @item @emph{Reference}:
1770 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.3.5.
1775 @node omp_unset_nest_lock
1776 @section @code{omp_unset_nest_lock} -- Unset nested lock
1778 @item @emph{Description}:
1779 A nested lock about to be unset must have been locked by @code{omp_set_nested_lock}
1780 or @code{omp_test_nested_lock} before. In addition, the lock must be held by the
1781 thread calling @code{omp_unset_nested_lock}. If the nesting count drops to zero, the
1782 lock becomes unlocked. If one ore more threads attempted to set the lock before,
1783 one of them is chosen to, again, set the lock to itself.
1786 @multitable @columnfractions .20 .80
1787 @item @emph{Prototype}: @tab @code{void omp_unset_nest_lock(omp_nest_lock_t *lock);}
1790 @item @emph{Fortran}:
1791 @multitable @columnfractions .20 .80
1792 @item @emph{Interface}: @tab @code{subroutine omp_unset_nest_lock(nvar)}
1793 @item @tab @code{integer(omp_nest_lock_kind), intent(inout) :: nvar}
1796 @item @emph{See also}:
1797 @ref{omp_set_nest_lock}
1799 @item @emph{Reference}:
1800 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.3.4.
1805 @node omp_destroy_nest_lock
1806 @section @code{omp_destroy_nest_lock} -- Destroy nested lock
1808 @item @emph{Description}:
1809 Destroy a nested lock. In order to be destroyed, a nested lock must be
1810 in the unlocked state and its nesting count must equal zero.
1813 @multitable @columnfractions .20 .80
1814 @item @emph{Prototype}: @tab @code{void omp_destroy_nest_lock(omp_nest_lock_t *);}
1817 @item @emph{Fortran}:
1818 @multitable @columnfractions .20 .80
1819 @item @emph{Interface}: @tab @code{subroutine omp_destroy_nest_lock(nvar)}
1820 @item @tab @code{integer(omp_nest_lock_kind), intent(inout) :: nvar}
1823 @item @emph{See also}:
1826 @item @emph{Reference}:
1827 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.3.2.
1833 @section @code{omp_get_wtick} -- Get timer precision
1835 @item @emph{Description}:
1836 Gets the timer precision, i.e., the number of seconds between two
1837 successive clock ticks.
1840 @multitable @columnfractions .20 .80
1841 @item @emph{Prototype}: @tab @code{double omp_get_wtick(void);}
1844 @item @emph{Fortran}:
1845 @multitable @columnfractions .20 .80
1846 @item @emph{Interface}: @tab @code{double precision function omp_get_wtick()}
1849 @item @emph{See also}:
1852 @item @emph{Reference}:
1853 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.4.2.
1859 @section @code{omp_get_wtime} -- Elapsed wall clock time
1861 @item @emph{Description}:
1862 Elapsed wall clock time in seconds. The time is measured per thread, no
1863 guarantee can be made that two distinct threads measure the same time.
1864 Time is measured from some "time in the past", which is an arbitrary time
1865 guaranteed not to change during the execution of the program.
1868 @multitable @columnfractions .20 .80
1869 @item @emph{Prototype}: @tab @code{double omp_get_wtime(void);}
1872 @item @emph{Fortran}:
1873 @multitable @columnfractions .20 .80
1874 @item @emph{Interface}: @tab @code{double precision function omp_get_wtime()}
1877 @item @emph{See also}:
1880 @item @emph{Reference}:
1881 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.4.1.
1886 @c ---------------------------------------------------------------------
1887 @c OpenMP Environment Variables
1888 @c ---------------------------------------------------------------------
1890 @node Environment Variables
1891 @chapter OpenMP Environment Variables
1893 The environment variables which beginning with @env{OMP_} are defined by
1894 section 4 of the OpenMP specification in version 4.0, while those
1895 beginning with @env{GOMP_} are GNU extensions.
1898 * OMP_CANCELLATION:: Set whether cancellation is activated
1899 * OMP_DISPLAY_ENV:: Show OpenMP version and environment variables
1900 * OMP_DEFAULT_DEVICE:: Set the device used in target regions
1901 * OMP_DYNAMIC:: Dynamic adjustment of threads
1902 * OMP_MAX_ACTIVE_LEVELS:: Set the maximum number of nested parallel regions
1903 * OMP_NESTED:: Nested parallel regions
1904 * OMP_NUM_THREADS:: Specifies the number of threads to use
1905 * OMP_PROC_BIND:: Whether theads may be moved between CPUs
1906 * OMP_PLACES:: Specifies on which CPUs the theads should be placed
1907 * OMP_STACKSIZE:: Set default thread stack size
1908 * OMP_SCHEDULE:: How threads are scheduled
1909 * OMP_THREAD_LIMIT:: Set the maximum number of threads
1910 * OMP_WAIT_POLICY:: How waiting threads are handled
1911 * GOMP_CPU_AFFINITY:: Bind threads to specific CPUs
1912 * GOMP_STACKSIZE:: Set default thread stack size
1913 * GOMP_SPINCOUNT:: Set the busy-wait spin count
1917 @node OMP_CANCELLATION
1918 @section @env{OMP_CANCELLATION} -- Set whether cancellation is activated
1919 @cindex Environment Variable
1921 @item @emph{Description}:
1922 If set to @code{TRUE}, the cancellation is activated. If set to @code{FALSE} or
1923 if unset, cancellation is disabled and the @code{cancel} construct is ignored.
1925 @item @emph{See also}:
1926 @ref{omp_get_cancellation}
1928 @item @emph{Reference}:
1929 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 4.11
1934 @node OMP_DISPLAY_ENV
1935 @section @env{OMP_DISPLAY_ENV} -- Show OpenMP version and environment variables
1936 @cindex Environment Variable
1938 @item @emph{Description}:
1939 If set to @code{TRUE}, the OpenMP version number and the values
1940 associated with the OpenMP environment variables are printed to @code{stderr}.
1941 If set to @code{VERBOSE}, it additionally shows the value of the environment
1942 variables which are GNU extensions. If undefined or set to @code{FALSE},
1943 this information will not be shown.
1946 @item @emph{Reference}:
1947 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 4.12
1952 @node OMP_DEFAULT_DEVICE
1953 @section @env{OMP_DEFAULT_DEVICE} -- Set the device used in target regions
1954 @cindex Environment Variable
1956 @item @emph{Description}:
1957 Set to choose the device which is used in a @code{target} region, unless the
1958 value is overridden by @code{omp_set_default_device} or by a @code{device}
1959 clause. The value shall be the nonnegative device number. If no device with
1960 the given device number exists, the code is executed on the host. If unset,
1961 device number 0 will be used.
1964 @item @emph{See also}:
1965 @ref{omp_get_default_device}, @ref{omp_set_default_device},
1967 @item @emph{Reference}:
1968 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 4.11
1974 @section @env{OMP_DYNAMIC} -- Dynamic adjustment of threads
1975 @cindex Environment Variable
1977 @item @emph{Description}:
1978 Enable or disable the dynamic adjustment of the number of threads
1979 within a team. The value of this environment variable shall be
1980 @code{TRUE} or @code{FALSE}. If undefined, dynamic adjustment is
1981 disabled by default.
1983 @item @emph{See also}:
1984 @ref{omp_set_dynamic}
1986 @item @emph{Reference}:
1987 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 4.3
1992 @node OMP_MAX_ACTIVE_LEVELS
1993 @section @env{OMP_MAX_ACTIVE_LEVELS} -- Set the maximum number of nested parallel regions
1994 @cindex Environment Variable
1996 @item @emph{Description}:
1997 Specifies the initial value for the maximum number of nested parallel
1998 regions. The value of this variable shall be a positive integer.
1999 If undefined, the number of active levels is unlimited.
2001 @item @emph{See also}:
2002 @ref{omp_set_max_active_levels}
2004 @item @emph{Reference}:
2005 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 4.9
2011 @section @env{OMP_NESTED} -- Nested parallel regions
2012 @cindex Environment Variable
2013 @cindex Implementation specific setting
2015 @item @emph{Description}:
2016 Enable or disable nested parallel regions, i.e., whether team members
2017 are allowed to create new teams. The value of this environment variable
2018 shall be @code{TRUE} or @code{FALSE}. If undefined, nested parallel
2019 regions are disabled by default.
2021 @item @emph{See also}:
2022 @ref{omp_set_nested}
2024 @item @emph{Reference}:
2025 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 4.6
2030 @node OMP_NUM_THREADS
2031 @section @env{OMP_NUM_THREADS} -- Specifies the number of threads to use
2032 @cindex Environment Variable
2033 @cindex Implementation specific setting
2035 @item @emph{Description}:
2036 Specifies the default number of threads to use in parallel regions. The
2037 value of this variable shall be a comma-separated list of positive integers;
2038 the value specified the number of threads to use for the corresponding nested
2039 level. If undefined one thread per CPU is used.
2041 @item @emph{See also}:
2042 @ref{omp_set_num_threads}
2044 @item @emph{Reference}:
2045 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 4.2
2051 @section @env{OMP_PROC_BIND} -- Whether theads may be moved between CPUs
2052 @cindex Environment Variable
2054 @item @emph{Description}:
2055 Specifies whether threads may be moved between processors. If set to
2056 @code{TRUE}, OpenMP theads should not be moved; if set to @code{FALSE}
2057 they may be moved. Alternatively, a comma separated list with the
2058 values @code{MASTER}, @code{CLOSE} and @code{SPREAD} can be used to specify
2059 the thread affinity policy for the corresponding nesting level. With
2060 @code{MASTER} the worker threads are in the same place partition as the
2061 master thread. With @code{CLOSE} those are kept close to the master thread
2062 in contiguous place partitions. And with @code{SPREAD} a sparse distribution
2063 across the place partitions is used.
2065 When undefined, @env{OMP_PROC_BIND} defaults to @code{TRUE} when
2066 @env{OMP_PLACES} or @env{GOMP_CPU_AFFINITY} is set and @code{FALSE} otherwise.
2068 @item @emph{See also}:
2069 @ref{OMP_PLACES}, @ref{GOMP_CPU_AFFINITY}, @ref{omp_get_proc_bind}
2071 @item @emph{Reference}:
2072 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 4.4
2078 @section @env{OMP_PLACES} -- Specifies on which CPUs the theads should be placed
2079 @cindex Environment Variable
2081 @item @emph{Description}:
2082 The thread placement can be either specified using an abstract name or by an
2083 explicit list of the places. The abstract names @code{threads}, @code{cores}
2084 and @code{sockets} can be optionally followed by a positive number in
2085 parentheses, which denotes the how many places shall be created. With
2086 @code{threads} each place corresponds to a single hardware thread; @code{cores}
2087 to a single core with the corresponding number of hardware threads; and with
2088 @code{sockets} the place corresponds to a single socket. The resulting
2089 placement can be shown by setting the @env{OMP_DISPLAY_ENV} environment
2092 Alternatively, the placement can be specified explicitly as comma-separated
2093 list of places. A place is specified by set of nonnegative numbers in curly
2094 braces, denoting the denoting the hardware threads. The hardware threads
2095 belonging to a place can either be specified as comma-separated list of
2096 nonnegative thread numbers or using an interval. Multiple places can also be
2097 either specified by a comma-separated list of places or by an interval. To
2098 specify an interval, a colon followed by the count is placed after after
2099 the hardware thread number or the place. Optionally, the length can be
2100 followed by a colon and the stride number -- otherwise a unit stride is
2101 assumed. For instance, the following specifies the same places list:
2102 @code{"@{0,1,2@}, @{3,4,6@}, @{7,8,9@}, @{10,11,12@}"};
2103 @code{"@{0:3@}, @{3:3@}, @{7:3@}, @{10:3@}"}; and @code{"@{0:2@}:4:3"}.
2105 If @env{OMP_PLACES} and @env{GOMP_CPU_AFFINITY} are unset and
2106 @env{OMP_PROC_BIND} is either unset or @code{false}, threads may be moved
2107 between CPUs following no placement policy.
2109 @item @emph{See also}:
2110 @ref{OMP_PROC_BIND}, @ref{GOMP_CPU_AFFINITY}, @ref{omp_get_proc_bind},
2111 @ref{OMP_DISPLAY_ENV}
2113 @item @emph{Reference}:
2114 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 4.5
2120 @section @env{OMP_STACKSIZE} -- Set default thread stack size
2121 @cindex Environment Variable
2123 @item @emph{Description}:
2124 Set the default thread stack size in kilobytes, unless the number
2125 is suffixed by @code{B}, @code{K}, @code{M} or @code{G}, in which
2126 case the size is, respectively, in bytes, kilobytes, megabytes
2127 or gigabytes. This is different from @code{pthread_attr_setstacksize}
2128 which gets the number of bytes as an argument. If the stack size cannot
2129 be set due to system constraints, an error is reported and the initial
2130 stack size is left unchanged. If undefined, the stack size is system
2133 @item @emph{Reference}:
2134 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 4.7
2140 @section @env{OMP_SCHEDULE} -- How threads are scheduled
2141 @cindex Environment Variable
2142 @cindex Implementation specific setting
2144 @item @emph{Description}:
2145 Allows to specify @code{schedule type} and @code{chunk size}.
2146 The value of the variable shall have the form: @code{type[,chunk]} where
2147 @code{type} is one of @code{static}, @code{dynamic}, @code{guided} or @code{auto}
2148 The optional @code{chunk} size shall be a positive integer. If undefined,
2149 dynamic scheduling and a chunk size of 1 is used.
2151 @item @emph{See also}:
2152 @ref{omp_set_schedule}
2154 @item @emph{Reference}:
2155 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Sections 2.7.1 and 4.1
2160 @node OMP_THREAD_LIMIT
2161 @section @env{OMP_THREAD_LIMIT} -- Set the maximum number of threads
2162 @cindex Environment Variable
2164 @item @emph{Description}:
2165 Specifies the number of threads to use for the whole program. The
2166 value of this variable shall be a positive integer. If undefined,
2167 the number of threads is not limited.
2169 @item @emph{See also}:
2170 @ref{OMP_NUM_THREADS}, @ref{omp_get_thread_limit}
2172 @item @emph{Reference}:
2173 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 4.10
2178 @node OMP_WAIT_POLICY
2179 @section @env{OMP_WAIT_POLICY} -- How waiting threads are handled
2180 @cindex Environment Variable
2182 @item @emph{Description}:
2183 Specifies whether waiting threads should be active or passive. If
2184 the value is @code{PASSIVE}, waiting threads should not consume CPU
2185 power while waiting; while the value is @code{ACTIVE} specifies that
2186 they should. If undefined, threads wait actively for a short time
2187 before waiting passively.
2189 @item @emph{See also}:
2190 @ref{GOMP_SPINCOUNT}
2192 @item @emph{Reference}:
2193 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 4.8
2198 @node GOMP_CPU_AFFINITY
2199 @section @env{GOMP_CPU_AFFINITY} -- Bind threads to specific CPUs
2200 @cindex Environment Variable
2202 @item @emph{Description}:
2203 Binds threads to specific CPUs. The variable should contain a space-separated
2204 or comma-separated list of CPUs. This list may contain different kinds of
2205 entries: either single CPU numbers in any order, a range of CPUs (M-N)
2206 or a range with some stride (M-N:S). CPU numbers are zero based. For example,
2207 @code{GOMP_CPU_AFFINITY="0 3 1-2 4-15:2"} will bind the initial thread
2208 to CPU 0, the second to CPU 3, the third to CPU 1, the fourth to
2209 CPU 2, the fifth to CPU 4, the sixth through tenth to CPUs 6, 8, 10, 12,
2210 and 14 respectively and then start assigning back from the beginning of
2211 the list. @code{GOMP_CPU_AFFINITY=0} binds all threads to CPU 0.
2213 There is no GNU OpenMP library routine to determine whether a CPU affinity
2214 specification is in effect. As a workaround, language-specific library
2215 functions, e.g., @code{getenv} in C or @code{GET_ENVIRONMENT_VARIABLE} in
2216 Fortran, may be used to query the setting of the @code{GOMP_CPU_AFFINITY}
2217 environment variable. A defined CPU affinity on startup cannot be changed
2218 or disabled during the runtime of the application.
2220 If both @env{GOMP_CPU_AFFINITY} and @env{OMP_PROC_BIND} are set,
2221 @env{OMP_PROC_BIND} has a higher precedence. If neither has been set and
2222 @env{OMP_PROC_BIND} is unset, or when @env{OMP_PROC_BIND} is set to
2223 @code{FALSE}, the host system will handle the assignment of threads to CPUs.
2225 @item @emph{See also}:
2226 @ref{OMP_PLACES}, @ref{OMP_PROC_BIND}
2231 @node GOMP_STACKSIZE
2232 @section @env{GOMP_STACKSIZE} -- Set default thread stack size
2233 @cindex Environment Variable
2234 @cindex Implementation specific setting
2236 @item @emph{Description}:
2237 Set the default thread stack size in kilobytes. This is different from
2238 @code{pthread_attr_setstacksize} which gets the number of bytes as an
2239 argument. If the stack size cannot be set due to system constraints, an
2240 error is reported and the initial stack size is left unchanged. If undefined,
2241 the stack size is system dependent.
2243 @item @emph{See also}:
2246 @item @emph{Reference}:
2247 @uref{http://gcc.gnu.org/ml/gcc-patches/2006-06/msg00493.html,
2248 GCC Patches Mailinglist},
2249 @uref{http://gcc.gnu.org/ml/gcc-patches/2006-06/msg00496.html,
2250 GCC Patches Mailinglist}
2255 @node GOMP_SPINCOUNT
2256 @section @env{GOMP_SPINCOUNT} -- Set the busy-wait spin count
2257 @cindex Environment Variable
2258 @cindex Implementation specific setting
2260 @item @emph{Description}:
2261 Determines how long a threads waits actively with consuming CPU power
2262 before waiting passively without consuming CPU power. The value may be
2263 either @code{INFINITE}, @code{INFINITY} to always wait actively or an
2264 integer which gives the number of spins of the busy-wait loop. The
2265 integer may optionally be followed by the following suffixes acting
2266 as multiplication factors: @code{k} (kilo, thousand), @code{M} (mega,
2267 million), @code{G} (giga, billion), or @code{T} (tera, trillion).
2268 If undefined, 0 is used when @env{OMP_WAIT_POLICY} is @code{PASSIVE},
2269 300,000 is used when @env{OMP_WAIT_POLICY} is undefined and
2270 30 billion is used when @env{OMP_WAIT_POLICY} is @code{ACTIVE}.
2271 If there are more OpenMP threads than available CPUs, 1000 and 100
2272 spins are used for @env{OMP_WAIT_POLICY} being @code{ACTIVE} or
2273 undefined, respectively; unless the @env{GOMP_SPINCOUNT} is lower
2274 or @env{OMP_WAIT_POLICY} is @code{PASSIVE}.
2276 @item @emph{See also}:
2277 @ref{OMP_WAIT_POLICY}
2282 @c ---------------------------------------------------------------------
2284 @c ---------------------------------------------------------------------
2286 @node The libgomp ABI
2287 @chapter The libgomp ABI
2289 The following sections present notes on the external ABI as
2290 presented by libgomp. Only maintainers should need them.
2293 * Implementing MASTER construct::
2294 * Implementing CRITICAL construct::
2295 * Implementing ATOMIC construct::
2296 * Implementing FLUSH construct::
2297 * Implementing BARRIER construct::
2298 * Implementing THREADPRIVATE construct::
2299 * Implementing PRIVATE clause::
2300 * Implementing FIRSTPRIVATE LASTPRIVATE COPYIN and COPYPRIVATE clauses::
2301 * Implementing REDUCTION clause::
2302 * Implementing PARALLEL construct::
2303 * Implementing FOR construct::
2304 * Implementing ORDERED construct::
2305 * Implementing SECTIONS construct::
2306 * Implementing SINGLE construct::
2307 * Implementing OpenACC's PARALLEL construct::
2311 @node Implementing MASTER construct
2312 @section Implementing MASTER construct
2315 if (omp_get_thread_num () == 0)
2319 Alternately, we generate two copies of the parallel subfunction
2320 and only include this in the version run by the master thread.
2321 Surely this is not worthwhile though...
2325 @node Implementing CRITICAL construct
2326 @section Implementing CRITICAL construct
2328 Without a specified name,
2331 void GOMP_critical_start (void);
2332 void GOMP_critical_end (void);
2335 so that we don't get COPY relocations from libgomp to the main
2338 With a specified name, use omp_set_lock and omp_unset_lock with
2339 name being transformed into a variable declared like
2342 omp_lock_t gomp_critical_user_<name> __attribute__((common))
2345 Ideally the ABI would specify that all zero is a valid unlocked
2346 state, and so we wouldn't need to initialize this at
2351 @node Implementing ATOMIC construct
2352 @section Implementing ATOMIC construct
2354 The target should implement the @code{__sync} builtins.
2356 Failing that we could add
2359 void GOMP_atomic_enter (void)
2360 void GOMP_atomic_exit (void)
2363 which reuses the regular lock code, but with yet another lock
2364 object private to the library.
2368 @node Implementing FLUSH construct
2369 @section Implementing FLUSH construct
2371 Expands to the @code{__sync_synchronize} builtin.
2375 @node Implementing BARRIER construct
2376 @section Implementing BARRIER construct
2379 void GOMP_barrier (void)
2383 @node Implementing THREADPRIVATE construct
2384 @section Implementing THREADPRIVATE construct
2386 In _most_ cases we can map this directly to @code{__thread}. Except
2387 that OMP allows constructors for C++ objects. We can either
2388 refuse to support this (how often is it used?) or we can
2389 implement something akin to .ctors.
2391 Even more ideally, this ctor feature is handled by extensions
2392 to the main pthreads library. Failing that, we can have a set
2393 of entry points to register ctor functions to be called.
2397 @node Implementing PRIVATE clause
2398 @section Implementing PRIVATE clause
2400 In association with a PARALLEL, or within the lexical extent
2401 of a PARALLEL block, the variable becomes a local variable in
2402 the parallel subfunction.
2404 In association with FOR or SECTIONS blocks, create a new
2405 automatic variable within the current function. This preserves
2406 the semantic of new variable creation.
2410 @node Implementing FIRSTPRIVATE LASTPRIVATE COPYIN and COPYPRIVATE clauses
2411 @section Implementing FIRSTPRIVATE LASTPRIVATE COPYIN and COPYPRIVATE clauses
2413 This seems simple enough for PARALLEL blocks. Create a private
2414 struct for communicating between the parent and subfunction.
2415 In the parent, copy in values for scalar and "small" structs;
2416 copy in addresses for others TREE_ADDRESSABLE types. In the
2417 subfunction, copy the value into the local variable.
2419 It is not clear what to do with bare FOR or SECTION blocks.
2420 The only thing I can figure is that we do something like:
2423 #pragma omp for firstprivate(x) lastprivate(y)
2424 for (int i = 0; i < n; ++i)
2441 where the "x=x" and "y=y" assignments actually have different
2442 uids for the two variables, i.e. not something you could write
2443 directly in C. Presumably this only makes sense if the "outer"
2444 x and y are global variables.
2446 COPYPRIVATE would work the same way, except the structure
2447 broadcast would have to happen via SINGLE machinery instead.
2451 @node Implementing REDUCTION clause
2452 @section Implementing REDUCTION clause
2454 The private struct mentioned in the previous section should have
2455 a pointer to an array of the type of the variable, indexed by the
2456 thread's @var{team_id}. The thread stores its final value into the
2457 array, and after the barrier, the master thread iterates over the
2458 array to collect the values.
2461 @node Implementing PARALLEL construct
2462 @section Implementing PARALLEL construct
2465 #pragma omp parallel
2474 void subfunction (void *data)
2481 GOMP_parallel_start (subfunction, &data, num_threads);
2482 subfunction (&data);
2483 GOMP_parallel_end ();
2487 void GOMP_parallel_start (void (*fn)(void *), void *data, unsigned num_threads)
2490 The @var{FN} argument is the subfunction to be run in parallel.
2492 The @var{DATA} argument is a pointer to a structure used to
2493 communicate data in and out of the subfunction, as discussed
2494 above with respect to FIRSTPRIVATE et al.
2496 The @var{NUM_THREADS} argument is 1 if an IF clause is present
2497 and false, or the value of the NUM_THREADS clause, if
2500 The function needs to create the appropriate number of
2501 threads and/or launch them from the dock. It needs to
2502 create the team structure and assign team ids.
2505 void GOMP_parallel_end (void)
2508 Tears down the team and returns us to the previous @code{omp_in_parallel()} state.
2512 @node Implementing FOR construct
2513 @section Implementing FOR construct
2516 #pragma omp parallel for
2517 for (i = lb; i <= ub; i++)
2524 void subfunction (void *data)
2527 while (GOMP_loop_static_next (&_s0, &_e0))
2530 for (i = _s0; i < _e1; i++)
2533 GOMP_loop_end_nowait ();
2536 GOMP_parallel_loop_static (subfunction, NULL, 0, lb, ub+1, 1, 0);
2538 GOMP_parallel_end ();
2542 #pragma omp for schedule(runtime)
2543 for (i = 0; i < n; i++)
2552 if (GOMP_loop_runtime_start (0, n, 1, &_s0, &_e0))
2555 for (i = _s0, i < _e0; i++)
2557 @} while (GOMP_loop_runtime_next (&_s0, _&e0));
2562 Note that while it looks like there is trickiness to propagating
2563 a non-constant STEP, there isn't really. We're explicitly allowed
2564 to evaluate it as many times as we want, and any variables involved
2565 should automatically be handled as PRIVATE or SHARED like any other
2566 variables. So the expression should remain evaluable in the
2567 subfunction. We can also pull it into a local variable if we like,
2568 but since its supposed to remain unchanged, we can also not if we like.
2570 If we have SCHEDULE(STATIC), and no ORDERED, then we ought to be
2571 able to get away with no work-sharing context at all, since we can
2572 simply perform the arithmetic directly in each thread to divide up
2573 the iterations. Which would mean that we wouldn't need to call any
2576 There are separate routines for handling loops with an ORDERED
2577 clause. Bookkeeping for that is non-trivial...
2581 @node Implementing ORDERED construct
2582 @section Implementing ORDERED construct
2585 void GOMP_ordered_start (void)
2586 void GOMP_ordered_end (void)
2591 @node Implementing SECTIONS construct
2592 @section Implementing SECTIONS construct
2597 #pragma omp sections
2611 for (i = GOMP_sections_start (3); i != 0; i = GOMP_sections_next ())
2628 @node Implementing SINGLE construct
2629 @section Implementing SINGLE construct
2643 if (GOMP_single_start ())
2651 #pragma omp single copyprivate(x)
2658 datap = GOMP_single_copy_start ();
2663 GOMP_single_copy_end (&data);
2672 @node Implementing OpenACC's PARALLEL construct
2673 @section Implementing OpenACC's PARALLEL construct
2676 void GOACC_parallel ()
2681 @c ---------------------------------------------------------------------
2683 @c ---------------------------------------------------------------------
2685 @node Reporting Bugs
2686 @chapter Reporting Bugs
2688 Bugs in the GNU OpenACC or OpenMP implementation should be reported via
2689 @uref{http://gcc.gnu.org/bugzilla/, Bugzilla}. As appropriate, please
2690 add "openacc", or "openmp", or both to the keywords field in the bug
2695 @c ---------------------------------------------------------------------
2696 @c GNU General Public License
2697 @c ---------------------------------------------------------------------
2699 @include gpl_v3.texi
2703 @c ---------------------------------------------------------------------
2704 @c GNU Free Documentation License
2705 @c ---------------------------------------------------------------------
2711 @c ---------------------------------------------------------------------
2712 @c Funding Free Software
2713 @c ---------------------------------------------------------------------
2715 @include funding.texi
2717 @c ---------------------------------------------------------------------
2719 @c ---------------------------------------------------------------------
2722 @unnumbered Library Index