/cp
[official-gcc.git] / libgomp / libgomp.texi
blobba430fc9fd754f7df1bbd1da0229eb00fd660e60
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-2013 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 OpenMP runtime library
35 @end direntry
37 This manual documents the GNU implementation of the OpenMP API for 
38 multi-platform shared-memory parallel programming in C/C++ and Fortran.
40 Published by the Free Software Foundation
41 51 Franklin Street, Fifth Floor
42 Boston, MA 02110-1301 USA
44 @insertcopying
45 @end ifinfo
48 @setchapternewpage odd
50 @titlepage
51 @title The GNU OpenMP Implementation
52 @page
53 @vskip 0pt plus 1filll
54 @comment For the @value{version-GCC} Version*
55 @sp 1
56 Published by the Free Software Foundation @*
57 51 Franklin Street, Fifth Floor@*
58 Boston, MA 02110-1301, USA@*
59 @sp 1
60 @insertcopying
61 @end titlepage
63 @summarycontents
64 @contents
65 @page
68 @node Top
69 @top Introduction
70 @cindex Introduction
72 This manual documents the usage of libgomp, the GNU implementation of the 
73 @uref{http://www.openmp.org, OpenMP} Application Programming Interface (API)
74 for multi-platform shared-memory parallel programming in C/C++ and Fortran.
78 @comment
79 @comment  When you add a new menu item, please keep the right hand
80 @comment  aligned to the same column.  Do not use tabs.  This provides
81 @comment  better formatting.
82 @comment
83 @menu
84 * Enabling OpenMP::            How to enable OpenMP for your applications.
85 * Runtime Library Routines::   The OpenMP runtime application programming 
86                                interface.
87 * Environment Variables::      Influencing runtime behavior with environment 
88                                variables.
89 * The libgomp ABI::            Notes on the external ABI presented by libgomp.
90 * Reporting Bugs::             How to report bugs in GNU OpenMP.
91 * Copying::                    GNU general public license says
92                                how you can copy and share libgomp.
93 * GNU Free Documentation License::
94                                How you can copy and share this manual.
95 * Funding::                    How to help assure continued work for free 
96                                software.
97 * Library Index::              Index of this documentation.
98 @end menu
101 @c ---------------------------------------------------------------------
102 @c Enabling OpenMP
103 @c ---------------------------------------------------------------------
105 @node Enabling OpenMP
106 @chapter Enabling OpenMP
108 To activate the OpenMP extensions for C/C++ and Fortran, the compile-time 
109 flag @command{-fopenmp} must be specified.  This enables the OpenMP directive
110 @code{#pragma omp} in C/C++ and @code{!$omp} directives in free form, 
111 @code{c$omp}, @code{*$omp} and @code{!$omp} directives in fixed form, 
112 @code{!$} conditional compilation sentinels in free form and @code{c$},
113 @code{*$} and @code{!$} sentinels in fixed form, for Fortran.  The flag also
114 arranges for automatic linking of the OpenMP runtime library 
115 (@ref{Runtime Library Routines}).
117 A complete description of all OpenMP directives accepted may be found in 
118 the @uref{http://www.openmp.org, OpenMP Application Program Interface} manual,
119 version 4.0.
122 @c ---------------------------------------------------------------------
123 @c Runtime Library Routines
124 @c ---------------------------------------------------------------------
126 @node Runtime Library Routines
127 @chapter Runtime Library Routines
129 The runtime routines described here are defined by Section 3 of the OpenMP
130 specification in version 4.0.  The routines are structured in following
131 three parts:
133 Control threads, processors and the parallel environment.  They have C
134 linkage, and do not throw exceptions.
136 @menu
137 * omp_get_active_level::        Number of active parallel regions
138 * omp_get_ancestor_thread_num:: Ancestor thread ID
139 * omp_get_cancellation::        Whether cancellation support is enabled
140 * omp_get_default_device::      Get the default device for target regions
141 * omp_get_dynamic::             Dynamic teams setting
142 * omp_get_level::               Number of parallel regions
143 * omp_get_max_active_levels::   Maximum number of active regions
144 * omp_get_max_threads::         Maximum number of threads of parallel region
145 * omp_get_nested::              Nested parallel regions
146 * omp_get_num_devices::         Number of target devices
147 * omp_get_num_procs::           Number of processors online
148 * omp_get_num_teams::           Number of teams
149 * omp_get_num_threads::         Size of the active team
150 * omp_get_proc_bind::           Whether theads may be moved between CPUs
151 * omp_get_schedule::            Obtain the runtime scheduling method
152 * omp_get_team_num::            Get team number
153 * omp_get_team_size::           Number of threads in a team
154 * omp_get_thread_limit::        Maximum number of threads
155 * omp_get_thread_num::          Current thread ID
156 * omp_in_parallel::             Whether a parallel region is active
157 * omp_in_final::                Whether in final or included task region
158 * omp_is_initial_device::       Whether executing on the host device
159 * omp_set_default_device::      Set the default device for target regions
160 * omp_set_dynamic::             Enable/disable dynamic teams
161 * omp_set_max_active_levels::   Limits the number of active parallel regions
162 * omp_set_nested::              Enable/disable nested parallel regions
163 * omp_set_num_threads::         Set upper team size limit
164 * omp_set_schedule::            Set the runtime scheduling method
165 @end menu
167 Initialize, set, test, unset and destroy simple and nested locks.
169 @menu
170 * omp_init_lock::            Initialize simple lock
171 * omp_set_lock::             Wait for and set simple lock
172 * omp_test_lock::            Test and set simple lock if available
173 * omp_unset_lock::           Unset simple lock
174 * omp_destroy_lock::         Destroy simple lock
175 * omp_init_nest_lock::       Initialize nested lock
176 * omp_set_nest_lock::        Wait for and set simple lock
177 * omp_test_nest_lock::       Test and set nested lock if available
178 * omp_unset_nest_lock::      Unset nested lock
179 * omp_destroy_nest_lock::    Destroy nested lock
180 @end menu
182 Portable, thread-based, wall clock timer.
184 @menu
185 * omp_get_wtick::            Get timer precision.
186 * omp_get_wtime::            Elapsed wall clock time.
187 @end menu
191 @node omp_get_active_level
192 @section @code{omp_get_active_level} -- Number of parallel regions
193 @table @asis
194 @item @emph{Description}:
195 This function returns the nesting level for the active parallel blocks,
196 which enclose the calling call.
198 @item @emph{C/C++}
199 @multitable @columnfractions .20 .80
200 @item @emph{Prototype}: @tab @code{int omp_get_active_level(void);}
201 @end multitable
203 @item @emph{Fortran}:
204 @multitable @columnfractions .20 .80
205 @item @emph{Interface}: @tab @code{integer function omp_get_active_level()}
206 @end multitable
208 @item @emph{See also}:
209 @ref{omp_get_level}, @ref{omp_get_max_active_levels}, @ref{omp_set_max_active_levels}
211 @item @emph{Reference}:
212 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.2.20.
213 @end table
217 @node omp_get_ancestor_thread_num
218 @section @code{omp_get_ancestor_thread_num} -- Ancestor thread ID
219 @table @asis
220 @item @emph{Description}:
221 This function returns the thread identification number for the given
222 nesting level of the current thread.  For values of @var{level} outside
223 zero to @code{omp_get_level} -1 is returned; if @var{level} is
224 @code{omp_get_level} the result is identical to @code{omp_get_thread_num}.
226 @item @emph{C/C++}
227 @multitable @columnfractions .20 .80
228 @item @emph{Prototype}: @tab @code{int omp_get_ancestor_thread_num(int level);}
229 @end multitable
231 @item @emph{Fortran}:
232 @multitable @columnfractions .20 .80
233 @item @emph{Interface}: @tab @code{integer function omp_get_ancestor_thread_num(level)}
234 @item                   @tab @code{integer level}
235 @end multitable
237 @item @emph{See also}:
238 @ref{omp_get_level}, @ref{omp_get_thread_num}, @ref{omp_get_team_size}
240 @item @emph{Reference}:
241 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.2.18.
242 @end table
246 @node omp_get_cancellation
247 @section @code{omp_get_cancellation} -- Whether cancellation support is enabled
248 @table @asis
249 @item @emph{Description}:
250 This function returns @code{true} if cancellation is activated, @code{false}
251 otherwise.  Here, @code{true} and @code{false} represent their language-specific
252 counterparts.  Unless @env{OMP_CANCELLATION} is set true, cancellations are
253 deactivated.
255 @item @emph{C/C++}:
256 @multitable @columnfractions .20 .80
257 @item @emph{Prototype}: @tab @code{int omp_get_cancellation(void);}
258 @end multitable
260 @item @emph{Fortran}:
261 @multitable @columnfractions .20 .80
262 @item @emph{Interface}: @tab @code{logical function omp_get_cancellation()}
263 @end multitable
265 @item @emph{See also}:
266 @ref{OMP_CANCELLATION}
268 @item @emph{Reference}:
269 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.2.9.
270 @end table
274 @node omp_get_default_device
275 @section @code{omp_get_default_device} -- Get the default device for target regions
276 @table @asis
277 @item @emph{Description}:
278 Get the default device for target regions without device clause.
280 @item @emph{C/C++}:
281 @multitable @columnfractions .20 .80
282 @item @emph{Prototype}: @tab @code{int omp_get_default_device(void);}
283 @end multitable
285 @item @emph{Fortran}:
286 @multitable @columnfractions .20 .80
287 @item @emph{Interface}: @tab @code{integer function omp_get_default_device()}
288 @end multitable
290 @item @emph{See also}:
291 @ref{OMP_DEFAULT_DEVICE}, @ref{omp_set_default_device}
293 @item @emph{Reference}:
294 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.2.24.
295 @end table
299 @node omp_get_dynamic
300 @section @code{omp_get_dynamic} -- Dynamic teams setting
301 @table @asis
302 @item @emph{Description}:
303 This function returns @code{true} if enabled, @code{false} otherwise. 
304 Here, @code{true} and @code{false} represent their language-specific 
305 counterparts.
307 The dynamic team setting may be initialized at startup by the 
308 @env{OMP_DYNAMIC} environment variable or at runtime using
309 @code{omp_set_dynamic}.  If undefined, dynamic adjustment is
310 disabled by default.
312 @item @emph{C/C++}:
313 @multitable @columnfractions .20 .80
314 @item @emph{Prototype}: @tab @code{int omp_get_dynamic(void);}
315 @end multitable
317 @item @emph{Fortran}:
318 @multitable @columnfractions .20 .80
319 @item @emph{Interface}: @tab @code{logical function omp_get_dynamic()}
320 @end multitable
322 @item @emph{See also}:
323 @ref{omp_set_dynamic}, @ref{OMP_DYNAMIC}
325 @item @emph{Reference}:
326 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.2.8.
327 @end table
331 @node omp_get_level
332 @section @code{omp_get_level} -- Obtain the current nesting level
333 @table @asis
334 @item @emph{Description}:
335 This function returns the nesting level for the parallel blocks,
336 which enclose the calling call.
338 @item @emph{C/C++}
339 @multitable @columnfractions .20 .80
340 @item @emph{Prototype}: @tab @code{int omp_get_level(void);}
341 @end multitable
343 @item @emph{Fortran}:
344 @multitable @columnfractions .20 .80
345 @item @emph{Interface}: @tab @code{integer function omp_level()}
346 @end multitable
348 @item @emph{See also}:
349 @ref{omp_get_active_level}
351 @item @emph{Reference}:
352 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.2.17.
353 @end table
357 @node omp_get_max_active_levels
358 @section @code{omp_get_max_active_levels} -- Maximum number of active regions
359 @table @asis
360 @item @emph{Description}:
361 This function obtains the maximum allowed number of nested, active parallel regions.
363 @item @emph{C/C++}
364 @multitable @columnfractions .20 .80
365 @item @emph{Prototype}: @tab @code{int omp_get_max_active_levels(void);}
366 @end multitable
368 @item @emph{Fortran}:
369 @multitable @columnfractions .20 .80
370 @item @emph{Interface}: @tab @code{integer function omp_get_max_active_levels()}
371 @end multitable
373 @item @emph{See also}:
374 @ref{omp_set_max_active_levels}, @ref{omp_get_active_level}
376 @item @emph{Reference}:
377 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.2.16.
378 @end table
382 @node omp_get_max_threads
383 @section @code{omp_get_max_threads} -- Maximum number of threads of parallel region
384 @table @asis
385 @item @emph{Description}:
386 Return the maximum number of threads used for the current parallel region
387 that does not use the clause @code{num_threads}.
389 @item @emph{C/C++}:
390 @multitable @columnfractions .20 .80
391 @item @emph{Prototype}: @tab @code{int omp_get_max_threads(void);}
392 @end multitable
394 @item @emph{Fortran}:
395 @multitable @columnfractions .20 .80
396 @item @emph{Interface}: @tab @code{integer function omp_get_max_threads()}
397 @end multitable
399 @item @emph{See also}:
400 @ref{omp_set_num_threads}, @ref{omp_set_dynamic}, @ref{omp_get_thread_limit}
402 @item @emph{Reference}:
403 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.2.3.
404 @end table
408 @node omp_get_nested
409 @section @code{omp_get_nested} -- Nested parallel regions
410 @table @asis
411 @item @emph{Description}:
412 This function returns @code{true} if nested parallel regions are
413 enabled, @code{false} otherwise.  Here, @code{true} and @code{false}
414 represent their language-specific counterparts.
416 Nested parallel regions may be initialized at startup by the 
417 @env{OMP_NESTED} environment variable or at runtime using
418 @code{omp_set_nested}.  If undefined, nested parallel regions are
419 disabled by default.
421 @item @emph{C/C++}:
422 @multitable @columnfractions .20 .80
423 @item @emph{Prototype}: @tab @code{int omp_get_nested(void);}
424 @end multitable
426 @item @emph{Fortran}:
427 @multitable @columnfractions .20 .80
428 @item @emph{Interface}: @tab @code{logical function omp_get_nested()}
429 @end multitable
431 @item @emph{See also}:
432 @ref{omp_set_nested}, @ref{OMP_NESTED}
434 @item @emph{Reference}:
435 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.2.11.
436 @end table
440 @node omp_get_num_devices
441 @section @code{omp_get_num_devices} -- Number of target devices
442 @table @asis
443 @item @emph{Description}:
444 Returns the number of target devices.
446 @item @emph{C/C++}:
447 @multitable @columnfractions .20 .80
448 @item @emph{Prototype}: @tab @code{int omp_get_num_devices(void);}
449 @end multitable
451 @item @emph{Fortran}:
452 @multitable @columnfractions .20 .80
453 @item @emph{Interface}: @tab @code{integer function omp_get_num_devices()}
454 @end multitable
456 @item @emph{Reference}:
457 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.2.25.
458 @end table
462 @node omp_get_num_procs
463 @section @code{omp_get_num_procs} -- Number of processors online
464 @table @asis
465 @item @emph{Description}:
466 Returns the number of processors online on that device.
468 @item @emph{C/C++}:
469 @multitable @columnfractions .20 .80
470 @item @emph{Prototype}: @tab @code{int omp_get_num_procs(void);}
471 @end multitable
473 @item @emph{Fortran}:
474 @multitable @columnfractions .20 .80
475 @item @emph{Interface}: @tab @code{integer function omp_get_num_procs()}
476 @end multitable
478 @item @emph{Reference}:
479 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.2.5.
480 @end table
484 @node omp_get_num_teams
485 @section @code{omp_get_num_teams} -- Number of teams
486 @table @asis
487 @item @emph{Description}:
488 Returns the number of teams in the current team region.
490 @item @emph{C/C++}:
491 @multitable @columnfractions .20 .80
492 @item @emph{Prototype}: @tab @code{int omp_get_num_teams(void);}
493 @end multitable
495 @item @emph{Fortran}:
496 @multitable @columnfractions .20 .80
497 @item @emph{Interface}: @tab @code{integer function omp_get_num_teams()}
498 @end multitable
500 @item @emph{Reference}:
501 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.2.26.
502 @end table
506 @node omp_get_num_threads
507 @section @code{omp_get_num_threads} -- Size of the active team
508 @table @asis
509 @item @emph{Description}:
510 Returns the number of threads in the current team.  In a sequential section of
511 the program @code{omp_get_num_threads} returns 1.
513 The default team size may be initialized at startup by the 
514 @env{OMP_NUM_THREADS} environment variable.  At runtime, the size
515 of the current team may be set either by the @code{NUM_THREADS}
516 clause or by @code{omp_set_num_threads}.  If none of the above were
517 used to define a specific value and @env{OMP_DYNAMIC} is disabled,
518 one thread per CPU online is used.
520 @item @emph{C/C++}:
521 @multitable @columnfractions .20 .80
522 @item @emph{Prototype}: @tab @code{int omp_get_num_threads(void);}
523 @end multitable
525 @item @emph{Fortran}:
526 @multitable @columnfractions .20 .80
527 @item @emph{Interface}: @tab @code{integer function omp_get_num_threads()}
528 @end multitable
530 @item @emph{See also}:
531 @ref{omp_get_max_threads}, @ref{omp_set_num_threads}, @ref{OMP_NUM_THREADS}
533 @item @emph{Reference}:
534 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.2.2.
535 @end table
539 @node omp_get_proc_bind
540 @section @code{omp_get_proc_bind} -- Whether theads may be moved between CPUs
541 @table @asis
542 @item @emph{Description}:
543 This functions returns the currently active thread affinity policy, which is
544 set via @env{OMP_PROC_BIND}.  Possible values are @code{omp_proc_bind_false},
545 @code{omp_proc_bind_true}, @code{omp_proc_bind_master},
546 @code{omp_proc_bind_close} and @code{omp_proc_bind_spread}.
548 @item @emph{C/C++}:
549 @multitable @columnfractions .20 .80
550 @item @emph{Prototype}: @tab @code{omp_proc_bind_t omp_get_proc_bind(void);}
551 @end multitable
553 @item @emph{Fortran}:
554 @multitable @columnfractions .20 .80
555 @item @emph{Interface}: @tab @code{integer(kind=omp_proc_bind_kind) function omp_get_proc_bind()}
556 @end multitable
558 @item @emph{See also}:
559 @ref{OMP_PROC_BIND}, @ref{OMP_PLACES}, @ref{GOMP_CPU_AFFINITY},
561 @item @emph{Reference}:
562 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.2.22.
563 @end table
567 @node omp_get_schedule
568 @section @code{omp_get_schedule} -- Obtain the runtime scheduling method
569 @table @asis
570 @item @emph{Description}:
571 Obtain the runtime scheduling method.  The @var{kind} argument will be
572 set to the value @code{omp_sched_static}, @code{omp_sched_dynamic},
573 @code{omp_sched_guided} or @code{omp_sched_auto}.  The second argument,
574 @var{modifier}, is set to the chunk size.
576 @item @emph{C/C++}
577 @multitable @columnfractions .20 .80
578 @item @emph{Prototype}: @tab @code{void omp_get_schedule(omp_sched_t *kind, int *modifier);}
579 @end multitable
581 @item @emph{Fortran}:
582 @multitable @columnfractions .20 .80
583 @item @emph{Interface}: @tab @code{subroutine omp_get_schedule(kind, modifier)}
584 @item                   @tab @code{integer(kind=omp_sched_kind) kind}
585 @item                   @tab @code{integer modifier}
586 @end multitable
588 @item @emph{See also}:
589 @ref{omp_set_schedule}, @ref{OMP_SCHEDULE}
591 @item @emph{Reference}:
592 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.2.13.
593 @end table
597 @node omp_get_team_num
598 @section @code{omp_get_team_num} -- Get team number
599 @table @asis
600 @item @emph{Description}:
601 Returns the team number of the calling thread.
603 @item @emph{C/C++}:
604 @multitable @columnfractions .20 .80
605 @item @emph{Prototype}: @tab @code{int omp_get_team_num(void);}
606 @end multitable
608 @item @emph{Fortran}:
609 @multitable @columnfractions .20 .80
610 @item @emph{Interface}: @tab @code{integer function omp_get_team_num()}
611 @end multitable
613 @item @emph{Reference}:
614 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.2.27.
615 @end table
619 @node omp_get_team_size
620 @section @code{omp_get_team_size} -- Number of threads in a team
621 @table @asis
622 @item @emph{Description}:
623 This function returns the number of threads in a thread team to which
624 either the current thread or its ancestor belongs.  For values of @var{level}
625 outside zero to @code{omp_get_level}, -1 is returned; if @var{level} is zero,
626 1 is returned, and for @code{omp_get_level}, the result is identical
627 to @code{omp_get_num_threads}.
629 @item @emph{C/C++}:
630 @multitable @columnfractions .20 .80
631 @item @emph{Prototype}: @tab @code{int omp_get_team_size(int level);}
632 @end multitable
634 @item @emph{Fortran}:
635 @multitable @columnfractions .20 .80
636 @item @emph{Interface}: @tab @code{integer function omp_get_team_size(level)}
637 @item                   @tab @code{integer level}
638 @end multitable
640 @item @emph{See also}:
641 @ref{omp_get_num_threads}, @ref{omp_get_level}, @ref{omp_get_ancestor_thread_num}
643 @item @emph{Reference}:
644 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.2.19.
645 @end table
649 @node omp_get_thread_limit
650 @section @code{omp_get_thread_limit} -- Maximum number of threads
651 @table @asis
652 @item @emph{Description}:
653 Return the maximum number of threads of the program.
655 @item @emph{C/C++}:
656 @multitable @columnfractions .20 .80
657 @item @emph{Prototype}: @tab @code{int omp_get_thread_limit(void);}
658 @end multitable
660 @item @emph{Fortran}:
661 @multitable @columnfractions .20 .80
662 @item @emph{Interface}: @tab @code{integer function omp_get_thread_limit()}
663 @end multitable
665 @item @emph{See also}:
666 @ref{omp_get_max_threads}, @ref{OMP_THREAD_LIMIT}
668 @item @emph{Reference}:
669 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.2.14.
670 @end table
674 @node omp_get_thread_num
675 @section @code{omp_get_thread_num} -- Current thread ID
676 @table @asis
677 @item @emph{Description}:
678 Returns a unique thread identification number within the current team.
679 In a sequential parts of the program, @code{omp_get_thread_num}
680 always returns 0.  In parallel regions the return value varies
681 from 0 to @code{omp_get_num_threads}-1 inclusive.  The return
682 value of the master thread of a team is always 0.
684 @item @emph{C/C++}:
685 @multitable @columnfractions .20 .80
686 @item @emph{Prototype}: @tab @code{int omp_get_thread_num(void);}
687 @end multitable
689 @item @emph{Fortran}:
690 @multitable @columnfractions .20 .80
691 @item @emph{Interface}: @tab @code{integer function omp_get_thread_num()}
692 @end multitable
694 @item @emph{See also}:
695 @ref{omp_get_num_threads}, @ref{omp_get_ancestor_thread_num}
697 @item @emph{Reference}:
698 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.2.4.
699 @end table
703 @node omp_in_parallel
704 @section @code{omp_in_parallel} -- Whether a parallel region is active
705 @table @asis
706 @item @emph{Description}:
707 This function returns @code{true} if currently running in parallel,
708 @code{false} otherwise.  Here, @code{true} and @code{false} represent
709 their language-specific counterparts.
711 @item @emph{C/C++}:
712 @multitable @columnfractions .20 .80
713 @item @emph{Prototype}: @tab @code{int omp_in_parallel(void);}
714 @end multitable
716 @item @emph{Fortran}:
717 @multitable @columnfractions .20 .80
718 @item @emph{Interface}: @tab @code{logical function omp_in_parallel()}
719 @end multitable
721 @item @emph{Reference}:
722 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.2.6.
723 @end table
726 @node omp_in_final
727 @section @code{omp_in_final} -- Whether in final or included task region
728 @table @asis
729 @item @emph{Description}:
730 This function returns @code{true} if currently running in a final
731 or included task region, @code{false} otherwise.  Here, @code{true}
732 and @code{false} represent their language-specific counterparts.
734 @item @emph{C/C++}:
735 @multitable @columnfractions .20 .80
736 @item @emph{Prototype}: @tab @code{int omp_in_final(void);}
737 @end multitable
739 @item @emph{Fortran}:
740 @multitable @columnfractions .20 .80
741 @item @emph{Interface}: @tab @code{logical function omp_in_final()}
742 @end multitable
744 @item @emph{Reference}:
745 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.2.21.
746 @end table
750 @node omp_is_initial_device
751 @section @code{omp_is_initial_device} -- Whether executing on the host device
752 @table @asis
753 @item @emph{Description}:
754 This function returns @code{true} if currently running on the host device,
755 @code{false} otherwise.  Here, @code{true} and @code{false} represent
756 their language-specific counterparts.
758 @item @emph{C/C++}:
759 @multitable @columnfractions .20 .80
760 @item @emph{Prototype}: @tab @code{int omp_is_initial_device(void);}
761 @end multitable
763 @item @emph{Fortran}:
764 @multitable @columnfractions .20 .80
765 @item @emph{Interface}: @tab @code{logical function omp_is_initial_device()}
766 @end multitable
768 @item @emph{Reference}:
769 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.2.28.
770 @end table
774 @node omp_set_default_device
775 @section @code{omp_set_default_device} -- Set the default device for target regions
776 @table @asis
777 @item @emph{Description}:
778 Set the default device for target regions without device clause.  The argument
779 shall be a nonnegative device number.
781 @item @emph{C/C++}:
782 @multitable @columnfractions .20 .80
783 @item @emph{Prototype}: @tab @code{void omp_set_default_device(int device_num);}
784 @end multitable
786 @item @emph{Fortran}:
787 @multitable @columnfractions .20 .80
788 @item @emph{Interface}: @tab @code{subroutine omp_set_default_device(device_num)}
789 @item                   @tab @code{integer device_num}
790 @end multitable
792 @item @emph{See also}:
793 @ref{OMP_DEFAULT_DEVICE}, @ref{omp_get_default_device}
795 @item @emph{Reference}:
796 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.2.23.
797 @end table
801 @node omp_set_dynamic
802 @section @code{omp_set_dynamic} -- Enable/disable dynamic teams
803 @table @asis
804 @item @emph{Description}:
805 Enable or disable the dynamic adjustment of the number of threads 
806 within a team.  The function takes the language-specific equivalent
807 of @code{true} and @code{false}, where @code{true} enables dynamic 
808 adjustment of team sizes and @code{false} disables it.
810 @item @emph{C/C++}:
811 @multitable @columnfractions .20 .80
812 @item @emph{Prototype}: @tab @code{void omp_set_dynamic(int dynamic_threads);}
813 @end multitable
815 @item @emph{Fortran}:
816 @multitable @columnfractions .20 .80
817 @item @emph{Interface}: @tab @code{subroutine omp_set_dynamic(dynamic_threads)}
818 @item                   @tab @code{logical, intent(in) :: dynamic_threads}
819 @end multitable
821 @item @emph{See also}:
822 @ref{OMP_DYNAMIC}, @ref{omp_get_dynamic}
824 @item @emph{Reference}:
825 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.2.7.
826 @end table
830 @node omp_set_max_active_levels
831 @section @code{omp_set_max_active_levels} -- Limits the number of active parallel regions
832 @table @asis
833 @item @emph{Description}:
834 This function limits the maximum allowed number of nested, active
835 parallel regions.
837 @item @emph{C/C++}
838 @multitable @columnfractions .20 .80
839 @item @emph{Prototype}: @tab @code{void omp_set_max_active_levels(int max_levels);}
840 @end multitable
842 @item @emph{Fortran}:
843 @multitable @columnfractions .20 .80
844 @item @emph{Interface}: @tab @code{subroutine omp_set_max_active_levels(max_levels)}
845 @item                   @tab @code{integer max_levels}
846 @end multitable
848 @item @emph{See also}:
849 @ref{omp_get_max_active_levels}, @ref{omp_get_active_level}
851 @item @emph{Reference}:
852 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.2.15.
853 @end table
857 @node omp_set_nested
858 @section @code{omp_set_nested} -- Enable/disable nested parallel regions
859 @table @asis
860 @item @emph{Description}:
861 Enable or disable nested parallel regions, i.e., whether team members
862 are allowed to create new teams.  The function takes the language-specific
863 equivalent of @code{true} and @code{false}, where @code{true} enables 
864 dynamic adjustment of team sizes and @code{false} disables it.
866 @item @emph{C/C++}:
867 @multitable @columnfractions .20 .80
868 @item @emph{Prototype}: @tab @code{void omp_set_nested(int nested);}
869 @end multitable
871 @item @emph{Fortran}:
872 @multitable @columnfractions .20 .80
873 @item @emph{Interface}: @tab @code{subroutine omp_set_nested(nested)}
874 @item                   @tab @code{logical, intent(in) :: nested}
875 @end multitable
877 @item @emph{See also}:
878 @ref{OMP_NESTED}, @ref{omp_get_nested}
880 @item @emph{Reference}:
881 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.2.10.
882 @end table
886 @node omp_set_num_threads
887 @section @code{omp_set_num_threads} -- Set upper team size limit
888 @table @asis
889 @item @emph{Description}:
890 Specifies the number of threads used by default in subsequent parallel 
891 sections, if those do not specify a @code{num_threads} clause.  The
892 argument of @code{omp_set_num_threads} shall be a positive integer.
894 @item @emph{C/C++}:
895 @multitable @columnfractions .20 .80
896 @item @emph{Prototype}: @tab @code{void omp_set_num_threads(int num_threads);}
897 @end multitable
899 @item @emph{Fortran}:
900 @multitable @columnfractions .20 .80
901 @item @emph{Interface}: @tab @code{subroutine omp_set_num_threads(num_threads)}
902 @item                   @tab @code{integer, intent(in) :: num_threads}
903 @end multitable
905 @item @emph{See also}:
906 @ref{OMP_NUM_THREADS}, @ref{omp_get_num_threads}, @ref{omp_get_max_threads}
908 @item @emph{Reference}:
909 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.2.1.
910 @end table
914 @node omp_set_schedule
915 @section @code{omp_set_schedule} -- Set the runtime scheduling method
916 @table @asis
917 @item @emph{Description}:
918 Sets the runtime scheduling method.  The @var{kind} argument can have the
919 value @code{omp_sched_static}, @code{omp_sched_dynamic},
920 @code{omp_sched_guided} or @code{omp_sched_auto}.  Except for
921 @code{omp_sched_auto}, the chunk size is set to the value of
922 @var{modifier} if positive, or to the default value if zero or negative.
923 For @code{omp_sched_auto} the @var{modifier} argument is ignored.
925 @item @emph{C/C++}
926 @multitable @columnfractions .20 .80
927 @item @emph{Prototype}: @tab @code{void omp_set_schedule(omp_sched_t kind, int modifier);}
928 @end multitable
930 @item @emph{Fortran}:
931 @multitable @columnfractions .20 .80
932 @item @emph{Interface}: @tab @code{subroutine omp_set_schedule(kind, modifier)}
933 @item                   @tab @code{integer(kind=omp_sched_kind) kind}
934 @item                   @tab @code{integer modifier}
935 @end multitable
937 @item @emph{See also}:
938 @ref{omp_get_schedule}
939 @ref{OMP_SCHEDULE}
941 @item @emph{Reference}:
942 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.2.12.
943 @end table
947 @node omp_init_lock
948 @section @code{omp_init_lock} -- Initialize simple lock
949 @table @asis
950 @item @emph{Description}:
951 Initialize a simple lock.  After initialization, the lock is in
952 an unlocked state.
954 @item @emph{C/C++}:
955 @multitable @columnfractions .20 .80
956 @item @emph{Prototype}: @tab @code{void omp_init_lock(omp_lock_t *lock);}
957 @end multitable
959 @item @emph{Fortran}:
960 @multitable @columnfractions .20 .80
961 @item @emph{Interface}: @tab @code{subroutine omp_init_lock(svar)}
962 @item                   @tab @code{integer(omp_lock_kind), intent(out) :: svar}
963 @end multitable
965 @item @emph{See also}:
966 @ref{omp_destroy_lock}
968 @item @emph{Reference}: 
969 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.3.1.
970 @end table
974 @node omp_set_lock
975 @section @code{omp_set_lock} -- Wait for and set simple lock
976 @table @asis
977 @item @emph{Description}:
978 Before setting a simple lock, the lock variable must be initialized by 
979 @code{omp_init_lock}.  The calling thread is blocked until the lock 
980 is available.  If the lock is already held by the current thread, 
981 a deadlock occurs.
983 @item @emph{C/C++}:
984 @multitable @columnfractions .20 .80
985 @item @emph{Prototype}: @tab @code{void omp_set_lock(omp_lock_t *lock);}
986 @end multitable
988 @item @emph{Fortran}:
989 @multitable @columnfractions .20 .80
990 @item @emph{Interface}: @tab @code{subroutine omp_set_lock(svar)}
991 @item                   @tab @code{integer(omp_lock_kind), intent(inout) :: svar}
992 @end multitable
994 @item @emph{See also}:
995 @ref{omp_init_lock}, @ref{omp_test_lock}, @ref{omp_unset_lock}
997 @item @emph{Reference}: 
998 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.3.3.
999 @end table
1003 @node omp_test_lock
1004 @section @code{omp_test_lock} -- Test and set simple lock if available
1005 @table @asis
1006 @item @emph{Description}:
1007 Before setting a simple lock, the lock variable must be initialized by 
1008 @code{omp_init_lock}.  Contrary to @code{omp_set_lock}, @code{omp_test_lock} 
1009 does not block if the lock is not available.  This function returns
1010 @code{true} upon success, @code{false} otherwise.  Here, @code{true} and
1011 @code{false} represent their language-specific counterparts.
1013 @item @emph{C/C++}:
1014 @multitable @columnfractions .20 .80
1015 @item @emph{Prototype}: @tab @code{int omp_test_lock(omp_lock_t *lock);}
1016 @end multitable
1018 @item @emph{Fortran}:
1019 @multitable @columnfractions .20 .80
1020 @item @emph{Interface}: @tab @code{logical function omp_test_lock(svar)}
1021 @item                   @tab @code{integer(omp_lock_kind), intent(inout) :: svar}
1022 @end multitable
1024 @item @emph{See also}:
1025 @ref{omp_init_lock}, @ref{omp_set_lock}, @ref{omp_set_lock}
1027 @item @emph{Reference}: 
1028 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.3.5.
1029 @end table
1033 @node omp_unset_lock
1034 @section @code{omp_unset_lock} -- Unset simple lock
1035 @table @asis
1036 @item @emph{Description}:
1037 A simple lock about to be unset must have been locked by @code{omp_set_lock}
1038 or @code{omp_test_lock} before.  In addition, the lock must be held by the
1039 thread calling @code{omp_unset_lock}.  Then, the lock becomes unlocked.  If one
1040 or more threads attempted to set the lock before, one of them is chosen to,
1041 again, set the lock to itself.
1043 @item @emph{C/C++}:
1044 @multitable @columnfractions .20 .80
1045 @item @emph{Prototype}: @tab @code{void omp_unset_lock(omp_lock_t *lock);}
1046 @end multitable
1048 @item @emph{Fortran}:
1049 @multitable @columnfractions .20 .80
1050 @item @emph{Interface}: @tab @code{subroutine omp_unset_lock(svar)}
1051 @item                   @tab @code{integer(omp_lock_kind), intent(inout) :: svar}
1052 @end multitable
1054 @item @emph{See also}:
1055 @ref{omp_set_lock}, @ref{omp_test_lock}
1057 @item @emph{Reference}: 
1058 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.3.4.
1059 @end table
1063 @node omp_destroy_lock
1064 @section @code{omp_destroy_lock} -- Destroy simple lock
1065 @table @asis
1066 @item @emph{Description}:
1067 Destroy a simple lock.  In order to be destroyed, a simple lock must be
1068 in the unlocked state. 
1070 @item @emph{C/C++}:
1071 @multitable @columnfractions .20 .80
1072 @item @emph{Prototype}: @tab @code{void omp_destroy_lock(omp_lock_t *lock);}
1073 @end multitable
1075 @item @emph{Fortran}:
1076 @multitable @columnfractions .20 .80
1077 @item @emph{Interface}: @tab @code{subroutine omp_destroy_lock(svar)}
1078 @item                   @tab @code{integer(omp_lock_kind), intent(inout) :: svar}
1079 @end multitable
1081 @item @emph{See also}:
1082 @ref{omp_init_lock}
1084 @item @emph{Reference}: 
1085 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.3.2.
1086 @end table
1090 @node omp_init_nest_lock
1091 @section @code{omp_init_nest_lock} -- Initialize nested lock
1092 @table @asis
1093 @item @emph{Description}:
1094 Initialize a nested lock.  After initialization, the lock is in
1095 an unlocked state and the nesting count is set to zero.
1097 @item @emph{C/C++}:
1098 @multitable @columnfractions .20 .80
1099 @item @emph{Prototype}: @tab @code{void omp_init_nest_lock(omp_nest_lock_t *lock);}
1100 @end multitable
1102 @item @emph{Fortran}:
1103 @multitable @columnfractions .20 .80
1104 @item @emph{Interface}: @tab @code{subroutine omp_init_nest_lock(nvar)}
1105 @item                   @tab @code{integer(omp_nest_lock_kind), intent(out) :: nvar}
1106 @end multitable
1108 @item @emph{See also}:
1109 @ref{omp_destroy_nest_lock}
1111 @item @emph{Reference}:
1112 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.3.1.
1113 @end table
1116 @node omp_set_nest_lock
1117 @section @code{omp_set_nest_lock} -- Wait for and set nested lock
1118 @table @asis
1119 @item @emph{Description}:
1120 Before setting a nested lock, the lock variable must be initialized by 
1121 @code{omp_init_nest_lock}.  The calling thread is blocked until the lock
1122 is available.  If the lock is already held by the current thread, the
1123 nesting count for the lock is incremented.
1125 @item @emph{C/C++}:
1126 @multitable @columnfractions .20 .80
1127 @item @emph{Prototype}: @tab @code{void omp_set_nest_lock(omp_nest_lock_t *lock);}
1128 @end multitable
1130 @item @emph{Fortran}:
1131 @multitable @columnfractions .20 .80
1132 @item @emph{Interface}: @tab @code{subroutine omp_set_nest_lock(nvar)}
1133 @item                   @tab @code{integer(omp_nest_lock_kind), intent(inout) :: nvar}
1134 @end multitable
1136 @item @emph{See also}:
1137 @ref{omp_init_nest_lock}, @ref{omp_unset_nest_lock}
1139 @item @emph{Reference}: 
1140 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.3.3.
1141 @end table
1145 @node omp_test_nest_lock
1146 @section @code{omp_test_nest_lock} -- Test and set nested lock if available
1147 @table @asis
1148 @item @emph{Description}:
1149 Before setting a nested lock, the lock variable must be initialized by 
1150 @code{omp_init_nest_lock}.  Contrary to @code{omp_set_nest_lock},
1151 @code{omp_test_nest_lock} does not block if the lock is not available. 
1152 If the lock is already held by the current thread, the new nesting count 
1153 is returned.  Otherwise, the return value equals zero.
1155 @item @emph{C/C++}:
1156 @multitable @columnfractions .20 .80
1157 @item @emph{Prototype}: @tab @code{int omp_test_nest_lock(omp_nest_lock_t *lock);}
1158 @end multitable
1160 @item @emph{Fortran}:
1161 @multitable @columnfractions .20 .80
1162 @item @emph{Interface}: @tab @code{logical function omp_test_nest_lock(nvar)}
1163 @item                   @tab @code{integer(omp_nest_lock_kind), intent(inout) :: nvar}
1164 @end multitable
1167 @item @emph{See also}:
1168 @ref{omp_init_lock}, @ref{omp_set_lock}, @ref{omp_set_lock}
1170 @item @emph{Reference}: 
1171 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.3.5.
1172 @end table
1176 @node omp_unset_nest_lock
1177 @section @code{omp_unset_nest_lock} -- Unset nested lock
1178 @table @asis
1179 @item @emph{Description}:
1180 A nested lock about to be unset must have been locked by @code{omp_set_nested_lock}
1181 or @code{omp_test_nested_lock} before.  In addition, the lock must be held by the
1182 thread calling @code{omp_unset_nested_lock}.  If the nesting count drops to zero, the
1183 lock becomes unlocked.  If one ore more threads attempted to set the lock before,
1184 one of them is chosen to, again, set the lock to itself.
1186 @item @emph{C/C++}:
1187 @multitable @columnfractions .20 .80
1188 @item @emph{Prototype}: @tab @code{void omp_unset_nest_lock(omp_nest_lock_t *lock);}
1189 @end multitable
1191 @item @emph{Fortran}:
1192 @multitable @columnfractions .20 .80
1193 @item @emph{Interface}: @tab @code{subroutine omp_unset_nest_lock(nvar)}
1194 @item                   @tab @code{integer(omp_nest_lock_kind), intent(inout) :: nvar}
1195 @end multitable
1197 @item @emph{See also}:
1198 @ref{omp_set_nest_lock}
1200 @item @emph{Reference}: 
1201 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.3.4.
1202 @end table
1206 @node omp_destroy_nest_lock
1207 @section @code{omp_destroy_nest_lock} -- Destroy nested lock
1208 @table @asis
1209 @item @emph{Description}:
1210 Destroy a nested lock.  In order to be destroyed, a nested lock must be
1211 in the unlocked state and its nesting count must equal zero.
1213 @item @emph{C/C++}:
1214 @multitable @columnfractions .20 .80
1215 @item @emph{Prototype}: @tab @code{void omp_destroy_nest_lock(omp_nest_lock_t *);}
1216 @end multitable
1218 @item @emph{Fortran}:
1219 @multitable @columnfractions .20 .80
1220 @item @emph{Interface}: @tab @code{subroutine omp_destroy_nest_lock(nvar)}
1221 @item                   @tab @code{integer(omp_nest_lock_kind), intent(inout) :: nvar}
1222 @end multitable
1224 @item @emph{See also}:
1225 @ref{omp_init_lock}
1227 @item @emph{Reference}: 
1228 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.3.2.
1229 @end table
1233 @node omp_get_wtick
1234 @section @code{omp_get_wtick} -- Get timer precision
1235 @table @asis
1236 @item @emph{Description}:
1237 Gets the timer precision, i.e., the number of seconds between two 
1238 successive clock ticks.
1240 @item @emph{C/C++}:
1241 @multitable @columnfractions .20 .80
1242 @item @emph{Prototype}: @tab @code{double omp_get_wtick(void);}
1243 @end multitable
1245 @item @emph{Fortran}:
1246 @multitable @columnfractions .20 .80
1247 @item @emph{Interface}: @tab @code{double precision function omp_get_wtick()}
1248 @end multitable
1250 @item @emph{See also}:
1251 @ref{omp_get_wtime}
1253 @item @emph{Reference}: 
1254 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.4.2.
1255 @end table
1259 @node omp_get_wtime
1260 @section @code{omp_get_wtime} -- Elapsed wall clock time
1261 @table @asis
1262 @item @emph{Description}:
1263 Elapsed wall clock time in seconds.  The time is measured per thread, no
1264 guarantee can be made that two distinct threads measure the same time.
1265 Time is measured from some "time in the past", which is an arbitrary time
1266 guaranteed not to change during the execution of the program.
1268 @item @emph{C/C++}:
1269 @multitable @columnfractions .20 .80
1270 @item @emph{Prototype}: @tab @code{double omp_get_wtime(void);}
1271 @end multitable
1273 @item @emph{Fortran}:
1274 @multitable @columnfractions .20 .80
1275 @item @emph{Interface}: @tab @code{double precision function omp_get_wtime()}
1276 @end multitable
1278 @item @emph{See also}:
1279 @ref{omp_get_wtick}
1281 @item @emph{Reference}: 
1282 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 3.4.1.
1283 @end table
1287 @c ---------------------------------------------------------------------
1288 @c Environment Variables
1289 @c ---------------------------------------------------------------------
1291 @node Environment Variables
1292 @chapter Environment Variables
1294 The environment variables which beginning with @env{OMP_} are defined by
1295 section 4 of the OpenMP specification in version 4.0, while those
1296 beginning with @env{GOMP_} are GNU extensions.
1298 @menu
1299 * OMP_CANCELLATION::      Set whether cancellation is activated
1300 * OMP_DISPLAY_ENV::       Show OpenMP version and environment variables
1301 * OMP_DEFAULT_DEVICE::    Set the device used in target regions
1302 * OMP_DYNAMIC::           Dynamic adjustment of threads
1303 * OMP_MAX_ACTIVE_LEVELS:: Set the maximum number of nested parallel regions
1304 * OMP_NESTED::            Nested parallel regions
1305 * OMP_NUM_THREADS::       Specifies the number of threads to use
1306 * OMP_PROC_BIND::         Whether theads may be moved between CPUs
1307 * OMP_PLACES::            Specifies on which CPUs the theads should be placed
1308 * OMP_STACKSIZE::         Set default thread stack size
1309 * OMP_SCHEDULE::          How threads are scheduled
1310 * OMP_THREAD_LIMIT::      Set the maximum number of threads
1311 * OMP_WAIT_POLICY::       How waiting threads are handled
1312 * GOMP_CPU_AFFINITY::     Bind threads to specific CPUs
1313 * GOMP_STACKSIZE::        Set default thread stack size
1314 * GOMP_SPINCOUNT::        Set the busy-wait spin count
1315 @end menu
1318 @node OMP_CANCELLATION
1319 @section @env{OMP_CANCELLATION} -- Set whether cancellation is activated
1320 @cindex Environment Variable
1321 @table @asis
1322 @item @emph{Description}:
1323 If set to @code{TRUE}, the cancellation is activated.  If set to @code{FALSE} or
1324 if unset, cancellation is disabled and the @code{cancel} construct is ignored.
1326 @item @emph{See also}:
1327 @ref{omp_get_cancellation}
1329 @item @emph{Reference}:
1330 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 4.11
1331 @end table
1335 @node OMP_DISPLAY_ENV
1336 @section @env{OMP_DISPLAY_ENV} -- Show OpenMP version and environment variables
1337 @cindex Environment Variable
1338 @table @asis
1339 @item @emph{Description}:
1340 If set to @code{TRUE}, the OpenMP version number and the values
1341 associated with the OpenMP environment variables are printed to @code{stderr}.
1342 If set to @code{VERBOSE}, it additionally shows the value of the environment
1343 variables which are GNU extensions.  If undefined or set to @code{FALSE},
1344 this information will not be shown.
1347 @item @emph{Reference}:
1348 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 4.12
1349 @end table
1353 @node OMP_DEFAULT_DEVICE
1354 @section @env{OMP_DEFAULT_DEVICE} -- Set the device used in target regions
1355 @cindex Environment Variable
1356 @table @asis
1357 @item @emph{Description}:
1358 Set to choose the device which is used in a @code{target} region, unless the
1359 value is overridden by @code{omp_set_default_device} or by a @code{device}
1360 clause.  The value shall be the nonnegative device number. If no device with
1361 the given device number exists, the code is executed on the host.  If unset,
1362 device number 0 will be used.
1365 @item @emph{See also}:
1366 @ref{omp_get_default_device}, @ref{omp_set_default_device},
1368 @item @emph{Reference}:
1369 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 4.11
1370 @end table
1374 @node OMP_DYNAMIC
1375 @section @env{OMP_DYNAMIC} -- Dynamic adjustment of threads
1376 @cindex Environment Variable
1377 @table @asis
1378 @item @emph{Description}:
1379 Enable or disable the dynamic adjustment of the number of threads 
1380 within a team.  The value of this environment variable shall be 
1381 @code{TRUE} or @code{FALSE}.  If undefined, dynamic adjustment is
1382 disabled by default.
1384 @item @emph{See also}:
1385 @ref{omp_set_dynamic}
1387 @item @emph{Reference}: 
1388 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 4.3
1389 @end table
1393 @node OMP_MAX_ACTIVE_LEVELS
1394 @section @env{OMP_MAX_ACTIVE_LEVELS} -- Set the maximum number of nested parallel regions
1395 @cindex Environment Variable
1396 @table @asis
1397 @item @emph{Description}:
1398 Specifies the initial value for the maximum number of nested parallel
1399 regions.  The value of this variable shall be a positive integer.
1400 If undefined, the number of active levels is unlimited.
1402 @item @emph{See also}:
1403 @ref{omp_set_max_active_levels}
1405 @item @emph{Reference}: 
1406 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 4.9
1407 @end table
1411 @node OMP_NESTED
1412 @section @env{OMP_NESTED} -- Nested parallel regions
1413 @cindex Environment Variable
1414 @cindex Implementation specific setting
1415 @table @asis
1416 @item @emph{Description}:
1417 Enable or disable nested parallel regions, i.e., whether team members
1418 are allowed to create new teams.  The value of this environment variable 
1419 shall be @code{TRUE} or @code{FALSE}.  If undefined, nested parallel 
1420 regions are disabled by default.
1422 @item @emph{See also}:
1423 @ref{omp_set_nested}
1425 @item @emph{Reference}: 
1426 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 4.6
1427 @end table
1431 @node OMP_NUM_THREADS
1432 @section @env{OMP_NUM_THREADS} -- Specifies the number of threads to use
1433 @cindex Environment Variable
1434 @cindex Implementation specific setting
1435 @table @asis
1436 @item @emph{Description}:
1437 Specifies the default number of threads to use in parallel regions.  The 
1438 value of this variable shall be a comma-separated list of positive integers;
1439 the value specified the number of threads to use for the corresponding nested
1440 level.  If undefined one thread per CPU is used.
1442 @item @emph{See also}:
1443 @ref{omp_set_num_threads}
1445 @item @emph{Reference}: 
1446 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 4.2
1447 @end table
1451 @node OMP_PLACES
1452 @section @env{OMP_PLACES} -- Specifies on which CPUs the theads should be placed
1453 @cindex Environment Variable
1454 @table @asis
1455 @item @emph{Description}:
1456 The thread placement can be either specified using an abstract name or by an
1457 explicit list of the places.  The abstract names @code{threads}, @code{cores}
1458 and @code{sockets} can be optionally followed by a positive number in
1459 parentheses, which denotes the how many places shall be created.  With
1460 @code{threads} each place corresponds to a single hardware thread; @code{cores}
1461 to a single core with the corresponding number of hardware threads; and with
1462 @code{sockets} the place corresponds to a single socket.  The resulting
1463 placement can be shown by setting the @env{OMP_DISPLAY_ENV} environment
1464 variable.
1466 Alternatively, the placement can be specified explicitly as comma-separated
1467 list of places.  A place is specified by set of nonnegative numbers in curly
1468 braces, denoting the denoting the hardware threads.  The hardware threads
1469 belonging to a place can either be specified as comma-separated list of
1470 nonnegative thread numbers or using an interval.  Multiple places can also be
1471 either specified by a comma-separated list of places or by an interval.  To
1472 specify an interval, a colon followed by the count is placed after after
1473 the hardware thread number or the place.  Optionally, the length can be
1474 followed by a colon and the stride number -- otherwise a unit stride is
1475 assumed.  For instance, the following specifies the same places list:
1476 @code{"@{0,1,2@}, @{3,4,6@}, @{7,8,9@}, @{10,11,12@}"};
1477 @code{"@{0:3@}, @{3:3@}, @{7:3@}, @{10:3@}"}; and @code{"@{0:2@}:4:3"}.
1479 If @env{OMP_PLACES} and @env{GOMP_CPU_AFFINITY} are unset and
1480 @env{OMP_PROC_BIND} is either unset or @code{false}, threads may be moved
1481 between CPUs following no placement policy.
1483 @item @emph{See also}:
1484 @ref{OMP_PROC_BIND}, @ref{GOMP_CPU_AFFINITY}, @ref{omp_get_proc_bind},
1485 @ref{OMP_DISPLAY_ENV}
1487 @item @emph{Reference}:
1488 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 4.5
1489 @end table
1493 @node OMP_PROC_BIND
1494 @section @env{OMP_PROC_BIND} -- Whether theads may be moved between CPUs
1495 @cindex Environment Variable
1496 @table @asis
1497 @item @emph{Description}:
1498 Specifies whether threads may be moved between processors.  If set to
1499 @code{TRUE}, OpenMP theads should not be moved; if set to @code{FALSE}
1500 they may be moved.  Alternatively, a comma separated list with the
1501 values @code{MASTER}, @code{CLOSE} and @code{SPREAD} can be used to specify
1502 the thread affinity policy for the corresponding nesting level.  With
1503 @code{MASTER} the worker threads are in the same place partition as the
1504 master thread.  With @code{CLOSE} those are kept close to the master thread
1505 in contiguous place partitions.  And with @code{SPREAD} a sparse distribution
1506 across the place partitions is used.
1508 When undefined, @env{OMP_PROC_BIND} defaults to @code{TRUE} when
1509 @env{OMP_PLACES} or @env{GOMP_CPU_AFFINITY} is set and @code{FALSE} otherwise.
1511 @item @emph{See also}:
1512 @ref{OMP_PLACES}, @ref{GOMP_CPU_AFFINITY}, @ref{omp_get_proc_bind}
1514 @item @emph{Reference}:
1515 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 4.4
1516 @end table
1520 @node OMP_SCHEDULE
1521 @section @env{OMP_SCHEDULE} -- How threads are scheduled
1522 @cindex Environment Variable
1523 @cindex Implementation specific setting
1524 @table @asis
1525 @item @emph{Description}:
1526 Allows to specify @code{schedule type} and @code{chunk size}. 
1527 The value of the variable shall have the form: @code{type[,chunk]} where
1528 @code{type} is one of @code{static}, @code{dynamic}, @code{guided} or @code{auto}
1529 The optional @code{chunk} size shall be a positive integer.  If undefined,
1530 dynamic scheduling and a chunk size of 1 is used.
1532 @item @emph{See also}:
1533 @ref{omp_set_schedule}
1535 @item @emph{Reference}: 
1536 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Sections 2.7.1 and 4.1
1537 @end table
1541 @node OMP_STACKSIZE
1542 @section @env{OMP_STACKSIZE} -- Set default thread stack size
1543 @cindex Environment Variable
1544 @table @asis
1545 @item @emph{Description}:
1546 Set the default thread stack size in kilobytes, unless the number
1547 is suffixed by @code{B}, @code{K}, @code{M} or @code{G}, in which
1548 case the size is, respectively, in bytes, kilobytes, megabytes
1549 or gigabytes.  This is different from @code{pthread_attr_setstacksize}
1550 which gets the number of bytes as an argument.  If the stack size cannot
1551 be set due to system constraints, an error is reported and the initial
1552 stack size is left unchanged.  If undefined, the stack size is system
1553 dependent.
1555 @item @emph{Reference}: 
1556 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 4.7
1557 @end table
1561 @node OMP_THREAD_LIMIT
1562 @section @env{OMP_THREAD_LIMIT} -- Set the maximum number of threads
1563 @cindex Environment Variable
1564 @table @asis
1565 @item @emph{Description}:
1566 Specifies the number of threads to use for the whole program.  The
1567 value of this variable shall be a positive integer.  If undefined,
1568 the number of threads is not limited.
1570 @item @emph{See also}:
1571 @ref{OMP_NUM_THREADS}, @ref{omp_get_thread_limit}
1573 @item @emph{Reference}: 
1574 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 4.10
1575 @end table
1579 @node OMP_WAIT_POLICY
1580 @section @env{OMP_WAIT_POLICY} -- How waiting threads are handled
1581 @cindex Environment Variable
1582 @table @asis
1583 @item @emph{Description}:
1584 Specifies whether waiting threads should be active or passive.  If
1585 the value is @code{PASSIVE}, waiting threads should not consume CPU
1586 power while waiting; while the value is @code{ACTIVE} specifies that
1587 they should.  If undefined, threads wait actively for a short time
1588 before waiting passively.
1590 @item @emph{See also}:
1591 @ref{GOMP_SPINCOUNT}
1593 @item @emph{Reference}: 
1594 @uref{http://www.openmp.org/, OpenMP specification v4.0}, Section 4.8
1595 @end table
1599 @node GOMP_CPU_AFFINITY
1600 @section @env{GOMP_CPU_AFFINITY} -- Bind threads to specific CPUs
1601 @cindex Environment Variable
1602 @table @asis
1603 @item @emph{Description}:
1604 Binds threads to specific CPUs.  The variable should contain a space-separated
1605 or comma-separated list of CPUs.  This list may contain different kinds of 
1606 entries: either single CPU numbers in any order, a range of CPUs (M-N) 
1607 or a range with some stride (M-N:S).  CPU numbers are zero based.  For example,
1608 @code{GOMP_CPU_AFFINITY="0 3 1-2 4-15:2"} will bind the initial thread
1609 to CPU 0, the second to CPU 3, the third to CPU 1, the fourth to 
1610 CPU 2, the fifth to CPU 4, the sixth through tenth to CPUs 6, 8, 10, 12,
1611 and 14 respectively and then start assigning back from the beginning of
1612 the list.  @code{GOMP_CPU_AFFINITY=0} binds all threads to CPU 0.
1614 There is no GNU OpenMP library routine to determine whether a CPU affinity 
1615 specification is in effect.  As a workaround, language-specific library 
1616 functions, e.g., @code{getenv} in C or @code{GET_ENVIRONMENT_VARIABLE} in 
1617 Fortran, may be used to query the setting of the @code{GOMP_CPU_AFFINITY} 
1618 environment variable.  A defined CPU affinity on startup cannot be changed 
1619 or disabled during the runtime of the application.
1621 If both @env{GOMP_CPU_AFFINITY} and @env{OMP_PROC_BIND} are set,
1622 @env{OMP_PROC_BIND} has a higher precedence.  If neither has been set and
1623 @env{OMP_PROC_BIND} is unset, or when @env{OMP_PROC_BIND} is set to
1624 @code{FALSE}, the host system will handle the assignment of threads to CPUs.
1626 @item @emph{See also}:
1627 @ref{OMP_PLACES}, @ref{OMP_PROC_BIND}
1628 @end table
1632 @node GOMP_STACKSIZE
1633 @section @env{GOMP_STACKSIZE} -- Set default thread stack size
1634 @cindex Environment Variable
1635 @cindex Implementation specific setting
1636 @table @asis
1637 @item @emph{Description}:
1638 Set the default thread stack size in kilobytes.  This is different from
1639 @code{pthread_attr_setstacksize} which gets the number of bytes as an 
1640 argument.  If the stack size cannot be set due to system constraints, an 
1641 error is reported and the initial stack size is left unchanged.  If undefined,
1642 the stack size is system dependent.
1644 @item @emph{See also}:
1645 @ref{OMP_STACKSIZE}
1647 @item @emph{Reference}: 
1648 @uref{http://gcc.gnu.org/ml/gcc-patches/2006-06/msg00493.html, 
1649 GCC Patches Mailinglist}, 
1650 @uref{http://gcc.gnu.org/ml/gcc-patches/2006-06/msg00496.html,
1651 GCC Patches Mailinglist}
1652 @end table
1656 @node GOMP_SPINCOUNT
1657 @section @env{GOMP_SPINCOUNT} -- Set the busy-wait spin count
1658 @cindex Environment Variable
1659 @cindex Implementation specific setting
1660 @table @asis
1661 @item @emph{Description}:
1662 Determines how long a threads waits actively with consuming CPU power
1663 before waiting passively without consuming CPU power.  The value may be
1664 either @code{INFINITE}, @code{INFINITY} to always wait actively or an
1665 integer which gives the number of spins of the busy-wait loop.  The
1666 integer may optionally be followed by the following suffixes acting
1667 as multiplication factors: @code{k} (kilo, thousand), @code{M} (mega,
1668 million), @code{G} (giga, billion), or @code{T} (tera, trillion).
1669 If undefined, 0 is used when @env{OMP_WAIT_POLICY} is @code{PASSIVE},
1670 300,000 is used when @env{OMP_WAIT_POLICY} is undefined and
1671 30 billion is used when @env{OMP_WAIT_POLICY} is @code{ACTIVE}.
1672 If there are more OpenMP threads than available CPUs, 1000 and 100
1673 spins are used for @env{OMP_WAIT_POLICY} being @code{ACTIVE} or
1674 undefined, respectively; unless the @env{GOMP_SPINCOUNT} is lower
1675 or @env{OMP_WAIT_POLICY} is @code{PASSIVE}.
1677 @item @emph{See also}:
1678 @ref{OMP_WAIT_POLICY}
1679 @end table
1683 @c ---------------------------------------------------------------------
1684 @c The libgomp ABI
1685 @c ---------------------------------------------------------------------
1687 @node The libgomp ABI
1688 @chapter The libgomp ABI
1690 The following sections present notes on the external ABI as 
1691 presented by libgomp.  Only maintainers should need them.
1693 @menu
1694 * Implementing MASTER construct::
1695 * Implementing CRITICAL construct::
1696 * Implementing ATOMIC construct::
1697 * Implementing FLUSH construct::
1698 * Implementing BARRIER construct::
1699 * Implementing THREADPRIVATE construct::
1700 * Implementing PRIVATE clause::
1701 * Implementing FIRSTPRIVATE LASTPRIVATE COPYIN and COPYPRIVATE clauses::
1702 * Implementing REDUCTION clause::
1703 * Implementing PARALLEL construct::
1704 * Implementing FOR construct::
1705 * Implementing ORDERED construct::
1706 * Implementing SECTIONS construct::
1707 * Implementing SINGLE construct::
1708 @end menu
1711 @node Implementing MASTER construct
1712 @section Implementing MASTER construct
1714 @smallexample
1715 if (omp_get_thread_num () == 0)
1716   block
1717 @end smallexample
1719 Alternately, we generate two copies of the parallel subfunction
1720 and only include this in the version run by the master thread.
1721 Surely this is not worthwhile though...
1725 @node Implementing CRITICAL construct
1726 @section Implementing CRITICAL construct
1728 Without a specified name,
1730 @smallexample
1731   void GOMP_critical_start (void);
1732   void GOMP_critical_end (void);
1733 @end smallexample
1735 so that we don't get COPY relocations from libgomp to the main
1736 application.
1738 With a specified name, use omp_set_lock and omp_unset_lock with
1739 name being transformed into a variable declared like
1741 @smallexample
1742   omp_lock_t gomp_critical_user_<name> __attribute__((common))
1743 @end smallexample
1745 Ideally the ABI would specify that all zero is a valid unlocked
1746 state, and so we wouldn't need to initialize this at
1747 startup.
1751 @node Implementing ATOMIC construct
1752 @section Implementing ATOMIC construct
1754 The target should implement the @code{__sync} builtins.
1756 Failing that we could add
1758 @smallexample
1759   void GOMP_atomic_enter (void)
1760   void GOMP_atomic_exit (void)
1761 @end smallexample
1763 which reuses the regular lock code, but with yet another lock
1764 object private to the library.
1768 @node Implementing FLUSH construct
1769 @section Implementing FLUSH construct
1771 Expands to the @code{__sync_synchronize} builtin.
1775 @node Implementing BARRIER construct
1776 @section Implementing BARRIER construct
1778 @smallexample
1779   void GOMP_barrier (void)
1780 @end smallexample
1783 @node Implementing THREADPRIVATE construct
1784 @section Implementing THREADPRIVATE construct
1786 In _most_ cases we can map this directly to @code{__thread}.  Except
1787 that OMP allows constructors for C++ objects.  We can either
1788 refuse to support this (how often is it used?) or we can 
1789 implement something akin to .ctors.
1791 Even more ideally, this ctor feature is handled by extensions
1792 to the main pthreads library.  Failing that, we can have a set
1793 of entry points to register ctor functions to be called.
1797 @node Implementing PRIVATE clause
1798 @section Implementing PRIVATE clause
1800 In association with a PARALLEL, or within the lexical extent
1801 of a PARALLEL block, the variable becomes a local variable in
1802 the parallel subfunction.
1804 In association with FOR or SECTIONS blocks, create a new
1805 automatic variable within the current function.  This preserves
1806 the semantic of new variable creation.
1810 @node Implementing FIRSTPRIVATE LASTPRIVATE COPYIN and COPYPRIVATE clauses
1811 @section Implementing FIRSTPRIVATE LASTPRIVATE COPYIN and COPYPRIVATE clauses
1813 This seems simple enough for PARALLEL blocks.  Create a private 
1814 struct for communicating between the parent and subfunction.
1815 In the parent, copy in values for scalar and "small" structs;
1816 copy in addresses for others TREE_ADDRESSABLE types.  In the 
1817 subfunction, copy the value into the local variable.
1819 It is not clear what to do with bare FOR or SECTION blocks.
1820 The only thing I can figure is that we do something like:
1822 @smallexample
1823 #pragma omp for firstprivate(x) lastprivate(y)
1824 for (int i = 0; i < n; ++i)
1825   body;
1826 @end smallexample
1828 which becomes
1830 @smallexample
1832   int x = x, y;
1834   // for stuff
1836   if (i == n)
1837     y = y;
1839 @end smallexample
1841 where the "x=x" and "y=y" assignments actually have different
1842 uids for the two variables, i.e. not something you could write
1843 directly in C.  Presumably this only makes sense if the "outer"
1844 x and y are global variables.
1846 COPYPRIVATE would work the same way, except the structure 
1847 broadcast would have to happen via SINGLE machinery instead.
1851 @node Implementing REDUCTION clause
1852 @section Implementing REDUCTION clause
1854 The private struct mentioned in the previous section should have 
1855 a pointer to an array of the type of the variable, indexed by the 
1856 thread's @var{team_id}.  The thread stores its final value into the 
1857 array, and after the barrier, the master thread iterates over the
1858 array to collect the values.
1861 @node Implementing PARALLEL construct
1862 @section Implementing PARALLEL construct
1864 @smallexample
1865   #pragma omp parallel
1866   @{
1867     body;
1868   @}
1869 @end smallexample
1871 becomes
1873 @smallexample
1874   void subfunction (void *data)
1875   @{
1876     use data;
1877     body;
1878   @}
1880   setup data;
1881   GOMP_parallel_start (subfunction, &data, num_threads);
1882   subfunction (&data);
1883   GOMP_parallel_end ();
1884 @end smallexample
1886 @smallexample
1887   void GOMP_parallel_start (void (*fn)(void *), void *data, unsigned num_threads)
1888 @end smallexample
1890 The @var{FN} argument is the subfunction to be run in parallel.
1892 The @var{DATA} argument is a pointer to a structure used to 
1893 communicate data in and out of the subfunction, as discussed
1894 above with respect to FIRSTPRIVATE et al.
1896 The @var{NUM_THREADS} argument is 1 if an IF clause is present
1897 and false, or the value of the NUM_THREADS clause, if
1898 present, or 0.
1900 The function needs to create the appropriate number of
1901 threads and/or launch them from the dock.  It needs to
1902 create the team structure and assign team ids.
1904 @smallexample
1905   void GOMP_parallel_end (void)
1906 @end smallexample
1908 Tears down the team and returns us to the previous @code{omp_in_parallel()} state.
1912 @node Implementing FOR construct
1913 @section Implementing FOR construct
1915 @smallexample
1916   #pragma omp parallel for
1917   for (i = lb; i <= ub; i++)
1918     body;
1919 @end smallexample
1921 becomes
1923 @smallexample
1924   void subfunction (void *data)
1925   @{
1926     long _s0, _e0;
1927     while (GOMP_loop_static_next (&_s0, &_e0))
1928     @{
1929       long _e1 = _e0, i;
1930       for (i = _s0; i < _e1; i++)
1931         body;
1932     @}
1933     GOMP_loop_end_nowait ();
1934   @}
1936   GOMP_parallel_loop_static (subfunction, NULL, 0, lb, ub+1, 1, 0);
1937   subfunction (NULL);
1938   GOMP_parallel_end ();
1939 @end smallexample
1941 @smallexample
1942   #pragma omp for schedule(runtime)
1943   for (i = 0; i < n; i++)
1944     body;
1945 @end smallexample
1947 becomes
1949 @smallexample
1950   @{
1951     long i, _s0, _e0;
1952     if (GOMP_loop_runtime_start (0, n, 1, &_s0, &_e0))
1953       do @{
1954         long _e1 = _e0;
1955         for (i = _s0, i < _e0; i++)
1956           body;
1957       @} while (GOMP_loop_runtime_next (&_s0, _&e0));
1958     GOMP_loop_end ();
1959   @}
1960 @end smallexample
1962 Note that while it looks like there is trickiness to propagating
1963 a non-constant STEP, there isn't really.  We're explicitly allowed
1964 to evaluate it as many times as we want, and any variables involved
1965 should automatically be handled as PRIVATE or SHARED like any other
1966 variables.  So the expression should remain evaluable in the 
1967 subfunction.  We can also pull it into a local variable if we like,
1968 but since its supposed to remain unchanged, we can also not if we like.
1970 If we have SCHEDULE(STATIC), and no ORDERED, then we ought to be
1971 able to get away with no work-sharing context at all, since we can
1972 simply perform the arithmetic directly in each thread to divide up
1973 the iterations.  Which would mean that we wouldn't need to call any
1974 of these routines.
1976 There are separate routines for handling loops with an ORDERED
1977 clause.  Bookkeeping for that is non-trivial...
1981 @node Implementing ORDERED construct
1982 @section Implementing ORDERED construct
1984 @smallexample
1985   void GOMP_ordered_start (void)
1986   void GOMP_ordered_end (void)
1987 @end smallexample
1991 @node Implementing SECTIONS construct
1992 @section Implementing SECTIONS construct
1994 A block as 
1996 @smallexample
1997   #pragma omp sections
1998   @{
1999     #pragma omp section
2000     stmt1;
2001     #pragma omp section
2002     stmt2;
2003     #pragma omp section
2004     stmt3;
2005   @}
2006 @end smallexample
2008 becomes
2010 @smallexample
2011   for (i = GOMP_sections_start (3); i != 0; i = GOMP_sections_next ())
2012     switch (i)
2013       @{
2014       case 1:
2015         stmt1;
2016         break;
2017       case 2:
2018         stmt2;
2019         break;
2020       case 3:
2021         stmt3;
2022         break;
2023       @}
2024   GOMP_barrier ();
2025 @end smallexample
2028 @node Implementing SINGLE construct
2029 @section Implementing SINGLE construct
2031 A block like 
2033 @smallexample
2034   #pragma omp single
2035   @{
2036     body;
2037   @}
2038 @end smallexample
2040 becomes
2042 @smallexample
2043   if (GOMP_single_start ())
2044     body;
2045   GOMP_barrier ();
2046 @end smallexample
2048 while 
2050 @smallexample
2051   #pragma omp single copyprivate(x)
2052     body;
2053 @end smallexample
2055 becomes
2057 @smallexample
2058   datap = GOMP_single_copy_start ();
2059   if (datap == NULL)
2060     @{
2061       body;
2062       data.x = x;
2063       GOMP_single_copy_end (&data);
2064     @}
2065   else
2066     x = datap->x;
2067   GOMP_barrier ();
2068 @end smallexample
2072 @c ---------------------------------------------------------------------
2073 @c 
2074 @c ---------------------------------------------------------------------
2076 @node Reporting Bugs
2077 @chapter Reporting Bugs
2079 Bugs in the GNU OpenMP implementation should be reported via 
2080 @uref{http://gcc.gnu.org/bugzilla/, Bugzilla}.  For all cases, please add 
2081 "openmp" to the keywords field in the bug report.
2085 @c ---------------------------------------------------------------------
2086 @c GNU General Public License
2087 @c ---------------------------------------------------------------------
2089 @include gpl_v3.texi
2093 @c ---------------------------------------------------------------------
2094 @c GNU Free Documentation License
2095 @c ---------------------------------------------------------------------
2097 @include fdl.texi
2101 @c ---------------------------------------------------------------------
2102 @c Funding Free Software
2103 @c ---------------------------------------------------------------------
2105 @include funding.texi
2107 @c ---------------------------------------------------------------------
2108 @c Index
2109 @c ---------------------------------------------------------------------
2111 @node Library Index
2112 @unnumbered Library Index
2114 @printindex cp
2116 @bye