1 \input texinfo @c -*-texinfo-*-
4 @setfilename libgomp.info
10 Copyright @copyright{} 2006-2021 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 Offloading and Multi Processing Runtime Library.
37 This manual documents libgomp, the GNU Offloading and Multi Processing
38 Runtime library. This is the GNU implementation of the OpenMP and
39 OpenACC APIs for parallel and accelerator programming in C/C++ and
42 Published by the Free Software Foundation
43 51 Franklin Street, Fifth Floor
44 Boston, MA 02110-1301 USA
50 @setchapternewpage odd
53 @title GNU Offloading and Multi Processing Runtime Library
54 @subtitle The GNU OpenMP and OpenACC Implementation
56 @vskip 0pt plus 1filll
57 @comment For the @value{version-GCC} Version*
59 Published by the Free Software Foundation @*
60 51 Franklin Street, Fifth Floor@*
61 Boston, MA 02110-1301, USA@*
71 @node Top, Enabling OpenMP
75 This manual documents the usage of libgomp, the GNU Offloading and
76 Multi Processing Runtime Library. This includes the GNU
77 implementation of the @uref{https://www.openmp.org, OpenMP} Application
78 Programming Interface (API) for multi-platform shared-memory parallel
79 programming in C/C++ and Fortran, and the GNU implementation of the
80 @uref{https://www.openacc.org, OpenACC} Application Programming
81 Interface (API) for offloading of code to accelerator devices in C/C++
84 Originally, libgomp implemented the GNU OpenMP Runtime Library. Based
85 on this, support for OpenACC and offloading (both OpenACC and OpenMP
86 4's target construct) has been added later on, and the library's name
87 changed to GNU Offloading and Multi Processing Runtime Library.
92 @comment When you add a new menu item, please keep the right hand
93 @comment aligned to the same column. Do not use tabs. This provides
94 @comment better formatting.
97 * Enabling OpenMP:: How to enable OpenMP for your applications.
98 * OpenMP Implementation Status:: List of implemented features by OpenMP version
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 * Enabling OpenACC:: How to enable OpenACC for your
107 * OpenACC Runtime Library Routines:: The OpenACC runtime application
108 programming interface.
109 * OpenACC Environment Variables:: Influencing OpenACC runtime behavior with
110 environment variables.
111 * CUDA Streams Usage:: Notes on the implementation of
112 asynchronous operations.
113 * OpenACC Library Interoperability:: OpenACC library interoperability with the
114 NVIDIA CUBLAS library.
115 * OpenACC Profiling Interface::
116 * The libgomp ABI:: Notes on the external ABI presented by libgomp.
117 * Reporting Bugs:: How to report bugs in the GNU Offloading and
118 Multi Processing Runtime Library.
119 * Copying:: GNU general public license says
120 how you can copy and share libgomp.
121 * GNU Free Documentation License::
122 How you can copy and share this manual.
123 * Funding:: How to help assure continued work for free
125 * Library Index:: Index of this documentation.
129 @c ---------------------------------------------------------------------
131 @c ---------------------------------------------------------------------
133 @node Enabling OpenMP
134 @chapter Enabling OpenMP
136 To activate the OpenMP extensions for C/C++ and Fortran, the compile-time
137 flag @command{-fopenmp} must be specified. This enables the OpenMP directive
138 @code{#pragma omp} in C/C++ and @code{!$omp} directives in free form,
139 @code{c$omp}, @code{*$omp} and @code{!$omp} directives in fixed form,
140 @code{!$} conditional compilation sentinels in free form and @code{c$},
141 @code{*$} and @code{!$} sentinels in fixed form, for Fortran. The flag also
142 arranges for automatic linking of the OpenMP runtime library
143 (@ref{Runtime Library Routines}).
145 A complete description of all OpenMP directives may be found in the
146 @uref{https://www.openmp.org, OpenMP Application Program Interface} manuals.
147 See also @ref{OpenMP Implementation Status}.
150 @c ---------------------------------------------------------------------
151 @c OpenMP Implementation Status
152 @c ---------------------------------------------------------------------
154 @node OpenMP Implementation Status
155 @chapter OpenMP Implementation Status
158 * OpenMP 4.5:: Feature completion status to 4.5 specification
159 * OpenMP 5.0:: Feature completion status to 5.0 specification
160 * OpenMP 5.1:: Feature completion status to 5.1 specification
163 The @code{_OPENMP} preprocessor macro and Fortran's @code{openmp_version}
164 parameter, provided by @code{omp_lib.h} and the @code{omp_lib} module, have
165 the value @code{201511} (i.e. OpenMP 4.5).
170 The OpenMP 4.5 specification is fully supported.
175 @unnumberedsubsec New features listed in Appendix B of the OpenMP specification
176 @c This list is sorted as in OpenMP 5.1's B.3 not as in OpenMP 5.0's B.2
178 @multitable @columnfractions .60 .10 .25
179 @headitem Description @tab Status @tab Comments
180 @item Array shaping @tab N @tab
181 @item Array sections with non-unit strides in C and C++ @tab N @tab
182 @item Iterators @tab Y @tab
183 @item @code{metadirective} directive @tab N @tab
184 @item @code{declare variant} directive
185 @tab P @tab Only C and C++, simd traits not handled correctly
186 @item @emph{target-offload-var} ICV and @code{OMP_TARGET_OFFLOAD}
187 env variable @tab Y @tab
188 @item Nested-parallel changes to @emph{max-active-levels-var} ICV @tab Y @tab
189 @item @code{requires} directive @tab P
190 @tab Only fulfillable requirement is @code{atomic_default_mem_order}
191 @item @code{teams} construct outside an enclosing target region @tab Y @tab
192 @item Non-rectangular loop nests @tab Y @tab
193 @item @code{!=} as relational-op in canonical loop form for C/C++ @tab Y @tab
194 @item @code{nonmonotonic} as default loop schedule modifier for worksharing-loop
195 constructs @tab Y @tab
196 @item Collapse of associated loops that are imperfectly nested loops @tab N @tab
197 @item Clauses @code{if}, @code{nontemporal} and @code{order(concurrent)} in
198 @code{simd} construct @tab Y @tab
199 @item @code{atomic} constructs in @code{simd} @tab Y @tab
200 @item @code{loop} construct @tab Y @tab
201 @item @code{order(concurrent)} clause @tab Y @tab
202 @item @code{scan} directive and @code{in_scan} modifier for the
203 @code{reduction} clause @tab Y @tab
204 @item @code{in_reduction} clause on @code{task} constructs @tab Y @tab
205 @item @code{in_reduction} clause on @code{target} constructs @tab P
206 @tab Only C/C++, @code{nowait} only stub
207 @item @code{task_reduction} clause with @code{taskgroup} @tab Y @tab
208 @item @code{task} modifier to @code{reduction} clause @tab Y @tab
209 @item @code{affinity} clause to @code{task} construct @tab Y @tab Stub only
210 @item @code{detach} clause to @code{task} construct @tab Y @tab
211 @item @code{omp_fulfill_event} runtime routine @tab Y @tab
212 @item @code{reduction} and @code{in_reduction} clauses on @code{taskloop}
213 and @code{taskloop simd} constructs @tab Y @tab
214 @item @code{taskloop} construct cancelable by @code{cancel} construct
216 @item @code{mutexinouset} @emph{dependence-type} for @code{depend} clause
218 @item Predefined memory spaces, memory allocators, allocator traits
219 @tab Y @tab Some are only stubs
220 @item Memory management routines @tab Y @tab
221 @item @code{allocate} directive @tab N @tab
222 @item @code{allocate} clause @tab P @tab initial support in C/C++ only
223 @item @code{use_device_addr} clause on @code{target data} @tab Y @tab
224 @item @code{ancestor} modifier on @code{device} clause
225 @tab P @tab Reverse offload unsupported
226 @item Implicit declare target directive @tab Y @tab
227 @item Discontiguous array section with @code{target update} construct
229 @item C/C++'s lvalue expressions in @code{to}, @code{from}
230 and @code{map} clauses @tab N @tab
231 @item C/C++'s lvalue expressions in @code{depend} clauses @tab Y @tab
232 @item Nested @code{declare target} directive @tab Y @tab
233 @item Combined @code{master} constructs @tab Y @tab
234 @item @code{depend} clause on @code{taskwait} @tab Y @tab
235 @item Weak memory ordering clauses on @code{atomic} and @code{flush} construct
237 @item @code{hint} clause on the @code{atomic} construct @tab Y @tab Stub only
238 @item @code{depobj} construct and depend objects @tab Y @tab
239 @item Lock hints were renamed to synchronization hints @tab Y @tab
240 @item @code{conditional} modifier to @code{lastprivate} clause @tab Y @tab
241 @item Map-order clarifications @tab P @tab
242 @item @code{close} @emph{map-type-modifier} @tab Y @tab
243 @item Mapping C/C++ pointer variables and to assign the address of
244 device memory mapped by an array section @tab P @tab
245 @item Mapping of Fortran pointer and allocatable variables, including pointer
246 and allocatable components of variables
247 @tab P @tab Mapping of vars with allocatable components unspported
248 @item @code{defaultmap} extensions @tab Y @tab
249 @item @code{declare mapper} directive @tab N @tab
250 @item @code{omp_get_supported_active_levels} routine @tab Y @tab
251 @item Runtime routines and environment variables to display runtime thread
252 affinity information @tab Y @tab
253 @item @code{omp_pause_resource} and @code{omp_pause_resource_all} runtime
255 @item @code{omp_get_device_num} runtime routine @tab Y @tab
256 @item OMPT interface @tab N @tab
257 @item OMPD interface @tab N @tab
260 @unnumberedsubsec Other new OpenMP 5.0 features
262 @multitable @columnfractions .60 .10 .25
263 @headitem Description @tab Status @tab Comments
264 @item Supporting C++'s range-based for loop @tab Y @tab
271 @unnumberedsubsec New features listed in Appendix B of the OpenMP specification
273 @multitable @columnfractions .60 .10 .25
274 @headitem Description @tab Status @tab Comments
275 @item OpenMP directive as C++ attribute specifiers @tab Y @tab
276 @item @code{omp_all_memory} reserved locator @tab N @tab
277 @item @emph{target_device trait} in OpenMP Context @tab N @tab
278 @item @code{target_device} selector set in context selectors @tab N @tab
279 @item C/C++'s @code{declare variant} directive: elision support of
280 preprocessed code @tab N @tab
281 @item @code{declare variant}: new clauses @code{adjust_args} and
282 @code{append_args} @tab N @tab
283 @item @code{dispatch} construct @tab N @tab
284 @item device-specific ICV settings the environment variables @tab N @tab
285 @item assume directive @tab N @tab
286 @item @code{nothing} directive @tab Y @tab
287 @item @code{error} directive @tab Y @tab
288 @item @code{masked} construct @tab Y @tab
289 @item @code{scope} directive @tab Y @tab
290 @item Loop transformation constructs @tab N @tab
291 @item @code{strict} modifier in the @code{grainsize} and @code{num_tasks}
292 clauses of the taskloop construct @tab Y @tab
293 @item @code{align} clause/modifier in @code{allocate} directive/clause
294 and @code{allocator} directive @tab N @tab
295 @item @code{thread_limit} clause to @code{target} construct @tab N @tab
296 @item @code{has_device_addr} clause to @code{target} construct @tab N @tab
297 @item iterators in @code{target update} motion clauses and @code{map}
299 @item indirect calls to the device version of a procedure or function in
300 @code{target} regions @tab N @tab
301 @item @code{interop} directive @tab N @tab
302 @item @code{omp_interop_t} object support in runtime routines @tab N @tab
303 @item @code{nowait} clause in @code{taskwait} directive @tab N @tab
304 @item Extensions to the @code{atomic} directive @tab N @tab
305 @item @code{seq_cst} clause on a @code{flush} construct @tab Y @tab
306 @item @code{inoutset} argument to the @code{depend} clause @tab N @tab
307 @item @code{private} and @code{firstprivate} argument to @code{default}
308 clause in C and C++ @tab Y @tab
309 @item @code{present} argument to @code{defaultmap} clause @tab N @tab
310 @item @code{omp_set_num_teams}, @code{omp_set_teams_thread_limit},
311 @code{omp_get_max_teams}, @code{omp_get_teams_thread_limit} runtime
313 @item @code{omp_target_is_accessible} runtime routine @tab N @tab
314 @item @code{omp_target_memcpy_async} and @code{omp_target_memcpy_rect_async}
315 runtime routines @tab N @tab
316 @item @code{omp_get_mapped_ptr} runtime routine @tab N @tab
317 @item @code{omp_calloc}, @code{omp_realloc}, @code{omp_aligned_alloc} and
318 @code{omp_aligned_calloc} runtime routines @tab N @tab
319 @item @code{omp_alloctrait_key_t} enum: @code{omp_atv_serialized} added,
320 @code{omp_atv_default} changed @tab Y @tab
321 @item @code{omp_display_env} runtime routine @tab P
322 @tab Not inside @code{target} regions
323 @item @code{ompt_scope_endpoint_t} enum: @code{ompt_scope_beginend} @tab N @tab
324 @item @code{ompt_sync_region_t} enum additions @tab N @tab
325 @item @code{ompt_state_t} enum: @code{ompt_state_wait_barrier_implementation}
326 and @code{ompt_state_wait_barrier_teams} @tab N @tab
327 @item @code{ompt_callback_target_data_op_emi_t},
328 @code{ompt_callback_target_emi_t}, @code{ompt_callback_target_map_emi_t}
329 and @code{ompt_callback_target_submit_emi_t} @tab N @tab
330 @item @code{ompt_callback_error_t} type @tab N @tab
331 @item @code{OMP_PLACES} syntax was extension @tab N @tab
332 @item @code{OMP_NUM_TEAMS} and @code{OMP_TEAMS_THREAD_LIMIT} environment
333 variables @tab N @tab
336 @unnumberedsubsec Other new OpenMP 5.1 features
338 @multitable @columnfractions .60 .10 .25
339 @headitem Description @tab Status @tab Comments
340 @item Suppport of strictly structured blocks in Fortran @tab N @tab
344 @c ---------------------------------------------------------------------
345 @c OpenMP Runtime Library Routines
346 @c ---------------------------------------------------------------------
348 @node Runtime Library Routines
349 @chapter OpenMP Runtime Library Routines
351 The runtime routines described here are defined by Section 3 of the OpenMP
352 specification in version 4.5. The routines are structured in following
356 Control threads, processors and the parallel environment. They have C
357 linkage, and do not throw exceptions.
359 * omp_get_active_level:: Number of active parallel regions
360 * omp_get_ancestor_thread_num:: Ancestor thread ID
361 * omp_get_cancellation:: Whether cancellation support is enabled
362 * omp_get_default_device:: Get the default device for target regions
363 * omp_get_device_num:: Get device that current thread is running on
364 * omp_get_dynamic:: Dynamic teams setting
365 * omp_get_initial_device:: Device number of host device
366 * omp_get_level:: Number of parallel regions
367 * omp_get_max_active_levels:: Current maximum number of active regions
368 * omp_get_max_task_priority:: Maximum task priority value that can be set
369 * omp_get_max_threads:: Maximum number of threads of parallel region
370 * omp_get_nested:: Nested parallel regions
371 * omp_get_num_devices:: Number of target devices
372 * omp_get_num_procs:: Number of processors online
373 * omp_get_num_teams:: Number of teams
374 * omp_get_num_threads:: Size of the active team
375 * omp_get_proc_bind:: Whether theads may be moved between CPUs
376 * omp_get_schedule:: Obtain the runtime scheduling method
377 * omp_get_supported_active_levels:: Maximum number of active regions supported
378 * omp_get_team_num:: Get team number
379 * omp_get_team_size:: Number of threads in a team
380 * omp_get_thread_limit:: Maximum number of threads
381 * omp_get_thread_num:: Current thread ID
382 * omp_in_parallel:: Whether a parallel region is active
383 * omp_in_final:: Whether in final or included task region
384 * omp_is_initial_device:: Whether executing on the host device
385 * omp_set_default_device:: Set the default device for target regions
386 * omp_set_dynamic:: Enable/disable dynamic teams
387 * omp_set_max_active_levels:: Limits the number of active parallel regions
388 * omp_set_nested:: Enable/disable nested parallel regions
389 * omp_set_num_threads:: Set upper team size limit
390 * omp_set_schedule:: Set the runtime scheduling method
392 Initialize, set, test, unset and destroy simple and nested locks.
394 * omp_init_lock:: Initialize simple lock
395 * omp_set_lock:: Wait for and set simple lock
396 * omp_test_lock:: Test and set simple lock if available
397 * omp_unset_lock:: Unset simple lock
398 * omp_destroy_lock:: Destroy simple lock
399 * omp_init_nest_lock:: Initialize nested lock
400 * omp_set_nest_lock:: Wait for and set simple lock
401 * omp_test_nest_lock:: Test and set nested lock if available
402 * omp_unset_nest_lock:: Unset nested lock
403 * omp_destroy_nest_lock:: Destroy nested lock
405 Portable, thread-based, wall clock timer.
407 * omp_get_wtick:: Get timer precision.
408 * omp_get_wtime:: Elapsed wall clock time.
410 Support for event objects.
412 * omp_fulfill_event:: Fulfill and destroy an OpenMP event.
417 @node omp_get_active_level
418 @section @code{omp_get_active_level} -- Number of parallel regions
420 @item @emph{Description}:
421 This function returns the nesting level for the active parallel blocks,
422 which enclose the calling call.
425 @multitable @columnfractions .20 .80
426 @item @emph{Prototype}: @tab @code{int omp_get_active_level(void);}
429 @item @emph{Fortran}:
430 @multitable @columnfractions .20 .80
431 @item @emph{Interface}: @tab @code{integer function omp_get_active_level()}
434 @item @emph{See also}:
435 @ref{omp_get_level}, @ref{omp_get_max_active_levels}, @ref{omp_set_max_active_levels}
437 @item @emph{Reference}:
438 @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.20.
443 @node omp_get_ancestor_thread_num
444 @section @code{omp_get_ancestor_thread_num} -- Ancestor thread ID
446 @item @emph{Description}:
447 This function returns the thread identification number for the given
448 nesting level of the current thread. For values of @var{level} outside
449 zero to @code{omp_get_level} -1 is returned; if @var{level} is
450 @code{omp_get_level} the result is identical to @code{omp_get_thread_num}.
453 @multitable @columnfractions .20 .80
454 @item @emph{Prototype}: @tab @code{int omp_get_ancestor_thread_num(int level);}
457 @item @emph{Fortran}:
458 @multitable @columnfractions .20 .80
459 @item @emph{Interface}: @tab @code{integer function omp_get_ancestor_thread_num(level)}
460 @item @tab @code{integer level}
463 @item @emph{See also}:
464 @ref{omp_get_level}, @ref{omp_get_thread_num}, @ref{omp_get_team_size}
466 @item @emph{Reference}:
467 @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.18.
472 @node omp_get_cancellation
473 @section @code{omp_get_cancellation} -- Whether cancellation support is enabled
475 @item @emph{Description}:
476 This function returns @code{true} if cancellation is activated, @code{false}
477 otherwise. Here, @code{true} and @code{false} represent their language-specific
478 counterparts. Unless @env{OMP_CANCELLATION} is set true, cancellations are
482 @multitable @columnfractions .20 .80
483 @item @emph{Prototype}: @tab @code{int omp_get_cancellation(void);}
486 @item @emph{Fortran}:
487 @multitable @columnfractions .20 .80
488 @item @emph{Interface}: @tab @code{logical function omp_get_cancellation()}
491 @item @emph{See also}:
492 @ref{OMP_CANCELLATION}
494 @item @emph{Reference}:
495 @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.9.
500 @node omp_get_default_device
501 @section @code{omp_get_default_device} -- Get the default device for target regions
503 @item @emph{Description}:
504 Get the default device for target regions without device clause.
507 @multitable @columnfractions .20 .80
508 @item @emph{Prototype}: @tab @code{int omp_get_default_device(void);}
511 @item @emph{Fortran}:
512 @multitable @columnfractions .20 .80
513 @item @emph{Interface}: @tab @code{integer function omp_get_default_device()}
516 @item @emph{See also}:
517 @ref{OMP_DEFAULT_DEVICE}, @ref{omp_set_default_device}
519 @item @emph{Reference}:
520 @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.30.
525 @node omp_get_dynamic
526 @section @code{omp_get_dynamic} -- Dynamic teams setting
528 @item @emph{Description}:
529 This function returns @code{true} if enabled, @code{false} otherwise.
530 Here, @code{true} and @code{false} represent their language-specific
533 The dynamic team setting may be initialized at startup by the
534 @env{OMP_DYNAMIC} environment variable or at runtime using
535 @code{omp_set_dynamic}. If undefined, dynamic adjustment is
539 @multitable @columnfractions .20 .80
540 @item @emph{Prototype}: @tab @code{int omp_get_dynamic(void);}
543 @item @emph{Fortran}:
544 @multitable @columnfractions .20 .80
545 @item @emph{Interface}: @tab @code{logical function omp_get_dynamic()}
548 @item @emph{See also}:
549 @ref{omp_set_dynamic}, @ref{OMP_DYNAMIC}
551 @item @emph{Reference}:
552 @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.8.
557 @node omp_get_initial_device
558 @section @code{omp_get_initial_device} -- Return device number of initial device
560 @item @emph{Description}:
561 This function returns a device number that represents the host device.
562 For OpenMP 5.1, this must be equal to the value returned by the
563 @code{omp_get_num_devices} function.
566 @multitable @columnfractions .20 .80
567 @item @emph{Prototype}: @tab @code{int omp_get_initial_device(void);}
570 @item @emph{Fortran}:
571 @multitable @columnfractions .20 .80
572 @item @emph{Interface}: @tab @code{integer function omp_get_initial_device()}
575 @item @emph{See also}:
576 @ref{omp_get_num_devices}
578 @item @emph{Reference}:
579 @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.35.
584 @node omp_get_device_num
585 @section @code{omp_get_device_num} -- Return device number of current device
587 @item @emph{Description}:
588 This function returns a device number that represents the device that the
589 current thread is executing on. For OpenMP 5.0, this must be equal to the
590 value returned by the @code{omp_get_initial_device} function when called
594 @multitable @columnfractions .20 .80
595 @item @emph{Prototype}: @tab @code{int omp_get_device_num(void);}
598 @item @emph{Fortran}:
599 @multitable @columnfractions .20 .80
600 @item @emph{Interface}: @tab @code{integer function omp_get_device_num()}
603 @item @emph{See also}:
604 @ref{omp_get_initial_device}
606 @item @emph{Reference}:
607 @uref{https://www.openmp.org, OpenMP specification v5.0}, Section 3.2.37.
613 @section @code{omp_get_level} -- Obtain the current nesting level
615 @item @emph{Description}:
616 This function returns the nesting level for the parallel blocks,
617 which enclose the calling call.
620 @multitable @columnfractions .20 .80
621 @item @emph{Prototype}: @tab @code{int omp_get_level(void);}
624 @item @emph{Fortran}:
625 @multitable @columnfractions .20 .80
626 @item @emph{Interface}: @tab @code{integer function omp_level()}
629 @item @emph{See also}:
630 @ref{omp_get_active_level}
632 @item @emph{Reference}:
633 @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.17.
638 @node omp_get_max_active_levels
639 @section @code{omp_get_max_active_levels} -- Current maximum number of active regions
641 @item @emph{Description}:
642 This function obtains the maximum allowed number of nested, active parallel regions.
645 @multitable @columnfractions .20 .80
646 @item @emph{Prototype}: @tab @code{int omp_get_max_active_levels(void);}
649 @item @emph{Fortran}:
650 @multitable @columnfractions .20 .80
651 @item @emph{Interface}: @tab @code{integer function omp_get_max_active_levels()}
654 @item @emph{See also}:
655 @ref{omp_set_max_active_levels}, @ref{omp_get_active_level}
657 @item @emph{Reference}:
658 @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.16.
662 @node omp_get_max_task_priority
663 @section @code{omp_get_max_task_priority} -- Maximum priority value
664 that can be set for tasks.
666 @item @emph{Description}:
667 This function obtains the maximum allowed priority number for tasks.
670 @multitable @columnfractions .20 .80
671 @item @emph{Prototype}: @tab @code{int omp_get_max_task_priority(void);}
674 @item @emph{Fortran}:
675 @multitable @columnfractions .20 .80
676 @item @emph{Interface}: @tab @code{integer function omp_get_max_task_priority()}
679 @item @emph{Reference}:
680 @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.29.
684 @node omp_get_max_threads
685 @section @code{omp_get_max_threads} -- Maximum number of threads of parallel region
687 @item @emph{Description}:
688 Return the maximum number of threads used for the current parallel region
689 that does not use the clause @code{num_threads}.
692 @multitable @columnfractions .20 .80
693 @item @emph{Prototype}: @tab @code{int omp_get_max_threads(void);}
696 @item @emph{Fortran}:
697 @multitable @columnfractions .20 .80
698 @item @emph{Interface}: @tab @code{integer function omp_get_max_threads()}
701 @item @emph{See also}:
702 @ref{omp_set_num_threads}, @ref{omp_set_dynamic}, @ref{omp_get_thread_limit}
704 @item @emph{Reference}:
705 @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.3.
711 @section @code{omp_get_nested} -- Nested parallel regions
713 @item @emph{Description}:
714 This function returns @code{true} if nested parallel regions are
715 enabled, @code{false} otherwise. Here, @code{true} and @code{false}
716 represent their language-specific counterparts.
718 The state of nested parallel regions at startup depends on several
719 environment variables. If @env{OMP_MAX_ACTIVE_LEVELS} is defined
720 and is set to greater than one, then nested parallel regions will be
721 enabled. If not defined, then the value of the @env{OMP_NESTED}
722 environment variable will be followed if defined. If neither are
723 defined, then if either @env{OMP_NUM_THREADS} or @env{OMP_PROC_BIND}
724 are defined with a list of more than one value, then nested parallel
725 regions are enabled. If none of these are defined, then nested parallel
726 regions are disabled by default.
728 Nested parallel regions can be enabled or disabled at runtime using
729 @code{omp_set_nested}, or by setting the maximum number of nested
730 regions with @code{omp_set_max_active_levels} to one to disable, or
734 @multitable @columnfractions .20 .80
735 @item @emph{Prototype}: @tab @code{int omp_get_nested(void);}
738 @item @emph{Fortran}:
739 @multitable @columnfractions .20 .80
740 @item @emph{Interface}: @tab @code{logical function omp_get_nested()}
743 @item @emph{See also}:
744 @ref{omp_set_max_active_levels}, @ref{omp_set_nested},
745 @ref{OMP_MAX_ACTIVE_LEVELS}, @ref{OMP_NESTED}
747 @item @emph{Reference}:
748 @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.11.
753 @node omp_get_num_devices
754 @section @code{omp_get_num_devices} -- Number of target devices
756 @item @emph{Description}:
757 Returns the number of target devices.
760 @multitable @columnfractions .20 .80
761 @item @emph{Prototype}: @tab @code{int omp_get_num_devices(void);}
764 @item @emph{Fortran}:
765 @multitable @columnfractions .20 .80
766 @item @emph{Interface}: @tab @code{integer function omp_get_num_devices()}
769 @item @emph{Reference}:
770 @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.31.
775 @node omp_get_num_procs
776 @section @code{omp_get_num_procs} -- Number of processors online
778 @item @emph{Description}:
779 Returns the number of processors online on that device.
782 @multitable @columnfractions .20 .80
783 @item @emph{Prototype}: @tab @code{int omp_get_num_procs(void);}
786 @item @emph{Fortran}:
787 @multitable @columnfractions .20 .80
788 @item @emph{Interface}: @tab @code{integer function omp_get_num_procs()}
791 @item @emph{Reference}:
792 @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.5.
797 @node omp_get_num_teams
798 @section @code{omp_get_num_teams} -- Number of teams
800 @item @emph{Description}:
801 Returns the number of teams in the current team region.
804 @multitable @columnfractions .20 .80
805 @item @emph{Prototype}: @tab @code{int omp_get_num_teams(void);}
808 @item @emph{Fortran}:
809 @multitable @columnfractions .20 .80
810 @item @emph{Interface}: @tab @code{integer function omp_get_num_teams()}
813 @item @emph{Reference}:
814 @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.32.
819 @node omp_get_num_threads
820 @section @code{omp_get_num_threads} -- Size of the active team
822 @item @emph{Description}:
823 Returns the number of threads in the current team. In a sequential section of
824 the program @code{omp_get_num_threads} returns 1.
826 The default team size may be initialized at startup by the
827 @env{OMP_NUM_THREADS} environment variable. At runtime, the size
828 of the current team may be set either by the @code{NUM_THREADS}
829 clause or by @code{omp_set_num_threads}. If none of the above were
830 used to define a specific value and @env{OMP_DYNAMIC} is disabled,
831 one thread per CPU online is used.
834 @multitable @columnfractions .20 .80
835 @item @emph{Prototype}: @tab @code{int omp_get_num_threads(void);}
838 @item @emph{Fortran}:
839 @multitable @columnfractions .20 .80
840 @item @emph{Interface}: @tab @code{integer function omp_get_num_threads()}
843 @item @emph{See also}:
844 @ref{omp_get_max_threads}, @ref{omp_set_num_threads}, @ref{OMP_NUM_THREADS}
846 @item @emph{Reference}:
847 @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.2.
852 @node omp_get_proc_bind
853 @section @code{omp_get_proc_bind} -- Whether theads may be moved between CPUs
855 @item @emph{Description}:
856 This functions returns the currently active thread affinity policy, which is
857 set via @env{OMP_PROC_BIND}. Possible values are @code{omp_proc_bind_false},
858 @code{omp_proc_bind_true}, @code{omp_proc_bind_primary},
859 @code{omp_proc_bind_master}, @code{omp_proc_bind_close} and @code{omp_proc_bind_spread},
860 where @code{omp_proc_bind_master} is an alias for @code{omp_proc_bind_primary}.
863 @multitable @columnfractions .20 .80
864 @item @emph{Prototype}: @tab @code{omp_proc_bind_t omp_get_proc_bind(void);}
867 @item @emph{Fortran}:
868 @multitable @columnfractions .20 .80
869 @item @emph{Interface}: @tab @code{integer(kind=omp_proc_bind_kind) function omp_get_proc_bind()}
872 @item @emph{See also}:
873 @ref{OMP_PROC_BIND}, @ref{OMP_PLACES}, @ref{GOMP_CPU_AFFINITY},
875 @item @emph{Reference}:
876 @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.22.
881 @node omp_get_schedule
882 @section @code{omp_get_schedule} -- Obtain the runtime scheduling method
884 @item @emph{Description}:
885 Obtain the runtime scheduling method. The @var{kind} argument will be
886 set to the value @code{omp_sched_static}, @code{omp_sched_dynamic},
887 @code{omp_sched_guided} or @code{omp_sched_auto}. The second argument,
888 @var{chunk_size}, is set to the chunk size.
891 @multitable @columnfractions .20 .80
892 @item @emph{Prototype}: @tab @code{void omp_get_schedule(omp_sched_t *kind, int *chunk_size);}
895 @item @emph{Fortran}:
896 @multitable @columnfractions .20 .80
897 @item @emph{Interface}: @tab @code{subroutine omp_get_schedule(kind, chunk_size)}
898 @item @tab @code{integer(kind=omp_sched_kind) kind}
899 @item @tab @code{integer chunk_size}
902 @item @emph{See also}:
903 @ref{omp_set_schedule}, @ref{OMP_SCHEDULE}
905 @item @emph{Reference}:
906 @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.13.
910 @node omp_get_supported_active_levels
911 @section @code{omp_get_supported_active_levels} -- Maximum number of active regions supported
913 @item @emph{Description}:
914 This function returns the maximum number of nested, active parallel regions
915 supported by this implementation.
918 @multitable @columnfractions .20 .80
919 @item @emph{Prototype}: @tab @code{int omp_get_supported_active_levels(void);}
922 @item @emph{Fortran}:
923 @multitable @columnfractions .20 .80
924 @item @emph{Interface}: @tab @code{integer function omp_get_supported_active_levels()}
927 @item @emph{See also}:
928 @ref{omp_get_max_active_levels}, @ref{omp_set_max_active_levels}
930 @item @emph{Reference}:
931 @uref{https://www.openmp.org, OpenMP specification v5.0}, Section 3.2.15.
936 @node omp_get_team_num
937 @section @code{omp_get_team_num} -- Get team number
939 @item @emph{Description}:
940 Returns the team number of the calling thread.
943 @multitable @columnfractions .20 .80
944 @item @emph{Prototype}: @tab @code{int omp_get_team_num(void);}
947 @item @emph{Fortran}:
948 @multitable @columnfractions .20 .80
949 @item @emph{Interface}: @tab @code{integer function omp_get_team_num()}
952 @item @emph{Reference}:
953 @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.33.
958 @node omp_get_team_size
959 @section @code{omp_get_team_size} -- Number of threads in a team
961 @item @emph{Description}:
962 This function returns the number of threads in a thread team to which
963 either the current thread or its ancestor belongs. For values of @var{level}
964 outside zero to @code{omp_get_level}, -1 is returned; if @var{level} is zero,
965 1 is returned, and for @code{omp_get_level}, the result is identical
966 to @code{omp_get_num_threads}.
969 @multitable @columnfractions .20 .80
970 @item @emph{Prototype}: @tab @code{int omp_get_team_size(int level);}
973 @item @emph{Fortran}:
974 @multitable @columnfractions .20 .80
975 @item @emph{Interface}: @tab @code{integer function omp_get_team_size(level)}
976 @item @tab @code{integer level}
979 @item @emph{See also}:
980 @ref{omp_get_num_threads}, @ref{omp_get_level}, @ref{omp_get_ancestor_thread_num}
982 @item @emph{Reference}:
983 @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.19.
988 @node omp_get_thread_limit
989 @section @code{omp_get_thread_limit} -- Maximum number of threads
991 @item @emph{Description}:
992 Return the maximum number of threads of the program.
995 @multitable @columnfractions .20 .80
996 @item @emph{Prototype}: @tab @code{int omp_get_thread_limit(void);}
999 @item @emph{Fortran}:
1000 @multitable @columnfractions .20 .80
1001 @item @emph{Interface}: @tab @code{integer function omp_get_thread_limit()}
1004 @item @emph{See also}:
1005 @ref{omp_get_max_threads}, @ref{OMP_THREAD_LIMIT}
1007 @item @emph{Reference}:
1008 @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.14.
1013 @node omp_get_thread_num
1014 @section @code{omp_get_thread_num} -- Current thread ID
1016 @item @emph{Description}:
1017 Returns a unique thread identification number within the current team.
1018 In a sequential parts of the program, @code{omp_get_thread_num}
1019 always returns 0. In parallel regions the return value varies
1020 from 0 to @code{omp_get_num_threads}-1 inclusive. The return
1021 value of the primary thread of a team is always 0.
1024 @multitable @columnfractions .20 .80
1025 @item @emph{Prototype}: @tab @code{int omp_get_thread_num(void);}
1028 @item @emph{Fortran}:
1029 @multitable @columnfractions .20 .80
1030 @item @emph{Interface}: @tab @code{integer function omp_get_thread_num()}
1033 @item @emph{See also}:
1034 @ref{omp_get_num_threads}, @ref{omp_get_ancestor_thread_num}
1036 @item @emph{Reference}:
1037 @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.4.
1042 @node omp_in_parallel
1043 @section @code{omp_in_parallel} -- Whether a parallel region is active
1045 @item @emph{Description}:
1046 This function returns @code{true} if currently running in parallel,
1047 @code{false} otherwise. Here, @code{true} and @code{false} represent
1048 their language-specific counterparts.
1051 @multitable @columnfractions .20 .80
1052 @item @emph{Prototype}: @tab @code{int omp_in_parallel(void);}
1055 @item @emph{Fortran}:
1056 @multitable @columnfractions .20 .80
1057 @item @emph{Interface}: @tab @code{logical function omp_in_parallel()}
1060 @item @emph{Reference}:
1061 @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.6.
1066 @section @code{omp_in_final} -- Whether in final or included task region
1068 @item @emph{Description}:
1069 This function returns @code{true} if currently running in a final
1070 or included task region, @code{false} otherwise. Here, @code{true}
1071 and @code{false} represent their language-specific counterparts.
1074 @multitable @columnfractions .20 .80
1075 @item @emph{Prototype}: @tab @code{int omp_in_final(void);}
1078 @item @emph{Fortran}:
1079 @multitable @columnfractions .20 .80
1080 @item @emph{Interface}: @tab @code{logical function omp_in_final()}
1083 @item @emph{Reference}:
1084 @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.21.
1089 @node omp_is_initial_device
1090 @section @code{omp_is_initial_device} -- Whether executing on the host device
1092 @item @emph{Description}:
1093 This function returns @code{true} if currently running on the host device,
1094 @code{false} otherwise. Here, @code{true} and @code{false} represent
1095 their language-specific counterparts.
1098 @multitable @columnfractions .20 .80
1099 @item @emph{Prototype}: @tab @code{int omp_is_initial_device(void);}
1102 @item @emph{Fortran}:
1103 @multitable @columnfractions .20 .80
1104 @item @emph{Interface}: @tab @code{logical function omp_is_initial_device()}
1107 @item @emph{Reference}:
1108 @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.34.
1113 @node omp_set_default_device
1114 @section @code{omp_set_default_device} -- Set the default device for target regions
1116 @item @emph{Description}:
1117 Set the default device for target regions without device clause. The argument
1118 shall be a nonnegative device number.
1121 @multitable @columnfractions .20 .80
1122 @item @emph{Prototype}: @tab @code{void omp_set_default_device(int device_num);}
1125 @item @emph{Fortran}:
1126 @multitable @columnfractions .20 .80
1127 @item @emph{Interface}: @tab @code{subroutine omp_set_default_device(device_num)}
1128 @item @tab @code{integer device_num}
1131 @item @emph{See also}:
1132 @ref{OMP_DEFAULT_DEVICE}, @ref{omp_get_default_device}
1134 @item @emph{Reference}:
1135 @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.29.
1140 @node omp_set_dynamic
1141 @section @code{omp_set_dynamic} -- Enable/disable dynamic teams
1143 @item @emph{Description}:
1144 Enable or disable the dynamic adjustment of the number of threads
1145 within a team. The function takes the language-specific equivalent
1146 of @code{true} and @code{false}, where @code{true} enables dynamic
1147 adjustment of team sizes and @code{false} disables it.
1150 @multitable @columnfractions .20 .80
1151 @item @emph{Prototype}: @tab @code{void omp_set_dynamic(int dynamic_threads);}
1154 @item @emph{Fortran}:
1155 @multitable @columnfractions .20 .80
1156 @item @emph{Interface}: @tab @code{subroutine omp_set_dynamic(dynamic_threads)}
1157 @item @tab @code{logical, intent(in) :: dynamic_threads}
1160 @item @emph{See also}:
1161 @ref{OMP_DYNAMIC}, @ref{omp_get_dynamic}
1163 @item @emph{Reference}:
1164 @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.7.
1169 @node omp_set_max_active_levels
1170 @section @code{omp_set_max_active_levels} -- Limits the number of active parallel regions
1172 @item @emph{Description}:
1173 This function limits the maximum allowed number of nested, active
1174 parallel regions. @var{max_levels} must be less or equal to
1175 the value returned by @code{omp_get_supported_active_levels}.
1178 @multitable @columnfractions .20 .80
1179 @item @emph{Prototype}: @tab @code{void omp_set_max_active_levels(int max_levels);}
1182 @item @emph{Fortran}:
1183 @multitable @columnfractions .20 .80
1184 @item @emph{Interface}: @tab @code{subroutine omp_set_max_active_levels(max_levels)}
1185 @item @tab @code{integer max_levels}
1188 @item @emph{See also}:
1189 @ref{omp_get_max_active_levels}, @ref{omp_get_active_level},
1190 @ref{omp_get_supported_active_levels}
1192 @item @emph{Reference}:
1193 @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.15.
1198 @node omp_set_nested
1199 @section @code{omp_set_nested} -- Enable/disable nested parallel regions
1201 @item @emph{Description}:
1202 Enable or disable nested parallel regions, i.e., whether team members
1203 are allowed to create new teams. The function takes the language-specific
1204 equivalent of @code{true} and @code{false}, where @code{true} enables
1205 dynamic adjustment of team sizes and @code{false} disables it.
1207 Enabling nested parallel regions will also set the maximum number of
1208 active nested regions to the maximum supported. Disabling nested parallel
1209 regions will set the maximum number of active nested regions to one.
1212 @multitable @columnfractions .20 .80
1213 @item @emph{Prototype}: @tab @code{void omp_set_nested(int nested);}
1216 @item @emph{Fortran}:
1217 @multitable @columnfractions .20 .80
1218 @item @emph{Interface}: @tab @code{subroutine omp_set_nested(nested)}
1219 @item @tab @code{logical, intent(in) :: nested}
1222 @item @emph{See also}:
1223 @ref{omp_get_nested}, @ref{omp_set_max_active_levels},
1224 @ref{OMP_MAX_ACTIVE_LEVELS}, @ref{OMP_NESTED}
1226 @item @emph{Reference}:
1227 @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.10.
1232 @node omp_set_num_threads
1233 @section @code{omp_set_num_threads} -- Set upper team size limit
1235 @item @emph{Description}:
1236 Specifies the number of threads used by default in subsequent parallel
1237 sections, if those do not specify a @code{num_threads} clause. The
1238 argument of @code{omp_set_num_threads} shall be a positive integer.
1241 @multitable @columnfractions .20 .80
1242 @item @emph{Prototype}: @tab @code{void omp_set_num_threads(int num_threads);}
1245 @item @emph{Fortran}:
1246 @multitable @columnfractions .20 .80
1247 @item @emph{Interface}: @tab @code{subroutine omp_set_num_threads(num_threads)}
1248 @item @tab @code{integer, intent(in) :: num_threads}
1251 @item @emph{See also}:
1252 @ref{OMP_NUM_THREADS}, @ref{omp_get_num_threads}, @ref{omp_get_max_threads}
1254 @item @emph{Reference}:
1255 @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.1.
1260 @node omp_set_schedule
1261 @section @code{omp_set_schedule} -- Set the runtime scheduling method
1263 @item @emph{Description}:
1264 Sets the runtime scheduling method. The @var{kind} argument can have the
1265 value @code{omp_sched_static}, @code{omp_sched_dynamic},
1266 @code{omp_sched_guided} or @code{omp_sched_auto}. Except for
1267 @code{omp_sched_auto}, the chunk size is set to the value of
1268 @var{chunk_size} if positive, or to the default value if zero or negative.
1269 For @code{omp_sched_auto} the @var{chunk_size} argument is ignored.
1272 @multitable @columnfractions .20 .80
1273 @item @emph{Prototype}: @tab @code{void omp_set_schedule(omp_sched_t kind, int chunk_size);}
1276 @item @emph{Fortran}:
1277 @multitable @columnfractions .20 .80
1278 @item @emph{Interface}: @tab @code{subroutine omp_set_schedule(kind, chunk_size)}
1279 @item @tab @code{integer(kind=omp_sched_kind) kind}
1280 @item @tab @code{integer chunk_size}
1283 @item @emph{See also}:
1284 @ref{omp_get_schedule}
1287 @item @emph{Reference}:
1288 @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.12.
1294 @section @code{omp_init_lock} -- Initialize simple lock
1296 @item @emph{Description}:
1297 Initialize a simple lock. After initialization, the lock is in
1301 @multitable @columnfractions .20 .80
1302 @item @emph{Prototype}: @tab @code{void omp_init_lock(omp_lock_t *lock);}
1305 @item @emph{Fortran}:
1306 @multitable @columnfractions .20 .80
1307 @item @emph{Interface}: @tab @code{subroutine omp_init_lock(svar)}
1308 @item @tab @code{integer(omp_lock_kind), intent(out) :: svar}
1311 @item @emph{See also}:
1312 @ref{omp_destroy_lock}
1314 @item @emph{Reference}:
1315 @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.3.1.
1321 @section @code{omp_set_lock} -- Wait for and set simple lock
1323 @item @emph{Description}:
1324 Before setting a simple lock, the lock variable must be initialized by
1325 @code{omp_init_lock}. The calling thread is blocked until the lock
1326 is available. If the lock is already held by the current thread,
1330 @multitable @columnfractions .20 .80
1331 @item @emph{Prototype}: @tab @code{void omp_set_lock(omp_lock_t *lock);}
1334 @item @emph{Fortran}:
1335 @multitable @columnfractions .20 .80
1336 @item @emph{Interface}: @tab @code{subroutine omp_set_lock(svar)}
1337 @item @tab @code{integer(omp_lock_kind), intent(inout) :: svar}
1340 @item @emph{See also}:
1341 @ref{omp_init_lock}, @ref{omp_test_lock}, @ref{omp_unset_lock}
1343 @item @emph{Reference}:
1344 @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.3.4.
1350 @section @code{omp_test_lock} -- Test and set simple lock if available
1352 @item @emph{Description}:
1353 Before setting a simple lock, the lock variable must be initialized by
1354 @code{omp_init_lock}. Contrary to @code{omp_set_lock}, @code{omp_test_lock}
1355 does not block if the lock is not available. This function returns
1356 @code{true} upon success, @code{false} otherwise. Here, @code{true} and
1357 @code{false} represent their language-specific counterparts.
1360 @multitable @columnfractions .20 .80
1361 @item @emph{Prototype}: @tab @code{int omp_test_lock(omp_lock_t *lock);}
1364 @item @emph{Fortran}:
1365 @multitable @columnfractions .20 .80
1366 @item @emph{Interface}: @tab @code{logical function omp_test_lock(svar)}
1367 @item @tab @code{integer(omp_lock_kind), intent(inout) :: svar}
1370 @item @emph{See also}:
1371 @ref{omp_init_lock}, @ref{omp_set_lock}, @ref{omp_set_lock}
1373 @item @emph{Reference}:
1374 @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.3.6.
1379 @node omp_unset_lock
1380 @section @code{omp_unset_lock} -- Unset simple lock
1382 @item @emph{Description}:
1383 A simple lock about to be unset must have been locked by @code{omp_set_lock}
1384 or @code{omp_test_lock} before. In addition, the lock must be held by the
1385 thread calling @code{omp_unset_lock}. Then, the lock becomes unlocked. If one
1386 or more threads attempted to set the lock before, one of them is chosen to,
1387 again, set the lock to itself.
1390 @multitable @columnfractions .20 .80
1391 @item @emph{Prototype}: @tab @code{void omp_unset_lock(omp_lock_t *lock);}
1394 @item @emph{Fortran}:
1395 @multitable @columnfractions .20 .80
1396 @item @emph{Interface}: @tab @code{subroutine omp_unset_lock(svar)}
1397 @item @tab @code{integer(omp_lock_kind), intent(inout) :: svar}
1400 @item @emph{See also}:
1401 @ref{omp_set_lock}, @ref{omp_test_lock}
1403 @item @emph{Reference}:
1404 @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.3.5.
1409 @node omp_destroy_lock
1410 @section @code{omp_destroy_lock} -- Destroy simple lock
1412 @item @emph{Description}:
1413 Destroy a simple lock. In order to be destroyed, a simple lock must be
1414 in the unlocked state.
1417 @multitable @columnfractions .20 .80
1418 @item @emph{Prototype}: @tab @code{void omp_destroy_lock(omp_lock_t *lock);}
1421 @item @emph{Fortran}:
1422 @multitable @columnfractions .20 .80
1423 @item @emph{Interface}: @tab @code{subroutine omp_destroy_lock(svar)}
1424 @item @tab @code{integer(omp_lock_kind), intent(inout) :: svar}
1427 @item @emph{See also}:
1430 @item @emph{Reference}:
1431 @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.3.3.
1436 @node omp_init_nest_lock
1437 @section @code{omp_init_nest_lock} -- Initialize nested lock
1439 @item @emph{Description}:
1440 Initialize a nested lock. After initialization, the lock is in
1441 an unlocked state and the nesting count is set to zero.
1444 @multitable @columnfractions .20 .80
1445 @item @emph{Prototype}: @tab @code{void omp_init_nest_lock(omp_nest_lock_t *lock);}
1448 @item @emph{Fortran}:
1449 @multitable @columnfractions .20 .80
1450 @item @emph{Interface}: @tab @code{subroutine omp_init_nest_lock(nvar)}
1451 @item @tab @code{integer(omp_nest_lock_kind), intent(out) :: nvar}
1454 @item @emph{See also}:
1455 @ref{omp_destroy_nest_lock}
1457 @item @emph{Reference}:
1458 @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.3.1.
1462 @node omp_set_nest_lock
1463 @section @code{omp_set_nest_lock} -- Wait for and set nested lock
1465 @item @emph{Description}:
1466 Before setting a nested lock, the lock variable must be initialized by
1467 @code{omp_init_nest_lock}. The calling thread is blocked until the lock
1468 is available. If the lock is already held by the current thread, the
1469 nesting count for the lock is incremented.
1472 @multitable @columnfractions .20 .80
1473 @item @emph{Prototype}: @tab @code{void omp_set_nest_lock(omp_nest_lock_t *lock);}
1476 @item @emph{Fortran}:
1477 @multitable @columnfractions .20 .80
1478 @item @emph{Interface}: @tab @code{subroutine omp_set_nest_lock(nvar)}
1479 @item @tab @code{integer(omp_nest_lock_kind), intent(inout) :: nvar}
1482 @item @emph{See also}:
1483 @ref{omp_init_nest_lock}, @ref{omp_unset_nest_lock}
1485 @item @emph{Reference}:
1486 @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.3.4.
1491 @node omp_test_nest_lock
1492 @section @code{omp_test_nest_lock} -- Test and set nested lock if available
1494 @item @emph{Description}:
1495 Before setting a nested lock, the lock variable must be initialized by
1496 @code{omp_init_nest_lock}. Contrary to @code{omp_set_nest_lock},
1497 @code{omp_test_nest_lock} does not block if the lock is not available.
1498 If the lock is already held by the current thread, the new nesting count
1499 is returned. Otherwise, the return value equals zero.
1502 @multitable @columnfractions .20 .80
1503 @item @emph{Prototype}: @tab @code{int omp_test_nest_lock(omp_nest_lock_t *lock);}
1506 @item @emph{Fortran}:
1507 @multitable @columnfractions .20 .80
1508 @item @emph{Interface}: @tab @code{logical function omp_test_nest_lock(nvar)}
1509 @item @tab @code{integer(omp_nest_lock_kind), intent(inout) :: nvar}
1513 @item @emph{See also}:
1514 @ref{omp_init_lock}, @ref{omp_set_lock}, @ref{omp_set_lock}
1516 @item @emph{Reference}:
1517 @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.3.6.
1522 @node omp_unset_nest_lock
1523 @section @code{omp_unset_nest_lock} -- Unset nested lock
1525 @item @emph{Description}:
1526 A nested lock about to be unset must have been locked by @code{omp_set_nested_lock}
1527 or @code{omp_test_nested_lock} before. In addition, the lock must be held by the
1528 thread calling @code{omp_unset_nested_lock}. If the nesting count drops to zero, the
1529 lock becomes unlocked. If one ore more threads attempted to set the lock before,
1530 one of them is chosen to, again, set the lock to itself.
1533 @multitable @columnfractions .20 .80
1534 @item @emph{Prototype}: @tab @code{void omp_unset_nest_lock(omp_nest_lock_t *lock);}
1537 @item @emph{Fortran}:
1538 @multitable @columnfractions .20 .80
1539 @item @emph{Interface}: @tab @code{subroutine omp_unset_nest_lock(nvar)}
1540 @item @tab @code{integer(omp_nest_lock_kind), intent(inout) :: nvar}
1543 @item @emph{See also}:
1544 @ref{omp_set_nest_lock}
1546 @item @emph{Reference}:
1547 @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.3.5.
1552 @node omp_destroy_nest_lock
1553 @section @code{omp_destroy_nest_lock} -- Destroy nested lock
1555 @item @emph{Description}:
1556 Destroy a nested lock. In order to be destroyed, a nested lock must be
1557 in the unlocked state and its nesting count must equal zero.
1560 @multitable @columnfractions .20 .80
1561 @item @emph{Prototype}: @tab @code{void omp_destroy_nest_lock(omp_nest_lock_t *);}
1564 @item @emph{Fortran}:
1565 @multitable @columnfractions .20 .80
1566 @item @emph{Interface}: @tab @code{subroutine omp_destroy_nest_lock(nvar)}
1567 @item @tab @code{integer(omp_nest_lock_kind), intent(inout) :: nvar}
1570 @item @emph{See also}:
1573 @item @emph{Reference}:
1574 @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.3.3.
1580 @section @code{omp_get_wtick} -- Get timer precision
1582 @item @emph{Description}:
1583 Gets the timer precision, i.e., the number of seconds between two
1584 successive clock ticks.
1587 @multitable @columnfractions .20 .80
1588 @item @emph{Prototype}: @tab @code{double omp_get_wtick(void);}
1591 @item @emph{Fortran}:
1592 @multitable @columnfractions .20 .80
1593 @item @emph{Interface}: @tab @code{double precision function omp_get_wtick()}
1596 @item @emph{See also}:
1599 @item @emph{Reference}:
1600 @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.4.2.
1606 @section @code{omp_get_wtime} -- Elapsed wall clock time
1608 @item @emph{Description}:
1609 Elapsed wall clock time in seconds. The time is measured per thread, no
1610 guarantee can be made that two distinct threads measure the same time.
1611 Time is measured from some "time in the past", which is an arbitrary time
1612 guaranteed not to change during the execution of the program.
1615 @multitable @columnfractions .20 .80
1616 @item @emph{Prototype}: @tab @code{double omp_get_wtime(void);}
1619 @item @emph{Fortran}:
1620 @multitable @columnfractions .20 .80
1621 @item @emph{Interface}: @tab @code{double precision function omp_get_wtime()}
1624 @item @emph{See also}:
1627 @item @emph{Reference}:
1628 @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.4.1.
1633 @node omp_fulfill_event
1634 @section @code{omp_fulfill_event} -- Fulfill and destroy an OpenMP event
1636 @item @emph{Description}:
1637 Fulfill the event associated with the event handle argument. Currently, it
1638 is only used to fulfill events generated by detach clauses on task
1639 constructs - the effect of fulfilling the event is to allow the task to
1642 The result of calling @code{omp_fulfill_event} with an event handle other
1643 than that generated by a detach clause is undefined. Calling it with an
1644 event handle that has already been fulfilled is also undefined.
1647 @multitable @columnfractions .20 .80
1648 @item @emph{Prototype}: @tab @code{void omp_fulfill_event(omp_event_handle_t event);}
1651 @item @emph{Fortran}:
1652 @multitable @columnfractions .20 .80
1653 @item @emph{Interface}: @tab @code{subroutine omp_fulfill_event(event)}
1654 @item @tab @code{integer (kind=omp_event_handle_kind) :: event}
1657 @item @emph{Reference}:
1658 @uref{https://www.openmp.org, OpenMP specification v5.0}, Section 3.5.1.
1663 @c ---------------------------------------------------------------------
1664 @c OpenMP Environment Variables
1665 @c ---------------------------------------------------------------------
1667 @node Environment Variables
1668 @chapter OpenMP Environment Variables
1670 The environment variables which beginning with @env{OMP_} are defined by
1671 section 4 of the OpenMP specification in version 4.5, while those
1672 beginning with @env{GOMP_} are GNU extensions.
1675 * OMP_CANCELLATION:: Set whether cancellation is activated
1676 * OMP_DISPLAY_ENV:: Show OpenMP version and environment variables
1677 * OMP_DEFAULT_DEVICE:: Set the device used in target regions
1678 * OMP_DYNAMIC:: Dynamic adjustment of threads
1679 * OMP_MAX_ACTIVE_LEVELS:: Set the maximum number of nested parallel regions
1680 * OMP_MAX_TASK_PRIORITY:: Set the maximum task priority value
1681 * OMP_NESTED:: Nested parallel regions
1682 * OMP_NUM_THREADS:: Specifies the number of threads to use
1683 * OMP_PROC_BIND:: Whether theads may be moved between CPUs
1684 * OMP_PLACES:: Specifies on which CPUs the theads should be placed
1685 * OMP_STACKSIZE:: Set default thread stack size
1686 * OMP_SCHEDULE:: How threads are scheduled
1687 * OMP_TARGET_OFFLOAD:: Controls offloading behaviour
1688 * OMP_THREAD_LIMIT:: Set the maximum number of threads
1689 * OMP_WAIT_POLICY:: How waiting threads are handled
1690 * GOMP_CPU_AFFINITY:: Bind threads to specific CPUs
1691 * GOMP_DEBUG:: Enable debugging output
1692 * GOMP_STACKSIZE:: Set default thread stack size
1693 * GOMP_SPINCOUNT:: Set the busy-wait spin count
1694 * GOMP_RTEMS_THREAD_POOLS:: Set the RTEMS specific thread pools
1698 @node OMP_CANCELLATION
1699 @section @env{OMP_CANCELLATION} -- Set whether cancellation is activated
1700 @cindex Environment Variable
1702 @item @emph{Description}:
1703 If set to @code{TRUE}, the cancellation is activated. If set to @code{FALSE} or
1704 if unset, cancellation is disabled and the @code{cancel} construct is ignored.
1706 @item @emph{See also}:
1707 @ref{omp_get_cancellation}
1709 @item @emph{Reference}:
1710 @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 4.11
1715 @node OMP_DISPLAY_ENV
1716 @section @env{OMP_DISPLAY_ENV} -- Show OpenMP version and environment variables
1717 @cindex Environment Variable
1719 @item @emph{Description}:
1720 If set to @code{TRUE}, the OpenMP version number and the values
1721 associated with the OpenMP environment variables are printed to @code{stderr}.
1722 If set to @code{VERBOSE}, it additionally shows the value of the environment
1723 variables which are GNU extensions. If undefined or set to @code{FALSE},
1724 this information will not be shown.
1727 @item @emph{Reference}:
1728 @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 4.12
1733 @node OMP_DEFAULT_DEVICE
1734 @section @env{OMP_DEFAULT_DEVICE} -- Set the device used in target regions
1735 @cindex Environment Variable
1737 @item @emph{Description}:
1738 Set to choose the device which is used in a @code{target} region, unless the
1739 value is overridden by @code{omp_set_default_device} or by a @code{device}
1740 clause. The value shall be the nonnegative device number. If no device with
1741 the given device number exists, the code is executed on the host. If unset,
1742 device number 0 will be used.
1745 @item @emph{See also}:
1746 @ref{omp_get_default_device}, @ref{omp_set_default_device},
1748 @item @emph{Reference}:
1749 @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 4.13
1755 @section @env{OMP_DYNAMIC} -- Dynamic adjustment of threads
1756 @cindex Environment Variable
1758 @item @emph{Description}:
1759 Enable or disable the dynamic adjustment of the number of threads
1760 within a team. The value of this environment variable shall be
1761 @code{TRUE} or @code{FALSE}. If undefined, dynamic adjustment is
1762 disabled by default.
1764 @item @emph{See also}:
1765 @ref{omp_set_dynamic}
1767 @item @emph{Reference}:
1768 @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 4.3
1773 @node OMP_MAX_ACTIVE_LEVELS
1774 @section @env{OMP_MAX_ACTIVE_LEVELS} -- Set the maximum number of nested parallel regions
1775 @cindex Environment Variable
1777 @item @emph{Description}:
1778 Specifies the initial value for the maximum number of nested parallel
1779 regions. The value of this variable shall be a positive integer.
1780 If undefined, then if @env{OMP_NESTED} is defined and set to true, or
1781 if @env{OMP_NUM_THREADS} or @env{OMP_PROC_BIND} are defined and set to
1782 a list with more than one item, the maximum number of nested parallel
1783 regions will be initialized to the largest number supported, otherwise
1784 it will be set to one.
1786 @item @emph{See also}:
1787 @ref{omp_set_max_active_levels}, @ref{OMP_NESTED}
1789 @item @emph{Reference}:
1790 @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 4.9
1795 @node OMP_MAX_TASK_PRIORITY
1796 @section @env{OMP_MAX_TASK_PRIORITY} -- Set the maximum priority
1797 number that can be set for a task.
1798 @cindex Environment Variable
1800 @item @emph{Description}:
1801 Specifies the initial value for the maximum priority value that can be
1802 set for a task. The value of this variable shall be a non-negative
1803 integer, and zero is allowed. If undefined, the default priority is
1806 @item @emph{See also}:
1807 @ref{omp_get_max_task_priority}
1809 @item @emph{Reference}:
1810 @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 4.14
1816 @section @env{OMP_NESTED} -- Nested parallel regions
1817 @cindex Environment Variable
1818 @cindex Implementation specific setting
1820 @item @emph{Description}:
1821 Enable or disable nested parallel regions, i.e., whether team members
1822 are allowed to create new teams. The value of this environment variable
1823 shall be @code{TRUE} or @code{FALSE}. If set to @code{TRUE}, the number
1824 of maximum active nested regions supported will by default be set to the
1825 maximum supported, otherwise it will be set to one. If
1826 @env{OMP_MAX_ACTIVE_LEVELS} is defined, its setting will override this
1827 setting. If both are undefined, nested parallel regions are enabled if
1828 @env{OMP_NUM_THREADS} or @env{OMP_PROC_BINDS} are defined to a list with
1829 more than one item, otherwise they are disabled by default.
1831 @item @emph{See also}:
1832 @ref{omp_set_max_active_levels}, @ref{omp_set_nested}
1834 @item @emph{Reference}:
1835 @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 4.6
1840 @node OMP_NUM_THREADS
1841 @section @env{OMP_NUM_THREADS} -- Specifies the number of threads to use
1842 @cindex Environment Variable
1843 @cindex Implementation specific setting
1845 @item @emph{Description}:
1846 Specifies the default number of threads to use in parallel regions. The
1847 value of this variable shall be a comma-separated list of positive integers;
1848 the value specifies the number of threads to use for the corresponding nested
1849 level. Specifying more than one item in the list will automatically enable
1850 nesting by default. If undefined one thread per CPU is used.
1852 @item @emph{See also}:
1853 @ref{omp_set_num_threads}, @ref{OMP_NESTED}
1855 @item @emph{Reference}:
1856 @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 4.2
1862 @section @env{OMP_PROC_BIND} -- Whether theads may be moved between CPUs
1863 @cindex Environment Variable
1865 @item @emph{Description}:
1866 Specifies whether threads may be moved between processors. If set to
1867 @code{TRUE}, OpenMP theads should not be moved; if set to @code{FALSE}
1868 they may be moved. Alternatively, a comma separated list with the
1869 values @code{PRIMARY}, @code{MASTER}, @code{CLOSE} and @code{SPREAD} can
1870 be used to specify the thread affinity policy for the corresponding nesting
1871 level. With @code{PRIMARY} and @code{MASTER} the worker threads are in the
1872 same place partition as the primary thread. With @code{CLOSE} those are
1873 kept close to the primary thread in contiguous place partitions. And
1874 with @code{SPREAD} a sparse distribution
1875 across the place partitions is used. Specifying more than one item in the
1876 list will automatically enable nesting by default.
1878 When undefined, @env{OMP_PROC_BIND} defaults to @code{TRUE} when
1879 @env{OMP_PLACES} or @env{GOMP_CPU_AFFINITY} is set and @code{FALSE} otherwise.
1881 @item @emph{See also}:
1882 @ref{omp_get_proc_bind}, @ref{GOMP_CPU_AFFINITY},
1883 @ref{OMP_NESTED}, @ref{OMP_PLACES}
1885 @item @emph{Reference}:
1886 @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 4.4
1892 @section @env{OMP_PLACES} -- Specifies on which CPUs the theads should be placed
1893 @cindex Environment Variable
1895 @item @emph{Description}:
1896 The thread placement can be either specified using an abstract name or by an
1897 explicit list of the places. The abstract names @code{threads}, @code{cores}
1898 and @code{sockets} can be optionally followed by a positive number in
1899 parentheses, which denotes the how many places shall be created. With
1900 @code{threads} each place corresponds to a single hardware thread; @code{cores}
1901 to a single core with the corresponding number of hardware threads; and with
1902 @code{sockets} the place corresponds to a single socket. The resulting
1903 placement can be shown by setting the @env{OMP_DISPLAY_ENV} environment
1906 Alternatively, the placement can be specified explicitly as comma-separated
1907 list of places. A place is specified by set of nonnegative numbers in curly
1908 braces, denoting the denoting the hardware threads. The hardware threads
1909 belonging to a place can either be specified as comma-separated list of
1910 nonnegative thread numbers or using an interval. Multiple places can also be
1911 either specified by a comma-separated list of places or by an interval. To
1912 specify an interval, a colon followed by the count is placed after after
1913 the hardware thread number or the place. Optionally, the length can be
1914 followed by a colon and the stride number -- otherwise a unit stride is
1915 assumed. For instance, the following specifies the same places list:
1916 @code{"@{0,1,2@}, @{3,4,6@}, @{7,8,9@}, @{10,11,12@}"};
1917 @code{"@{0:3@}, @{3:3@}, @{7:3@}, @{10:3@}"}; and @code{"@{0:2@}:4:3"}.
1919 If @env{OMP_PLACES} and @env{GOMP_CPU_AFFINITY} are unset and
1920 @env{OMP_PROC_BIND} is either unset or @code{false}, threads may be moved
1921 between CPUs following no placement policy.
1923 @item @emph{See also}:
1924 @ref{OMP_PROC_BIND}, @ref{GOMP_CPU_AFFINITY}, @ref{omp_get_proc_bind},
1925 @ref{OMP_DISPLAY_ENV}
1927 @item @emph{Reference}:
1928 @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 4.5
1934 @section @env{OMP_STACKSIZE} -- Set default thread stack size
1935 @cindex Environment Variable
1937 @item @emph{Description}:
1938 Set the default thread stack size in kilobytes, unless the number
1939 is suffixed by @code{B}, @code{K}, @code{M} or @code{G}, in which
1940 case the size is, respectively, in bytes, kilobytes, megabytes
1941 or gigabytes. This is different from @code{pthread_attr_setstacksize}
1942 which gets the number of bytes as an argument. If the stack size cannot
1943 be set due to system constraints, an error is reported and the initial
1944 stack size is left unchanged. If undefined, the stack size is system
1947 @item @emph{Reference}:
1948 @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 4.7
1954 @section @env{OMP_SCHEDULE} -- How threads are scheduled
1955 @cindex Environment Variable
1956 @cindex Implementation specific setting
1958 @item @emph{Description}:
1959 Allows to specify @code{schedule type} and @code{chunk size}.
1960 The value of the variable shall have the form: @code{type[,chunk]} where
1961 @code{type} is one of @code{static}, @code{dynamic}, @code{guided} or @code{auto}
1962 The optional @code{chunk} size shall be a positive integer. If undefined,
1963 dynamic scheduling and a chunk size of 1 is used.
1965 @item @emph{See also}:
1966 @ref{omp_set_schedule}
1968 @item @emph{Reference}:
1969 @uref{https://www.openmp.org, OpenMP specification v4.5}, Sections 2.7.1.1 and 4.1
1974 @node OMP_TARGET_OFFLOAD
1975 @section @env{OMP_TARGET_OFFLOAD} -- Controls offloading behaviour
1976 @cindex Environment Variable
1977 @cindex Implementation specific setting
1979 @item @emph{Description}:
1980 Specifies the behaviour with regard to offloading code to a device. This
1981 variable can be set to one of three values - @code{MANDATORY}, @code{DISABLED}
1984 If set to @code{MANDATORY}, the program will terminate with an error if
1985 the offload device is not present or is not supported. If set to
1986 @code{DISABLED}, then offloading is disabled and all code will run on the
1987 host. If set to @code{DEFAULT}, the program will try offloading to the
1988 device first, then fall back to running code on the host if it cannot.
1990 If undefined, then the program will behave as if @code{DEFAULT} was set.
1992 @item @emph{Reference}:
1993 @uref{https://www.openmp.org, OpenMP specification v5.0}, Section 6.17
1998 @node OMP_THREAD_LIMIT
1999 @section @env{OMP_THREAD_LIMIT} -- Set the maximum number of threads
2000 @cindex Environment Variable
2002 @item @emph{Description}:
2003 Specifies the number of threads to use for the whole program. The
2004 value of this variable shall be a positive integer. If undefined,
2005 the number of threads is not limited.
2007 @item @emph{See also}:
2008 @ref{OMP_NUM_THREADS}, @ref{omp_get_thread_limit}
2010 @item @emph{Reference}:
2011 @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 4.10
2016 @node OMP_WAIT_POLICY
2017 @section @env{OMP_WAIT_POLICY} -- How waiting threads are handled
2018 @cindex Environment Variable
2020 @item @emph{Description}:
2021 Specifies whether waiting threads should be active or passive. If
2022 the value is @code{PASSIVE}, waiting threads should not consume CPU
2023 power while waiting; while the value is @code{ACTIVE} specifies that
2024 they should. If undefined, threads wait actively for a short time
2025 before waiting passively.
2027 @item @emph{See also}:
2028 @ref{GOMP_SPINCOUNT}
2030 @item @emph{Reference}:
2031 @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 4.8
2036 @node GOMP_CPU_AFFINITY
2037 @section @env{GOMP_CPU_AFFINITY} -- Bind threads to specific CPUs
2038 @cindex Environment Variable
2040 @item @emph{Description}:
2041 Binds threads to specific CPUs. The variable should contain a space-separated
2042 or comma-separated list of CPUs. This list may contain different kinds of
2043 entries: either single CPU numbers in any order, a range of CPUs (M-N)
2044 or a range with some stride (M-N:S). CPU numbers are zero based. For example,
2045 @code{GOMP_CPU_AFFINITY="0 3 1-2 4-15:2"} will bind the initial thread
2046 to CPU 0, the second to CPU 3, the third to CPU 1, the fourth to
2047 CPU 2, the fifth to CPU 4, the sixth through tenth to CPUs 6, 8, 10, 12,
2048 and 14 respectively and then start assigning back from the beginning of
2049 the list. @code{GOMP_CPU_AFFINITY=0} binds all threads to CPU 0.
2051 There is no libgomp library routine to determine whether a CPU affinity
2052 specification is in effect. As a workaround, language-specific library
2053 functions, e.g., @code{getenv} in C or @code{GET_ENVIRONMENT_VARIABLE} in
2054 Fortran, may be used to query the setting of the @code{GOMP_CPU_AFFINITY}
2055 environment variable. A defined CPU affinity on startup cannot be changed
2056 or disabled during the runtime of the application.
2058 If both @env{GOMP_CPU_AFFINITY} and @env{OMP_PROC_BIND} are set,
2059 @env{OMP_PROC_BIND} has a higher precedence. If neither has been set and
2060 @env{OMP_PROC_BIND} is unset, or when @env{OMP_PROC_BIND} is set to
2061 @code{FALSE}, the host system will handle the assignment of threads to CPUs.
2063 @item @emph{See also}:
2064 @ref{OMP_PLACES}, @ref{OMP_PROC_BIND}
2070 @section @env{GOMP_DEBUG} -- Enable debugging output
2071 @cindex Environment Variable
2073 @item @emph{Description}:
2074 Enable debugging output. The variable should be set to @code{0}
2075 (disabled, also the default if not set), or @code{1} (enabled).
2077 If enabled, some debugging output will be printed during execution.
2078 This is currently not specified in more detail, and subject to change.
2083 @node GOMP_STACKSIZE
2084 @section @env{GOMP_STACKSIZE} -- Set default thread stack size
2085 @cindex Environment Variable
2086 @cindex Implementation specific setting
2088 @item @emph{Description}:
2089 Set the default thread stack size in kilobytes. This is different from
2090 @code{pthread_attr_setstacksize} which gets the number of bytes as an
2091 argument. If the stack size cannot be set due to system constraints, an
2092 error is reported and the initial stack size is left unchanged. If undefined,
2093 the stack size is system dependent.
2095 @item @emph{See also}:
2098 @item @emph{Reference}:
2099 @uref{https://gcc.gnu.org/ml/gcc-patches/2006-06/msg00493.html,
2100 GCC Patches Mailinglist},
2101 @uref{https://gcc.gnu.org/ml/gcc-patches/2006-06/msg00496.html,
2102 GCC Patches Mailinglist}
2107 @node GOMP_SPINCOUNT
2108 @section @env{GOMP_SPINCOUNT} -- Set the busy-wait spin count
2109 @cindex Environment Variable
2110 @cindex Implementation specific setting
2112 @item @emph{Description}:
2113 Determines how long a threads waits actively with consuming CPU power
2114 before waiting passively without consuming CPU power. The value may be
2115 either @code{INFINITE}, @code{INFINITY} to always wait actively or an
2116 integer which gives the number of spins of the busy-wait loop. The
2117 integer may optionally be followed by the following suffixes acting
2118 as multiplication factors: @code{k} (kilo, thousand), @code{M} (mega,
2119 million), @code{G} (giga, billion), or @code{T} (tera, trillion).
2120 If undefined, 0 is used when @env{OMP_WAIT_POLICY} is @code{PASSIVE},
2121 300,000 is used when @env{OMP_WAIT_POLICY} is undefined and
2122 30 billion is used when @env{OMP_WAIT_POLICY} is @code{ACTIVE}.
2123 If there are more OpenMP threads than available CPUs, 1000 and 100
2124 spins are used for @env{OMP_WAIT_POLICY} being @code{ACTIVE} or
2125 undefined, respectively; unless the @env{GOMP_SPINCOUNT} is lower
2126 or @env{OMP_WAIT_POLICY} is @code{PASSIVE}.
2128 @item @emph{See also}:
2129 @ref{OMP_WAIT_POLICY}
2134 @node GOMP_RTEMS_THREAD_POOLS
2135 @section @env{GOMP_RTEMS_THREAD_POOLS} -- Set the RTEMS specific thread pools
2136 @cindex Environment Variable
2137 @cindex Implementation specific setting
2139 @item @emph{Description}:
2140 This environment variable is only used on the RTEMS real-time operating system.
2141 It determines the scheduler instance specific thread pools. The format for
2142 @env{GOMP_RTEMS_THREAD_POOLS} is a list of optional
2143 @code{<thread-pool-count>[$<priority>]@@<scheduler-name>} configurations
2144 separated by @code{:} where:
2146 @item @code{<thread-pool-count>} is the thread pool count for this scheduler
2148 @item @code{$<priority>} is an optional priority for the worker threads of a
2149 thread pool according to @code{pthread_setschedparam}. In case a priority
2150 value is omitted, then a worker thread will inherit the priority of the OpenMP
2151 primary thread that created it. The priority of the worker thread is not
2152 changed after creation, even if a new OpenMP primary thread using the worker has
2153 a different priority.
2154 @item @code{@@<scheduler-name>} is the scheduler instance name according to the
2155 RTEMS application configuration.
2157 In case no thread pool configuration is specified for a scheduler instance,
2158 then each OpenMP primary thread of this scheduler instance will use its own
2159 dynamically allocated thread pool. To limit the worker thread count of the
2160 thread pools, each OpenMP primary thread must call @code{omp_set_num_threads}.
2161 @item @emph{Example}:
2162 Lets suppose we have three scheduler instances @code{IO}, @code{WRK0}, and
2163 @code{WRK1} with @env{GOMP_RTEMS_THREAD_POOLS} set to
2164 @code{"1@@WRK0:3$4@@WRK1"}. Then there are no thread pool restrictions for
2165 scheduler instance @code{IO}. In the scheduler instance @code{WRK0} there is
2166 one thread pool available. Since no priority is specified for this scheduler
2167 instance, the worker thread inherits the priority of the OpenMP primary thread
2168 that created it. In the scheduler instance @code{WRK1} there are three thread
2169 pools available and their worker threads run at priority four.
2174 @c ---------------------------------------------------------------------
2176 @c ---------------------------------------------------------------------
2178 @node Enabling OpenACC
2179 @chapter Enabling OpenACC
2181 To activate the OpenACC extensions for C/C++ and Fortran, the compile-time
2182 flag @option{-fopenacc} must be specified. This enables the OpenACC directive
2183 @code{#pragma acc} in C/C++ and @code{!$acc} directives in free form,
2184 @code{c$acc}, @code{*$acc} and @code{!$acc} directives in fixed form,
2185 @code{!$} conditional compilation sentinels in free form and @code{c$},
2186 @code{*$} and @code{!$} sentinels in fixed form, for Fortran. The flag also
2187 arranges for automatic linking of the OpenACC runtime library
2188 (@ref{OpenACC Runtime Library Routines}).
2190 See @uref{https://gcc.gnu.org/wiki/OpenACC} for more information.
2192 A complete description of all OpenACC directives accepted may be found in
2193 the @uref{https://www.openacc.org, OpenACC} Application Programming
2194 Interface manual, version 2.6.
2198 @c ---------------------------------------------------------------------
2199 @c OpenACC Runtime Library Routines
2200 @c ---------------------------------------------------------------------
2202 @node OpenACC Runtime Library Routines
2203 @chapter OpenACC Runtime Library Routines
2205 The runtime routines described here are defined by section 3 of the OpenACC
2206 specifications in version 2.6.
2207 They have C linkage, and do not throw exceptions.
2208 Generally, they are available only for the host, with the exception of
2209 @code{acc_on_device}, which is available for both the host and the
2210 acceleration device.
2213 * acc_get_num_devices:: Get number of devices for the given device
2215 * acc_set_device_type:: Set type of device accelerator to use.
2216 * acc_get_device_type:: Get type of device accelerator to be used.
2217 * acc_set_device_num:: Set device number to use.
2218 * acc_get_device_num:: Get device number to be used.
2219 * acc_get_property:: Get device property.
2220 * acc_async_test:: Tests for completion of a specific asynchronous
2222 * acc_async_test_all:: Tests for completion of all asynchronous
2224 * acc_wait:: Wait for completion of a specific asynchronous
2226 * acc_wait_all:: Waits for completion of all asynchronous
2228 * acc_wait_all_async:: Wait for completion of all asynchronous
2230 * acc_wait_async:: Wait for completion of asynchronous operations.
2231 * acc_init:: Initialize runtime for a specific device type.
2232 * acc_shutdown:: Shuts down the runtime for a specific device
2234 * acc_on_device:: Whether executing on a particular device
2235 * acc_malloc:: Allocate device memory.
2236 * acc_free:: Free device memory.
2237 * acc_copyin:: Allocate device memory and copy host memory to
2239 * acc_present_or_copyin:: If the data is not present on the device,
2240 allocate device memory and copy from host
2242 * acc_create:: Allocate device memory and map it to host
2244 * acc_present_or_create:: If the data is not present on the device,
2245 allocate device memory and map it to host
2247 * acc_copyout:: Copy device memory to host memory.
2248 * acc_delete:: Free device memory.
2249 * acc_update_device:: Update device memory from mapped host memory.
2250 * acc_update_self:: Update host memory from mapped device memory.
2251 * acc_map_data:: Map previously allocated device memory to host
2253 * acc_unmap_data:: Unmap device memory from host memory.
2254 * acc_deviceptr:: Get device pointer associated with specific
2256 * acc_hostptr:: Get host pointer associated with specific
2258 * acc_is_present:: Indicate whether host variable / array is
2260 * acc_memcpy_to_device:: Copy host memory to device memory.
2261 * acc_memcpy_from_device:: Copy device memory to host memory.
2262 * acc_attach:: Let device pointer point to device-pointer target.
2263 * acc_detach:: Let device pointer point to host-pointer target.
2265 API routines for target platforms.
2267 * acc_get_current_cuda_device:: Get CUDA device handle.
2268 * acc_get_current_cuda_context::Get CUDA context handle.
2269 * acc_get_cuda_stream:: Get CUDA stream handle.
2270 * acc_set_cuda_stream:: Set CUDA stream handle.
2272 API routines for the OpenACC Profiling Interface.
2274 * acc_prof_register:: Register callbacks.
2275 * acc_prof_unregister:: Unregister callbacks.
2276 * acc_prof_lookup:: Obtain inquiry functions.
2277 * acc_register_library:: Library registration.
2282 @node acc_get_num_devices
2283 @section @code{acc_get_num_devices} -- Get number of devices for given device type
2285 @item @emph{Description}
2286 This function returns a value indicating the number of devices available
2287 for the device type specified in @var{devicetype}.
2290 @multitable @columnfractions .20 .80
2291 @item @emph{Prototype}: @tab @code{int acc_get_num_devices(acc_device_t devicetype);}
2294 @item @emph{Fortran}:
2295 @multitable @columnfractions .20 .80
2296 @item @emph{Interface}: @tab @code{integer function acc_get_num_devices(devicetype)}
2297 @item @tab @code{integer(kind=acc_device_kind) devicetype}
2300 @item @emph{Reference}:
2301 @uref{https://www.openacc.org, OpenACC specification v2.6}, section
2307 @node acc_set_device_type
2308 @section @code{acc_set_device_type} -- Set type of device accelerator to use.
2310 @item @emph{Description}
2311 This function indicates to the runtime library which device type, specified
2312 in @var{devicetype}, to use when executing a parallel or kernels region.
2315 @multitable @columnfractions .20 .80
2316 @item @emph{Prototype}: @tab @code{acc_set_device_type(acc_device_t devicetype);}
2319 @item @emph{Fortran}:
2320 @multitable @columnfractions .20 .80
2321 @item @emph{Interface}: @tab @code{subroutine acc_set_device_type(devicetype)}
2322 @item @tab @code{integer(kind=acc_device_kind) devicetype}
2325 @item @emph{Reference}:
2326 @uref{https://www.openacc.org, OpenACC specification v2.6}, section
2332 @node acc_get_device_type
2333 @section @code{acc_get_device_type} -- Get type of device accelerator to be used.
2335 @item @emph{Description}
2336 This function returns what device type will be used when executing a
2337 parallel or kernels region.
2339 This function returns @code{acc_device_none} if
2340 @code{acc_get_device_type} is called from
2341 @code{acc_ev_device_init_start}, @code{acc_ev_device_init_end}
2342 callbacks of the OpenACC Profiling Interface (@ref{OpenACC Profiling
2343 Interface}), that is, if the device is currently being initialized.
2346 @multitable @columnfractions .20 .80
2347 @item @emph{Prototype}: @tab @code{acc_device_t acc_get_device_type(void);}
2350 @item @emph{Fortran}:
2351 @multitable @columnfractions .20 .80
2352 @item @emph{Interface}: @tab @code{function acc_get_device_type(void)}
2353 @item @tab @code{integer(kind=acc_device_kind) acc_get_device_type}
2356 @item @emph{Reference}:
2357 @uref{https://www.openacc.org, OpenACC specification v2.6}, section
2363 @node acc_set_device_num
2364 @section @code{acc_set_device_num} -- Set device number to use.
2366 @item @emph{Description}
2367 This function will indicate to the runtime which device number,
2368 specified by @var{devicenum}, associated with the specified device
2369 type @var{devicetype}.
2372 @multitable @columnfractions .20 .80
2373 @item @emph{Prototype}: @tab @code{acc_set_device_num(int devicenum, acc_device_t devicetype);}
2376 @item @emph{Fortran}:
2377 @multitable @columnfractions .20 .80
2378 @item @emph{Interface}: @tab @code{subroutine acc_set_device_num(devicenum, devicetype)}
2379 @item @tab @code{integer devicenum}
2380 @item @tab @code{integer(kind=acc_device_kind) devicetype}
2383 @item @emph{Reference}:
2384 @uref{https://www.openacc.org, OpenACC specification v2.6}, section
2390 @node acc_get_device_num
2391 @section @code{acc_get_device_num} -- Get device number to be used.
2393 @item @emph{Description}
2394 This function returns which device number associated with the specified device
2395 type @var{devicetype}, will be used when executing a parallel or kernels
2399 @multitable @columnfractions .20 .80
2400 @item @emph{Prototype}: @tab @code{int acc_get_device_num(acc_device_t devicetype);}
2403 @item @emph{Fortran}:
2404 @multitable @columnfractions .20 .80
2405 @item @emph{Interface}: @tab @code{function acc_get_device_num(devicetype)}
2406 @item @tab @code{integer(kind=acc_device_kind) devicetype}
2407 @item @tab @code{integer acc_get_device_num}
2410 @item @emph{Reference}:
2411 @uref{https://www.openacc.org, OpenACC specification v2.6}, section
2417 @node acc_get_property
2418 @section @code{acc_get_property} -- Get device property.
2419 @cindex acc_get_property
2420 @cindex acc_get_property_string
2422 @item @emph{Description}
2423 These routines return the value of the specified @var{property} for the
2424 device being queried according to @var{devicenum} and @var{devicetype}.
2425 Integer-valued and string-valued properties are returned by
2426 @code{acc_get_property} and @code{acc_get_property_string} respectively.
2427 The Fortran @code{acc_get_property_string} subroutine returns the string
2428 retrieved in its fourth argument while the remaining entry points are
2429 functions, which pass the return value as their result.
2431 Note for Fortran, only: the OpenACC technical committee corrected and, hence,
2432 modified the interface introduced in OpenACC 2.6. The kind-value parameter
2433 @code{acc_device_property} has been renamed to @code{acc_device_property_kind}
2434 for consistency and the return type of the @code{acc_get_property} function is
2435 now a @code{c_size_t} integer instead of a @code{acc_device_property} integer.
2436 The parameter @code{acc_device_property} will continue to be provided,
2437 but might be removed in a future version of GCC.
2440 @multitable @columnfractions .20 .80
2441 @item @emph{Prototype}: @tab @code{size_t acc_get_property(int devicenum, acc_device_t devicetype, acc_device_property_t property);}
2442 @item @emph{Prototype}: @tab @code{const char *acc_get_property_string(int devicenum, acc_device_t devicetype, acc_device_property_t property);}
2445 @item @emph{Fortran}:
2446 @multitable @columnfractions .20 .80
2447 @item @emph{Interface}: @tab @code{function acc_get_property(devicenum, devicetype, property)}
2448 @item @emph{Interface}: @tab @code{subroutine acc_get_property_string(devicenum, devicetype, property, string)}
2449 @item @tab @code{use ISO_C_Binding, only: c_size_t}
2450 @item @tab @code{integer devicenum}
2451 @item @tab @code{integer(kind=acc_device_kind) devicetype}
2452 @item @tab @code{integer(kind=acc_device_property_kind) property}
2453 @item @tab @code{integer(kind=c_size_t) acc_get_property}
2454 @item @tab @code{character(*) string}
2457 @item @emph{Reference}:
2458 @uref{https://www.openacc.org, OpenACC specification v2.6}, section
2464 @node acc_async_test
2465 @section @code{acc_async_test} -- Test for completion of a specific asynchronous operation.
2467 @item @emph{Description}
2468 This function tests for completion of the asynchronous operation specified
2469 in @var{arg}. In C/C++, a non-zero value will be returned to indicate
2470 the specified asynchronous operation has completed. While Fortran will return
2471 a @code{true}. If the asynchronous operation has not completed, C/C++ returns
2472 a zero and Fortran returns a @code{false}.
2475 @multitable @columnfractions .20 .80
2476 @item @emph{Prototype}: @tab @code{int acc_async_test(int arg);}
2479 @item @emph{Fortran}:
2480 @multitable @columnfractions .20 .80
2481 @item @emph{Interface}: @tab @code{function acc_async_test(arg)}
2482 @item @tab @code{integer(kind=acc_handle_kind) arg}
2483 @item @tab @code{logical acc_async_test}
2486 @item @emph{Reference}:
2487 @uref{https://www.openacc.org, OpenACC specification v2.6}, section
2493 @node acc_async_test_all
2494 @section @code{acc_async_test_all} -- Tests for completion of all asynchronous operations.
2496 @item @emph{Description}
2497 This function tests for completion of all asynchronous operations.
2498 In C/C++, a non-zero value will be returned to indicate all asynchronous
2499 operations have completed. While Fortran will return a @code{true}. If
2500 any asynchronous operation has not completed, C/C++ returns a zero and
2501 Fortran returns a @code{false}.
2504 @multitable @columnfractions .20 .80
2505 @item @emph{Prototype}: @tab @code{int acc_async_test_all(void);}
2508 @item @emph{Fortran}:
2509 @multitable @columnfractions .20 .80
2510 @item @emph{Interface}: @tab @code{function acc_async_test()}
2511 @item @tab @code{logical acc_get_device_num}
2514 @item @emph{Reference}:
2515 @uref{https://www.openacc.org, OpenACC specification v2.6}, section
2522 @section @code{acc_wait} -- Wait for completion of a specific asynchronous operation.
2524 @item @emph{Description}
2525 This function waits for completion of the asynchronous operation
2526 specified in @var{arg}.
2529 @multitable @columnfractions .20 .80
2530 @item @emph{Prototype}: @tab @code{acc_wait(arg);}
2531 @item @emph{Prototype (OpenACC 1.0 compatibility)}: @tab @code{acc_async_wait(arg);}
2534 @item @emph{Fortran}:
2535 @multitable @columnfractions .20 .80
2536 @item @emph{Interface}: @tab @code{subroutine acc_wait(arg)}
2537 @item @tab @code{integer(acc_handle_kind) arg}
2538 @item @emph{Interface (OpenACC 1.0 compatibility)}: @tab @code{subroutine acc_async_wait(arg)}
2539 @item @tab @code{integer(acc_handle_kind) arg}
2542 @item @emph{Reference}:
2543 @uref{https://www.openacc.org, OpenACC specification v2.6}, section
2550 @section @code{acc_wait_all} -- Waits for completion of all asynchronous operations.
2552 @item @emph{Description}
2553 This function waits for the completion of all asynchronous operations.
2556 @multitable @columnfractions .20 .80
2557 @item @emph{Prototype}: @tab @code{acc_wait_all(void);}
2558 @item @emph{Prototype (OpenACC 1.0 compatibility)}: @tab @code{acc_async_wait_all(void);}
2561 @item @emph{Fortran}:
2562 @multitable @columnfractions .20 .80
2563 @item @emph{Interface}: @tab @code{subroutine acc_wait_all()}
2564 @item @emph{Interface (OpenACC 1.0 compatibility)}: @tab @code{subroutine acc_async_wait_all()}
2567 @item @emph{Reference}:
2568 @uref{https://www.openacc.org, OpenACC specification v2.6}, section
2574 @node acc_wait_all_async
2575 @section @code{acc_wait_all_async} -- Wait for completion of all asynchronous operations.
2577 @item @emph{Description}
2578 This function enqueues a wait operation on the queue @var{async} for any
2579 and all asynchronous operations that have been previously enqueued on
2583 @multitable @columnfractions .20 .80
2584 @item @emph{Prototype}: @tab @code{acc_wait_all_async(int async);}
2587 @item @emph{Fortran}:
2588 @multitable @columnfractions .20 .80
2589 @item @emph{Interface}: @tab @code{subroutine acc_wait_all_async(async)}
2590 @item @tab @code{integer(acc_handle_kind) async}
2593 @item @emph{Reference}:
2594 @uref{https://www.openacc.org, OpenACC specification v2.6}, section
2600 @node acc_wait_async
2601 @section @code{acc_wait_async} -- Wait for completion of asynchronous operations.
2603 @item @emph{Description}
2604 This function enqueues a wait operation on queue @var{async} for any and all
2605 asynchronous operations enqueued on queue @var{arg}.
2608 @multitable @columnfractions .20 .80
2609 @item @emph{Prototype}: @tab @code{acc_wait_async(int arg, int async);}
2612 @item @emph{Fortran}:
2613 @multitable @columnfractions .20 .80
2614 @item @emph{Interface}: @tab @code{subroutine acc_wait_async(arg, async)}
2615 @item @tab @code{integer(acc_handle_kind) arg, async}
2618 @item @emph{Reference}:
2619 @uref{https://www.openacc.org, OpenACC specification v2.6}, section
2626 @section @code{acc_init} -- Initialize runtime for a specific device type.
2628 @item @emph{Description}
2629 This function initializes the runtime for the device type specified in
2633 @multitable @columnfractions .20 .80
2634 @item @emph{Prototype}: @tab @code{acc_init(acc_device_t devicetype);}
2637 @item @emph{Fortran}:
2638 @multitable @columnfractions .20 .80
2639 @item @emph{Interface}: @tab @code{subroutine acc_init(devicetype)}
2640 @item @tab @code{integer(acc_device_kind) devicetype}
2643 @item @emph{Reference}:
2644 @uref{https://www.openacc.org, OpenACC specification v2.6}, section
2651 @section @code{acc_shutdown} -- Shuts down the runtime for a specific device type.
2653 @item @emph{Description}
2654 This function shuts down the runtime for the device type specified in
2658 @multitable @columnfractions .20 .80
2659 @item @emph{Prototype}: @tab @code{acc_shutdown(acc_device_t devicetype);}
2662 @item @emph{Fortran}:
2663 @multitable @columnfractions .20 .80
2664 @item @emph{Interface}: @tab @code{subroutine acc_shutdown(devicetype)}
2665 @item @tab @code{integer(acc_device_kind) devicetype}
2668 @item @emph{Reference}:
2669 @uref{https://www.openacc.org, OpenACC specification v2.6}, section
2676 @section @code{acc_on_device} -- Whether executing on a particular device
2678 @item @emph{Description}:
2679 This function returns whether the program is executing on a particular
2680 device specified in @var{devicetype}. In C/C++ a non-zero value is
2681 returned to indicate the device is executing on the specified device type.
2682 In Fortran, @code{true} will be returned. If the program is not executing
2683 on the specified device type C/C++ will return a zero, while Fortran will
2684 return @code{false}.
2687 @multitable @columnfractions .20 .80
2688 @item @emph{Prototype}: @tab @code{acc_on_device(acc_device_t devicetype);}
2691 @item @emph{Fortran}:
2692 @multitable @columnfractions .20 .80
2693 @item @emph{Interface}: @tab @code{function acc_on_device(devicetype)}
2694 @item @tab @code{integer(acc_device_kind) devicetype}
2695 @item @tab @code{logical acc_on_device}
2699 @item @emph{Reference}:
2700 @uref{https://www.openacc.org, OpenACC specification v2.6}, section
2707 @section @code{acc_malloc} -- Allocate device memory.
2709 @item @emph{Description}
2710 This function allocates @var{len} bytes of device memory. It returns
2711 the device address of the allocated memory.
2714 @multitable @columnfractions .20 .80
2715 @item @emph{Prototype}: @tab @code{d_void* acc_malloc(size_t len);}
2718 @item @emph{Reference}:
2719 @uref{https://www.openacc.org, OpenACC specification v2.6}, section
2726 @section @code{acc_free} -- Free device memory.
2728 @item @emph{Description}
2729 Free previously allocated device memory at the device address @code{a}.
2732 @multitable @columnfractions .20 .80
2733 @item @emph{Prototype}: @tab @code{acc_free(d_void *a);}
2736 @item @emph{Reference}:
2737 @uref{https://www.openacc.org, OpenACC specification v2.6}, section
2744 @section @code{acc_copyin} -- Allocate device memory and copy host memory to it.
2746 @item @emph{Description}
2747 In C/C++, this function allocates @var{len} bytes of device memory
2748 and maps it to the specified host address in @var{a}. The device
2749 address of the newly allocated device memory is returned.
2751 In Fortran, two (2) forms are supported. In the first form, @var{a} specifies
2752 a contiguous array section. The second form @var{a} specifies a
2753 variable or array element and @var{len} specifies the length in bytes.
2756 @multitable @columnfractions .20 .80
2757 @item @emph{Prototype}: @tab @code{void *acc_copyin(h_void *a, size_t len);}
2758 @item @emph{Prototype}: @tab @code{void *acc_copyin_async(h_void *a, size_t len, int async);}
2761 @item @emph{Fortran}:
2762 @multitable @columnfractions .20 .80
2763 @item @emph{Interface}: @tab @code{subroutine acc_copyin(a)}
2764 @item @tab @code{type, dimension(:[,:]...) :: a}
2765 @item @emph{Interface}: @tab @code{subroutine acc_copyin(a, len)}
2766 @item @tab @code{type, dimension(:[,:]...) :: a}
2767 @item @tab @code{integer len}
2768 @item @emph{Interface}: @tab @code{subroutine acc_copyin_async(a, async)}
2769 @item @tab @code{type, dimension(:[,:]...) :: a}
2770 @item @tab @code{integer(acc_handle_kind) :: async}
2771 @item @emph{Interface}: @tab @code{subroutine acc_copyin_async(a, len, async)}
2772 @item @tab @code{type, dimension(:[,:]...) :: a}
2773 @item @tab @code{integer len}
2774 @item @tab @code{integer(acc_handle_kind) :: async}
2777 @item @emph{Reference}:
2778 @uref{https://www.openacc.org, OpenACC specification v2.6}, section
2784 @node acc_present_or_copyin
2785 @section @code{acc_present_or_copyin} -- If the data is not present on the device, allocate device memory and copy from host memory.
2787 @item @emph{Description}
2788 This function tests if the host data specified by @var{a} and of length
2789 @var{len} is present or not. If it is not present, then device memory
2790 will be allocated and the host memory copied. The device address of
2791 the newly allocated device memory is returned.
2793 In Fortran, two (2) forms are supported. In the first form, @var{a} specifies
2794 a contiguous array section. The second form @var{a} specifies a variable or
2795 array element and @var{len} specifies the length in bytes.
2797 Note that @code{acc_present_or_copyin} and @code{acc_pcopyin} exist for
2798 backward compatibility with OpenACC 2.0; use @ref{acc_copyin} instead.
2801 @multitable @columnfractions .20 .80
2802 @item @emph{Prototype}: @tab @code{void *acc_present_or_copyin(h_void *a, size_t len);}
2803 @item @emph{Prototype}: @tab @code{void *acc_pcopyin(h_void *a, size_t len);}
2806 @item @emph{Fortran}:
2807 @multitable @columnfractions .20 .80
2808 @item @emph{Interface}: @tab @code{subroutine acc_present_or_copyin(a)}
2809 @item @tab @code{type, dimension(:[,:]...) :: a}
2810 @item @emph{Interface}: @tab @code{subroutine acc_present_or_copyin(a, len)}
2811 @item @tab @code{type, dimension(:[,:]...) :: a}
2812 @item @tab @code{integer len}
2813 @item @emph{Interface}: @tab @code{subroutine acc_pcopyin(a)}
2814 @item @tab @code{type, dimension(:[,:]...) :: a}
2815 @item @emph{Interface}: @tab @code{subroutine acc_pcopyin(a, len)}
2816 @item @tab @code{type, dimension(:[,:]...) :: a}
2817 @item @tab @code{integer len}
2820 @item @emph{Reference}:
2821 @uref{https://www.openacc.org, OpenACC specification v2.6}, section
2828 @section @code{acc_create} -- Allocate device memory and map it to host memory.
2830 @item @emph{Description}
2831 This function allocates device memory and maps it to host memory specified
2832 by the host address @var{a} with a length of @var{len} bytes. In C/C++,
2833 the function returns the device address of the allocated device memory.
2835 In Fortran, two (2) forms are supported. In the first form, @var{a} specifies
2836 a contiguous array section. The second form @var{a} specifies a variable or
2837 array element and @var{len} specifies the length in bytes.
2840 @multitable @columnfractions .20 .80
2841 @item @emph{Prototype}: @tab @code{void *acc_create(h_void *a, size_t len);}
2842 @item @emph{Prototype}: @tab @code{void *acc_create_async(h_void *a, size_t len, int async);}
2845 @item @emph{Fortran}:
2846 @multitable @columnfractions .20 .80
2847 @item @emph{Interface}: @tab @code{subroutine acc_create(a)}
2848 @item @tab @code{type, dimension(:[,:]...) :: a}
2849 @item @emph{Interface}: @tab @code{subroutine acc_create(a, len)}
2850 @item @tab @code{type, dimension(:[,:]...) :: a}
2851 @item @tab @code{integer len}
2852 @item @emph{Interface}: @tab @code{subroutine acc_create_async(a, async)}
2853 @item @tab @code{type, dimension(:[,:]...) :: a}
2854 @item @tab @code{integer(acc_handle_kind) :: async}
2855 @item @emph{Interface}: @tab @code{subroutine acc_create_async(a, len, async)}
2856 @item @tab @code{type, dimension(:[,:]...) :: a}
2857 @item @tab @code{integer len}
2858 @item @tab @code{integer(acc_handle_kind) :: async}
2861 @item @emph{Reference}:
2862 @uref{https://www.openacc.org, OpenACC specification v2.6}, section
2868 @node acc_present_or_create
2869 @section @code{acc_present_or_create} -- If the data is not present on the device, allocate device memory and map it to host memory.
2871 @item @emph{Description}
2872 This function tests if the host data specified by @var{a} and of length
2873 @var{len} is present or not. If it is not present, then device memory
2874 will be allocated and mapped to host memory. In C/C++, the device address
2875 of the newly allocated device memory is returned.
2877 In Fortran, two (2) forms are supported. In the first form, @var{a} specifies
2878 a contiguous array section. The second form @var{a} specifies a variable or
2879 array element and @var{len} specifies the length in bytes.
2881 Note that @code{acc_present_or_create} and @code{acc_pcreate} exist for
2882 backward compatibility with OpenACC 2.0; use @ref{acc_create} instead.
2885 @multitable @columnfractions .20 .80
2886 @item @emph{Prototype}: @tab @code{void *acc_present_or_create(h_void *a, size_t len)}
2887 @item @emph{Prototype}: @tab @code{void *acc_pcreate(h_void *a, size_t len)}
2890 @item @emph{Fortran}:
2891 @multitable @columnfractions .20 .80
2892 @item @emph{Interface}: @tab @code{subroutine acc_present_or_create(a)}
2893 @item @tab @code{type, dimension(:[,:]...) :: a}
2894 @item @emph{Interface}: @tab @code{subroutine acc_present_or_create(a, len)}
2895 @item @tab @code{type, dimension(:[,:]...) :: a}
2896 @item @tab @code{integer len}
2897 @item @emph{Interface}: @tab @code{subroutine acc_pcreate(a)}
2898 @item @tab @code{type, dimension(:[,:]...) :: a}
2899 @item @emph{Interface}: @tab @code{subroutine acc_pcreate(a, len)}
2900 @item @tab @code{type, dimension(:[,:]...) :: a}
2901 @item @tab @code{integer len}
2904 @item @emph{Reference}:
2905 @uref{https://www.openacc.org, OpenACC specification v2.6}, section
2912 @section @code{acc_copyout} -- Copy device memory to host memory.
2914 @item @emph{Description}
2915 This function copies mapped device memory to host memory which is specified
2916 by host address @var{a} for a length @var{len} bytes in C/C++.
2918 In Fortran, two (2) forms are supported. In the first form, @var{a} specifies
2919 a contiguous array section. The second form @var{a} specifies a variable or
2920 array element and @var{len} specifies the length in bytes.
2923 @multitable @columnfractions .20 .80
2924 @item @emph{Prototype}: @tab @code{acc_copyout(h_void *a, size_t len);}
2925 @item @emph{Prototype}: @tab @code{acc_copyout_async(h_void *a, size_t len, int async);}
2926 @item @emph{Prototype}: @tab @code{acc_copyout_finalize(h_void *a, size_t len);}
2927 @item @emph{Prototype}: @tab @code{acc_copyout_finalize_async(h_void *a, size_t len, int async);}
2930 @item @emph{Fortran}:
2931 @multitable @columnfractions .20 .80
2932 @item @emph{Interface}: @tab @code{subroutine acc_copyout(a)}
2933 @item @tab @code{type, dimension(:[,:]...) :: a}
2934 @item @emph{Interface}: @tab @code{subroutine acc_copyout(a, len)}
2935 @item @tab @code{type, dimension(:[,:]...) :: a}
2936 @item @tab @code{integer len}
2937 @item @emph{Interface}: @tab @code{subroutine acc_copyout_async(a, async)}
2938 @item @tab @code{type, dimension(:[,:]...) :: a}
2939 @item @tab @code{integer(acc_handle_kind) :: async}
2940 @item @emph{Interface}: @tab @code{subroutine acc_copyout_async(a, len, async)}
2941 @item @tab @code{type, dimension(:[,:]...) :: a}
2942 @item @tab @code{integer len}
2943 @item @tab @code{integer(acc_handle_kind) :: async}
2944 @item @emph{Interface}: @tab @code{subroutine acc_copyout_finalize(a)}
2945 @item @tab @code{type, dimension(:[,:]...) :: a}
2946 @item @emph{Interface}: @tab @code{subroutine acc_copyout_finalize(a, len)}
2947 @item @tab @code{type, dimension(:[,:]...) :: a}
2948 @item @tab @code{integer len}
2949 @item @emph{Interface}: @tab @code{subroutine acc_copyout_finalize_async(a, async)}
2950 @item @tab @code{type, dimension(:[,:]...) :: a}
2951 @item @tab @code{integer(acc_handle_kind) :: async}
2952 @item @emph{Interface}: @tab @code{subroutine acc_copyout_finalize_async(a, len, async)}
2953 @item @tab @code{type, dimension(:[,:]...) :: a}
2954 @item @tab @code{integer len}
2955 @item @tab @code{integer(acc_handle_kind) :: async}
2958 @item @emph{Reference}:
2959 @uref{https://www.openacc.org, OpenACC specification v2.6}, section
2966 @section @code{acc_delete} -- Free device memory.
2968 @item @emph{Description}
2969 This function frees previously allocated device memory specified by
2970 the device address @var{a} and the length of @var{len} bytes.
2972 In Fortran, two (2) forms are supported. In the first form, @var{a} specifies
2973 a contiguous array section. The second form @var{a} specifies a variable or
2974 array element and @var{len} specifies the length in bytes.
2977 @multitable @columnfractions .20 .80
2978 @item @emph{Prototype}: @tab @code{acc_delete(h_void *a, size_t len);}
2979 @item @emph{Prototype}: @tab @code{acc_delete_async(h_void *a, size_t len, int async);}
2980 @item @emph{Prototype}: @tab @code{acc_delete_finalize(h_void *a, size_t len);}
2981 @item @emph{Prototype}: @tab @code{acc_delete_finalize_async(h_void *a, size_t len, int async);}
2984 @item @emph{Fortran}:
2985 @multitable @columnfractions .20 .80
2986 @item @emph{Interface}: @tab @code{subroutine acc_delete(a)}
2987 @item @tab @code{type, dimension(:[,:]...) :: a}
2988 @item @emph{Interface}: @tab @code{subroutine acc_delete(a, len)}
2989 @item @tab @code{type, dimension(:[,:]...) :: a}
2990 @item @tab @code{integer len}
2991 @item @emph{Interface}: @tab @code{subroutine acc_delete_async(a, async)}
2992 @item @tab @code{type, dimension(:[,:]...) :: a}
2993 @item @tab @code{integer(acc_handle_kind) :: async}
2994 @item @emph{Interface}: @tab @code{subroutine acc_delete_async(a, len, async)}
2995 @item @tab @code{type, dimension(:[,:]...) :: a}
2996 @item @tab @code{integer len}
2997 @item @tab @code{integer(acc_handle_kind) :: async}
2998 @item @emph{Interface}: @tab @code{subroutine acc_delete_finalize(a)}
2999 @item @tab @code{type, dimension(:[,:]...) :: a}
3000 @item @emph{Interface}: @tab @code{subroutine acc_delete_finalize(a, len)}
3001 @item @tab @code{type, dimension(:[,:]...) :: a}
3002 @item @tab @code{integer len}
3003 @item @emph{Interface}: @tab @code{subroutine acc_delete_async_finalize(a, async)}
3004 @item @tab @code{type, dimension(:[,:]...) :: a}
3005 @item @tab @code{integer(acc_handle_kind) :: async}
3006 @item @emph{Interface}: @tab @code{subroutine acc_delete_async_finalize(a, len, async)}
3007 @item @tab @code{type, dimension(:[,:]...) :: a}
3008 @item @tab @code{integer len}
3009 @item @tab @code{integer(acc_handle_kind) :: async}
3012 @item @emph{Reference}:
3013 @uref{https://www.openacc.org, OpenACC specification v2.6}, section
3019 @node acc_update_device
3020 @section @code{acc_update_device} -- Update device memory from mapped host memory.
3022 @item @emph{Description}
3023 This function updates the device copy from the previously mapped host memory.
3024 The host memory is specified with the host address @var{a} and a length of
3027 In Fortran, two (2) forms are supported. In the first form, @var{a} specifies
3028 a contiguous array section. The second form @var{a} specifies a variable or
3029 array element and @var{len} specifies the length in bytes.
3032 @multitable @columnfractions .20 .80
3033 @item @emph{Prototype}: @tab @code{acc_update_device(h_void *a, size_t len);}
3034 @item @emph{Prototype}: @tab @code{acc_update_device(h_void *a, size_t len, async);}
3037 @item @emph{Fortran}:
3038 @multitable @columnfractions .20 .80
3039 @item @emph{Interface}: @tab @code{subroutine acc_update_device(a)}
3040 @item @tab @code{type, dimension(:[,:]...) :: a}
3041 @item @emph{Interface}: @tab @code{subroutine acc_update_device(a, len)}
3042 @item @tab @code{type, dimension(:[,:]...) :: a}
3043 @item @tab @code{integer len}
3044 @item @emph{Interface}: @tab @code{subroutine acc_update_device_async(a, async)}
3045 @item @tab @code{type, dimension(:[,:]...) :: a}
3046 @item @tab @code{integer(acc_handle_kind) :: async}
3047 @item @emph{Interface}: @tab @code{subroutine acc_update_device_async(a, len, async)}
3048 @item @tab @code{type, dimension(:[,:]...) :: a}
3049 @item @tab @code{integer len}
3050 @item @tab @code{integer(acc_handle_kind) :: async}
3053 @item @emph{Reference}:
3054 @uref{https://www.openacc.org, OpenACC specification v2.6}, section
3060 @node acc_update_self
3061 @section @code{acc_update_self} -- Update host memory from mapped device memory.
3063 @item @emph{Description}
3064 This function updates the host copy from the previously mapped device memory.
3065 The host memory is specified with the host address @var{a} and a length of
3068 In Fortran, two (2) forms are supported. In the first form, @var{a} specifies
3069 a contiguous array section. The second form @var{a} specifies a variable or
3070 array element and @var{len} specifies the length in bytes.
3073 @multitable @columnfractions .20 .80
3074 @item @emph{Prototype}: @tab @code{acc_update_self(h_void *a, size_t len);}
3075 @item @emph{Prototype}: @tab @code{acc_update_self_async(h_void *a, size_t len, int async);}
3078 @item @emph{Fortran}:
3079 @multitable @columnfractions .20 .80
3080 @item @emph{Interface}: @tab @code{subroutine acc_update_self(a)}
3081 @item @tab @code{type, dimension(:[,:]...) :: a}
3082 @item @emph{Interface}: @tab @code{subroutine acc_update_self(a, len)}
3083 @item @tab @code{type, dimension(:[,:]...) :: a}
3084 @item @tab @code{integer len}
3085 @item @emph{Interface}: @tab @code{subroutine acc_update_self_async(a, async)}
3086 @item @tab @code{type, dimension(:[,:]...) :: a}
3087 @item @tab @code{integer(acc_handle_kind) :: async}
3088 @item @emph{Interface}: @tab @code{subroutine acc_update_self_async(a, len, async)}
3089 @item @tab @code{type, dimension(:[,:]...) :: a}
3090 @item @tab @code{integer len}
3091 @item @tab @code{integer(acc_handle_kind) :: async}
3094 @item @emph{Reference}:
3095 @uref{https://www.openacc.org, OpenACC specification v2.6}, section
3102 @section @code{acc_map_data} -- Map previously allocated device memory to host memory.
3104 @item @emph{Description}
3105 This function maps previously allocated device and host memory. The device
3106 memory is specified with the device address @var{d}. The host memory is
3107 specified with the host address @var{h} and a length of @var{len}.
3110 @multitable @columnfractions .20 .80
3111 @item @emph{Prototype}: @tab @code{acc_map_data(h_void *h, d_void *d, size_t len);}
3114 @item @emph{Reference}:
3115 @uref{https://www.openacc.org, OpenACC specification v2.6}, section
3121 @node acc_unmap_data
3122 @section @code{acc_unmap_data} -- Unmap device memory from host memory.
3124 @item @emph{Description}
3125 This function unmaps previously mapped device and host memory. The latter
3126 specified by @var{h}.
3129 @multitable @columnfractions .20 .80
3130 @item @emph{Prototype}: @tab @code{acc_unmap_data(h_void *h);}
3133 @item @emph{Reference}:
3134 @uref{https://www.openacc.org, OpenACC specification v2.6}, section
3141 @section @code{acc_deviceptr} -- Get device pointer associated with specific host address.
3143 @item @emph{Description}
3144 This function returns the device address that has been mapped to the
3145 host address specified by @var{h}.
3148 @multitable @columnfractions .20 .80
3149 @item @emph{Prototype}: @tab @code{void *acc_deviceptr(h_void *h);}
3152 @item @emph{Reference}:
3153 @uref{https://www.openacc.org, OpenACC specification v2.6}, section
3160 @section @code{acc_hostptr} -- Get host pointer associated with specific device address.
3162 @item @emph{Description}
3163 This function returns the host address that has been mapped to the
3164 device address specified by @var{d}.
3167 @multitable @columnfractions .20 .80
3168 @item @emph{Prototype}: @tab @code{void *acc_hostptr(d_void *d);}
3171 @item @emph{Reference}:
3172 @uref{https://www.openacc.org, OpenACC specification v2.6}, section
3178 @node acc_is_present
3179 @section @code{acc_is_present} -- Indicate whether host variable / array is present on device.
3181 @item @emph{Description}
3182 This function indicates whether the specified host address in @var{a} and a
3183 length of @var{len} bytes is present on the device. In C/C++, a non-zero
3184 value is returned to indicate the presence of the mapped memory on the
3185 device. A zero is returned to indicate the memory is not mapped on the
3188 In Fortran, two (2) forms are supported. In the first form, @var{a} specifies
3189 a contiguous array section. The second form @var{a} specifies a variable or
3190 array element and @var{len} specifies the length in bytes. If the host
3191 memory is mapped to device memory, then a @code{true} is returned. Otherwise,
3192 a @code{false} is return to indicate the mapped memory is not present.
3195 @multitable @columnfractions .20 .80
3196 @item @emph{Prototype}: @tab @code{int acc_is_present(h_void *a, size_t len);}
3199 @item @emph{Fortran}:
3200 @multitable @columnfractions .20 .80
3201 @item @emph{Interface}: @tab @code{function acc_is_present(a)}
3202 @item @tab @code{type, dimension(:[,:]...) :: a}
3203 @item @tab @code{logical acc_is_present}
3204 @item @emph{Interface}: @tab @code{function acc_is_present(a, len)}
3205 @item @tab @code{type, dimension(:[,:]...) :: a}
3206 @item @tab @code{integer len}
3207 @item @tab @code{logical acc_is_present}
3210 @item @emph{Reference}:
3211 @uref{https://www.openacc.org, OpenACC specification v2.6}, section
3217 @node acc_memcpy_to_device
3218 @section @code{acc_memcpy_to_device} -- Copy host memory to device memory.
3220 @item @emph{Description}
3221 This function copies host memory specified by host address of @var{src} to
3222 device memory specified by the device address @var{dest} for a length of
3226 @multitable @columnfractions .20 .80
3227 @item @emph{Prototype}: @tab @code{acc_memcpy_to_device(d_void *dest, h_void *src, size_t bytes);}
3230 @item @emph{Reference}:
3231 @uref{https://www.openacc.org, OpenACC specification v2.6}, section
3237 @node acc_memcpy_from_device
3238 @section @code{acc_memcpy_from_device} -- Copy device memory to host memory.
3240 @item @emph{Description}
3241 This function copies host memory specified by host address of @var{src} from
3242 device memory specified by the device address @var{dest} for a length of
3246 @multitable @columnfractions .20 .80
3247 @item @emph{Prototype}: @tab @code{acc_memcpy_from_device(d_void *dest, h_void *src, size_t bytes);}
3250 @item @emph{Reference}:
3251 @uref{https://www.openacc.org, OpenACC specification v2.6}, section
3258 @section @code{acc_attach} -- Let device pointer point to device-pointer target.
3260 @item @emph{Description}
3261 This function updates a pointer on the device from pointing to a host-pointer
3262 address to pointing to the corresponding device data.
3265 @multitable @columnfractions .20 .80
3266 @item @emph{Prototype}: @tab @code{acc_attach(h_void **ptr);}
3267 @item @emph{Prototype}: @tab @code{acc_attach_async(h_void **ptr, int async);}
3270 @item @emph{Reference}:
3271 @uref{https://www.openacc.org, OpenACC specification v2.6}, section
3278 @section @code{acc_detach} -- Let device pointer point to host-pointer target.
3280 @item @emph{Description}
3281 This function updates a pointer on the device from pointing to a device-pointer
3282 address to pointing to the corresponding host data.
3285 @multitable @columnfractions .20 .80
3286 @item @emph{Prototype}: @tab @code{acc_detach(h_void **ptr);}
3287 @item @emph{Prototype}: @tab @code{acc_detach_async(h_void **ptr, int async);}
3288 @item @emph{Prototype}: @tab @code{acc_detach_finalize(h_void **ptr);}
3289 @item @emph{Prototype}: @tab @code{acc_detach_finalize_async(h_void **ptr, int async);}
3292 @item @emph{Reference}:
3293 @uref{https://www.openacc.org, OpenACC specification v2.6}, section
3299 @node acc_get_current_cuda_device
3300 @section @code{acc_get_current_cuda_device} -- Get CUDA device handle.
3302 @item @emph{Description}
3303 This function returns the CUDA device handle. This handle is the same
3304 as used by the CUDA Runtime or Driver API's.
3307 @multitable @columnfractions .20 .80
3308 @item @emph{Prototype}: @tab @code{void *acc_get_current_cuda_device(void);}
3311 @item @emph{Reference}:
3312 @uref{https://www.openacc.org, OpenACC specification v2.6}, section
3318 @node acc_get_current_cuda_context
3319 @section @code{acc_get_current_cuda_context} -- Get CUDA context handle.
3321 @item @emph{Description}
3322 This function returns the CUDA context handle. This handle is the same
3323 as used by the CUDA Runtime or Driver API's.
3326 @multitable @columnfractions .20 .80
3327 @item @emph{Prototype}: @tab @code{void *acc_get_current_cuda_context(void);}
3330 @item @emph{Reference}:
3331 @uref{https://www.openacc.org, OpenACC specification v2.6}, section
3337 @node acc_get_cuda_stream
3338 @section @code{acc_get_cuda_stream} -- Get CUDA stream handle.
3340 @item @emph{Description}
3341 This function returns the CUDA stream handle for the queue @var{async}.
3342 This handle is the same as used by the CUDA Runtime or Driver API's.
3345 @multitable @columnfractions .20 .80
3346 @item @emph{Prototype}: @tab @code{void *acc_get_cuda_stream(int async);}
3349 @item @emph{Reference}:
3350 @uref{https://www.openacc.org, OpenACC specification v2.6}, section
3356 @node acc_set_cuda_stream
3357 @section @code{acc_set_cuda_stream} -- Set CUDA stream handle.
3359 @item @emph{Description}
3360 This function associates the stream handle specified by @var{stream} with
3361 the queue @var{async}.
3363 This cannot be used to change the stream handle associated with
3364 @code{acc_async_sync}.
3366 The return value is not specified.
3369 @multitable @columnfractions .20 .80
3370 @item @emph{Prototype}: @tab @code{int acc_set_cuda_stream(int async, void *stream);}
3373 @item @emph{Reference}:
3374 @uref{https://www.openacc.org, OpenACC specification v2.6}, section
3380 @node acc_prof_register
3381 @section @code{acc_prof_register} -- Register callbacks.
3383 @item @emph{Description}:
3384 This function registers callbacks.
3387 @multitable @columnfractions .20 .80
3388 @item @emph{Prototype}: @tab @code{void acc_prof_register (acc_event_t, acc_prof_callback, acc_register_t);}
3391 @item @emph{See also}:
3392 @ref{OpenACC Profiling Interface}
3394 @item @emph{Reference}:
3395 @uref{https://www.openacc.org, OpenACC specification v2.6}, section
3401 @node acc_prof_unregister
3402 @section @code{acc_prof_unregister} -- Unregister callbacks.
3404 @item @emph{Description}:
3405 This function unregisters callbacks.
3408 @multitable @columnfractions .20 .80
3409 @item @emph{Prototype}: @tab @code{void acc_prof_unregister (acc_event_t, acc_prof_callback, acc_register_t);}
3412 @item @emph{See also}:
3413 @ref{OpenACC Profiling Interface}
3415 @item @emph{Reference}:
3416 @uref{https://www.openacc.org, OpenACC specification v2.6}, section
3422 @node acc_prof_lookup
3423 @section @code{acc_prof_lookup} -- Obtain inquiry functions.
3425 @item @emph{Description}:
3426 Function to obtain inquiry functions.
3429 @multitable @columnfractions .20 .80
3430 @item @emph{Prototype}: @tab @code{acc_query_fn acc_prof_lookup (const char *);}
3433 @item @emph{See also}:
3434 @ref{OpenACC Profiling Interface}
3436 @item @emph{Reference}:
3437 @uref{https://www.openacc.org, OpenACC specification v2.6}, section
3443 @node acc_register_library
3444 @section @code{acc_register_library} -- Library registration.
3446 @item @emph{Description}:
3447 Function for library registration.
3450 @multitable @columnfractions .20 .80
3451 @item @emph{Prototype}: @tab @code{void acc_register_library (acc_prof_reg, acc_prof_reg, acc_prof_lookup_func);}
3454 @item @emph{See also}:
3455 @ref{OpenACC Profiling Interface}, @ref{ACC_PROFLIB}
3457 @item @emph{Reference}:
3458 @uref{https://www.openacc.org, OpenACC specification v2.6}, section
3464 @c ---------------------------------------------------------------------
3465 @c OpenACC Environment Variables
3466 @c ---------------------------------------------------------------------
3468 @node OpenACC Environment Variables
3469 @chapter OpenACC Environment Variables
3471 The variables @env{ACC_DEVICE_TYPE} and @env{ACC_DEVICE_NUM}
3472 are defined by section 4 of the OpenACC specification in version 2.0.
3473 The variable @env{ACC_PROFLIB}
3474 is defined by section 4 of the OpenACC specification in version 2.6.
3475 The variable @env{GCC_ACC_NOTIFY} is used for diagnostic purposes.
3486 @node ACC_DEVICE_TYPE
3487 @section @code{ACC_DEVICE_TYPE}
3489 @item @emph{Reference}:
3490 @uref{https://www.openacc.org, OpenACC specification v2.6}, section
3496 @node ACC_DEVICE_NUM
3497 @section @code{ACC_DEVICE_NUM}
3499 @item @emph{Reference}:
3500 @uref{https://www.openacc.org, OpenACC specification v2.6}, section
3507 @section @code{ACC_PROFLIB}
3509 @item @emph{See also}:
3510 @ref{acc_register_library}, @ref{OpenACC Profiling Interface}
3512 @item @emph{Reference}:
3513 @uref{https://www.openacc.org, OpenACC specification v2.6}, section
3519 @node GCC_ACC_NOTIFY
3520 @section @code{GCC_ACC_NOTIFY}
3522 @item @emph{Description}:
3523 Print debug information pertaining to the accelerator.
3528 @c ---------------------------------------------------------------------
3529 @c CUDA Streams Usage
3530 @c ---------------------------------------------------------------------
3532 @node CUDA Streams Usage
3533 @chapter CUDA Streams Usage
3535 This applies to the @code{nvptx} plugin only.
3537 The library provides elements that perform asynchronous movement of
3538 data and asynchronous operation of computing constructs. This
3539 asynchronous functionality is implemented by making use of CUDA
3540 streams@footnote{See "Stream Management" in "CUDA Driver API",
3541 TRM-06703-001, Version 5.5, for additional information}.
3543 The primary means by that the asynchronous functionality is accessed
3544 is through the use of those OpenACC directives which make use of the
3545 @code{async} and @code{wait} clauses. When the @code{async} clause is
3546 first used with a directive, it creates a CUDA stream. If an
3547 @code{async-argument} is used with the @code{async} clause, then the
3548 stream is associated with the specified @code{async-argument}.
3550 Following the creation of an association between a CUDA stream and the
3551 @code{async-argument} of an @code{async} clause, both the @code{wait}
3552 clause and the @code{wait} directive can be used. When either the
3553 clause or directive is used after stream creation, it creates a
3554 rendezvous point whereby execution waits until all operations
3555 associated with the @code{async-argument}, that is, stream, have
3558 Normally, the management of the streams that are created as a result of
3559 using the @code{async} clause, is done without any intervention by the
3560 caller. This implies the association between the @code{async-argument}
3561 and the CUDA stream will be maintained for the lifetime of the program.
3562 However, this association can be changed through the use of the library
3563 function @code{acc_set_cuda_stream}. When the function
3564 @code{acc_set_cuda_stream} is called, the CUDA stream that was
3565 originally associated with the @code{async} clause will be destroyed.
3566 Caution should be taken when changing the association as subsequent
3567 references to the @code{async-argument} refer to a different
3572 @c ---------------------------------------------------------------------
3573 @c OpenACC Library Interoperability
3574 @c ---------------------------------------------------------------------
3576 @node OpenACC Library Interoperability
3577 @chapter OpenACC Library Interoperability
3579 @section Introduction
3581 The OpenACC library uses the CUDA Driver API, and may interact with
3582 programs that use the Runtime library directly, or another library
3583 based on the Runtime library, e.g., CUBLAS@footnote{See section 2.26,
3584 "Interactions with the CUDA Driver API" in
3585 "CUDA Runtime API", Version 5.5, and section 2.27, "VDPAU
3586 Interoperability", in "CUDA Driver API", TRM-06703-001, Version 5.5,
3587 for additional information on library interoperability.}.
3588 This chapter describes the use cases and what changes are
3589 required in order to use both the OpenACC library and the CUBLAS and Runtime
3590 libraries within a program.
3592 @section First invocation: NVIDIA CUBLAS library API
3594 In this first use case (see below), a function in the CUBLAS library is called
3595 prior to any of the functions in the OpenACC library. More specifically, the
3596 function @code{cublasCreate()}.
3598 When invoked, the function initializes the library and allocates the
3599 hardware resources on the host and the device on behalf of the caller. Once
3600 the initialization and allocation has completed, a handle is returned to the
3601 caller. The OpenACC library also requires initialization and allocation of
3602 hardware resources. Since the CUBLAS library has already allocated the
3603 hardware resources for the device, all that is left to do is to initialize
3604 the OpenACC library and acquire the hardware resources on the host.
3606 Prior to calling the OpenACC function that initializes the library and
3607 allocate the host hardware resources, you need to acquire the device number
3608 that was allocated during the call to @code{cublasCreate()}. The invoking of the
3609 runtime library function @code{cudaGetDevice()} accomplishes this. Once
3610 acquired, the device number is passed along with the device type as
3611 parameters to the OpenACC library function @code{acc_set_device_num()}.
3613 Once the call to @code{acc_set_device_num()} has completed, the OpenACC
3614 library uses the context that was created during the call to
3615 @code{cublasCreate()}. In other words, both libraries will be sharing the
3619 /* Create the handle */
3620 s = cublasCreate(&h);
3621 if (s != CUBLAS_STATUS_SUCCESS)
3623 fprintf(stderr, "cublasCreate failed %d\n", s);
3627 /* Get the device number */
3628 e = cudaGetDevice(&dev);
3629 if (e != cudaSuccess)
3631 fprintf(stderr, "cudaGetDevice failed %d\n", e);
3635 /* Initialize OpenACC library and use device 'dev' */
3636 acc_set_device_num(dev, acc_device_nvidia);
3641 @section First invocation: OpenACC library API
3643 In this second use case (see below), a function in the OpenACC library is
3644 called prior to any of the functions in the CUBLAS library. More specificially,
3645 the function @code{acc_set_device_num()}.
3647 In the use case presented here, the function @code{acc_set_device_num()}
3648 is used to both initialize the OpenACC library and allocate the hardware
3649 resources on the host and the device. In the call to the function, the
3650 call parameters specify which device to use and what device
3651 type to use, i.e., @code{acc_device_nvidia}. It should be noted that this
3652 is but one method to initialize the OpenACC library and allocate the
3653 appropriate hardware resources. Other methods are available through the
3654 use of environment variables and these will be discussed in the next section.
3656 Once the call to @code{acc_set_device_num()} has completed, other OpenACC
3657 functions can be called as seen with multiple calls being made to
3658 @code{acc_copyin()}. In addition, calls can be made to functions in the
3659 CUBLAS library. In the use case a call to @code{cublasCreate()} is made
3660 subsequent to the calls to @code{acc_copyin()}.
3661 As seen in the previous use case, a call to @code{cublasCreate()}
3662 initializes the CUBLAS library and allocates the hardware resources on the
3663 host and the device. However, since the device has already been allocated,
3664 @code{cublasCreate()} will only initialize the CUBLAS library and allocate
3665 the appropriate hardware resources on the host. The context that was created
3666 as part of the OpenACC initialization is shared with the CUBLAS library,
3667 similarly to the first use case.
3672 acc_set_device_num(dev, acc_device_nvidia);
3674 /* Copy the first set to the device */
3675 d_X = acc_copyin(&h_X[0], N * sizeof (float));
3678 fprintf(stderr, "copyin error h_X\n");
3682 /* Copy the second set to the device */
3683 d_Y = acc_copyin(&h_Y1[0], N * sizeof (float));
3686 fprintf(stderr, "copyin error h_Y1\n");
3690 /* Create the handle */
3691 s = cublasCreate(&h);
3692 if (s != CUBLAS_STATUS_SUCCESS)
3694 fprintf(stderr, "cublasCreate failed %d\n", s);
3698 /* Perform saxpy using CUBLAS library function */
3699 s = cublasSaxpy(h, N, &alpha, d_X, 1, d_Y, 1);
3700 if (s != CUBLAS_STATUS_SUCCESS)
3702 fprintf(stderr, "cublasSaxpy failed %d\n", s);
3706 /* Copy the results from the device */
3707 acc_memcpy_from_device(&h_Y1[0], d_Y, N * sizeof (float));
3712 @section OpenACC library and environment variables
3714 There are two environment variables associated with the OpenACC library
3715 that may be used to control the device type and device number:
3716 @env{ACC_DEVICE_TYPE} and @env{ACC_DEVICE_NUM}, respectively. These two
3717 environment variables can be used as an alternative to calling
3718 @code{acc_set_device_num()}. As seen in the second use case, the device
3719 type and device number were specified using @code{acc_set_device_num()}.
3720 If however, the aforementioned environment variables were set, then the
3721 call to @code{acc_set_device_num()} would not be required.
3724 The use of the environment variables is only relevant when an OpenACC function
3725 is called prior to a call to @code{cudaCreate()}. If @code{cudaCreate()}
3726 is called prior to a call to an OpenACC function, then you must call
3727 @code{acc_set_device_num()}@footnote{More complete information
3728 about @env{ACC_DEVICE_TYPE} and @env{ACC_DEVICE_NUM} can be found in
3729 sections 4.1 and 4.2 of the @uref{https://www.openacc.org, OpenACC}
3730 Application Programming Interface”, Version 2.6.}
3734 @c ---------------------------------------------------------------------
3735 @c OpenACC Profiling Interface
3736 @c ---------------------------------------------------------------------
3738 @node OpenACC Profiling Interface
3739 @chapter OpenACC Profiling Interface
3741 @section Implementation Status and Implementation-Defined Behavior
3743 We're implementing the OpenACC Profiling Interface as defined by the
3744 OpenACC 2.6 specification. We're clarifying some aspects here as
3745 @emph{implementation-defined behavior}, while they're still under
3746 discussion within the OpenACC Technical Committee.
3748 This implementation is tuned to keep the performance impact as low as
3749 possible for the (very common) case that the Profiling Interface is
3750 not enabled. This is relevant, as the Profiling Interface affects all
3751 the @emph{hot} code paths (in the target code, not in the offloaded
3752 code). Users of the OpenACC Profiling Interface can be expected to
3753 understand that performance will be impacted to some degree once the
3754 Profiling Interface has gotten enabled: for example, because of the
3755 @emph{runtime} (libgomp) calling into a third-party @emph{library} for
3756 every event that has been registered.
3758 We're not yet accounting for the fact that @cite{OpenACC events may
3759 occur during event processing}.
3760 We just handle one case specially, as required by CUDA 9.0
3761 @command{nvprof}, that @code{acc_get_device_type}
3762 (@ref{acc_get_device_type})) may be called from
3763 @code{acc_ev_device_init_start}, @code{acc_ev_device_init_end}
3766 We're not yet implementing initialization via a
3767 @code{acc_register_library} function that is either statically linked
3768 in, or dynamically via @env{LD_PRELOAD}.
3769 Initialization via @code{acc_register_library} functions dynamically
3770 loaded via the @env{ACC_PROFLIB} environment variable does work, as
3771 does directly calling @code{acc_prof_register},
3772 @code{acc_prof_unregister}, @code{acc_prof_lookup}.
3774 As currently there are no inquiry functions defined, calls to
3775 @code{acc_prof_lookup} will always return @code{NULL}.
3777 There aren't separate @emph{start}, @emph{stop} events defined for the
3778 event types @code{acc_ev_create}, @code{acc_ev_delete},
3779 @code{acc_ev_alloc}, @code{acc_ev_free}. It's not clear if these
3780 should be triggered before or after the actual device-specific call is
3781 made. We trigger them after.
3783 Remarks about data provided to callbacks:
3787 @item @code{acc_prof_info.event_type}
3788 It's not clear if for @emph{nested} event callbacks (for example,
3789 @code{acc_ev_enqueue_launch_start} as part of a parent compute
3790 construct), this should be set for the nested event
3791 (@code{acc_ev_enqueue_launch_start}), or if the value of the parent
3792 construct should remain (@code{acc_ev_compute_construct_start}). In
3793 this implementation, the value will generally correspond to the
3794 innermost nested event type.
3796 @item @code{acc_prof_info.device_type}
3800 For @code{acc_ev_compute_construct_start}, and in presence of an
3801 @code{if} clause with @emph{false} argument, this will still refer to
3802 the offloading device type.
3803 It's not clear if that's the expected behavior.
3806 Complementary to the item before, for
3807 @code{acc_ev_compute_construct_end}, this is set to
3808 @code{acc_device_host} in presence of an @code{if} clause with
3809 @emph{false} argument.
3810 It's not clear if that's the expected behavior.
3814 @item @code{acc_prof_info.thread_id}
3815 Always @code{-1}; not yet implemented.
3817 @item @code{acc_prof_info.async}
3821 Not yet implemented correctly for
3822 @code{acc_ev_compute_construct_start}.
3825 In a compute construct, for host-fallback
3826 execution/@code{acc_device_host} it will always be
3827 @code{acc_async_sync}.
3828 It's not clear if that's the expected behavior.
3831 For @code{acc_ev_device_init_start} and @code{acc_ev_device_init_end},
3832 it will always be @code{acc_async_sync}.
3833 It's not clear if that's the expected behavior.
3837 @item @code{acc_prof_info.async_queue}
3838 There is no @cite{limited number of asynchronous queues} in libgomp.
3839 This will always have the same value as @code{acc_prof_info.async}.
3841 @item @code{acc_prof_info.src_file}
3842 Always @code{NULL}; not yet implemented.
3844 @item @code{acc_prof_info.func_name}
3845 Always @code{NULL}; not yet implemented.
3847 @item @code{acc_prof_info.line_no}
3848 Always @code{-1}; not yet implemented.
3850 @item @code{acc_prof_info.end_line_no}
3851 Always @code{-1}; not yet implemented.
3853 @item @code{acc_prof_info.func_line_no}
3854 Always @code{-1}; not yet implemented.
3856 @item @code{acc_prof_info.func_end_line_no}
3857 Always @code{-1}; not yet implemented.
3859 @item @code{acc_event_info.event_type}, @code{acc_event_info.*.event_type}
3860 Relating to @code{acc_prof_info.event_type} discussed above, in this
3861 implementation, this will always be the same value as
3862 @code{acc_prof_info.event_type}.
3864 @item @code{acc_event_info.*.parent_construct}
3868 Will be @code{acc_construct_parallel} for all OpenACC compute
3869 constructs as well as many OpenACC Runtime API calls; should be the
3870 one matching the actual construct, or
3871 @code{acc_construct_runtime_api}, respectively.
3874 Will be @code{acc_construct_enter_data} or
3875 @code{acc_construct_exit_data} when processing variable mappings
3876 specified in OpenACC @emph{declare} directives; should be
3877 @code{acc_construct_declare}.
3880 For implicit @code{acc_ev_device_init_start},
3881 @code{acc_ev_device_init_end}, and explicit as well as implicit
3882 @code{acc_ev_alloc}, @code{acc_ev_free},
3883 @code{acc_ev_enqueue_upload_start}, @code{acc_ev_enqueue_upload_end},
3884 @code{acc_ev_enqueue_download_start}, and
3885 @code{acc_ev_enqueue_download_end}, will be
3886 @code{acc_construct_parallel}; should reflect the real parent
3891 @item @code{acc_event_info.*.implicit}
3892 For @code{acc_ev_alloc}, @code{acc_ev_free},
3893 @code{acc_ev_enqueue_upload_start}, @code{acc_ev_enqueue_upload_end},
3894 @code{acc_ev_enqueue_download_start}, and
3895 @code{acc_ev_enqueue_download_end}, this currently will be @code{1}
3896 also for explicit usage.
3898 @item @code{acc_event_info.data_event.var_name}
3899 Always @code{NULL}; not yet implemented.
3901 @item @code{acc_event_info.data_event.host_ptr}
3902 For @code{acc_ev_alloc}, and @code{acc_ev_free}, this is always
3905 @item @code{typedef union acc_api_info}
3906 @dots{} as printed in @cite{5.2.3. Third Argument: API-Specific
3907 Information}. This should obviously be @code{typedef @emph{struct}
3910 @item @code{acc_api_info.device_api}
3911 Possibly not yet implemented correctly for
3912 @code{acc_ev_compute_construct_start},
3913 @code{acc_ev_device_init_start}, @code{acc_ev_device_init_end}:
3914 will always be @code{acc_device_api_none} for these event types.
3915 For @code{acc_ev_enter_data_start}, it will be
3916 @code{acc_device_api_none} in some cases.
3918 @item @code{acc_api_info.device_type}
3919 Always the same as @code{acc_prof_info.device_type}.
3921 @item @code{acc_api_info.vendor}
3922 Always @code{-1}; not yet implemented.
3924 @item @code{acc_api_info.device_handle}
3925 Always @code{NULL}; not yet implemented.
3927 @item @code{acc_api_info.context_handle}
3928 Always @code{NULL}; not yet implemented.
3930 @item @code{acc_api_info.async_handle}
3931 Always @code{NULL}; not yet implemented.
3935 Remarks about certain event types:
3939 @item @code{acc_ev_device_init_start}, @code{acc_ev_device_init_end}
3943 @c See 'DEVICE_INIT_INSIDE_COMPUTE_CONSTRUCT' in
3944 @c 'libgomp.oacc-c-c++-common/acc_prof-kernels-1.c',
3945 @c 'libgomp.oacc-c-c++-common/acc_prof-parallel-1.c'.
3946 When a compute construct triggers implicit
3947 @code{acc_ev_device_init_start} and @code{acc_ev_device_init_end}
3948 events, they currently aren't @emph{nested within} the corresponding
3949 @code{acc_ev_compute_construct_start} and
3950 @code{acc_ev_compute_construct_end}, but they're currently observed
3951 @emph{before} @code{acc_ev_compute_construct_start}.
3952 It's not clear what to do: the standard asks us provide a lot of
3953 details to the @code{acc_ev_compute_construct_start} callback, without
3954 (implicitly) initializing a device before?
3957 Callbacks for these event types will not be invoked for calls to the
3958 @code{acc_set_device_type} and @code{acc_set_device_num} functions.
3959 It's not clear if they should be.
3963 @item @code{acc_ev_enter_data_start}, @code{acc_ev_enter_data_end}, @code{acc_ev_exit_data_start}, @code{acc_ev_exit_data_end}
3967 Callbacks for these event types will also be invoked for OpenACC
3968 @emph{host_data} constructs.
3969 It's not clear if they should be.
3972 Callbacks for these event types will also be invoked when processing
3973 variable mappings specified in OpenACC @emph{declare} directives.
3974 It's not clear if they should be.
3980 Callbacks for the following event types will be invoked, but dispatch
3981 and information provided therein has not yet been thoroughly reviewed:
3984 @item @code{acc_ev_alloc}
3985 @item @code{acc_ev_free}
3986 @item @code{acc_ev_update_start}, @code{acc_ev_update_end}
3987 @item @code{acc_ev_enqueue_upload_start}, @code{acc_ev_enqueue_upload_end}
3988 @item @code{acc_ev_enqueue_download_start}, @code{acc_ev_enqueue_download_end}
3991 During device initialization, and finalization, respectively,
3992 callbacks for the following event types will not yet be invoked:
3995 @item @code{acc_ev_alloc}
3996 @item @code{acc_ev_free}
3999 Callbacks for the following event types have not yet been implemented,
4000 so currently won't be invoked:
4003 @item @code{acc_ev_device_shutdown_start}, @code{acc_ev_device_shutdown_end}
4004 @item @code{acc_ev_runtime_shutdown}
4005 @item @code{acc_ev_create}, @code{acc_ev_delete}
4006 @item @code{acc_ev_wait_start}, @code{acc_ev_wait_end}
4009 For the following runtime library functions, not all expected
4010 callbacks will be invoked (mostly concerning implicit device
4014 @item @code{acc_get_num_devices}
4015 @item @code{acc_set_device_type}
4016 @item @code{acc_get_device_type}
4017 @item @code{acc_set_device_num}
4018 @item @code{acc_get_device_num}
4019 @item @code{acc_init}
4020 @item @code{acc_shutdown}
4023 Aside from implicit device initialization, for the following runtime
4024 library functions, no callbacks will be invoked for shared-memory
4025 offloading devices (it's not clear if they should be):
4028 @item @code{acc_malloc}
4029 @item @code{acc_free}
4030 @item @code{acc_copyin}, @code{acc_present_or_copyin}, @code{acc_copyin_async}
4031 @item @code{acc_create}, @code{acc_present_or_create}, @code{acc_create_async}
4032 @item @code{acc_copyout}, @code{acc_copyout_async}, @code{acc_copyout_finalize}, @code{acc_copyout_finalize_async}
4033 @item @code{acc_delete}, @code{acc_delete_async}, @code{acc_delete_finalize}, @code{acc_delete_finalize_async}
4034 @item @code{acc_update_device}, @code{acc_update_device_async}
4035 @item @code{acc_update_self}, @code{acc_update_self_async}
4036 @item @code{acc_map_data}, @code{acc_unmap_data}
4037 @item @code{acc_memcpy_to_device}, @code{acc_memcpy_to_device_async}
4038 @item @code{acc_memcpy_from_device}, @code{acc_memcpy_from_device_async}
4043 @c ---------------------------------------------------------------------
4045 @c ---------------------------------------------------------------------
4047 @node The libgomp ABI
4048 @chapter The libgomp ABI
4050 The following sections present notes on the external ABI as
4051 presented by libgomp. Only maintainers should need them.
4054 * Implementing MASTER construct::
4055 * Implementing CRITICAL construct::
4056 * Implementing ATOMIC construct::
4057 * Implementing FLUSH construct::
4058 * Implementing BARRIER construct::
4059 * Implementing THREADPRIVATE construct::
4060 * Implementing PRIVATE clause::
4061 * Implementing FIRSTPRIVATE LASTPRIVATE COPYIN and COPYPRIVATE clauses::
4062 * Implementing REDUCTION clause::
4063 * Implementing PARALLEL construct::
4064 * Implementing FOR construct::
4065 * Implementing ORDERED construct::
4066 * Implementing SECTIONS construct::
4067 * Implementing SINGLE construct::
4068 * Implementing OpenACC's PARALLEL construct::
4072 @node Implementing MASTER construct
4073 @section Implementing MASTER construct
4076 if (omp_get_thread_num () == 0)
4080 Alternately, we generate two copies of the parallel subfunction
4081 and only include this in the version run by the primary thread.
4082 Surely this is not worthwhile though...
4086 @node Implementing CRITICAL construct
4087 @section Implementing CRITICAL construct
4089 Without a specified name,
4092 void GOMP_critical_start (void);
4093 void GOMP_critical_end (void);
4096 so that we don't get COPY relocations from libgomp to the main
4099 With a specified name, use omp_set_lock and omp_unset_lock with
4100 name being transformed into a variable declared like
4103 omp_lock_t gomp_critical_user_<name> __attribute__((common))
4106 Ideally the ABI would specify that all zero is a valid unlocked
4107 state, and so we wouldn't need to initialize this at
4112 @node Implementing ATOMIC construct
4113 @section Implementing ATOMIC construct
4115 The target should implement the @code{__sync} builtins.
4117 Failing that we could add
4120 void GOMP_atomic_enter (void)
4121 void GOMP_atomic_exit (void)
4124 which reuses the regular lock code, but with yet another lock
4125 object private to the library.
4129 @node Implementing FLUSH construct
4130 @section Implementing FLUSH construct
4132 Expands to the @code{__sync_synchronize} builtin.
4136 @node Implementing BARRIER construct
4137 @section Implementing BARRIER construct
4140 void GOMP_barrier (void)
4144 @node Implementing THREADPRIVATE construct
4145 @section Implementing THREADPRIVATE construct
4147 In _most_ cases we can map this directly to @code{__thread}. Except
4148 that OMP allows constructors for C++ objects. We can either
4149 refuse to support this (how often is it used?) or we can
4150 implement something akin to .ctors.
4152 Even more ideally, this ctor feature is handled by extensions
4153 to the main pthreads library. Failing that, we can have a set
4154 of entry points to register ctor functions to be called.
4158 @node Implementing PRIVATE clause
4159 @section Implementing PRIVATE clause
4161 In association with a PARALLEL, or within the lexical extent
4162 of a PARALLEL block, the variable becomes a local variable in
4163 the parallel subfunction.
4165 In association with FOR or SECTIONS blocks, create a new
4166 automatic variable within the current function. This preserves
4167 the semantic of new variable creation.
4171 @node Implementing FIRSTPRIVATE LASTPRIVATE COPYIN and COPYPRIVATE clauses
4172 @section Implementing FIRSTPRIVATE LASTPRIVATE COPYIN and COPYPRIVATE clauses
4174 This seems simple enough for PARALLEL blocks. Create a private
4175 struct for communicating between the parent and subfunction.
4176 In the parent, copy in values for scalar and "small" structs;
4177 copy in addresses for others TREE_ADDRESSABLE types. In the
4178 subfunction, copy the value into the local variable.
4180 It is not clear what to do with bare FOR or SECTION blocks.
4181 The only thing I can figure is that we do something like:
4184 #pragma omp for firstprivate(x) lastprivate(y)
4185 for (int i = 0; i < n; ++i)
4202 where the "x=x" and "y=y" assignments actually have different
4203 uids for the two variables, i.e. not something you could write
4204 directly in C. Presumably this only makes sense if the "outer"
4205 x and y are global variables.
4207 COPYPRIVATE would work the same way, except the structure
4208 broadcast would have to happen via SINGLE machinery instead.
4212 @node Implementing REDUCTION clause
4213 @section Implementing REDUCTION clause
4215 The private struct mentioned in the previous section should have
4216 a pointer to an array of the type of the variable, indexed by the
4217 thread's @var{team_id}. The thread stores its final value into the
4218 array, and after the barrier, the primary thread iterates over the
4219 array to collect the values.
4222 @node Implementing PARALLEL construct
4223 @section Implementing PARALLEL construct
4226 #pragma omp parallel
4235 void subfunction (void *data)
4242 GOMP_parallel_start (subfunction, &data, num_threads);
4243 subfunction (&data);
4244 GOMP_parallel_end ();
4248 void GOMP_parallel_start (void (*fn)(void *), void *data, unsigned num_threads)
4251 The @var{FN} argument is the subfunction to be run in parallel.
4253 The @var{DATA} argument is a pointer to a structure used to
4254 communicate data in and out of the subfunction, as discussed
4255 above with respect to FIRSTPRIVATE et al.
4257 The @var{NUM_THREADS} argument is 1 if an IF clause is present
4258 and false, or the value of the NUM_THREADS clause, if
4261 The function needs to create the appropriate number of
4262 threads and/or launch them from the dock. It needs to
4263 create the team structure and assign team ids.
4266 void GOMP_parallel_end (void)
4269 Tears down the team and returns us to the previous @code{omp_in_parallel()} state.
4273 @node Implementing FOR construct
4274 @section Implementing FOR construct
4277 #pragma omp parallel for
4278 for (i = lb; i <= ub; i++)
4285 void subfunction (void *data)
4288 while (GOMP_loop_static_next (&_s0, &_e0))
4291 for (i = _s0; i < _e1; i++)
4294 GOMP_loop_end_nowait ();
4297 GOMP_parallel_loop_static (subfunction, NULL, 0, lb, ub+1, 1, 0);
4299 GOMP_parallel_end ();
4303 #pragma omp for schedule(runtime)
4304 for (i = 0; i < n; i++)
4313 if (GOMP_loop_runtime_start (0, n, 1, &_s0, &_e0))
4316 for (i = _s0, i < _e0; i++)
4318 @} while (GOMP_loop_runtime_next (&_s0, _&e0));
4323 Note that while it looks like there is trickiness to propagating
4324 a non-constant STEP, there isn't really. We're explicitly allowed
4325 to evaluate it as many times as we want, and any variables involved
4326 should automatically be handled as PRIVATE or SHARED like any other
4327 variables. So the expression should remain evaluable in the
4328 subfunction. We can also pull it into a local variable if we like,
4329 but since its supposed to remain unchanged, we can also not if we like.
4331 If we have SCHEDULE(STATIC), and no ORDERED, then we ought to be
4332 able to get away with no work-sharing context at all, since we can
4333 simply perform the arithmetic directly in each thread to divide up
4334 the iterations. Which would mean that we wouldn't need to call any
4337 There are separate routines for handling loops with an ORDERED
4338 clause. Bookkeeping for that is non-trivial...
4342 @node Implementing ORDERED construct
4343 @section Implementing ORDERED construct
4346 void GOMP_ordered_start (void)
4347 void GOMP_ordered_end (void)
4352 @node Implementing SECTIONS construct
4353 @section Implementing SECTIONS construct
4358 #pragma omp sections
4372 for (i = GOMP_sections_start (3); i != 0; i = GOMP_sections_next ())
4389 @node Implementing SINGLE construct
4390 @section Implementing SINGLE construct
4404 if (GOMP_single_start ())
4412 #pragma omp single copyprivate(x)
4419 datap = GOMP_single_copy_start ();
4424 GOMP_single_copy_end (&data);
4433 @node Implementing OpenACC's PARALLEL construct
4434 @section Implementing OpenACC's PARALLEL construct
4437 void GOACC_parallel ()
4442 @c ---------------------------------------------------------------------
4444 @c ---------------------------------------------------------------------
4446 @node Reporting Bugs
4447 @chapter Reporting Bugs
4449 Bugs in the GNU Offloading and Multi Processing Runtime Library should
4450 be reported via @uref{https://gcc.gnu.org/bugzilla/, Bugzilla}. Please add
4451 "openacc", or "openmp", or both to the keywords field in the bug
4452 report, as appropriate.
4456 @c ---------------------------------------------------------------------
4457 @c GNU General Public License
4458 @c ---------------------------------------------------------------------
4460 @include gpl_v3.texi
4464 @c ---------------------------------------------------------------------
4465 @c GNU Free Documentation License
4466 @c ---------------------------------------------------------------------
4472 @c ---------------------------------------------------------------------
4473 @c Funding Free Software
4474 @c ---------------------------------------------------------------------
4476 @include funding.texi
4478 @c ---------------------------------------------------------------------
4480 @c ---------------------------------------------------------------------
4483 @unnumbered Library Index