Daily bump.
[official-gcc.git] / libgomp / libgomp.texi
blobcc5ee1cd6b1ff0e71ef8fead027025992d80fb37
1 \input texinfo @c -*-texinfo-*-
3 @c %**start of header
4 @setfilename libgomp.info
5 @settitle GNU libgomp
6 @c %**end of header
9 @copying
10 Copyright @copyright{} 2006-2017 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:
22      A GNU Manual
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.
29 @end copying
31 @ifinfo
32 @dircategory GNU Libraries
33 @direntry
34 * libgomp: (libgomp).          GNU Offloading and Multi Processing Runtime Library.
35 @end direntry
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
40 Fortran.
42 Published by the Free Software Foundation
43 51 Franklin Street, Fifth Floor
44 Boston, MA 02110-1301 USA
46 @insertcopying
47 @end ifinfo
50 @setchapternewpage odd
52 @titlepage
53 @title GNU Offloading and Multi Processing Runtime Library
54 @subtitle The GNU OpenMP and OpenACC Implementation
55 @page
56 @vskip 0pt plus 1filll
57 @comment For the @value{version-GCC} Version*
58 @sp 1
59 Published by the Free Software Foundation @*
60 51 Franklin Street, Fifth Floor@*
61 Boston, MA 02110-1301, USA@*
62 @sp 1
63 @insertcopying
64 @end titlepage
66 @summarycontents
67 @contents
68 @page
71 @node Top
72 @top Introduction
73 @cindex Introduction
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{http://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{http://www.openacc.org/, OpenACC} Application Programming
81 Interface (API) for offloading of code to accelerator devices in C/C++
82 and Fortran.
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.
91 @comment
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.
95 @comment
96 @menu
97 * Enabling OpenMP::            How to enable OpenMP for your applications.
98 * Runtime Library Routines::   The OpenMP runtime application programming 
99                                interface.
100 * Environment Variables::      Influencing runtime behavior with environment 
101                                variables.
102 * Enabling OpenACC::           How to enable OpenACC for your
103                                applications.
104 * OpenACC Runtime Library Routines:: The OpenACC runtime application
105                                programming interface.
106 * OpenACC Environment Variables:: Influencing OpenACC runtime behavior with
107                                environment variables.
108 * CUDA Streams Usage::         Notes on the implementation of
109                                asynchronous operations.
110 * OpenACC Library Interoperability:: OpenACC library interoperability with the
111                                NVIDIA CUBLAS library.
112 * The libgomp ABI::            Notes on the external ABI presented by libgomp.
113 * Reporting Bugs::             How to report bugs in the GNU Offloading and
114                                Multi Processing Runtime Library.
115 * Copying::                    GNU general public license says
116                                how you can copy and share libgomp.
117 * GNU Free Documentation License::
118                                How you can copy and share this manual.
119 * Funding::                    How to help assure continued work for free 
120                                software.
121 * Library Index::              Index of this documentation.
122 @end menu
125 @c ---------------------------------------------------------------------
126 @c Enabling OpenMP
127 @c ---------------------------------------------------------------------
129 @node Enabling OpenMP
130 @chapter Enabling OpenMP
132 To activate the OpenMP extensions for C/C++ and Fortran, the compile-time 
133 flag @command{-fopenmp} must be specified.  This enables the OpenMP directive
134 @code{#pragma omp} in C/C++ and @code{!$omp} directives in free form, 
135 @code{c$omp}, @code{*$omp} and @code{!$omp} directives in fixed form, 
136 @code{!$} conditional compilation sentinels in free form and @code{c$},
137 @code{*$} and @code{!$} sentinels in fixed form, for Fortran.  The flag also
138 arranges for automatic linking of the OpenMP runtime library 
139 (@ref{Runtime Library Routines}).
141 A complete description of all OpenMP directives accepted may be found in 
142 the @uref{http://www.openmp.org, OpenMP Application Program Interface} manual,
143 version 4.5.
146 @c ---------------------------------------------------------------------
147 @c Runtime Library Routines
148 @c ---------------------------------------------------------------------
150 @node Runtime Library Routines
151 @chapter Runtime Library Routines
153 The runtime routines described here are defined by Section 3 of the OpenMP
154 specification in version 4.5.  The routines are structured in following
155 three parts:
157 @menu
158 Control threads, processors and the parallel environment.  They have C
159 linkage, and do not throw exceptions.
161 * omp_get_active_level::        Number of active parallel regions
162 * omp_get_ancestor_thread_num:: Ancestor thread ID
163 * omp_get_cancellation::        Whether cancellation support is enabled
164 * omp_get_default_device::      Get the default device for target regions
165 * omp_get_dynamic::             Dynamic teams setting
166 * omp_get_level::               Number of parallel regions
167 * omp_get_max_active_levels::   Maximum number of active regions
168 * omp_get_max_task_priority::   Maximum task priority value that can be set
169 * omp_get_max_threads::         Maximum number of threads of parallel region
170 * omp_get_nested::              Nested parallel regions
171 * omp_get_num_devices::         Number of target devices
172 * omp_get_num_procs::           Number of processors online
173 * omp_get_num_teams::           Number of teams
174 * omp_get_num_threads::         Size of the active team
175 * omp_get_proc_bind::           Whether theads may be moved between CPUs
176 * omp_get_schedule::            Obtain the runtime scheduling method
177 * omp_get_team_num::            Get team number
178 * omp_get_team_size::           Number of threads in a team
179 * omp_get_thread_limit::        Maximum number of threads
180 * omp_get_thread_num::          Current thread ID
181 * omp_in_parallel::             Whether a parallel region is active
182 * omp_in_final::                Whether in final or included task region
183 * omp_is_initial_device::       Whether executing on the host device
184 * omp_set_default_device::      Set the default device for target regions
185 * omp_set_dynamic::             Enable/disable dynamic teams
186 * omp_set_max_active_levels::   Limits the number of active parallel regions
187 * omp_set_nested::              Enable/disable nested parallel regions
188 * omp_set_num_threads::         Set upper team size limit
189 * omp_set_schedule::            Set the runtime scheduling method
191 Initialize, set, test, unset and destroy simple and nested locks.
193 * omp_init_lock::            Initialize simple lock
194 * omp_set_lock::             Wait for and set simple lock
195 * omp_test_lock::            Test and set simple lock if available
196 * omp_unset_lock::           Unset simple lock
197 * omp_destroy_lock::         Destroy simple lock
198 * omp_init_nest_lock::       Initialize nested lock
199 * omp_set_nest_lock::        Wait for and set simple lock
200 * omp_test_nest_lock::       Test and set nested lock if available
201 * omp_unset_nest_lock::      Unset nested lock
202 * omp_destroy_nest_lock::    Destroy nested lock
204 Portable, thread-based, wall clock timer.
206 * omp_get_wtick::            Get timer precision.
207 * omp_get_wtime::            Elapsed wall clock time.
208 @end menu
212 @node omp_get_active_level
213 @section @code{omp_get_active_level} -- Number of parallel regions
214 @table @asis
215 @item @emph{Description}:
216 This function returns the nesting level for the active parallel blocks,
217 which enclose the calling call.
219 @item @emph{C/C++}
220 @multitable @columnfractions .20 .80
221 @item @emph{Prototype}: @tab @code{int omp_get_active_level(void);}
222 @end multitable
224 @item @emph{Fortran}:
225 @multitable @columnfractions .20 .80
226 @item @emph{Interface}: @tab @code{integer function omp_get_active_level()}
227 @end multitable
229 @item @emph{See also}:
230 @ref{omp_get_level}, @ref{omp_get_max_active_levels}, @ref{omp_set_max_active_levels}
232 @item @emph{Reference}:
233 @uref{http://www.openmp.org/, OpenMP specification v4.5}, Section 3.2.20.
234 @end table
238 @node omp_get_ancestor_thread_num
239 @section @code{omp_get_ancestor_thread_num} -- Ancestor thread ID
240 @table @asis
241 @item @emph{Description}:
242 This function returns the thread identification number for the given
243 nesting level of the current thread.  For values of @var{level} outside
244 zero to @code{omp_get_level} -1 is returned; if @var{level} is
245 @code{omp_get_level} the result is identical to @code{omp_get_thread_num}.
247 @item @emph{C/C++}
248 @multitable @columnfractions .20 .80
249 @item @emph{Prototype}: @tab @code{int omp_get_ancestor_thread_num(int level);}
250 @end multitable
252 @item @emph{Fortran}:
253 @multitable @columnfractions .20 .80
254 @item @emph{Interface}: @tab @code{integer function omp_get_ancestor_thread_num(level)}
255 @item                   @tab @code{integer level}
256 @end multitable
258 @item @emph{See also}:
259 @ref{omp_get_level}, @ref{omp_get_thread_num}, @ref{omp_get_team_size}
261 @item @emph{Reference}:
262 @uref{http://www.openmp.org/, OpenMP specification v4.5}, Section 3.2.18.
263 @end table
267 @node omp_get_cancellation
268 @section @code{omp_get_cancellation} -- Whether cancellation support is enabled
269 @table @asis
270 @item @emph{Description}:
271 This function returns @code{true} if cancellation is activated, @code{false}
272 otherwise.  Here, @code{true} and @code{false} represent their language-specific
273 counterparts.  Unless @env{OMP_CANCELLATION} is set true, cancellations are
274 deactivated.
276 @item @emph{C/C++}:
277 @multitable @columnfractions .20 .80
278 @item @emph{Prototype}: @tab @code{int omp_get_cancellation(void);}
279 @end multitable
281 @item @emph{Fortran}:
282 @multitable @columnfractions .20 .80
283 @item @emph{Interface}: @tab @code{logical function omp_get_cancellation()}
284 @end multitable
286 @item @emph{See also}:
287 @ref{OMP_CANCELLATION}
289 @item @emph{Reference}:
290 @uref{http://www.openmp.org/, OpenMP specification v4.5}, Section 3.2.9.
291 @end table
295 @node omp_get_default_device
296 @section @code{omp_get_default_device} -- Get the default device for target regions
297 @table @asis
298 @item @emph{Description}:
299 Get the default device for target regions without device clause.
301 @item @emph{C/C++}:
302 @multitable @columnfractions .20 .80
303 @item @emph{Prototype}: @tab @code{int omp_get_default_device(void);}
304 @end multitable
306 @item @emph{Fortran}:
307 @multitable @columnfractions .20 .80
308 @item @emph{Interface}: @tab @code{integer function omp_get_default_device()}
309 @end multitable
311 @item @emph{See also}:
312 @ref{OMP_DEFAULT_DEVICE}, @ref{omp_set_default_device}
314 @item @emph{Reference}:
315 @uref{http://www.openmp.org/, OpenMP specification v4.5}, Section 3.2.30.
316 @end table
320 @node omp_get_dynamic
321 @section @code{omp_get_dynamic} -- Dynamic teams setting
322 @table @asis
323 @item @emph{Description}:
324 This function returns @code{true} if enabled, @code{false} otherwise. 
325 Here, @code{true} and @code{false} represent their language-specific 
326 counterparts.
328 The dynamic team setting may be initialized at startup by the 
329 @env{OMP_DYNAMIC} environment variable or at runtime using
330 @code{omp_set_dynamic}.  If undefined, dynamic adjustment is
331 disabled by default.
333 @item @emph{C/C++}:
334 @multitable @columnfractions .20 .80
335 @item @emph{Prototype}: @tab @code{int omp_get_dynamic(void);}
336 @end multitable
338 @item @emph{Fortran}:
339 @multitable @columnfractions .20 .80
340 @item @emph{Interface}: @tab @code{logical function omp_get_dynamic()}
341 @end multitable
343 @item @emph{See also}:
344 @ref{omp_set_dynamic}, @ref{OMP_DYNAMIC}
346 @item @emph{Reference}:
347 @uref{http://www.openmp.org/, OpenMP specification v4.5}, Section 3.2.8.
348 @end table
352 @node omp_get_level
353 @section @code{omp_get_level} -- Obtain the current nesting level
354 @table @asis
355 @item @emph{Description}:
356 This function returns the nesting level for the parallel blocks,
357 which enclose the calling call.
359 @item @emph{C/C++}
360 @multitable @columnfractions .20 .80
361 @item @emph{Prototype}: @tab @code{int omp_get_level(void);}
362 @end multitable
364 @item @emph{Fortran}:
365 @multitable @columnfractions .20 .80
366 @item @emph{Interface}: @tab @code{integer function omp_level()}
367 @end multitable
369 @item @emph{See also}:
370 @ref{omp_get_active_level}
372 @item @emph{Reference}:
373 @uref{http://www.openmp.org/, OpenMP specification v4.5}, Section 3.2.17.
374 @end table
378 @node omp_get_max_active_levels
379 @section @code{omp_get_max_active_levels} -- Maximum number of active regions
380 @table @asis
381 @item @emph{Description}:
382 This function obtains the maximum allowed number of nested, active parallel regions.
384 @item @emph{C/C++}
385 @multitable @columnfractions .20 .80
386 @item @emph{Prototype}: @tab @code{int omp_get_max_active_levels(void);}
387 @end multitable
389 @item @emph{Fortran}:
390 @multitable @columnfractions .20 .80
391 @item @emph{Interface}: @tab @code{integer function omp_get_max_active_levels()}
392 @end multitable
394 @item @emph{See also}:
395 @ref{omp_set_max_active_levels}, @ref{omp_get_active_level}
397 @item @emph{Reference}:
398 @uref{http://www.openmp.org/, OpenMP specification v4.5}, Section 3.2.16.
399 @end table
402 @node omp_get_max_task_priority
403 @section @code{omp_get_max_task_priority} -- Maximum priority value
404 that can be set for tasks.
405 @table @asis
406 @item @emph{Description}:
407 This function obtains the maximum allowed priority number for tasks.
409 @item @emph{C/C++}
410 @multitable @columnfractions .20 .80
411 @item @emph{Prototype}: @tab @code{int omp_get_max_task_priority(void);}
412 @end multitable
414 @item @emph{Fortran}:
415 @multitable @columnfractions .20 .80
416 @item @emph{Interface}: @tab @code{integer function omp_get_max_task_priority()}
417 @end multitable
419 @item @emph{Reference}:
420 @uref{http://www.openmp.org/, OpenMP specification v4.5}, Section 3.2.29.
421 @end table
424 @node omp_get_max_threads
425 @section @code{omp_get_max_threads} -- Maximum number of threads of parallel region
426 @table @asis
427 @item @emph{Description}:
428 Return the maximum number of threads used for the current parallel region
429 that does not use the clause @code{num_threads}.
431 @item @emph{C/C++}:
432 @multitable @columnfractions .20 .80
433 @item @emph{Prototype}: @tab @code{int omp_get_max_threads(void);}
434 @end multitable
436 @item @emph{Fortran}:
437 @multitable @columnfractions .20 .80
438 @item @emph{Interface}: @tab @code{integer function omp_get_max_threads()}
439 @end multitable
441 @item @emph{See also}:
442 @ref{omp_set_num_threads}, @ref{omp_set_dynamic}, @ref{omp_get_thread_limit}
444 @item @emph{Reference}:
445 @uref{http://www.openmp.org/, OpenMP specification v4.5}, Section 3.2.3.
446 @end table
450 @node omp_get_nested
451 @section @code{omp_get_nested} -- Nested parallel regions
452 @table @asis
453 @item @emph{Description}:
454 This function returns @code{true} if nested parallel regions are
455 enabled, @code{false} otherwise.  Here, @code{true} and @code{false}
456 represent their language-specific counterparts.
458 Nested parallel regions may be initialized at startup by the 
459 @env{OMP_NESTED} environment variable or at runtime using
460 @code{omp_set_nested}.  If undefined, nested parallel regions are
461 disabled by default.
463 @item @emph{C/C++}:
464 @multitable @columnfractions .20 .80
465 @item @emph{Prototype}: @tab @code{int omp_get_nested(void);}
466 @end multitable
468 @item @emph{Fortran}:
469 @multitable @columnfractions .20 .80
470 @item @emph{Interface}: @tab @code{logical function omp_get_nested()}
471 @end multitable
473 @item @emph{See also}:
474 @ref{omp_set_nested}, @ref{OMP_NESTED}
476 @item @emph{Reference}:
477 @uref{http://www.openmp.org/, OpenMP specification v4.5}, Section 3.2.11.
478 @end table
482 @node omp_get_num_devices
483 @section @code{omp_get_num_devices} -- Number of target devices
484 @table @asis
485 @item @emph{Description}:
486 Returns the number of target devices.
488 @item @emph{C/C++}:
489 @multitable @columnfractions .20 .80
490 @item @emph{Prototype}: @tab @code{int omp_get_num_devices(void);}
491 @end multitable
493 @item @emph{Fortran}:
494 @multitable @columnfractions .20 .80
495 @item @emph{Interface}: @tab @code{integer function omp_get_num_devices()}
496 @end multitable
498 @item @emph{Reference}:
499 @uref{http://www.openmp.org/, OpenMP specification v4.5}, Section 3.2.31.
500 @end table
504 @node omp_get_num_procs
505 @section @code{omp_get_num_procs} -- Number of processors online
506 @table @asis
507 @item @emph{Description}:
508 Returns the number of processors online on that device.
510 @item @emph{C/C++}:
511 @multitable @columnfractions .20 .80
512 @item @emph{Prototype}: @tab @code{int omp_get_num_procs(void);}
513 @end multitable
515 @item @emph{Fortran}:
516 @multitable @columnfractions .20 .80
517 @item @emph{Interface}: @tab @code{integer function omp_get_num_procs()}
518 @end multitable
520 @item @emph{Reference}:
521 @uref{http://www.openmp.org/, OpenMP specification v4.5}, Section 3.2.5.
522 @end table
526 @node omp_get_num_teams
527 @section @code{omp_get_num_teams} -- Number of teams
528 @table @asis
529 @item @emph{Description}:
530 Returns the number of teams in the current team region.
532 @item @emph{C/C++}:
533 @multitable @columnfractions .20 .80
534 @item @emph{Prototype}: @tab @code{int omp_get_num_teams(void);}
535 @end multitable
537 @item @emph{Fortran}:
538 @multitable @columnfractions .20 .80
539 @item @emph{Interface}: @tab @code{integer function omp_get_num_teams()}
540 @end multitable
542 @item @emph{Reference}:
543 @uref{http://www.openmp.org/, OpenMP specification v4.5}, Section 3.2.32.
544 @end table
548 @node omp_get_num_threads
549 @section @code{omp_get_num_threads} -- Size of the active team
550 @table @asis
551 @item @emph{Description}:
552 Returns the number of threads in the current team.  In a sequential section of
553 the program @code{omp_get_num_threads} returns 1.
555 The default team size may be initialized at startup by the 
556 @env{OMP_NUM_THREADS} environment variable.  At runtime, the size
557 of the current team may be set either by the @code{NUM_THREADS}
558 clause or by @code{omp_set_num_threads}.  If none of the above were
559 used to define a specific value and @env{OMP_DYNAMIC} is disabled,
560 one thread per CPU online is used.
562 @item @emph{C/C++}:
563 @multitable @columnfractions .20 .80
564 @item @emph{Prototype}: @tab @code{int omp_get_num_threads(void);}
565 @end multitable
567 @item @emph{Fortran}:
568 @multitable @columnfractions .20 .80
569 @item @emph{Interface}: @tab @code{integer function omp_get_num_threads()}
570 @end multitable
572 @item @emph{See also}:
573 @ref{omp_get_max_threads}, @ref{omp_set_num_threads}, @ref{OMP_NUM_THREADS}
575 @item @emph{Reference}:
576 @uref{http://www.openmp.org/, OpenMP specification v4.5}, Section 3.2.2.
577 @end table
581 @node omp_get_proc_bind
582 @section @code{omp_get_proc_bind} -- Whether theads may be moved between CPUs
583 @table @asis
584 @item @emph{Description}:
585 This functions returns the currently active thread affinity policy, which is
586 set via @env{OMP_PROC_BIND}.  Possible values are @code{omp_proc_bind_false},
587 @code{omp_proc_bind_true}, @code{omp_proc_bind_master},
588 @code{omp_proc_bind_close} and @code{omp_proc_bind_spread}.
590 @item @emph{C/C++}:
591 @multitable @columnfractions .20 .80
592 @item @emph{Prototype}: @tab @code{omp_proc_bind_t omp_get_proc_bind(void);}
593 @end multitable
595 @item @emph{Fortran}:
596 @multitable @columnfractions .20 .80
597 @item @emph{Interface}: @tab @code{integer(kind=omp_proc_bind_kind) function omp_get_proc_bind()}
598 @end multitable
600 @item @emph{See also}:
601 @ref{OMP_PROC_BIND}, @ref{OMP_PLACES}, @ref{GOMP_CPU_AFFINITY},
603 @item @emph{Reference}:
604 @uref{http://www.openmp.org/, OpenMP specification v4.5}, Section 3.2.22.
605 @end table
609 @node omp_get_schedule
610 @section @code{omp_get_schedule} -- Obtain the runtime scheduling method
611 @table @asis
612 @item @emph{Description}:
613 Obtain the runtime scheduling method.  The @var{kind} argument will be
614 set to the value @code{omp_sched_static}, @code{omp_sched_dynamic},
615 @code{omp_sched_guided} or @code{omp_sched_auto}.  The second argument,
616 @var{chunk_size}, is set to the chunk size.
618 @item @emph{C/C++}
619 @multitable @columnfractions .20 .80
620 @item @emph{Prototype}: @tab @code{void omp_get_schedule(omp_sched_t *kind, int *chunk_size);}
621 @end multitable
623 @item @emph{Fortran}:
624 @multitable @columnfractions .20 .80
625 @item @emph{Interface}: @tab @code{subroutine omp_get_schedule(kind, chunk_size)}
626 @item                   @tab @code{integer(kind=omp_sched_kind) kind}
627 @item                   @tab @code{integer chunk_size}
628 @end multitable
630 @item @emph{See also}:
631 @ref{omp_set_schedule}, @ref{OMP_SCHEDULE}
633 @item @emph{Reference}:
634 @uref{http://www.openmp.org/, OpenMP specification v4.5}, Section 3.2.13.
635 @end table
639 @node omp_get_team_num
640 @section @code{omp_get_team_num} -- Get team number
641 @table @asis
642 @item @emph{Description}:
643 Returns the team number of the calling thread.
645 @item @emph{C/C++}:
646 @multitable @columnfractions .20 .80
647 @item @emph{Prototype}: @tab @code{int omp_get_team_num(void);}
648 @end multitable
650 @item @emph{Fortran}:
651 @multitable @columnfractions .20 .80
652 @item @emph{Interface}: @tab @code{integer function omp_get_team_num()}
653 @end multitable
655 @item @emph{Reference}:
656 @uref{http://www.openmp.org/, OpenMP specification v4.5}, Section 3.2.33.
657 @end table
661 @node omp_get_team_size
662 @section @code{omp_get_team_size} -- Number of threads in a team
663 @table @asis
664 @item @emph{Description}:
665 This function returns the number of threads in a thread team to which
666 either the current thread or its ancestor belongs.  For values of @var{level}
667 outside zero to @code{omp_get_level}, -1 is returned; if @var{level} is zero,
668 1 is returned, and for @code{omp_get_level}, the result is identical
669 to @code{omp_get_num_threads}.
671 @item @emph{C/C++}:
672 @multitable @columnfractions .20 .80
673 @item @emph{Prototype}: @tab @code{int omp_get_team_size(int level);}
674 @end multitable
676 @item @emph{Fortran}:
677 @multitable @columnfractions .20 .80
678 @item @emph{Interface}: @tab @code{integer function omp_get_team_size(level)}
679 @item                   @tab @code{integer level}
680 @end multitable
682 @item @emph{See also}:
683 @ref{omp_get_num_threads}, @ref{omp_get_level}, @ref{omp_get_ancestor_thread_num}
685 @item @emph{Reference}:
686 @uref{http://www.openmp.org/, OpenMP specification v4.5}, Section 3.2.19.
687 @end table
691 @node omp_get_thread_limit
692 @section @code{omp_get_thread_limit} -- Maximum number of threads
693 @table @asis
694 @item @emph{Description}:
695 Return the maximum number of threads of the program.
697 @item @emph{C/C++}:
698 @multitable @columnfractions .20 .80
699 @item @emph{Prototype}: @tab @code{int omp_get_thread_limit(void);}
700 @end multitable
702 @item @emph{Fortran}:
703 @multitable @columnfractions .20 .80
704 @item @emph{Interface}: @tab @code{integer function omp_get_thread_limit()}
705 @end multitable
707 @item @emph{See also}:
708 @ref{omp_get_max_threads}, @ref{OMP_THREAD_LIMIT}
710 @item @emph{Reference}:
711 @uref{http://www.openmp.org/, OpenMP specification v4.5}, Section 3.2.14.
712 @end table
716 @node omp_get_thread_num
717 @section @code{omp_get_thread_num} -- Current thread ID
718 @table @asis
719 @item @emph{Description}:
720 Returns a unique thread identification number within the current team.
721 In a sequential parts of the program, @code{omp_get_thread_num}
722 always returns 0.  In parallel regions the return value varies
723 from 0 to @code{omp_get_num_threads}-1 inclusive.  The return
724 value of the master thread of a team is always 0.
726 @item @emph{C/C++}:
727 @multitable @columnfractions .20 .80
728 @item @emph{Prototype}: @tab @code{int omp_get_thread_num(void);}
729 @end multitable
731 @item @emph{Fortran}:
732 @multitable @columnfractions .20 .80
733 @item @emph{Interface}: @tab @code{integer function omp_get_thread_num()}
734 @end multitable
736 @item @emph{See also}:
737 @ref{omp_get_num_threads}, @ref{omp_get_ancestor_thread_num}
739 @item @emph{Reference}:
740 @uref{http://www.openmp.org/, OpenMP specification v4.5}, Section 3.2.4.
741 @end table
745 @node omp_in_parallel
746 @section @code{omp_in_parallel} -- Whether a parallel region is active
747 @table @asis
748 @item @emph{Description}:
749 This function returns @code{true} if currently running in parallel,
750 @code{false} otherwise.  Here, @code{true} and @code{false} represent
751 their language-specific counterparts.
753 @item @emph{C/C++}:
754 @multitable @columnfractions .20 .80
755 @item @emph{Prototype}: @tab @code{int omp_in_parallel(void);}
756 @end multitable
758 @item @emph{Fortran}:
759 @multitable @columnfractions .20 .80
760 @item @emph{Interface}: @tab @code{logical function omp_in_parallel()}
761 @end multitable
763 @item @emph{Reference}:
764 @uref{http://www.openmp.org/, OpenMP specification v4.5}, Section 3.2.6.
765 @end table
768 @node omp_in_final
769 @section @code{omp_in_final} -- Whether in final or included task region
770 @table @asis
771 @item @emph{Description}:
772 This function returns @code{true} if currently running in a final
773 or included task region, @code{false} otherwise.  Here, @code{true}
774 and @code{false} represent their language-specific counterparts.
776 @item @emph{C/C++}:
777 @multitable @columnfractions .20 .80
778 @item @emph{Prototype}: @tab @code{int omp_in_final(void);}
779 @end multitable
781 @item @emph{Fortran}:
782 @multitable @columnfractions .20 .80
783 @item @emph{Interface}: @tab @code{logical function omp_in_final()}
784 @end multitable
786 @item @emph{Reference}:
787 @uref{http://www.openmp.org/, OpenMP specification v4.5}, Section 3.2.21.
788 @end table
792 @node omp_is_initial_device
793 @section @code{omp_is_initial_device} -- Whether executing on the host device
794 @table @asis
795 @item @emph{Description}:
796 This function returns @code{true} if currently running on the host device,
797 @code{false} otherwise.  Here, @code{true} and @code{false} represent
798 their language-specific counterparts.
800 @item @emph{C/C++}:
801 @multitable @columnfractions .20 .80
802 @item @emph{Prototype}: @tab @code{int omp_is_initial_device(void);}
803 @end multitable
805 @item @emph{Fortran}:
806 @multitable @columnfractions .20 .80
807 @item @emph{Interface}: @tab @code{logical function omp_is_initial_device()}
808 @end multitable
810 @item @emph{Reference}:
811 @uref{http://www.openmp.org/, OpenMP specification v4.5}, Section 3.2.34.
812 @end table
816 @node omp_set_default_device
817 @section @code{omp_set_default_device} -- Set the default device for target regions
818 @table @asis
819 @item @emph{Description}:
820 Set the default device for target regions without device clause.  The argument
821 shall be a nonnegative device number.
823 @item @emph{C/C++}:
824 @multitable @columnfractions .20 .80
825 @item @emph{Prototype}: @tab @code{void omp_set_default_device(int device_num);}
826 @end multitable
828 @item @emph{Fortran}:
829 @multitable @columnfractions .20 .80
830 @item @emph{Interface}: @tab @code{subroutine omp_set_default_device(device_num)}
831 @item                   @tab @code{integer device_num}
832 @end multitable
834 @item @emph{See also}:
835 @ref{OMP_DEFAULT_DEVICE}, @ref{omp_get_default_device}
837 @item @emph{Reference}:
838 @uref{http://www.openmp.org/, OpenMP specification v4.5}, Section 3.2.29.
839 @end table
843 @node omp_set_dynamic
844 @section @code{omp_set_dynamic} -- Enable/disable dynamic teams
845 @table @asis
846 @item @emph{Description}:
847 Enable or disable the dynamic adjustment of the number of threads 
848 within a team.  The function takes the language-specific equivalent
849 of @code{true} and @code{false}, where @code{true} enables dynamic 
850 adjustment of team sizes and @code{false} disables it.
852 @item @emph{C/C++}:
853 @multitable @columnfractions .20 .80
854 @item @emph{Prototype}: @tab @code{void omp_set_dynamic(int dynamic_threads);}
855 @end multitable
857 @item @emph{Fortran}:
858 @multitable @columnfractions .20 .80
859 @item @emph{Interface}: @tab @code{subroutine omp_set_dynamic(dynamic_threads)}
860 @item                   @tab @code{logical, intent(in) :: dynamic_threads}
861 @end multitable
863 @item @emph{See also}:
864 @ref{OMP_DYNAMIC}, @ref{omp_get_dynamic}
866 @item @emph{Reference}:
867 @uref{http://www.openmp.org/, OpenMP specification v4.5}, Section 3.2.7.
868 @end table
872 @node omp_set_max_active_levels
873 @section @code{omp_set_max_active_levels} -- Limits the number of active parallel regions
874 @table @asis
875 @item @emph{Description}:
876 This function limits the maximum allowed number of nested, active
877 parallel regions.
879 @item @emph{C/C++}
880 @multitable @columnfractions .20 .80
881 @item @emph{Prototype}: @tab @code{void omp_set_max_active_levels(int max_levels);}
882 @end multitable
884 @item @emph{Fortran}:
885 @multitable @columnfractions .20 .80
886 @item @emph{Interface}: @tab @code{subroutine omp_set_max_active_levels(max_levels)}
887 @item                   @tab @code{integer max_levels}
888 @end multitable
890 @item @emph{See also}:
891 @ref{omp_get_max_active_levels}, @ref{omp_get_active_level}
893 @item @emph{Reference}:
894 @uref{http://www.openmp.org/, OpenMP specification v4.5}, Section 3.2.15.
895 @end table
899 @node omp_set_nested
900 @section @code{omp_set_nested} -- Enable/disable nested parallel regions
901 @table @asis
902 @item @emph{Description}:
903 Enable or disable nested parallel regions, i.e., whether team members
904 are allowed to create new teams.  The function takes the language-specific
905 equivalent of @code{true} and @code{false}, where @code{true} enables 
906 dynamic adjustment of team sizes and @code{false} disables it.
908 @item @emph{C/C++}:
909 @multitable @columnfractions .20 .80
910 @item @emph{Prototype}: @tab @code{void omp_set_nested(int nested);}
911 @end multitable
913 @item @emph{Fortran}:
914 @multitable @columnfractions .20 .80
915 @item @emph{Interface}: @tab @code{subroutine omp_set_nested(nested)}
916 @item                   @tab @code{logical, intent(in) :: nested}
917 @end multitable
919 @item @emph{See also}:
920 @ref{OMP_NESTED}, @ref{omp_get_nested}
922 @item @emph{Reference}:
923 @uref{http://www.openmp.org/, OpenMP specification v4.5}, Section 3.2.10.
924 @end table
928 @node omp_set_num_threads
929 @section @code{omp_set_num_threads} -- Set upper team size limit
930 @table @asis
931 @item @emph{Description}:
932 Specifies the number of threads used by default in subsequent parallel 
933 sections, if those do not specify a @code{num_threads} clause.  The
934 argument of @code{omp_set_num_threads} shall be a positive integer.
936 @item @emph{C/C++}:
937 @multitable @columnfractions .20 .80
938 @item @emph{Prototype}: @tab @code{void omp_set_num_threads(int num_threads);}
939 @end multitable
941 @item @emph{Fortran}:
942 @multitable @columnfractions .20 .80
943 @item @emph{Interface}: @tab @code{subroutine omp_set_num_threads(num_threads)}
944 @item                   @tab @code{integer, intent(in) :: num_threads}
945 @end multitable
947 @item @emph{See also}:
948 @ref{OMP_NUM_THREADS}, @ref{omp_get_num_threads}, @ref{omp_get_max_threads}
950 @item @emph{Reference}:
951 @uref{http://www.openmp.org/, OpenMP specification v4.5}, Section 3.2.1.
952 @end table
956 @node omp_set_schedule
957 @section @code{omp_set_schedule} -- Set the runtime scheduling method
958 @table @asis
959 @item @emph{Description}:
960 Sets the runtime scheduling method.  The @var{kind} argument can have the
961 value @code{omp_sched_static}, @code{omp_sched_dynamic},
962 @code{omp_sched_guided} or @code{omp_sched_auto}.  Except for
963 @code{omp_sched_auto}, the chunk size is set to the value of
964 @var{chunk_size} if positive, or to the default value if zero or negative.
965 For @code{omp_sched_auto} the @var{chunk_size} argument is ignored.
967 @item @emph{C/C++}
968 @multitable @columnfractions .20 .80
969 @item @emph{Prototype}: @tab @code{void omp_set_schedule(omp_sched_t kind, int chunk_size);}
970 @end multitable
972 @item @emph{Fortran}:
973 @multitable @columnfractions .20 .80
974 @item @emph{Interface}: @tab @code{subroutine omp_set_schedule(kind, chunk_size)}
975 @item                   @tab @code{integer(kind=omp_sched_kind) kind}
976 @item                   @tab @code{integer chunk_size}
977 @end multitable
979 @item @emph{See also}:
980 @ref{omp_get_schedule}
981 @ref{OMP_SCHEDULE}
983 @item @emph{Reference}:
984 @uref{http://www.openmp.org/, OpenMP specification v4.5}, Section 3.2.12.
985 @end table
989 @node omp_init_lock
990 @section @code{omp_init_lock} -- Initialize simple lock
991 @table @asis
992 @item @emph{Description}:
993 Initialize a simple lock.  After initialization, the lock is in
994 an unlocked state.
996 @item @emph{C/C++}:
997 @multitable @columnfractions .20 .80
998 @item @emph{Prototype}: @tab @code{void omp_init_lock(omp_lock_t *lock);}
999 @end multitable
1001 @item @emph{Fortran}:
1002 @multitable @columnfractions .20 .80
1003 @item @emph{Interface}: @tab @code{subroutine omp_init_lock(svar)}
1004 @item                   @tab @code{integer(omp_lock_kind), intent(out) :: svar}
1005 @end multitable
1007 @item @emph{See also}:
1008 @ref{omp_destroy_lock}
1010 @item @emph{Reference}: 
1011 @uref{http://www.openmp.org/, OpenMP specification v4.5}, Section 3.3.1.
1012 @end table
1016 @node omp_set_lock
1017 @section @code{omp_set_lock} -- Wait for and set simple lock
1018 @table @asis
1019 @item @emph{Description}:
1020 Before setting a simple lock, the lock variable must be initialized by 
1021 @code{omp_init_lock}.  The calling thread is blocked until the lock 
1022 is available.  If the lock is already held by the current thread, 
1023 a deadlock occurs.
1025 @item @emph{C/C++}:
1026 @multitable @columnfractions .20 .80
1027 @item @emph{Prototype}: @tab @code{void omp_set_lock(omp_lock_t *lock);}
1028 @end multitable
1030 @item @emph{Fortran}:
1031 @multitable @columnfractions .20 .80
1032 @item @emph{Interface}: @tab @code{subroutine omp_set_lock(svar)}
1033 @item                   @tab @code{integer(omp_lock_kind), intent(inout) :: svar}
1034 @end multitable
1036 @item @emph{See also}:
1037 @ref{omp_init_lock}, @ref{omp_test_lock}, @ref{omp_unset_lock}
1039 @item @emph{Reference}: 
1040 @uref{http://www.openmp.org/, OpenMP specification v4.5}, Section 3.3.4.
1041 @end table
1045 @node omp_test_lock
1046 @section @code{omp_test_lock} -- Test and set simple lock if available
1047 @table @asis
1048 @item @emph{Description}:
1049 Before setting a simple lock, the lock variable must be initialized by 
1050 @code{omp_init_lock}.  Contrary to @code{omp_set_lock}, @code{omp_test_lock} 
1051 does not block if the lock is not available.  This function returns
1052 @code{true} upon success, @code{false} otherwise.  Here, @code{true} and
1053 @code{false} represent their language-specific counterparts.
1055 @item @emph{C/C++}:
1056 @multitable @columnfractions .20 .80
1057 @item @emph{Prototype}: @tab @code{int omp_test_lock(omp_lock_t *lock);}
1058 @end multitable
1060 @item @emph{Fortran}:
1061 @multitable @columnfractions .20 .80
1062 @item @emph{Interface}: @tab @code{logical function omp_test_lock(svar)}
1063 @item                   @tab @code{integer(omp_lock_kind), intent(inout) :: svar}
1064 @end multitable
1066 @item @emph{See also}:
1067 @ref{omp_init_lock}, @ref{omp_set_lock}, @ref{omp_set_lock}
1069 @item @emph{Reference}: 
1070 @uref{http://www.openmp.org/, OpenMP specification v4.5}, Section 3.3.6.
1071 @end table
1075 @node omp_unset_lock
1076 @section @code{omp_unset_lock} -- Unset simple lock
1077 @table @asis
1078 @item @emph{Description}:
1079 A simple lock about to be unset must have been locked by @code{omp_set_lock}
1080 or @code{omp_test_lock} before.  In addition, the lock must be held by the
1081 thread calling @code{omp_unset_lock}.  Then, the lock becomes unlocked.  If one
1082 or more threads attempted to set the lock before, one of them is chosen to,
1083 again, set the lock to itself.
1085 @item @emph{C/C++}:
1086 @multitable @columnfractions .20 .80
1087 @item @emph{Prototype}: @tab @code{void omp_unset_lock(omp_lock_t *lock);}
1088 @end multitable
1090 @item @emph{Fortran}:
1091 @multitable @columnfractions .20 .80
1092 @item @emph{Interface}: @tab @code{subroutine omp_unset_lock(svar)}
1093 @item                   @tab @code{integer(omp_lock_kind), intent(inout) :: svar}
1094 @end multitable
1096 @item @emph{See also}:
1097 @ref{omp_set_lock}, @ref{omp_test_lock}
1099 @item @emph{Reference}: 
1100 @uref{http://www.openmp.org/, OpenMP specification v4.5}, Section 3.3.5.
1101 @end table
1105 @node omp_destroy_lock
1106 @section @code{omp_destroy_lock} -- Destroy simple lock
1107 @table @asis
1108 @item @emph{Description}:
1109 Destroy a simple lock.  In order to be destroyed, a simple lock must be
1110 in the unlocked state. 
1112 @item @emph{C/C++}:
1113 @multitable @columnfractions .20 .80
1114 @item @emph{Prototype}: @tab @code{void omp_destroy_lock(omp_lock_t *lock);}
1115 @end multitable
1117 @item @emph{Fortran}:
1118 @multitable @columnfractions .20 .80
1119 @item @emph{Interface}: @tab @code{subroutine omp_destroy_lock(svar)}
1120 @item                   @tab @code{integer(omp_lock_kind), intent(inout) :: svar}
1121 @end multitable
1123 @item @emph{See also}:
1124 @ref{omp_init_lock}
1126 @item @emph{Reference}: 
1127 @uref{http://www.openmp.org/, OpenMP specification v4.5}, Section 3.3.3.
1128 @end table
1132 @node omp_init_nest_lock
1133 @section @code{omp_init_nest_lock} -- Initialize nested lock
1134 @table @asis
1135 @item @emph{Description}:
1136 Initialize a nested lock.  After initialization, the lock is in
1137 an unlocked state and the nesting count is set to zero.
1139 @item @emph{C/C++}:
1140 @multitable @columnfractions .20 .80
1141 @item @emph{Prototype}: @tab @code{void omp_init_nest_lock(omp_nest_lock_t *lock);}
1142 @end multitable
1144 @item @emph{Fortran}:
1145 @multitable @columnfractions .20 .80
1146 @item @emph{Interface}: @tab @code{subroutine omp_init_nest_lock(nvar)}
1147 @item                   @tab @code{integer(omp_nest_lock_kind), intent(out) :: nvar}
1148 @end multitable
1150 @item @emph{See also}:
1151 @ref{omp_destroy_nest_lock}
1153 @item @emph{Reference}:
1154 @uref{http://www.openmp.org/, OpenMP specification v4.5}, Section 3.3.1.
1155 @end table
1158 @node omp_set_nest_lock
1159 @section @code{omp_set_nest_lock} -- Wait for and set nested lock
1160 @table @asis
1161 @item @emph{Description}:
1162 Before setting a nested lock, the lock variable must be initialized by 
1163 @code{omp_init_nest_lock}.  The calling thread is blocked until the lock
1164 is available.  If the lock is already held by the current thread, the
1165 nesting count for the lock is incremented.
1167 @item @emph{C/C++}:
1168 @multitable @columnfractions .20 .80
1169 @item @emph{Prototype}: @tab @code{void omp_set_nest_lock(omp_nest_lock_t *lock);}
1170 @end multitable
1172 @item @emph{Fortran}:
1173 @multitable @columnfractions .20 .80
1174 @item @emph{Interface}: @tab @code{subroutine omp_set_nest_lock(nvar)}
1175 @item                   @tab @code{integer(omp_nest_lock_kind), intent(inout) :: nvar}
1176 @end multitable
1178 @item @emph{See also}:
1179 @ref{omp_init_nest_lock}, @ref{omp_unset_nest_lock}
1181 @item @emph{Reference}: 
1182 @uref{http://www.openmp.org/, OpenMP specification v4.5}, Section 3.3.4.
1183 @end table
1187 @node omp_test_nest_lock
1188 @section @code{omp_test_nest_lock} -- Test and set nested lock if available
1189 @table @asis
1190 @item @emph{Description}:
1191 Before setting a nested lock, the lock variable must be initialized by 
1192 @code{omp_init_nest_lock}.  Contrary to @code{omp_set_nest_lock},
1193 @code{omp_test_nest_lock} does not block if the lock is not available. 
1194 If the lock is already held by the current thread, the new nesting count 
1195 is returned.  Otherwise, the return value equals zero.
1197 @item @emph{C/C++}:
1198 @multitable @columnfractions .20 .80
1199 @item @emph{Prototype}: @tab @code{int omp_test_nest_lock(omp_nest_lock_t *lock);}
1200 @end multitable
1202 @item @emph{Fortran}:
1203 @multitable @columnfractions .20 .80
1204 @item @emph{Interface}: @tab @code{logical function omp_test_nest_lock(nvar)}
1205 @item                   @tab @code{integer(omp_nest_lock_kind), intent(inout) :: nvar}
1206 @end multitable
1209 @item @emph{See also}:
1210 @ref{omp_init_lock}, @ref{omp_set_lock}, @ref{omp_set_lock}
1212 @item @emph{Reference}: 
1213 @uref{http://www.openmp.org/, OpenMP specification v4.5}, Section 3.3.6.
1214 @end table
1218 @node omp_unset_nest_lock
1219 @section @code{omp_unset_nest_lock} -- Unset nested lock
1220 @table @asis
1221 @item @emph{Description}:
1222 A nested lock about to be unset must have been locked by @code{omp_set_nested_lock}
1223 or @code{omp_test_nested_lock} before.  In addition, the lock must be held by the
1224 thread calling @code{omp_unset_nested_lock}.  If the nesting count drops to zero, the
1225 lock becomes unlocked.  If one ore more threads attempted to set the lock before,
1226 one of them is chosen to, again, set the lock to itself.
1228 @item @emph{C/C++}:
1229 @multitable @columnfractions .20 .80
1230 @item @emph{Prototype}: @tab @code{void omp_unset_nest_lock(omp_nest_lock_t *lock);}
1231 @end multitable
1233 @item @emph{Fortran}:
1234 @multitable @columnfractions .20 .80
1235 @item @emph{Interface}: @tab @code{subroutine omp_unset_nest_lock(nvar)}
1236 @item                   @tab @code{integer(omp_nest_lock_kind), intent(inout) :: nvar}
1237 @end multitable
1239 @item @emph{See also}:
1240 @ref{omp_set_nest_lock}
1242 @item @emph{Reference}: 
1243 @uref{http://www.openmp.org/, OpenMP specification v4.5}, Section 3.3.5.
1244 @end table
1248 @node omp_destroy_nest_lock
1249 @section @code{omp_destroy_nest_lock} -- Destroy nested lock
1250 @table @asis
1251 @item @emph{Description}:
1252 Destroy a nested lock.  In order to be destroyed, a nested lock must be
1253 in the unlocked state and its nesting count must equal zero.
1255 @item @emph{C/C++}:
1256 @multitable @columnfractions .20 .80
1257 @item @emph{Prototype}: @tab @code{void omp_destroy_nest_lock(omp_nest_lock_t *);}
1258 @end multitable
1260 @item @emph{Fortran}:
1261 @multitable @columnfractions .20 .80
1262 @item @emph{Interface}: @tab @code{subroutine omp_destroy_nest_lock(nvar)}
1263 @item                   @tab @code{integer(omp_nest_lock_kind), intent(inout) :: nvar}
1264 @end multitable
1266 @item @emph{See also}:
1267 @ref{omp_init_lock}
1269 @item @emph{Reference}: 
1270 @uref{http://www.openmp.org/, OpenMP specification v4.5}, Section 3.3.3.
1271 @end table
1275 @node omp_get_wtick
1276 @section @code{omp_get_wtick} -- Get timer precision
1277 @table @asis
1278 @item @emph{Description}:
1279 Gets the timer precision, i.e., the number of seconds between two 
1280 successive clock ticks.
1282 @item @emph{C/C++}:
1283 @multitable @columnfractions .20 .80
1284 @item @emph{Prototype}: @tab @code{double omp_get_wtick(void);}
1285 @end multitable
1287 @item @emph{Fortran}:
1288 @multitable @columnfractions .20 .80
1289 @item @emph{Interface}: @tab @code{double precision function omp_get_wtick()}
1290 @end multitable
1292 @item @emph{See also}:
1293 @ref{omp_get_wtime}
1295 @item @emph{Reference}: 
1296 @uref{http://www.openmp.org/, OpenMP specification v4.5}, Section 3.4.2.
1297 @end table
1301 @node omp_get_wtime
1302 @section @code{omp_get_wtime} -- Elapsed wall clock time
1303 @table @asis
1304 @item @emph{Description}:
1305 Elapsed wall clock time in seconds.  The time is measured per thread, no
1306 guarantee can be made that two distinct threads measure the same time.
1307 Time is measured from some "time in the past", which is an arbitrary time
1308 guaranteed not to change during the execution of the program.
1310 @item @emph{C/C++}:
1311 @multitable @columnfractions .20 .80
1312 @item @emph{Prototype}: @tab @code{double omp_get_wtime(void);}
1313 @end multitable
1315 @item @emph{Fortran}:
1316 @multitable @columnfractions .20 .80
1317 @item @emph{Interface}: @tab @code{double precision function omp_get_wtime()}
1318 @end multitable
1320 @item @emph{See also}:
1321 @ref{omp_get_wtick}
1323 @item @emph{Reference}: 
1324 @uref{http://www.openmp.org/, OpenMP specification v4.5}, Section 3.4.1.
1325 @end table
1329 @c ---------------------------------------------------------------------
1330 @c Environment Variables
1331 @c ---------------------------------------------------------------------
1333 @node Environment Variables
1334 @chapter Environment Variables
1336 The environment variables which beginning with @env{OMP_} are defined by
1337 section 4 of the OpenMP specification in version 4.5, while those
1338 beginning with @env{GOMP_} are GNU extensions.
1340 @menu
1341 * OMP_CANCELLATION::        Set whether cancellation is activated
1342 * OMP_DISPLAY_ENV::         Show OpenMP version and environment variables
1343 * OMP_DEFAULT_DEVICE::      Set the device used in target regions
1344 * OMP_DYNAMIC::             Dynamic adjustment of threads
1345 * OMP_MAX_ACTIVE_LEVELS::   Set the maximum number of nested parallel regions
1346 * OMP_MAX_TASK_PRIORITY::   Set the maximum task priority value
1347 * OMP_NESTED::              Nested parallel regions
1348 * OMP_NUM_THREADS::         Specifies the number of threads to use
1349 * OMP_PROC_BIND::           Whether theads may be moved between CPUs
1350 * OMP_PLACES::              Specifies on which CPUs the theads should be placed
1351 * OMP_STACKSIZE::           Set default thread stack size
1352 * OMP_SCHEDULE::            How threads are scheduled
1353 * OMP_THREAD_LIMIT::        Set the maximum number of threads
1354 * OMP_WAIT_POLICY::         How waiting threads are handled
1355 * GOMP_CPU_AFFINITY::       Bind threads to specific CPUs
1356 * GOMP_DEBUG::              Enable debugging output
1357 * GOMP_STACKSIZE::          Set default thread stack size
1358 * GOMP_SPINCOUNT::          Set the busy-wait spin count
1359 * GOMP_RTEMS_THREAD_POOLS:: Set the RTEMS specific thread pools
1360 @end menu
1363 @node OMP_CANCELLATION
1364 @section @env{OMP_CANCELLATION} -- Set whether cancellation is activated
1365 @cindex Environment Variable
1366 @table @asis
1367 @item @emph{Description}:
1368 If set to @code{TRUE}, the cancellation is activated.  If set to @code{FALSE} or
1369 if unset, cancellation is disabled and the @code{cancel} construct is ignored.
1371 @item @emph{See also}:
1372 @ref{omp_get_cancellation}
1374 @item @emph{Reference}:
1375 @uref{http://www.openmp.org/, OpenMP specification v4.5}, Section 4.11
1376 @end table
1380 @node OMP_DISPLAY_ENV
1381 @section @env{OMP_DISPLAY_ENV} -- Show OpenMP version and environment variables
1382 @cindex Environment Variable
1383 @table @asis
1384 @item @emph{Description}:
1385 If set to @code{TRUE}, the OpenMP version number and the values
1386 associated with the OpenMP environment variables are printed to @code{stderr}.
1387 If set to @code{VERBOSE}, it additionally shows the value of the environment
1388 variables which are GNU extensions.  If undefined or set to @code{FALSE},
1389 this information will not be shown.
1392 @item @emph{Reference}:
1393 @uref{http://www.openmp.org/, OpenMP specification v4.5}, Section 4.12
1394 @end table
1398 @node OMP_DEFAULT_DEVICE
1399 @section @env{OMP_DEFAULT_DEVICE} -- Set the device used in target regions
1400 @cindex Environment Variable
1401 @table @asis
1402 @item @emph{Description}:
1403 Set to choose the device which is used in a @code{target} region, unless the
1404 value is overridden by @code{omp_set_default_device} or by a @code{device}
1405 clause.  The value shall be the nonnegative device number. If no device with
1406 the given device number exists, the code is executed on the host.  If unset,
1407 device number 0 will be used.
1410 @item @emph{See also}:
1411 @ref{omp_get_default_device}, @ref{omp_set_default_device},
1413 @item @emph{Reference}:
1414 @uref{http://www.openmp.org/, OpenMP specification v4.5}, Section 4.13
1415 @end table
1419 @node OMP_DYNAMIC
1420 @section @env{OMP_DYNAMIC} -- Dynamic adjustment of threads
1421 @cindex Environment Variable
1422 @table @asis
1423 @item @emph{Description}:
1424 Enable or disable the dynamic adjustment of the number of threads 
1425 within a team.  The value of this environment variable shall be 
1426 @code{TRUE} or @code{FALSE}.  If undefined, dynamic adjustment is
1427 disabled by default.
1429 @item @emph{See also}:
1430 @ref{omp_set_dynamic}
1432 @item @emph{Reference}: 
1433 @uref{http://www.openmp.org/, OpenMP specification v4.5}, Section 4.3
1434 @end table
1438 @node OMP_MAX_ACTIVE_LEVELS
1439 @section @env{OMP_MAX_ACTIVE_LEVELS} -- Set the maximum number of nested parallel regions
1440 @cindex Environment Variable
1441 @table @asis
1442 @item @emph{Description}:
1443 Specifies the initial value for the maximum number of nested parallel
1444 regions.  The value of this variable shall be a positive integer.
1445 If undefined, the number of active levels is unlimited.
1447 @item @emph{See also}:
1448 @ref{omp_set_max_active_levels}
1450 @item @emph{Reference}: 
1451 @uref{http://www.openmp.org/, OpenMP specification v4.5}, Section 4.9
1452 @end table
1456 @node OMP_MAX_TASK_PRIORITY
1457 @section @env{OMP_MAX_TASK_PRIORITY} -- Set the maximum priority
1458 number that can be set for a task.
1459 @cindex Environment Variable
1460 @table @asis
1461 @item @emph{Description}:
1462 Specifies the initial value for the maximum priority value that can be
1463 set for a task.  The value of this variable shall be a non-negative
1464 integer, and zero is allowed.  If undefined, the default priority is
1467 @item @emph{See also}:
1468 @ref{omp_get_max_task_priority}
1470 @item @emph{Reference}: 
1471 @uref{http://www.openmp.org/, OpenMP specification v4.5}, Section 4.14
1472 @end table
1476 @node OMP_NESTED
1477 @section @env{OMP_NESTED} -- Nested parallel regions
1478 @cindex Environment Variable
1479 @cindex Implementation specific setting
1480 @table @asis
1481 @item @emph{Description}:
1482 Enable or disable nested parallel regions, i.e., whether team members
1483 are allowed to create new teams.  The value of this environment variable 
1484 shall be @code{TRUE} or @code{FALSE}.  If undefined, nested parallel 
1485 regions are disabled by default.
1487 @item @emph{See also}:
1488 @ref{omp_set_nested}
1490 @item @emph{Reference}: 
1491 @uref{http://www.openmp.org/, OpenMP specification v4.5}, Section 4.6
1492 @end table
1496 @node OMP_NUM_THREADS
1497 @section @env{OMP_NUM_THREADS} -- Specifies the number of threads to use
1498 @cindex Environment Variable
1499 @cindex Implementation specific setting
1500 @table @asis
1501 @item @emph{Description}:
1502 Specifies the default number of threads to use in parallel regions.  The 
1503 value of this variable shall be a comma-separated list of positive integers;
1504 the value specified the number of threads to use for the corresponding nested
1505 level.  If undefined one thread per CPU is used.
1507 @item @emph{See also}:
1508 @ref{omp_set_num_threads}
1510 @item @emph{Reference}: 
1511 @uref{http://www.openmp.org/, OpenMP specification v4.5}, Section 4.2
1512 @end table
1516 @node OMP_PROC_BIND
1517 @section @env{OMP_PROC_BIND} -- Whether theads may be moved between CPUs
1518 @cindex Environment Variable
1519 @table @asis
1520 @item @emph{Description}:
1521 Specifies whether threads may be moved between processors.  If set to
1522 @code{TRUE}, OpenMP theads should not be moved; if set to @code{FALSE}
1523 they may be moved.  Alternatively, a comma separated list with the
1524 values @code{MASTER}, @code{CLOSE} and @code{SPREAD} can be used to specify
1525 the thread affinity policy for the corresponding nesting level.  With
1526 @code{MASTER} the worker threads are in the same place partition as the
1527 master thread.  With @code{CLOSE} those are kept close to the master thread
1528 in contiguous place partitions.  And with @code{SPREAD} a sparse distribution
1529 across the place partitions is used.
1531 When undefined, @env{OMP_PROC_BIND} defaults to @code{TRUE} when
1532 @env{OMP_PLACES} or @env{GOMP_CPU_AFFINITY} is set and @code{FALSE} otherwise.
1534 @item @emph{See also}:
1535 @ref{OMP_PLACES}, @ref{GOMP_CPU_AFFINITY}, @ref{omp_get_proc_bind}
1537 @item @emph{Reference}:
1538 @uref{http://www.openmp.org/, OpenMP specification v4.5}, Section 4.4
1539 @end table
1543 @node OMP_PLACES
1544 @section @env{OMP_PLACES} -- Specifies on which CPUs the theads should be placed
1545 @cindex Environment Variable
1546 @table @asis
1547 @item @emph{Description}:
1548 The thread placement can be either specified using an abstract name or by an
1549 explicit list of the places.  The abstract names @code{threads}, @code{cores}
1550 and @code{sockets} can be optionally followed by a positive number in
1551 parentheses, which denotes the how many places shall be created.  With
1552 @code{threads} each place corresponds to a single hardware thread; @code{cores}
1553 to a single core with the corresponding number of hardware threads; and with
1554 @code{sockets} the place corresponds to a single socket.  The resulting
1555 placement can be shown by setting the @env{OMP_DISPLAY_ENV} environment
1556 variable.
1558 Alternatively, the placement can be specified explicitly as comma-separated
1559 list of places.  A place is specified by set of nonnegative numbers in curly
1560 braces, denoting the denoting the hardware threads.  The hardware threads
1561 belonging to a place can either be specified as comma-separated list of
1562 nonnegative thread numbers or using an interval.  Multiple places can also be
1563 either specified by a comma-separated list of places or by an interval.  To
1564 specify an interval, a colon followed by the count is placed after after
1565 the hardware thread number or the place.  Optionally, the length can be
1566 followed by a colon and the stride number -- otherwise a unit stride is
1567 assumed.  For instance, the following specifies the same places list:
1568 @code{"@{0,1,2@}, @{3,4,6@}, @{7,8,9@}, @{10,11,12@}"};
1569 @code{"@{0:3@}, @{3:3@}, @{7:3@}, @{10:3@}"}; and @code{"@{0:2@}:4:3"}.
1571 If @env{OMP_PLACES} and @env{GOMP_CPU_AFFINITY} are unset and
1572 @env{OMP_PROC_BIND} is either unset or @code{false}, threads may be moved
1573 between CPUs following no placement policy.
1575 @item @emph{See also}:
1576 @ref{OMP_PROC_BIND}, @ref{GOMP_CPU_AFFINITY}, @ref{omp_get_proc_bind},
1577 @ref{OMP_DISPLAY_ENV}
1579 @item @emph{Reference}:
1580 @uref{http://www.openmp.org/, OpenMP specification v4.5}, Section 4.5
1581 @end table
1585 @node OMP_STACKSIZE
1586 @section @env{OMP_STACKSIZE} -- Set default thread stack size
1587 @cindex Environment Variable
1588 @table @asis
1589 @item @emph{Description}:
1590 Set the default thread stack size in kilobytes, unless the number
1591 is suffixed by @code{B}, @code{K}, @code{M} or @code{G}, in which
1592 case the size is, respectively, in bytes, kilobytes, megabytes
1593 or gigabytes.  This is different from @code{pthread_attr_setstacksize}
1594 which gets the number of bytes as an argument.  If the stack size cannot
1595 be set due to system constraints, an error is reported and the initial
1596 stack size is left unchanged.  If undefined, the stack size is system
1597 dependent.
1599 @item @emph{Reference}: 
1600 @uref{http://www.openmp.org/, OpenMP specification v4.5}, Section 4.7
1601 @end table
1605 @node OMP_SCHEDULE
1606 @section @env{OMP_SCHEDULE} -- How threads are scheduled
1607 @cindex Environment Variable
1608 @cindex Implementation specific setting
1609 @table @asis
1610 @item @emph{Description}:
1611 Allows to specify @code{schedule type} and @code{chunk size}. 
1612 The value of the variable shall have the form: @code{type[,chunk]} where
1613 @code{type} is one of @code{static}, @code{dynamic}, @code{guided} or @code{auto}
1614 The optional @code{chunk} size shall be a positive integer.  If undefined,
1615 dynamic scheduling and a chunk size of 1 is used.
1617 @item @emph{See also}:
1618 @ref{omp_set_schedule}
1620 @item @emph{Reference}: 
1621 @uref{http://www.openmp.org/, OpenMP specification v4.5}, Sections 2.7.1.1 and 4.1
1622 @end table
1626 @node OMP_THREAD_LIMIT
1627 @section @env{OMP_THREAD_LIMIT} -- Set the maximum number of threads
1628 @cindex Environment Variable
1629 @table @asis
1630 @item @emph{Description}:
1631 Specifies the number of threads to use for the whole program.  The
1632 value of this variable shall be a positive integer.  If undefined,
1633 the number of threads is not limited.
1635 @item @emph{See also}:
1636 @ref{OMP_NUM_THREADS}, @ref{omp_get_thread_limit}
1638 @item @emph{Reference}: 
1639 @uref{http://www.openmp.org/, OpenMP specification v4.5}, Section 4.10
1640 @end table
1644 @node OMP_WAIT_POLICY
1645 @section @env{OMP_WAIT_POLICY} -- How waiting threads are handled
1646 @cindex Environment Variable
1647 @table @asis
1648 @item @emph{Description}:
1649 Specifies whether waiting threads should be active or passive.  If
1650 the value is @code{PASSIVE}, waiting threads should not consume CPU
1651 power while waiting; while the value is @code{ACTIVE} specifies that
1652 they should.  If undefined, threads wait actively for a short time
1653 before waiting passively.
1655 @item @emph{See also}:
1656 @ref{GOMP_SPINCOUNT}
1658 @item @emph{Reference}: 
1659 @uref{http://www.openmp.org/, OpenMP specification v4.5}, Section 4.8
1660 @end table
1664 @node GOMP_CPU_AFFINITY
1665 @section @env{GOMP_CPU_AFFINITY} -- Bind threads to specific CPUs
1666 @cindex Environment Variable
1667 @table @asis
1668 @item @emph{Description}:
1669 Binds threads to specific CPUs.  The variable should contain a space-separated
1670 or comma-separated list of CPUs.  This list may contain different kinds of 
1671 entries: either single CPU numbers in any order, a range of CPUs (M-N) 
1672 or a range with some stride (M-N:S).  CPU numbers are zero based.  For example,
1673 @code{GOMP_CPU_AFFINITY="0 3 1-2 4-15:2"} will bind the initial thread
1674 to CPU 0, the second to CPU 3, the third to CPU 1, the fourth to 
1675 CPU 2, the fifth to CPU 4, the sixth through tenth to CPUs 6, 8, 10, 12,
1676 and 14 respectively and then start assigning back from the beginning of
1677 the list.  @code{GOMP_CPU_AFFINITY=0} binds all threads to CPU 0.
1679 There is no libgomp library routine to determine whether a CPU affinity
1680 specification is in effect.  As a workaround, language-specific library 
1681 functions, e.g., @code{getenv} in C or @code{GET_ENVIRONMENT_VARIABLE} in 
1682 Fortran, may be used to query the setting of the @code{GOMP_CPU_AFFINITY} 
1683 environment variable.  A defined CPU affinity on startup cannot be changed 
1684 or disabled during the runtime of the application.
1686 If both @env{GOMP_CPU_AFFINITY} and @env{OMP_PROC_BIND} are set,
1687 @env{OMP_PROC_BIND} has a higher precedence.  If neither has been set and
1688 @env{OMP_PROC_BIND} is unset, or when @env{OMP_PROC_BIND} is set to
1689 @code{FALSE}, the host system will handle the assignment of threads to CPUs.
1691 @item @emph{See also}:
1692 @ref{OMP_PLACES}, @ref{OMP_PROC_BIND}
1693 @end table
1697 @node GOMP_DEBUG
1698 @section @env{GOMP_DEBUG} -- Enable debugging output
1699 @cindex Environment Variable
1700 @table @asis
1701 @item @emph{Description}:
1702 Enable debugging output.  The variable should be set to @code{0}
1703 (disabled, also the default if not set), or @code{1} (enabled).
1705 If enabled, some debugging output will be printed during execution.
1706 This is currently not specified in more detail, and subject to change.
1707 @end table
1711 @node GOMP_STACKSIZE
1712 @section @env{GOMP_STACKSIZE} -- Set default thread stack size
1713 @cindex Environment Variable
1714 @cindex Implementation specific setting
1715 @table @asis
1716 @item @emph{Description}:
1717 Set the default thread stack size in kilobytes.  This is different from
1718 @code{pthread_attr_setstacksize} which gets the number of bytes as an 
1719 argument.  If the stack size cannot be set due to system constraints, an 
1720 error is reported and the initial stack size is left unchanged.  If undefined,
1721 the stack size is system dependent.
1723 @item @emph{See also}:
1724 @ref{OMP_STACKSIZE}
1726 @item @emph{Reference}: 
1727 @uref{http://gcc.gnu.org/ml/gcc-patches/2006-06/msg00493.html, 
1728 GCC Patches Mailinglist}, 
1729 @uref{http://gcc.gnu.org/ml/gcc-patches/2006-06/msg00496.html,
1730 GCC Patches Mailinglist}
1731 @end table
1735 @node GOMP_SPINCOUNT
1736 @section @env{GOMP_SPINCOUNT} -- Set the busy-wait spin count
1737 @cindex Environment Variable
1738 @cindex Implementation specific setting
1739 @table @asis
1740 @item @emph{Description}:
1741 Determines how long a threads waits actively with consuming CPU power
1742 before waiting passively without consuming CPU power.  The value may be
1743 either @code{INFINITE}, @code{INFINITY} to always wait actively or an
1744 integer which gives the number of spins of the busy-wait loop.  The
1745 integer may optionally be followed by the following suffixes acting
1746 as multiplication factors: @code{k} (kilo, thousand), @code{M} (mega,
1747 million), @code{G} (giga, billion), or @code{T} (tera, trillion).
1748 If undefined, 0 is used when @env{OMP_WAIT_POLICY} is @code{PASSIVE},
1749 300,000 is used when @env{OMP_WAIT_POLICY} is undefined and
1750 30 billion is used when @env{OMP_WAIT_POLICY} is @code{ACTIVE}.
1751 If there are more OpenMP threads than available CPUs, 1000 and 100
1752 spins are used for @env{OMP_WAIT_POLICY} being @code{ACTIVE} or
1753 undefined, respectively; unless the @env{GOMP_SPINCOUNT} is lower
1754 or @env{OMP_WAIT_POLICY} is @code{PASSIVE}.
1756 @item @emph{See also}:
1757 @ref{OMP_WAIT_POLICY}
1758 @end table
1762 @node GOMP_RTEMS_THREAD_POOLS
1763 @section @env{GOMP_RTEMS_THREAD_POOLS} -- Set the RTEMS specific thread pools
1764 @cindex Environment Variable
1765 @cindex Implementation specific setting
1766 @table @asis
1767 @item @emph{Description}:
1768 This environment variable is only used on the RTEMS real-time operating system.
1769 It determines the scheduler instance specific thread pools.  The format for
1770 @env{GOMP_RTEMS_THREAD_POOLS} is a list of optional
1771 @code{<thread-pool-count>[$<priority>]@@<scheduler-name>} configurations
1772 separated by @code{:} where:
1773 @itemize @bullet
1774 @item @code{<thread-pool-count>} is the thread pool count for this scheduler
1775 instance.
1776 @item @code{$<priority>} is an optional priority for the worker threads of a
1777 thread pool according to @code{pthread_setschedparam}.  In case a priority
1778 value is omitted, then a worker thread will inherit the priority of the OpenMP
1779 master thread that created it.  The priority of the worker thread is not
1780 changed after creation, even if a new OpenMP master thread using the worker has
1781 a different priority.
1782 @item @code{@@<scheduler-name>} is the scheduler instance name according to the
1783 RTEMS application configuration.
1784 @end itemize
1785 In case no thread pool configuration is specified for a scheduler instance,
1786 then each OpenMP master thread of this scheduler instance will use its own
1787 dynamically allocated thread pool.  To limit the worker thread count of the
1788 thread pools, each OpenMP master thread must call @code{omp_set_num_threads}.
1789 @item @emph{Example}:
1790 Lets suppose we have three scheduler instances @code{IO}, @code{WRK0}, and
1791 @code{WRK1} with @env{GOMP_RTEMS_THREAD_POOLS} set to
1792 @code{"1@@WRK0:3$4@@WRK1"}.  Then there are no thread pool restrictions for
1793 scheduler instance @code{IO}.  In the scheduler instance @code{WRK0} there is
1794 one thread pool available.  Since no priority is specified for this scheduler
1795 instance, the worker thread inherits the priority of the OpenMP master thread
1796 that created it.  In the scheduler instance @code{WRK1} there are three thread
1797 pools available and their worker threads run at priority four.
1798 @end table
1802 @c ---------------------------------------------------------------------
1803 @c Enabling OpenACC
1804 @c ---------------------------------------------------------------------
1806 @node Enabling OpenACC
1807 @chapter Enabling OpenACC
1809 To activate the OpenACC extensions for C/C++ and Fortran, the compile-time 
1810 flag @option{-fopenacc} must be specified.  This enables the OpenACC directive
1811 @code{#pragma acc} in C/C++ and @code{!$accp} directives in free form,
1812 @code{c$acc}, @code{*$acc} and @code{!$acc} directives in fixed form,
1813 @code{!$} conditional compilation sentinels in free form and @code{c$},
1814 @code{*$} and @code{!$} sentinels in fixed form, for Fortran.  The flag also
1815 arranges for automatic linking of the OpenACC runtime library 
1816 (@ref{OpenACC Runtime Library Routines}).
1818 A complete description of all OpenACC directives accepted may be found in 
1819 the @uref{http://www.openacc.org/, OpenACC} Application Programming
1820 Interface manual, version 2.0.
1822 Note that this is an experimental feature and subject to
1823 change in future versions of GCC.  See
1824 @uref{https://gcc.gnu.org/wiki/OpenACC} for more information.
1828 @c ---------------------------------------------------------------------
1829 @c OpenACC Runtime Library Routines
1830 @c ---------------------------------------------------------------------
1832 @node OpenACC Runtime Library Routines
1833 @chapter OpenACC Runtime Library Routines
1835 The runtime routines described here are defined by section 3 of the OpenACC
1836 specifications in version 2.0.
1837 They have C linkage, and do not throw exceptions.
1838 Generally, they are available only for the host, with the exception of
1839 @code{acc_on_device}, which is available for both the host and the
1840 acceleration device.
1842 @menu
1843 * acc_get_num_devices::         Get number of devices for the given device
1844                                 type.
1845 * acc_set_device_type::         Set type of device accelerator to use.
1846 * acc_get_device_type::         Get type of device accelerator to be used.
1847 * acc_set_device_num::          Set device number to use.
1848 * acc_get_device_num::          Get device number to be used.
1849 * acc_async_test::              Tests for completion of a specific asynchronous
1850                                 operation.
1851 * acc_async_test_all::          Tests for completion of all asychronous
1852                                 operations.
1853 * acc_wait::                    Wait for completion of a specific asynchronous
1854                                 operation.
1855 * acc_wait_all::                Waits for completion of all asyncrhonous
1856                                 operations.
1857 * acc_wait_all_async::          Wait for completion of all asynchronous
1858                                 operations.
1859 * acc_wait_async::              Wait for completion of asynchronous operations.
1860 * acc_init::                    Initialize runtime for a specific device type.
1861 * acc_shutdown::                Shuts down the runtime for a specific device
1862                                 type.
1863 * acc_on_device::               Whether executing on a particular device
1864 * acc_malloc::                  Allocate device memory.
1865 * acc_free::                    Free device memory.
1866 * acc_copyin::                  Allocate device memory and copy host memory to
1867                                 it.
1868 * acc_present_or_copyin::       If the data is not present on the device,
1869                                 allocate device memory and copy from host
1870                                 memory.
1871 * acc_create::                  Allocate device memory and map it to host
1872                                 memory.
1873 * acc_present_or_create::       If the data is not present on the device,
1874                                 allocate device memory and map it to host
1875                                 memory.
1876 * acc_copyout::                 Copy device memory to host memory.
1877 * acc_delete::                  Free device memory.
1878 * acc_update_device::           Update device memory from mapped host memory.
1879 * acc_update_self::             Update host memory from mapped device memory.
1880 * acc_map_data::                Map previously allocated device memory to host
1881                                 memory.
1882 * acc_unmap_data::              Unmap device memory from host memory.
1883 * acc_deviceptr::               Get device pointer associated with specific
1884                                 host address.
1885 * acc_hostptr::                 Get host pointer associated with specific
1886                                 device address.
1887 * acc_is_present::              Indiciate whether host variable / array is
1888                                 present on device.
1889 * acc_memcpy_to_device::        Copy host memory to device memory.
1890 * acc_memcpy_from_device::      Copy device memory to host memory.
1892 API routines for target platforms.
1894 * acc_get_current_cuda_device:: Get CUDA device handle.
1895 * acc_get_current_cuda_context::Get CUDA context handle.
1896 * acc_get_cuda_stream::         Get CUDA stream handle.
1897 * acc_set_cuda_stream::         Set CUDA stream handle.
1898 @end menu
1902 @node acc_get_num_devices
1903 @section @code{acc_get_num_devices} -- Get number of devices for given device type
1904 @table @asis
1905 @item @emph{Description}
1906 This function returns a value indicating the number of devices available
1907 for the device type specified in @var{devicetype}. 
1909 @item @emph{C/C++}:
1910 @multitable @columnfractions .20 .80
1911 @item @emph{Prototype}: @tab @code{int acc_get_num_devices(acc_device_t devicetype);}
1912 @end multitable
1914 @item @emph{Fortran}:
1915 @multitable @columnfractions .20 .80
1916 @item @emph{Interface}: @tab @code{integer function acc_get_num_devices(devicetype)}
1917 @item                  @tab @code{integer(kind=acc_device_kind) devicetype}
1918 @end multitable
1920 @item @emph{Reference}:
1921 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
1922 3.2.1.
1923 @end table
1927 @node acc_set_device_type
1928 @section @code{acc_set_device_type} -- Set type of device accelerator to use.
1929 @table @asis
1930 @item @emph{Description}
1931 This function indicates to the runtime library which device typr, specified
1932 in @var{devicetype}, to use when executing a parallel or kernels region. 
1934 @item @emph{C/C++}:
1935 @multitable @columnfractions .20 .80
1936 @item @emph{Prototype}: @tab @code{acc_set_device_type(acc_device_t devicetype);}
1937 @end multitable
1939 @item @emph{Fortran}:
1940 @multitable @columnfractions .20 .80
1941 @item @emph{Interface}: @tab @code{subroutine acc_set_device_type(devicetype)}
1942 @item                   @tab @code{integer(kind=acc_device_kind) devicetype}
1943 @end multitable
1945 @item @emph{Reference}:
1946 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
1947 3.2.2.
1948 @end table
1952 @node acc_get_device_type
1953 @section @code{acc_get_device_type} -- Get type of device accelerator to be used.
1954 @table @asis
1955 @item @emph{Description}
1956 This function returns what device type will be used when executing a
1957 parallel or kernels region.
1959 @item @emph{C/C++}:
1960 @multitable @columnfractions .20 .80
1961 @item @emph{Prototype}: @tab @code{acc_device_t acc_get_device_type(void);}
1962 @end multitable
1964 @item @emph{Fortran}:
1965 @multitable @columnfractions .20 .80
1966 @item @emph{Interface}: @tab @code{function acc_get_device_type(void)}
1967 @item                  @tab @code{integer(kind=acc_device_kind) acc_get_device_type}
1968 @end multitable
1970 @item @emph{Reference}:
1971 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
1972 3.2.3.
1973 @end table
1977 @node acc_set_device_num
1978 @section @code{acc_set_device_num} -- Set device number to use.
1979 @table @asis
1980 @item @emph{Description}
1981 This function will indicate to the runtime which device number,
1982 specified by @var{num}, associated with the specifed device
1983 type @var{devicetype}.
1985 @item @emph{C/C++}:
1986 @multitable @columnfractions .20 .80
1987 @item @emph{Prototype}: @tab @code{acc_set_device_num(int num, acc_device_t devicetype);}
1988 @end multitable
1990 @item @emph{Fortran}:
1991 @multitable @columnfractions .20 .80
1992 @item @emph{Interface}: @tab @code{subroutine acc_set_device_num(devicenum, devicetype)}
1993 @item                   @tab @code{integer devicenum}
1994 @item                   @tab @code{integer(kind=acc_device_kind) devicetype}
1995 @end multitable
1997 @item @emph{Reference}:
1998 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
1999 3.2.4.
2000 @end table
2004 @node acc_get_device_num
2005 @section @code{acc_get_device_num} -- Get device number to be used.
2006 @table @asis
2007 @item @emph{Description}
2008 This function returns which device number associated with the specified device
2009 type @var{devicetype}, will be used when executing a parallel or kernels
2010 region.
2012 @item @emph{C/C++}:
2013 @multitable @columnfractions .20 .80
2014 @item @emph{Prototype}: @tab @code{int acc_get_device_num(acc_device_t devicetype);}
2015 @end multitable
2017 @item @emph{Fortran}:
2018 @multitable @columnfractions .20 .80
2019 @item @emph{Interface}: @tab @code{function acc_get_device_num(devicetype)}
2020 @item                   @tab @code{integer(kind=acc_device_kind) devicetype}
2021 @item                   @tab @code{integer acc_get_device_num}
2022 @end multitable
2024 @item @emph{Reference}:
2025 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
2026 3.2.5.
2027 @end table
2031 @node acc_async_test
2032 @section @code{acc_async_test} -- Test for completion of a specific asynchronous operation.
2033 @table @asis
2034 @item @emph{Description}
2035 This function tests for completion of the asynchrounous operation specified
2036 in @var{arg}. In C/C++, a non-zero value will be returned to indicate
2037 the specified asynchronous operation has completed. While Fortran will return
2038 a @code{true}. If the asynchrounous operation has not completed, C/C++ returns
2039 a zero and Fortran returns a @code{false}.
2041 @item @emph{C/C++}:
2042 @multitable @columnfractions .20 .80
2043 @item @emph{Prototype}: @tab @code{int acc_async_test(int arg);}
2044 @end multitable
2046 @item @emph{Fortran}:
2047 @multitable @columnfractions .20 .80
2048 @item @emph{Interface}: @tab @code{function acc_async_test(arg)}
2049 @item                   @tab @code{integer(kind=acc_handle_kind) arg}
2050 @item                   @tab @code{logical acc_async_test}
2051 @end multitable
2053 @item @emph{Reference}:
2054 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
2055 3.2.6.
2056 @end table
2060 @node acc_async_test_all
2061 @section @code{acc_async_test_all} -- Tests for completion of all asynchronous operations.
2062 @table @asis
2063 @item @emph{Description}
2064 This function tests for completion of all asynchrounous operations.
2065 In C/C++, a non-zero value will be returned to indicate all asynchronous
2066 operations have completed. While Fortran will return a @code{true}. If
2067 any asynchronous operation has not completed, C/C++ returns a zero and
2068 Fortran returns a @code{false}.
2070 @item @emph{C/C++}:
2071 @multitable @columnfractions .20 .80
2072 @item @emph{Prototype}: @tab @code{int acc_async_test_all(void);}
2073 @end multitable
2075 @item @emph{Fortran}:
2076 @multitable @columnfractions .20 .80
2077 @item @emph{Interface}: @tab @code{function acc_async_test()}
2078 @item                   @tab @code{logical acc_get_device_num}
2079 @end multitable
2081 @item @emph{Reference}:
2082 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
2083 3.2.7.
2084 @end table
2088 @node acc_wait
2089 @section @code{acc_wait} -- Wait for completion of a specific asynchronous operation.
2090 @table @asis
2091 @item @emph{Description}
2092 This function waits for completion of the asynchronous operation
2093 specified in @var{arg}.
2095 @item @emph{C/C++}:
2096 @multitable @columnfractions .20 .80
2097 @item @emph{Prototype}: @tab @code{acc_wait(arg);}
2098 @end multitable
2100 @item @emph{Fortran}:
2101 @multitable @columnfractions .20 .80
2102 @item @emph{Interface}: @tab @code{subroutine acc_wait(arg)}
2103 @item                   @tab @code{integer(acc_handle_kind) arg}
2104 @end multitable
2106 @item @emph{Reference}:
2107 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
2108 3.2.8.
2109 @end table
2113 @node acc_wait_all
2114 @section @code{acc_wait_all} -- Waits for completion of all asynchronous operations.
2115 @table @asis
2116 @item @emph{Description}
2117 This function waits for the completion of all asynchronous operations.
2119 @item @emph{C/C++}:
2120 @multitable @columnfractions .20 .80
2121 @item @emph{Prototype}: @tab @code{acc_wait_all(void);}
2122 @end multitable
2124 @item @emph{Fortran}:
2125 @multitable @columnfractions .20 .80
2126 @item @emph{Interface}: @tab @code{subroutine acc_wait_async()}
2127 @end multitable
2129 @item @emph{Reference}:
2130 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
2131 3.2.10.
2132 @end table
2136 @node acc_wait_all_async
2137 @section @code{acc_wait_all_async} -- Wait for completion of all asynchronous operations.
2138 @table @asis
2139 @item @emph{Description}
2140 This function enqueues a wait operation on the queue @var{async} for any
2141 and all asynchronous operations that have been previously enqueued on
2142 any queue.
2144 @item @emph{C/C++}:
2145 @multitable @columnfractions .20 .80
2146 @item @emph{Prototype}: @tab @code{acc_wait_all_async(int async);}
2147 @end multitable
2149 @item @emph{Fortran}:
2150 @multitable @columnfractions .20 .80
2151 @item @emph{Interface}: @tab @code{subroutine acc_wait_all_async(async)}
2152 @item                   @tab @code{integer(acc_handle_kind) async}
2153 @end multitable
2155 @item @emph{Reference}:
2156 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
2157 3.2.11.
2158 @end table
2162 @node acc_wait_async
2163 @section @code{acc_wait_async} -- Wait for completion of asynchronous operations.
2164 @table @asis
2165 @item @emph{Description}
2166 This function enqueues a wait operation on queue @var{async} for any and all
2167 asynchronous operations enqueued on queue @var{arg}.
2169 @item @emph{C/C++}:
2170 @multitable @columnfractions .20 .80
2171 @item @emph{Prototype}: @tab @code{acc_wait_async(int arg, int async);}
2172 @end multitable
2174 @item @emph{Fortran}:
2175 @multitable @columnfractions .20 .80
2176 @item @emph{Interface}: @tab @code{subroutine acc_wait_async(arg, async)}
2177 @item                   @tab @code{integer(acc_handle_kind) arg, async}
2178 @end multitable
2180 @item @emph{Reference}:
2181 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
2182 3.2.9.
2183 @end table
2187 @node acc_init
2188 @section @code{acc_init} -- Initialize runtime for a specific device type.
2189 @table @asis
2190 @item @emph{Description}
2191 This function initializes the runtime for the device type specified in
2192 @var{devicetype}.
2194 @item @emph{C/C++}:
2195 @multitable @columnfractions .20 .80
2196 @item @emph{Prototype}: @tab @code{acc_init(acc_device_t devicetype);}
2197 @end multitable
2199 @item @emph{Fortran}:
2200 @multitable @columnfractions .20 .80
2201 @item @emph{Interface}: @tab @code{subroutine acc_init(devicetype)}
2202 @item                   @tab @code{integer(acc_device_kind) devicetype}
2203 @end multitable
2205 @item @emph{Reference}:
2206 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
2207 3.2.12.
2208 @end table
2212 @node acc_shutdown
2213 @section @code{acc_shutdown} -- Shuts down the runtime for a specific device type.
2214 @table @asis
2215 @item @emph{Description}
2216 This function shuts down the runtime for the device type specified in
2217 @var{devicetype}.
2219 @item @emph{C/C++}:
2220 @multitable @columnfractions .20 .80
2221 @item @emph{Prototype}: @tab @code{acc_shutdown(acc_device_t devicetype);}
2222 @end multitable
2224 @item @emph{Fortran}:
2225 @multitable @columnfractions .20 .80
2226 @item @emph{Interface}: @tab @code{subroutine acc_shutdown(devicetype)}
2227 @item                   @tab @code{integer(acc_device_kind) devicetype}
2228 @end multitable
2230 @item @emph{Reference}:
2231 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
2232 3.2.13.
2233 @end table
2237 @node acc_on_device
2238 @section @code{acc_on_device} -- Whether executing on a particular device
2239 @table @asis
2240 @item @emph{Description}:
2241 This function returns whether the program is executing on a particular
2242 device specified in @var{devicetype}. In C/C++ a non-zero value is
2243 returned to indicate the device is execiting on the specified device type.
2244 In Fortran, @code{true} will be returned. If the program is not executing
2245 on the specified device type C/C++ will return a zero, while Fortran will
2246 return @code{false}.
2248 @item @emph{C/C++}:
2249 @multitable @columnfractions .20 .80
2250 @item @emph{Prototype}: @tab @code{acc_on_device(acc_device_t devicetype);}
2251 @end multitable
2253 @item @emph{Fortran}:
2254 @multitable @columnfractions .20 .80
2255 @item @emph{Interface}: @tab @code{function acc_on_device(devicetype)}
2256 @item                   @tab @code{integer(acc_device_kind) devicetype}
2257 @item                   @tab @code{logical acc_on_device}
2258 @end multitable
2261 @item @emph{Reference}:
2262 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
2263 3.2.14.
2264 @end table
2268 @node acc_malloc
2269 @section @code{acc_malloc} -- Allocate device memory.
2270 @table @asis
2271 @item @emph{Description}
2272 This function allocates @var{len} bytes of device memory. It returns
2273 the device address of the allocated memory.
2275 @item @emph{C/C++}:
2276 @multitable @columnfractions .20 .80
2277 @item @emph{Prototype}: @tab @code{d_void* acc_malloc(size_t len);}
2278 @end multitable
2280 @item @emph{Reference}:
2281 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
2282 3.2.15.
2283 @end table
2287 @node acc_free
2288 @section @code{acc_free} -- Free device memory.
2289 @table @asis
2290 @item @emph{Description}
2291 Free previously allocated device memory at the device address @code{a}.
2293 @item @emph{C/C++}:
2294 @multitable @columnfractions .20 .80
2295 @item @emph{Prototype}: @tab @code{acc_free(d_void *a);}
2296 @end multitable
2298 @item @emph{Reference}:
2299 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
2300 3.2.16.
2301 @end table
2305 @node acc_copyin
2306 @section @code{acc_copyin} -- Allocate device memory and copy host memory to it.
2307 @table @asis
2308 @item @emph{Description}
2309 In C/C++, this function allocates @var{len} bytes of device memory
2310 and maps it to the specified host address in @var{a}. The device
2311 address of the newly allocated device memory is returned.
2313 In Fortran, two (2) forms are supported. In the first form, @var{a} specifies
2314 a contiguous array section. The second form @var{a} specifies a
2315 variable or array element and @var{len} specifies the length in bytes.
2317 @item @emph{C/C++}:
2318 @multitable @columnfractions .20 .80
2319 @item @emph{Prototype}: @tab @code{void *acc_copyin(h_void *a, size_t len);}
2320 @end multitable
2322 @item @emph{Fortran}:
2323 @multitable @columnfractions .20 .80
2324 @item @emph{Interface}: @tab @code{subroutine acc_copyin(a)}
2325 @item                   @tab @code{type, dimension(:[,:]...) :: a}
2326 @item @emph{Interface}: @tab @code{subroutine acc_copyin(a, len)}
2327 @item                   @tab @code{type, dimension(:[,:]...) :: a}
2328 @item                   @tab @code{integer len}
2329 @end multitable
2331 @item @emph{Reference}:
2332 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
2333 3.2.17.
2334 @end table
2338 @node acc_present_or_copyin
2339 @section @code{acc_present_or_copyin} -- If the data is not present on the device, allocate device memory and copy from host memory.
2340 @table @asis
2341 @item @emph{Description}
2342 This function tests if the host data specifed by @var{a} and of length
2343 @var{len} is present or not. If it is not present, then device memory
2344 will be allocated and the host memory copied. The device address of
2345 the newly allocated device memory is returned.
2347 In Fortran, two (2) forms are supported. In the first form, @var{a} specifies
2348 a contiguous array section. The second form @var{a} specifies a variable or
2349 array element and @var{len} specifies the length in bytes.
2351 @item @emph{C/C++}:
2352 @multitable @columnfractions .20 .80
2353 @item @emph{Prototype}: @tab @code{void *acc_present_or_copyin(h_void *a, size_t len);}
2354 @item @emph{Prototype}: @tab @code{void *acc_pcopyin(h_void *a, size_t len);}
2355 @end multitable
2357 @item @emph{Fortran}:
2358 @multitable @columnfractions .20 .80
2359 @item @emph{Interface}: @tab @code{subroutine acc_present_or_copyin(a)}
2360 @item                   @tab @code{type, dimension(:[,:]...) :: a}
2361 @item @emph{Interface}: @tab @code{subroutine acc_present_or_copyin(a, len)}
2362 @item                   @tab @code{type, dimension(:[,:]...) :: a}
2363 @item                   @tab @code{integer len}
2364 @item @emph{Interface}: @tab @code{subroutine acc_pcopyin(a)}
2365 @item                   @tab @code{type, dimension(:[,:]...) :: a}
2366 @item @emph{Interface}: @tab @code{subroutine acc_pcopyin(a, len)}
2367 @item                   @tab @code{type, dimension(:[,:]...) :: a}
2368 @item                   @tab @code{integer len}
2369 @end multitable
2371 @item @emph{Reference}:
2372 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
2373 3.2.18.
2374 @end table
2378 @node acc_create
2379 @section @code{acc_create} -- Allocate device memory and map it to host memory.
2380 @table @asis
2381 @item @emph{Description}
2382 This function allocates device memory and maps it to host memory specified
2383 by the host address @var{a} with a length of @var{len} bytes. In C/C++,
2384 the function returns the device address of the allocated device memory.
2386 In Fortran, two (2) forms are supported. In the first form, @var{a} specifies
2387 a contiguous array section. The second form @var{a} specifies a variable or
2388 array element and @var{len} specifies the length in bytes.
2390 @item @emph{C/C++}:
2391 @multitable @columnfractions .20 .80
2392 @item @emph{Prototype}: @tab @code{void *acc_create(h_void *a, size_t len);}
2393 @end multitable
2395 @item @emph{Fortran}:
2396 @multitable @columnfractions .20 .80
2397 @item @emph{Interface}: @tab @code{subroutine acc_create(a)}
2398 @item                   @tab @code{type, dimension(:[,:]...) :: a}
2399 @item @emph{Interface}: @tab @code{subroutine acc_create(a, len)}
2400 @item                   @tab @code{type, dimension(:[,:]...) :: a}
2401 @item                   @tab @code{integer len}
2402 @end multitable
2404 @item @emph{Reference}:
2405 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
2406 3.2.19.
2407 @end table
2411 @node acc_present_or_create
2412 @section @code{acc_present_or_create} -- If the data is not present on the device, allocate device memory and map it to host memory.
2413 @table @asis
2414 @item @emph{Description}
2415 This function tests if the host data specifed by @var{a} and of length
2416 @var{len} is present or not. If it is not present, then device memory
2417 will be allocated and mapped to host memory. In C/C++, the device address
2418 of the newly allocated device memory is returned.
2420 In Fortran, two (2) forms are supported. In the first form, @var{a} specifies
2421 a contiguous array section. The second form @var{a} specifies a variable or
2422 array element and @var{len} specifies the length in bytes.
2425 @item @emph{C/C++}:
2426 @multitable @columnfractions .20 .80
2427 @item @emph{Prototype}: @tab @code{void *acc_present_or_create(h_void *a, size_t len)}
2428 @item @emph{Prototype}: @tab @code{void *acc_pcreate(h_void *a, size_t len)}
2429 @end multitable
2431 @item @emph{Fortran}:
2432 @multitable @columnfractions .20 .80
2433 @item @emph{Interface}: @tab @code{subroutine acc_present_or_create(a)}
2434 @item                   @tab @code{type, dimension(:[,:]...) :: a}
2435 @item @emph{Interface}: @tab @code{subroutine acc_present_or_create(a, len)}
2436 @item                   @tab @code{type, dimension(:[,:]...) :: a}
2437 @item                   @tab @code{integer len}
2438 @item @emph{Interface}: @tab @code{subroutine acc_pcreate(a)}
2439 @item                   @tab @code{type, dimension(:[,:]...) :: a}
2440 @item @emph{Interface}: @tab @code{subroutine acc_pcreate(a, len)}
2441 @item                   @tab @code{type, dimension(:[,:]...) :: a}
2442 @item                   @tab @code{integer len}
2443 @end multitable
2445 @item @emph{Reference}:
2446 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
2447 3.2.20.
2448 @end table
2452 @node acc_copyout
2453 @section @code{acc_copyout} -- Copy device memory to host memory.
2454 @table @asis
2455 @item @emph{Description}
2456 This function copies mapped device memory to host memory which is specified
2457 by host address @var{a} for a length @var{len} bytes in C/C++.
2459 In Fortran, two (2) forms are supported. In the first form, @var{a} specifies
2460 a contiguous array section. The second form @var{a} specifies a variable or
2461 array element and @var{len} specifies the length in bytes.
2463 @item @emph{C/C++}:
2464 @multitable @columnfractions .20 .80
2465 @item @emph{Prototype}: @tab @code{acc_copyout(h_void *a, size_t len);}
2466 @end multitable
2468 @item @emph{Fortran}:
2469 @multitable @columnfractions .20 .80
2470 @item @emph{Interface}: @tab @code{subroutine acc_copyout(a)}
2471 @item                   @tab @code{type, dimension(:[,:]...) :: a}
2472 @item @emph{Interface}: @tab @code{subroutine acc_copyout(a, len)}
2473 @item                   @tab @code{type, dimension(:[,:]...) :: a}
2474 @item                   @tab @code{integer len}
2475 @end multitable
2477 @item @emph{Reference}:
2478 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
2479 3.2.21.
2480 @end table
2484 @node acc_delete
2485 @section @code{acc_delete} -- Free device memory.
2486 @table @asis
2487 @item @emph{Description}
2488 This function frees previously allocated device memory specified by
2489 the device address @var{a} and the length of @var{len} bytes.
2491 In Fortran, two (2) forms are supported. In the first form, @var{a} specifies
2492 a contiguous array section. The second form @var{a} specifies a variable or
2493 array element and @var{len} specifies the length in bytes.
2495 @item @emph{C/C++}:
2496 @multitable @columnfractions .20 .80
2497 @item @emph{Prototype}: @tab @code{acc_delete(h_void *a, size_t len);}
2498 @end multitable
2500 @item @emph{Fortran}:
2501 @multitable @columnfractions .20 .80
2502 @item @emph{Interface}: @tab @code{subroutine acc_delete(a)}
2503 @item                   @tab @code{type, dimension(:[,:]...) :: a}
2504 @item @emph{Interface}: @tab @code{subroutine acc_delete(a, len)}
2505 @item                   @tab @code{type, dimension(:[,:]...) :: a}
2506 @item                   @tab @code{integer len}
2507 @end multitable
2509 @item @emph{Reference}:
2510 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
2511 3.2.22.
2512 @end table
2516 @node acc_update_device
2517 @section @code{acc_update_device} -- Update device memory from mapped host memory.
2518 @table @asis
2519 @item @emph{Description}
2520 This function updates the device copy from the previously mapped host memory.
2521 The host memory is specified with the host address @var{a} and a length of
2522 @var{len} bytes.
2524 In Fortran, two (2) forms are supported. In the first form, @var{a} specifies
2525 a contiguous array section. The second form @var{a} specifies a variable or
2526 array element and @var{len} specifies the length in bytes.
2528 @item @emph{C/C++}:
2529 @multitable @columnfractions .20 .80
2530 @item @emph{Prototype}: @tab @code{acc_update_device(h_void *a, size_t len);}
2531 @end multitable
2533 @item @emph{Fortran}:
2534 @multitable @columnfractions .20 .80
2535 @item @emph{Interface}: @tab @code{subroutine acc_update_device(a)}
2536 @item                   @tab @code{type, dimension(:[,:]...) :: a}
2537 @item @emph{Interface}: @tab @code{subroutine acc_update_device(a, len)}
2538 @item                   @tab @code{type, dimension(:[,:]...) :: a}
2539 @item                   @tab @code{integer len}
2540 @end multitable
2542 @item @emph{Reference}:
2543 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
2544 3.2.23.
2545 @end table
2549 @node acc_update_self
2550 @section @code{acc_update_self} -- Update host memory from mapped device memory.
2551 @table @asis
2552 @item @emph{Description}
2553 This function updates the host copy from the previously mapped device memory.
2554 The host memory is specified with the host address @var{a} and a length of
2555 @var{len} bytes.
2557 In Fortran, two (2) forms are supported. In the first form, @var{a} specifies
2558 a contiguous array section. The second form @var{a} specifies a variable or
2559 array element and @var{len} specifies the length in bytes.
2561 @item @emph{C/C++}:
2562 @multitable @columnfractions .20 .80
2563 @item @emph{Prototype}: @tab @code{acc_update_self(h_void *a, size_t len);}
2564 @end multitable
2566 @item @emph{Fortran}:
2567 @multitable @columnfractions .20 .80
2568 @item @emph{Interface}: @tab @code{subroutine acc_update_self(a)}
2569 @item                   @tab @code{type, dimension(:[,:]...) :: a}
2570 @item @emph{Interface}: @tab @code{subroutine acc_update_self(a, len)}
2571 @item                   @tab @code{type, dimension(:[,:]...) :: a}
2572 @item                   @tab @code{integer len}
2573 @end multitable
2575 @item @emph{Reference}:
2576 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
2577 3.2.24.
2578 @end table
2582 @node acc_map_data
2583 @section @code{acc_map_data} -- Map previously allocated device memory to host memory.
2584 @table @asis
2585 @item @emph{Description}
2586 This function maps previously allocated device and host memory. The device
2587 memory is specified with the device address @var{d}. The host memory is
2588 specified with the host address @var{h} and a length of @var{len}.
2590 @item @emph{C/C++}:
2591 @multitable @columnfractions .20 .80
2592 @item @emph{Prototype}: @tab @code{acc_map_data(h_void *h, d_void *d, size_t len);}
2593 @end multitable
2595 @item @emph{Reference}:
2596 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
2597 3.2.25.
2598 @end table
2602 @node acc_unmap_data
2603 @section @code{acc_unmap_data} -- Unmap device memory from host memory.
2604 @table @asis
2605 @item @emph{Description}
2606 This function unmaps previously mapped device and host memory. The latter
2607 specified by @var{h}.
2609 @item @emph{C/C++}:
2610 @multitable @columnfractions .20 .80
2611 @item @emph{Prototype}: @tab @code{acc_unmap_data(h_void *h);}
2612 @end multitable
2614 @item @emph{Reference}:
2615 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
2616 3.2.26.
2617 @end table
2621 @node acc_deviceptr
2622 @section @code{acc_deviceptr} -- Get device pointer associated with specific host address.
2623 @table @asis
2624 @item @emph{Description}
2625 This function returns the device address that has been mapped to the
2626 host address specified by @var{h}.
2628 @item @emph{C/C++}:
2629 @multitable @columnfractions .20 .80
2630 @item @emph{Prototype}: @tab @code{void *acc_deviceptr(h_void *h);}
2631 @end multitable
2633 @item @emph{Reference}:
2634 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
2635 3.2.27.
2636 @end table
2640 @node acc_hostptr
2641 @section @code{acc_hostptr} -- Get host pointer associated with specific device address.
2642 @table @asis
2643 @item @emph{Description}
2644 This function returns the host address that has been mapped to the
2645 device address specified by @var{d}.
2647 @item @emph{C/C++}:
2648 @multitable @columnfractions .20 .80
2649 @item @emph{Prototype}: @tab @code{void *acc_hostptr(d_void *d);}
2650 @end multitable
2652 @item @emph{Reference}:
2653 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
2654 3.2.28.
2655 @end table
2659 @node acc_is_present
2660 @section @code{acc_is_present} -- Indicate whether host variable / array is present on device.
2661 @table @asis
2662 @item @emph{Description}
2663 This function indicates whether the specified host address in @var{a} and a
2664 length of @var{len} bytes is present on the device. In C/C++, a non-zero
2665 value is returned to indicate the presence of the mapped memory on the
2666 device. A zero is returned to indicate the memory is not mapped on the
2667 device.
2669 In Fortran, two (2) forms are supported. In the first form, @var{a} specifies
2670 a contiguous array section. The second form @var{a} specifies a variable or
2671 array element and @var{len} specifies the length in bytes. If the host
2672 memory is mapped to device memory, then a @code{true} is returned. Otherwise,
2673 a @code{false} is return to indicate the mapped memory is not present.
2675 @item @emph{C/C++}:
2676 @multitable @columnfractions .20 .80
2677 @item @emph{Prototype}: @tab @code{int acc_is_present(h_void *a, size_t len);}
2678 @end multitable
2680 @item @emph{Fortran}:
2681 @multitable @columnfractions .20 .80
2682 @item @emph{Interface}: @tab @code{function acc_is_present(a)}
2683 @item                   @tab @code{type, dimension(:[,:]...) :: a}
2684 @item                   @tab @code{logical acc_is_present}
2685 @item @emph{Interface}: @tab @code{function acc_is_present(a, len)}
2686 @item                   @tab @code{type, dimension(:[,:]...) :: a}
2687 @item                   @tab @code{integer len}
2688 @item                   @tab @code{logical acc_is_present}
2689 @end multitable
2691 @item @emph{Reference}:
2692 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
2693 3.2.29.
2694 @end table
2698 @node acc_memcpy_to_device
2699 @section @code{acc_memcpy_to_device} -- Copy host memory to device memory.
2700 @table @asis
2701 @item @emph{Description}
2702 This function copies host memory specified by host address of @var{src} to
2703 device memory specified by the device address @var{dest} for a length of
2704 @var{bytes} bytes.
2706 @item @emph{C/C++}:
2707 @multitable @columnfractions .20 .80
2708 @item @emph{Prototype}: @tab @code{acc_memcpy_to_device(d_void *dest, h_void *src, size_t bytes);}
2709 @end multitable
2711 @item @emph{Reference}:
2712 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
2713 3.2.30.
2714 @end table
2718 @node acc_memcpy_from_device
2719 @section @code{acc_memcpy_from_device} -- Copy device memory to host memory.
2720 @table @asis
2721 @item @emph{Description}
2722 This function copies host memory specified by host address of @var{src} from
2723 device memory specified by the device address @var{dest} for a length of
2724 @var{bytes} bytes.
2726 @item @emph{C/C++}:
2727 @multitable @columnfractions .20 .80
2728 @item @emph{Prototype}: @tab @code{acc_memcpy_from_device(d_void *dest, h_void *src, size_t bytes);}
2729 @end multitable
2731 @item @emph{Reference}:
2732 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
2733 3.2.31.
2734 @end table
2738 @node acc_get_current_cuda_device
2739 @section @code{acc_get_current_cuda_device} -- Get CUDA device handle.
2740 @table @asis
2741 @item @emph{Description}
2742 This function returns the CUDA device handle. This handle is the same
2743 as used by the CUDA Runtime or Driver API's.
2745 @item @emph{C/C++}:
2746 @multitable @columnfractions .20 .80
2747 @item @emph{Prototype}: @tab @code{void *acc_get_current_cuda_device(void);}
2748 @end multitable
2750 @item @emph{Reference}:
2751 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
2752 A.2.1.1.
2753 @end table
2757 @node acc_get_current_cuda_context
2758 @section @code{acc_get_current_cuda_context} -- Get CUDA context handle.
2759 @table @asis
2760 @item @emph{Description}
2761 This function returns the CUDA context handle. This handle is the same
2762 as used by the CUDA Runtime or Driver API's.
2764 @item @emph{C/C++}:
2765 @multitable @columnfractions .20 .80
2766 @item @emph{Prototype}: @tab @code{acc_get_current_cuda_context(void);}
2767 @end multitable
2769 @item @emph{Reference}:
2770 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
2771 A.2.1.2.
2772 @end table
2776 @node acc_get_cuda_stream
2777 @section @code{acc_get_cuda_stream} -- Get CUDA stream handle.
2778 @table @asis
2779 @item @emph{Description}
2780 This function returns the CUDA stream handle. This handle is the same
2781 as used by the CUDA Runtime or Driver API's.
2783 @item @emph{C/C++}:
2784 @multitable @columnfractions .20 .80
2785 @item @emph{Prototype}: @tab @code{acc_get_cuda_stream(void);}
2786 @end multitable
2788 @item @emph{Reference}:
2789 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
2790 A.2.1.3.
2791 @end table
2795 @node acc_set_cuda_stream
2796 @section @code{acc_set_cuda_stream} -- Set CUDA stream handle.
2797 @table @asis
2798 @item @emph{Description}
2799 This function associates the stream handle specified by @var{stream} with
2800 the asynchronous value specified by @var{async}.
2802 @item @emph{C/C++}:
2803 @multitable @columnfractions .20 .80
2804 @item @emph{Prototype}: @tab @code{acc_set_cuda_stream(int async void *stream);}
2805 @end multitable
2807 @item @emph{Reference}:
2808 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
2809 A.2.1.4.
2810 @end table
2814 @c ---------------------------------------------------------------------
2815 @c OpenACC Environment Variables
2816 @c ---------------------------------------------------------------------
2818 @node OpenACC Environment Variables
2819 @chapter OpenACC Environment Variables
2821 The variables @env{ACC_DEVICE_TYPE} and @env{ACC_DEVICE_NUM}
2822 are defined by section 4 of the OpenACC specification in version 2.0.
2823 The variable @env{GCC_ACC_NOTIFY} is used for diagnostic purposes.
2825 @menu
2826 * ACC_DEVICE_TYPE::
2827 * ACC_DEVICE_NUM::
2828 * GCC_ACC_NOTIFY::
2829 @end menu
2833 @node ACC_DEVICE_TYPE
2834 @section @code{ACC_DEVICE_TYPE}
2835 @table @asis
2836 @item @emph{Reference}:
2837 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
2838 4.1.
2839 @end table
2843 @node ACC_DEVICE_NUM
2844 @section @code{ACC_DEVICE_NUM}
2845 @table @asis
2846 @item @emph{Reference}:
2847 @uref{http://www.openacc.org/, OpenACC specification v2.0}, section
2848 4.2.
2849 @end table
2853 @node GCC_ACC_NOTIFY
2854 @section @code{GCC_ACC_NOTIFY}
2855 @table @asis
2856 @item @emph{Description}:
2857 Print debug information pertaining to the accelerator.
2858 @end table
2862 @c ---------------------------------------------------------------------
2863 @c CUDA Streams Usage
2864 @c ---------------------------------------------------------------------
2866 @node CUDA Streams Usage
2867 @chapter CUDA Streams Usage
2869 This applies to the @code{nvptx} plugin only.
2871 The library provides elements that perform asynchronous movement of
2872 data and asynchronous operation of computing constructs.  This
2873 asynchronous functionality is implemented by making use of CUDA
2874 streams@footnote{See "Stream Management" in "CUDA Driver API",
2875 TRM-06703-001, Version 5.5, for additional information}.
2877 The primary means by that the asychronous functionality is accessed
2878 is through the use of those OpenACC directives which make use of the
2879 @code{async} and @code{wait} clauses.  When the @code{async} clause is
2880 first used with a directive, it creates a CUDA stream.  If an
2881 @code{async-argument} is used with the @code{async} clause, then the
2882 stream is associated with the specified @code{async-argument}.
2884 Following the creation of an association between a CUDA stream and the
2885 @code{async-argument} of an @code{async} clause, both the @code{wait}
2886 clause and the @code{wait} directive can be used.  When either the
2887 clause or directive is used after stream creation, it creates a
2888 rendezvous point whereby execution waits until all operations
2889 associated with the @code{async-argument}, that is, stream, have
2890 completed.
2892 Normally, the management of the streams that are created as a result of
2893 using the @code{async} clause, is done without any intervention by the
2894 caller.  This implies the association between the @code{async-argument}
2895 and the CUDA stream will be maintained for the lifetime of the program.
2896 However, this association can be changed through the use of the library
2897 function @code{acc_set_cuda_stream}.  When the function
2898 @code{acc_set_cuda_stream} is called, the CUDA stream that was
2899 originally associated with the @code{async} clause will be destroyed.
2900 Caution should be taken when changing the association as subsequent
2901 references to the @code{async-argument} refer to a different
2902 CUDA stream.
2906 @c ---------------------------------------------------------------------
2907 @c OpenACC Library Interoperability
2908 @c ---------------------------------------------------------------------
2910 @node OpenACC Library Interoperability
2911 @chapter OpenACC Library Interoperability
2913 @section Introduction
2915 The OpenACC library uses the CUDA Driver API, and may interact with
2916 programs that use the Runtime library directly, or another library
2917 based on the Runtime library, e.g., CUBLAS@footnote{See section 2.26,
2918 "Interactions with the CUDA Driver API" in
2919 "CUDA Runtime API", Version 5.5, and section 2.27, "VDPAU
2920 Interoperability", in "CUDA Driver API", TRM-06703-001, Version 5.5,
2921 for additional information on library interoperability.}.
2922 This chapter describes the use cases and what changes are
2923 required in order to use both the OpenACC library and the CUBLAS and Runtime
2924 libraries within a program.
2926 @section First invocation: NVIDIA CUBLAS library API
2928 In this first use case (see below), a function in the CUBLAS library is called
2929 prior to any of the functions in the OpenACC library. More specifically, the
2930 function @code{cublasCreate()}.
2932 When invoked, the function initializes the library and allocates the
2933 hardware resources on the host and the device on behalf of the caller. Once
2934 the initialization and allocation has completed, a handle is returned to the
2935 caller. The OpenACC library also requires initialization and allocation of
2936 hardware resources. Since the CUBLAS library has already allocated the
2937 hardware resources for the device, all that is left to do is to initialize
2938 the OpenACC library and acquire the hardware resources on the host.
2940 Prior to calling the OpenACC function that initializes the library and
2941 allocate the host hardware resources, you need to acquire the device number
2942 that was allocated during the call to @code{cublasCreate()}. The invoking of the
2943 runtime library function @code{cudaGetDevice()} accomplishes this. Once
2944 acquired, the device number is passed along with the device type as
2945 parameters to the OpenACC library function @code{acc_set_device_num()}.
2947 Once the call to @code{acc_set_device_num()} has completed, the OpenACC
2948 library uses the  context that was created during the call to
2949 @code{cublasCreate()}. In other words, both libraries will be sharing the
2950 same context.
2952 @smallexample
2953     /* Create the handle */
2954     s = cublasCreate(&h);
2955     if (s != CUBLAS_STATUS_SUCCESS)
2956     @{
2957         fprintf(stderr, "cublasCreate failed %d\n", s);
2958         exit(EXIT_FAILURE);
2959     @}
2961     /* Get the device number */
2962     e = cudaGetDevice(&dev);
2963     if (e != cudaSuccess)
2964     @{
2965         fprintf(stderr, "cudaGetDevice failed %d\n", e);
2966         exit(EXIT_FAILURE);
2967     @}
2969     /* Initialize OpenACC library and use device 'dev' */
2970     acc_set_device_num(dev, acc_device_nvidia);
2972 @end smallexample
2973 @center Use Case 1 
2975 @section First invocation: OpenACC library API
2977 In this second use case (see below), a function in the OpenACC library is
2978 called prior to any of the functions in the CUBLAS library. More specificially,
2979 the function @code{acc_set_device_num()}.
2981 In the use case presented here, the function @code{acc_set_device_num()}
2982 is used to both initialize the OpenACC library and allocate the hardware
2983 resources on the host and the device. In the call to the function, the
2984 call parameters specify which device to use and what device
2985 type to use, i.e., @code{acc_device_nvidia}. It should be noted that this
2986 is but one method to initialize the OpenACC library and allocate the
2987 appropriate hardware resources. Other methods are available through the
2988 use of environment variables and these will be discussed in the next section.
2990 Once the call to @code{acc_set_device_num()} has completed, other OpenACC
2991 functions can be called as seen with multiple calls being made to
2992 @code{acc_copyin()}. In addition, calls can be made to functions in the
2993 CUBLAS library. In the use case a call to @code{cublasCreate()} is made
2994 subsequent to the calls to @code{acc_copyin()}.
2995 As seen in the previous use case, a call to @code{cublasCreate()}
2996 initializes the CUBLAS library and allocates the hardware resources on the
2997 host and the device.  However, since the device has already been allocated,
2998 @code{cublasCreate()} will only initialize the CUBLAS library and allocate
2999 the appropriate hardware resources on the host. The context that was created
3000 as part of the OpenACC initialization is shared with the CUBLAS library,
3001 similarly to the first use case.
3003 @smallexample
3004     dev = 0;
3006     acc_set_device_num(dev, acc_device_nvidia);
3008     /* Copy the first set to the device */
3009     d_X = acc_copyin(&h_X[0], N * sizeof (float));
3010     if (d_X == NULL)
3011     @{ 
3012         fprintf(stderr, "copyin error h_X\n");
3013         exit(EXIT_FAILURE);
3014     @}
3016     /* Copy the second set to the device */
3017     d_Y = acc_copyin(&h_Y1[0], N * sizeof (float));
3018     if (d_Y == NULL)
3019     @{ 
3020         fprintf(stderr, "copyin error h_Y1\n");
3021         exit(EXIT_FAILURE);
3022     @}
3024     /* Create the handle */
3025     s = cublasCreate(&h);
3026     if (s != CUBLAS_STATUS_SUCCESS)
3027     @{
3028         fprintf(stderr, "cublasCreate failed %d\n", s);
3029         exit(EXIT_FAILURE);
3030     @}
3032     /* Perform saxpy using CUBLAS library function */
3033     s = cublasSaxpy(h, N, &alpha, d_X, 1, d_Y, 1);
3034     if (s != CUBLAS_STATUS_SUCCESS)
3035     @{
3036         fprintf(stderr, "cublasSaxpy failed %d\n", s);
3037         exit(EXIT_FAILURE);
3038     @}
3040     /* Copy the results from the device */
3041     acc_memcpy_from_device(&h_Y1[0], d_Y, N * sizeof (float));
3043 @end smallexample
3044 @center Use Case 2
3046 @section OpenACC library and environment variables
3048 There are two environment variables associated with the OpenACC library
3049 that may be used to control the device type and device number:
3050 @env{ACC_DEVICE_TYPE} and @env{ACC_DEVICE_NUM}, respecively. These two
3051 environement variables can be used as an alternative to calling
3052 @code{acc_set_device_num()}. As seen in the second use case, the device
3053 type and device number were specified using @code{acc_set_device_num()}.
3054 If however, the aforementioned environment variables were set, then the
3055 call to @code{acc_set_device_num()} would not be required.
3058 The use of the environment variables is only relevant when an OpenACC function
3059 is called prior to a call to @code{cudaCreate()}. If @code{cudaCreate()}
3060 is called prior to a call to an OpenACC function, then you must call
3061 @code{acc_set_device_num()}@footnote{More complete information
3062 about @env{ACC_DEVICE_TYPE} and @env{ACC_DEVICE_NUM} can be found in
3063 sections 4.1 and 4.2 of the @uref{http://www.openacc.org/, OpenACC}
3064 Application Programming Interface”, Version 2.0.}
3068 @c ---------------------------------------------------------------------
3069 @c The libgomp ABI
3070 @c ---------------------------------------------------------------------
3072 @node The libgomp ABI
3073 @chapter The libgomp ABI
3075 The following sections present notes on the external ABI as 
3076 presented by libgomp.  Only maintainers should need them.
3078 @menu
3079 * Implementing MASTER construct::
3080 * Implementing CRITICAL construct::
3081 * Implementing ATOMIC construct::
3082 * Implementing FLUSH construct::
3083 * Implementing BARRIER construct::
3084 * Implementing THREADPRIVATE construct::
3085 * Implementing PRIVATE clause::
3086 * Implementing FIRSTPRIVATE LASTPRIVATE COPYIN and COPYPRIVATE clauses::
3087 * Implementing REDUCTION clause::
3088 * Implementing PARALLEL construct::
3089 * Implementing FOR construct::
3090 * Implementing ORDERED construct::
3091 * Implementing SECTIONS construct::
3092 * Implementing SINGLE construct::
3093 * Implementing OpenACC's PARALLEL construct::
3094 @end menu
3097 @node Implementing MASTER construct
3098 @section Implementing MASTER construct
3100 @smallexample
3101 if (omp_get_thread_num () == 0)
3102   block
3103 @end smallexample
3105 Alternately, we generate two copies of the parallel subfunction
3106 and only include this in the version run by the master thread.
3107 Surely this is not worthwhile though...
3111 @node Implementing CRITICAL construct
3112 @section Implementing CRITICAL construct
3114 Without a specified name,
3116 @smallexample
3117   void GOMP_critical_start (void);
3118   void GOMP_critical_end (void);
3119 @end smallexample
3121 so that we don't get COPY relocations from libgomp to the main
3122 application.
3124 With a specified name, use omp_set_lock and omp_unset_lock with
3125 name being transformed into a variable declared like
3127 @smallexample
3128   omp_lock_t gomp_critical_user_<name> __attribute__((common))
3129 @end smallexample
3131 Ideally the ABI would specify that all zero is a valid unlocked
3132 state, and so we wouldn't need to initialize this at
3133 startup.
3137 @node Implementing ATOMIC construct
3138 @section Implementing ATOMIC construct
3140 The target should implement the @code{__sync} builtins.
3142 Failing that we could add
3144 @smallexample
3145   void GOMP_atomic_enter (void)
3146   void GOMP_atomic_exit (void)
3147 @end smallexample
3149 which reuses the regular lock code, but with yet another lock
3150 object private to the library.
3154 @node Implementing FLUSH construct
3155 @section Implementing FLUSH construct
3157 Expands to the @code{__sync_synchronize} builtin.
3161 @node Implementing BARRIER construct
3162 @section Implementing BARRIER construct
3164 @smallexample
3165   void GOMP_barrier (void)
3166 @end smallexample
3169 @node Implementing THREADPRIVATE construct
3170 @section Implementing THREADPRIVATE construct
3172 In _most_ cases we can map this directly to @code{__thread}.  Except
3173 that OMP allows constructors for C++ objects.  We can either
3174 refuse to support this (how often is it used?) or we can 
3175 implement something akin to .ctors.
3177 Even more ideally, this ctor feature is handled by extensions
3178 to the main pthreads library.  Failing that, we can have a set
3179 of entry points to register ctor functions to be called.
3183 @node Implementing PRIVATE clause
3184 @section Implementing PRIVATE clause
3186 In association with a PARALLEL, or within the lexical extent
3187 of a PARALLEL block, the variable becomes a local variable in
3188 the parallel subfunction.
3190 In association with FOR or SECTIONS blocks, create a new
3191 automatic variable within the current function.  This preserves
3192 the semantic of new variable creation.
3196 @node Implementing FIRSTPRIVATE LASTPRIVATE COPYIN and COPYPRIVATE clauses
3197 @section Implementing FIRSTPRIVATE LASTPRIVATE COPYIN and COPYPRIVATE clauses
3199 This seems simple enough for PARALLEL blocks.  Create a private 
3200 struct for communicating between the parent and subfunction.
3201 In the parent, copy in values for scalar and "small" structs;
3202 copy in addresses for others TREE_ADDRESSABLE types.  In the 
3203 subfunction, copy the value into the local variable.
3205 It is not clear what to do with bare FOR or SECTION blocks.
3206 The only thing I can figure is that we do something like:
3208 @smallexample
3209 #pragma omp for firstprivate(x) lastprivate(y)
3210 for (int i = 0; i < n; ++i)
3211   body;
3212 @end smallexample
3214 which becomes
3216 @smallexample
3218   int x = x, y;
3220   // for stuff
3222   if (i == n)
3223     y = y;
3225 @end smallexample
3227 where the "x=x" and "y=y" assignments actually have different
3228 uids for the two variables, i.e. not something you could write
3229 directly in C.  Presumably this only makes sense if the "outer"
3230 x and y are global variables.
3232 COPYPRIVATE would work the same way, except the structure 
3233 broadcast would have to happen via SINGLE machinery instead.
3237 @node Implementing REDUCTION clause
3238 @section Implementing REDUCTION clause
3240 The private struct mentioned in the previous section should have 
3241 a pointer to an array of the type of the variable, indexed by the 
3242 thread's @var{team_id}.  The thread stores its final value into the 
3243 array, and after the barrier, the master thread iterates over the
3244 array to collect the values.
3247 @node Implementing PARALLEL construct
3248 @section Implementing PARALLEL construct
3250 @smallexample
3251   #pragma omp parallel
3252   @{
3253     body;
3254   @}
3255 @end smallexample
3257 becomes
3259 @smallexample
3260   void subfunction (void *data)
3261   @{
3262     use data;
3263     body;
3264   @}
3266   setup data;
3267   GOMP_parallel_start (subfunction, &data, num_threads);
3268   subfunction (&data);
3269   GOMP_parallel_end ();
3270 @end smallexample
3272 @smallexample
3273   void GOMP_parallel_start (void (*fn)(void *), void *data, unsigned num_threads)
3274 @end smallexample
3276 The @var{FN} argument is the subfunction to be run in parallel.
3278 The @var{DATA} argument is a pointer to a structure used to 
3279 communicate data in and out of the subfunction, as discussed
3280 above with respect to FIRSTPRIVATE et al.
3282 The @var{NUM_THREADS} argument is 1 if an IF clause is present
3283 and false, or the value of the NUM_THREADS clause, if
3284 present, or 0.
3286 The function needs to create the appropriate number of
3287 threads and/or launch them from the dock.  It needs to
3288 create the team structure and assign team ids.
3290 @smallexample
3291   void GOMP_parallel_end (void)
3292 @end smallexample
3294 Tears down the team and returns us to the previous @code{omp_in_parallel()} state.
3298 @node Implementing FOR construct
3299 @section Implementing FOR construct
3301 @smallexample
3302   #pragma omp parallel for
3303   for (i = lb; i <= ub; i++)
3304     body;
3305 @end smallexample
3307 becomes
3309 @smallexample
3310   void subfunction (void *data)
3311   @{
3312     long _s0, _e0;
3313     while (GOMP_loop_static_next (&_s0, &_e0))
3314     @{
3315       long _e1 = _e0, i;
3316       for (i = _s0; i < _e1; i++)
3317         body;
3318     @}
3319     GOMP_loop_end_nowait ();
3320   @}
3322   GOMP_parallel_loop_static (subfunction, NULL, 0, lb, ub+1, 1, 0);
3323   subfunction (NULL);
3324   GOMP_parallel_end ();
3325 @end smallexample
3327 @smallexample
3328   #pragma omp for schedule(runtime)
3329   for (i = 0; i < n; i++)
3330     body;
3331 @end smallexample
3333 becomes
3335 @smallexample
3336   @{
3337     long i, _s0, _e0;
3338     if (GOMP_loop_runtime_start (0, n, 1, &_s0, &_e0))
3339       do @{
3340         long _e1 = _e0;
3341         for (i = _s0, i < _e0; i++)
3342           body;
3343       @} while (GOMP_loop_runtime_next (&_s0, _&e0));
3344     GOMP_loop_end ();
3345   @}
3346 @end smallexample
3348 Note that while it looks like there is trickiness to propagating
3349 a non-constant STEP, there isn't really.  We're explicitly allowed
3350 to evaluate it as many times as we want, and any variables involved
3351 should automatically be handled as PRIVATE or SHARED like any other
3352 variables.  So the expression should remain evaluable in the 
3353 subfunction.  We can also pull it into a local variable if we like,
3354 but since its supposed to remain unchanged, we can also not if we like.
3356 If we have SCHEDULE(STATIC), and no ORDERED, then we ought to be
3357 able to get away with no work-sharing context at all, since we can
3358 simply perform the arithmetic directly in each thread to divide up
3359 the iterations.  Which would mean that we wouldn't need to call any
3360 of these routines.
3362 There are separate routines for handling loops with an ORDERED
3363 clause.  Bookkeeping for that is non-trivial...
3367 @node Implementing ORDERED construct
3368 @section Implementing ORDERED construct
3370 @smallexample
3371   void GOMP_ordered_start (void)
3372   void GOMP_ordered_end (void)
3373 @end smallexample
3377 @node Implementing SECTIONS construct
3378 @section Implementing SECTIONS construct
3380 A block as 
3382 @smallexample
3383   #pragma omp sections
3384   @{
3385     #pragma omp section
3386     stmt1;
3387     #pragma omp section
3388     stmt2;
3389     #pragma omp section
3390     stmt3;
3391   @}
3392 @end smallexample
3394 becomes
3396 @smallexample
3397   for (i = GOMP_sections_start (3); i != 0; i = GOMP_sections_next ())
3398     switch (i)
3399       @{
3400       case 1:
3401         stmt1;
3402         break;
3403       case 2:
3404         stmt2;
3405         break;
3406       case 3:
3407         stmt3;
3408         break;
3409       @}
3410   GOMP_barrier ();
3411 @end smallexample
3414 @node Implementing SINGLE construct
3415 @section Implementing SINGLE construct
3417 A block like 
3419 @smallexample
3420   #pragma omp single
3421   @{
3422     body;
3423   @}
3424 @end smallexample
3426 becomes
3428 @smallexample
3429   if (GOMP_single_start ())
3430     body;
3431   GOMP_barrier ();
3432 @end smallexample
3434 while 
3436 @smallexample
3437   #pragma omp single copyprivate(x)
3438     body;
3439 @end smallexample
3441 becomes
3443 @smallexample
3444   datap = GOMP_single_copy_start ();
3445   if (datap == NULL)
3446     @{
3447       body;
3448       data.x = x;
3449       GOMP_single_copy_end (&data);
3450     @}
3451   else
3452     x = datap->x;
3453   GOMP_barrier ();
3454 @end smallexample
3458 @node Implementing OpenACC's PARALLEL construct
3459 @section Implementing OpenACC's PARALLEL construct
3461 @smallexample
3462   void GOACC_parallel ()
3463 @end smallexample
3467 @c ---------------------------------------------------------------------
3468 @c Reporting Bugs
3469 @c ---------------------------------------------------------------------
3471 @node Reporting Bugs
3472 @chapter Reporting Bugs
3474 Bugs in the GNU Offloading and Multi Processing Runtime Library should
3475 be reported via @uref{http://gcc.gnu.org/bugzilla/, Bugzilla}.  Please add
3476 "openacc", or "openmp", or both to the keywords field in the bug
3477 report, as appropriate.
3481 @c ---------------------------------------------------------------------
3482 @c GNU General Public License
3483 @c ---------------------------------------------------------------------
3485 @include gpl_v3.texi
3489 @c ---------------------------------------------------------------------
3490 @c GNU Free Documentation License
3491 @c ---------------------------------------------------------------------
3493 @include fdl.texi
3497 @c ---------------------------------------------------------------------
3498 @c Funding Free Software
3499 @c ---------------------------------------------------------------------
3501 @include funding.texi
3503 @c ---------------------------------------------------------------------
3504 @c Index
3505 @c ---------------------------------------------------------------------
3507 @node Library Index
3508 @unnumbered Library Index
3510 @printindex cp
3512 @bye