1 \input texinfo @c -*-texinfo-*-
4 @setfilename libgomp.info
10 Copyright @copyright{} 2006, 2007, 2008 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.2 or
14 any later version published by the Free Software Foundation; with the
15 Invariant Sections being ``Funding Free Software'', the Front-Cover
16 texts being (a) (see below), and with the Back-Cover Texts being (b)
17 (see below). A copy of the license is included in the section entitled
18 ``GNU Free Documentation License''.
20 (a) The FSF's Front-Cover Text is:
24 (b) The FSF's Back-Cover Text is:
26 You have freedom to copy and modify this GNU Manual, like GNU
27 software. Copies published by the Free Software Foundation raise
28 funds for GNU development.
32 @dircategory GNU Libraries
34 * libgomp: (libgomp). GNU OpenMP runtime library
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
48 @setchapternewpage odd
51 @title The GNU OpenMP Implementation
53 @vskip 0pt plus 1filll
54 @comment For the @value{version-GCC} Version*
56 Published by the Free Software Foundation @*
57 51 Franklin Street, Fifth Floor@*
58 Boston, MA 02110-1301, USA@*
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.
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.
84 * Enabling OpenMP:: How to enable OpenMP for your applications.
85 * Runtime Library Routines:: The OpenMP runtime application programming
87 * Environment Variables:: Influencing runtime behavior with environment
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
97 * Index:: Index of this documentation.
101 @c ---------------------------------------------------------------------
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,
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 specifications in version 2.5.
132 Control threads, processors and the parallel environment.
135 * omp_get_dynamic:: Dynamic teams setting
136 * omp_get_max_threads:: Maximum number of threads
137 * omp_get_nested:: Nested parallel regions
138 * omp_get_num_procs:: Number of processors online
139 * omp_get_num_threads:: Size of the active team
140 * omp_get_thread_num:: Current thread ID
141 * omp_in_parallel:: Whether a parallel region is active
142 * omp_set_dynamic:: Enable/disable dynamic teams
143 * omp_set_nested:: Enable/disable nested parallel regions
144 * omp_set_num_threads:: Set upper team size limit
147 Initialize, set, test, unset and destroy simple and nested locks.
150 * omp_init_lock:: Initialize simple lock
151 * omp_set_lock:: Wait for and set simple lock
152 * omp_test_lock:: Test and set simple lock if available
153 * omp_unset_lock:: Unset simple lock
154 * omp_destroy_lock:: Destroy simple lock
155 * omp_init_nest_lock:: Initialize nested lock
156 * omp_set_nest_lock:: Wait for and set simple lock
157 * omp_test_nest_lock:: Test and set nested lock if available
158 * omp_unset_nest_lock:: Unset nested lock
159 * omp_destroy_nest_lock:: Destroy nested lock
162 Portable, thread-based, wall clock timer.
165 * omp_get_wtick:: Get timer precision.
166 * omp_get_wtime:: Elapsed wall clock time.
169 @node omp_get_dynamic
170 @section @code{omp_get_dynamic} -- Dynamic teams setting
172 @item @emph{Description}:
173 This function returns @code{true} if enabled, @code{false} otherwise.
174 Here, @code{true} and @code{false} represent their language-specific
177 The dynamic team setting may be initialized at startup by the
178 @code{OMP_DYNAMIC} environment variable or at runtime using
179 @code{omp_set_dynamic}. If undefined, dynamic adjustment is
183 @multitable @columnfractions .20 .80
184 @item @emph{Prototype}: @tab @code{int omp_get_dynamic();}
187 @item @emph{Fortran}:
188 @multitable @columnfractions .20 .80
189 @item @emph{Interface}: @tab @code{logical function omp_get_dynamic()}
192 @item @emph{See also}:
193 @ref{omp_set_dynamic}, @ref{OMP_DYNAMIC}
195 @item @emph{Reference}:
196 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.2.8.
201 @node omp_get_max_threads
202 @section @code{omp_get_max_threads} -- Maximum number of threads
204 @item @emph{Description}:
205 Return the maximum number of threads used for parallel regions that do
206 not use the clause @code{num_threads}.
209 @multitable @columnfractions .20 .80
210 @item @emph{Prototype}: @tab @code{int omp_get_max_threads();}
213 @item @emph{Fortran}:
214 @multitable @columnfractions .20 .80
215 @item @emph{Interface}: @tab @code{integer function omp_get_max_threads()}
218 @item @emph{See also}:
219 @ref{omp_set_num_threads}, @ref{omp_set_dynamic}
221 @item @emph{Reference}:
222 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.2.3.
228 @section @code{omp_get_nested} -- Nested parallel regions
230 @item @emph{Description}:
231 This function returns @code{true} if nested parallel regions are
232 enabled, @code{false} otherwise. Here, @code{true} and @code{false}
233 represent their language-specific counterparts.
235 Nested parallel regions may be initialized at startup by the
236 @code{OMP_NESTED} environment variable or at runtime using
237 @code{omp_set_nested}. If undefined, nested parallel regions are
241 @multitable @columnfractions .20 .80
242 @item @emph{Prototype}: @tab @code{int omp_get_nested();}
245 @item @emph{Fortran}:
246 @multitable @columnfractions .20 .80
247 @item @emph{Interface}: @tab @code{integer function omp_get_nested()}
250 @item @emph{See also}:
251 @ref{omp_set_nested}, @ref{OMP_NESTED}
253 @item @emph{Reference}:
254 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.2.10.
259 @node omp_get_num_procs
260 @section @code{omp_get_num_procs} -- Number of processors online
262 @item @emph{Description}:
263 Returns the number of processors online.
266 @multitable @columnfractions .20 .80
267 @item @emph{Prototype}: @tab @code{int omp_get_num_procs();}
270 @item @emph{Fortran}:
271 @multitable @columnfractions .20 .80
272 @item @emph{Interface}: @tab @code{integer function omp_get_num_procs()}
275 @item @emph{Reference}:
276 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.2.5.
281 @node omp_get_num_threads
282 @section @code{omp_get_num_threads} -- Size of the active team
284 @item @emph{Description}:
285 The number of threads in the current team. In a sequential section of
286 the program @code{omp_get_num_threads} returns 1.
288 The default team size may be initialized at startup by the
289 @code{OMP_NUM_THREADS} environment variable. At runtime, the size
290 of the current team may be set either by the @code{NUM_THREADS}
291 clause or by @code{omp_set_num_threads}. If none of the above were
292 used to define a specific value and @code{OMP_DYNAMIC} is disabled,
293 one thread per CPU online is used.
296 @multitable @columnfractions .20 .80
297 @item @emph{Prototype}: @tab @code{int omp_get_num_threads();}
300 @item @emph{Fortran}:
301 @multitable @columnfractions .20 .80
302 @item @emph{Interface}: @tab @code{integer function omp_get_num_threads()}
305 @item @emph{See also}:
306 @ref{omp_get_max_threads}, @ref{omp_set_num_threads}, @ref{OMP_NUM_THREADS}
308 @item @emph{Reference}:
309 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.2.2.
314 @node omp_get_thread_num
315 @section @code{omp_get_thread_num} -- Current thread ID
317 @item @emph{Description}:
318 Unique thread identification number. In a sequential parts of the program,
319 @code{omp_get_thread_num} always returns 0. In parallel regions the return
320 value varies from 0 to @code{omp_get_max_threads}-1 inclusive. The return
321 value of the master thread of a team is always 0.
324 @multitable @columnfractions .20 .80
325 @item @emph{Prototype}: @tab @code{int omp_get_thread_num();}
328 @item @emph{Fortran}:
329 @multitable @columnfractions .20 .80
330 @item @emph{Interface}: @tab @code{integer function omp_get_thread_num()}
333 @item @emph{See also}:
334 @ref{omp_get_max_threads}
336 @item @emph{Reference}:
337 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.2.4.
342 @node omp_in_parallel
343 @section @code{omp_in_parallel} -- Whether a parallel region is active
345 @item @emph{Description}:
346 This function returns @code{true} if currently running in parallel,
347 @code{false} otherwise. Here, @code{true} and @code{false} represent
348 their language-specific counterparts.
351 @multitable @columnfractions .20 .80
352 @item @emph{Prototype}: @tab @code{int omp_in_parallel();}
355 @item @emph{Fortran}:
356 @multitable @columnfractions .20 .80
357 @item @emph{Interface}: @tab @code{logical function omp_in_parallel()}
360 @item @emph{Reference}:
361 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.2.6.
365 @node omp_set_dynamic
366 @section @code{omp_set_dynamic} -- Enable/disable dynamic teams
368 @item @emph{Description}:
369 Enable or disable the dynamic adjustment of the number of threads
370 within a team. The function takes the language-specific equivalent
371 of @code{true} and @code{false}, where @code{true} enables dynamic
372 adjustment of team sizes and @code{false} disables it.
375 @multitable @columnfractions .20 .80
376 @item @emph{Prototype}: @tab @code{void omp_set_dynamic(int);}
379 @item @emph{Fortran}:
380 @multitable @columnfractions .20 .80
381 @item @emph{Interface}: @tab @code{subroutine omp_set_dynamic(set)}
382 @item @tab @code{integer, intent(in) :: set}
385 @item @emph{See also}:
386 @ref{OMP_DYNAMIC}, @ref{omp_get_dynamic}
388 @item @emph{Reference}:
389 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.2.7.
395 @section @code{omp_set_nested} -- Enable/disable nested parallel regions
397 @item @emph{Description}:
398 Enable or disable nested parallel regions, i.e., whether team members
399 are allowed to create new teams. The function takes the language-specific
400 equivalent of @code{true} and @code{false}, where @code{true} enables
401 dynamic adjustment of team sizes and @code{false} disables it.
404 @multitable @columnfractions .20 .80
405 @item @emph{Prototype}: @tab @code{void omp_set_dynamic(int);}
408 @item @emph{Fortran}:
409 @multitable @columnfractions .20 .80
410 @item @emph{Interface}: @tab @code{subroutine omp_set_dynamic(set)}
411 @item @tab @code{integer, intent(in) :: set}
414 @item @emph{See also}:
415 @ref{OMP_NESTED}, @ref{omp_get_nested}
417 @item @emph{Reference}:
418 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.2.9.
423 @node omp_set_num_threads
424 @section @code{omp_set_num_threads} -- Set upper team size limit
426 @item @emph{Description}:
427 Specifies the number of threads used by default in subsequent parallel
428 sections, if those do not specify a @code{num_threads} clause. The
429 argument of @code{omp_set_num_threads} shall be a positive integer.
432 @multitable @columnfractions .20 .80
433 @item @emph{Prototype}: @tab @code{void omp_set_num_threads(int);}
436 @item @emph{Fortran}:
437 @multitable @columnfractions .20 .80
438 @item @emph{Interface}: @tab @code{subroutine omp_set_num_threads(set)}
439 @item @tab @code{integer, intent(in) :: set}
442 @item @emph{See also}:
443 @ref{OMP_NUM_THREADS}, @ref{omp_get_num_threads}, @ref{omp_get_max_threads}
445 @item @emph{Reference}:
446 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.2.1.
452 @section @code{omp_init_lock} -- Initialize simple lock
454 @item @emph{Description}:
455 Initialize a simple lock. After initialization, the lock is in
459 @multitable @columnfractions .20 .80
460 @item @emph{Prototype}: @tab @code{void omp_init_lock(omp_lock_t *lock);}
463 @item @emph{Fortran}:
464 @multitable @columnfractions .20 .80
465 @item @emph{Interface}: @tab @code{subroutine omp_init_lock(lock)}
466 @item @tab @code{integer(omp_lock_kind), intent(out) :: lock}
469 @item @emph{See also}:
470 @ref{omp_destroy_lock}
472 @item @emph{Reference}:
473 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.3.1.
479 @section @code{omp_set_lock} -- Wait for and set simple lock
481 @item @emph{Description}:
482 Before setting a simple lock, the lock variable must be initialized by
483 @code{omp_init_lock}. The calling thread is blocked until the lock
484 is available. If the lock is already held by the current thread,
488 @multitable @columnfractions .20 .80
489 @item @emph{Prototype}: @tab @code{void omp_set_lock(omp_lock_t *lock);}
492 @item @emph{Fortran}:
493 @multitable @columnfractions .20 .80
494 @item @emph{Interface}: @tab @code{subroutine omp_set_lock(lock)}
495 @item @tab @code{integer(omp_lock_kind), intent(out) :: lock}
498 @item @emph{See also}:
499 @ref{omp_init_lock}, @ref{omp_test_lock}, @ref{omp_unset_lock}
501 @item @emph{Reference}:
502 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.3.3.
508 @section @code{omp_test_lock} -- Test and set simple lock if available
510 @item @emph{Description}:
511 Before setting a simple lock, the lock variable must be initialized by
512 @code{omp_init_lock}. Contrary to @code{omp_set_lock}, @code{omp_test_lock}
513 does not block if the lock is not available. This function returns
514 @code{true} upon success, @code{false} otherwise. Here, @code{true} and
515 @code{false} represent their language-specific counterparts.
518 @multitable @columnfractions .20 .80
519 @item @emph{Prototype}: @tab @code{int omp_test_lock(omp_lock_t *lock);}
522 @item @emph{Fortran}:
523 @multitable @columnfractions .20 .80
524 @item @emph{Interface}: @tab @code{subroutine omp_test_lock(lock)}
525 @item @tab @code{logical(omp_logical_kind) :: omp_test_lock}
526 @item @tab @code{integer(omp_lock_kind), intent(out) :: lock}
529 @item @emph{See also}:
530 @ref{omp_init_lock}, @ref{omp_set_lock}, @ref{omp_set_lock}
532 @item @emph{Reference}:
533 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.3.5.
539 @section @code{omp_unset_lock} -- Unset simple lock
541 @item @emph{Description}:
542 A simple lock about to be unset must have been locked by @code{omp_set_lock}
543 or @code{omp_test_lock} before. In addition, the lock must be held by the
544 thread calling @code{omp_unset_lock}. Then, the lock becomes unlocked. If one
545 ore more threads attempted to set the lock before, one of them is chosen to,
546 again, set the lock for itself.
549 @multitable @columnfractions .20 .80
550 @item @emph{Prototype}: @tab @code{void omp_unset_lock(omp_lock_t *lock);}
553 @item @emph{Fortran}:
554 @multitable @columnfractions .20 .80
555 @item @emph{Interface}: @tab @code{subroutine omp_unset_lock(lock)}
556 @item @tab @code{integer(omp_lock_kind), intent(out) :: lock}
559 @item @emph{See also}:
560 @ref{omp_set_lock}, @ref{omp_test_lock}
562 @item @emph{Reference}:
563 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.3.4.
568 @node omp_destroy_lock
569 @section @code{omp_destroy_lock} -- Destroy simple lock
571 @item @emph{Description}:
572 Destroy a simple lock. In order to be destroyed, a simple lock must be
573 in the unlocked state.
576 @multitable @columnfractions .20 .80
577 @item @emph{Prototype}: @tab @code{void omp_destroy_lock(omp_lock_t *);}
580 @item @emph{Fortran}:
581 @multitable @columnfractions .20 .80
582 @item @emph{Interface}: @tab @code{subroutine omp_destroy_lock(lock)}
583 @item @tab @code{integer(omp_lock_kind), intent(inout) :: lock}
586 @item @emph{See also}:
589 @item @emph{Reference}:
590 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.3.2.
595 @node omp_init_nest_lock
596 @section @code{omp_init_nest_lock} -- Initialize nested lock
598 @item @emph{Description}:
599 Initialize a nested lock. After initialization, the lock is in
600 an unlocked state and the nesting count is set to zero.
603 @multitable @columnfractions .20 .80
604 @item @emph{Prototype}: @tab @code{void omp_init_nest_lock(omp_nest_lock_t *lock);}
607 @item @emph{Fortran}:
608 @multitable @columnfractions .20 .80
609 @item @emph{Interface}: @tab @code{subroutine omp_init_nest_lock(lock)}
610 @item @tab @code{integer(omp_nest_lock_kind), intent(out) :: lock}
613 @item @emph{See also}:
614 @ref{omp_destroy_nest_lock}
616 @item @emph{Reference}:
617 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.3.1.
621 @node omp_set_nest_lock
622 @section @code{omp_set_nest_lock} -- Wait for and set simple lock
624 @item @emph{Description}:
625 Before setting a nested lock, the lock variable must be initialized by
626 @code{omp_init_nest_lock}. The calling thread is blocked until the lock
627 is available. If the lock is already held by the current thread, the
628 nesting count for the lock in incremented.
631 @multitable @columnfractions .20 .80
632 @item @emph{Prototype}: @tab @code{void omp_set_nest_lock(omp_nest_lock_t *lock);}
635 @item @emph{Fortran}:
636 @multitable @columnfractions .20 .80
637 @item @emph{Interface}: @tab @code{subroutine omp_set_nest_lock(lock)}
638 @item @tab @code{integer(omp_nest_lock_kind), intent(out) :: lock}
641 @item @emph{See also}:
642 @ref{omp_init_nest_lock}, @ref{omp_unset_nest_lock}
644 @item @emph{Reference}:
645 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.3.3.
650 @node omp_test_nest_lock
651 @section @code{omp_test_nest_lock} -- Test and set nested lock if available
653 @item @emph{Description}:
654 Before setting a nested lock, the lock variable must be initialized by
655 @code{omp_init_nest_lock}. Contrary to @code{omp_set_nest_lock},
656 @code{omp_test_nest_lock} does not block if the lock is not available.
657 If the lock is already held by the current thread, the new nesting count
658 is returned. Otherwise, the return value equals zero.
661 @multitable @columnfractions .20 .80
662 @item @emph{Prototype}: @tab @code{int omp_test_nest_lock(omp_nest_lock_t *lock);}
665 @item @emph{Fortran}:
666 @multitable @columnfractions .20 .80
667 @item @emph{Interface}: @tab @code{integer function omp_test_nest_lock(lock)}
668 @item @tab @code{integer(omp_integer_kind) :: omp_test_nest_lock}
669 @item @tab @code{integer(omp_nest_lock_kind), intent(inout) :: lock}
673 @item @emph{See also}:
674 @ref{omp_init_lock}, @ref{omp_set_lock}, @ref{omp_set_lock}
676 @item @emph{Reference}:
677 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.3.5.
682 @node omp_unset_nest_lock
683 @section @code{omp_unset_nest_lock} -- Unset nested lock
685 @item @emph{Description}:
686 A nested lock about to be unset must have been locked by @code{omp_set_nested_lock}
687 or @code{omp_test_nested_lock} before. In addition, the lock must be held by the
688 thread calling @code{omp_unset_nested_lock}. If the nesting count drops to zero, the
689 lock becomes unlocked. If one ore more threads attempted to set the lock before,
690 one of them is chosen to, again, set the lock for itself.
693 @multitable @columnfractions .20 .80
694 @item @emph{Prototype}: @tab @code{void omp_unset_nest_lock(omp_nest_lock_t *lock);}
697 @item @emph{Fortran}:
698 @multitable @columnfractions .20 .80
699 @item @emph{Interface}: @tab @code{subroutine omp_unset_nest_lock(lock)}
700 @item @tab @code{integer(omp_nest_lock_kind), intent(out) :: lock}
703 @item @emph{See also}:
704 @ref{omp_set_nest_lock}
706 @item @emph{Reference}:
707 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.3.4.
712 @node omp_destroy_nest_lock
713 @section @code{omp_destroy_nest_lock} -- Destroy nested lock
715 @item @emph{Description}:
716 Destroy a nested lock. In order to be destroyed, a nested lock must be
717 in the unlocked state and its nesting count must equal zero.
720 @multitable @columnfractions .20 .80
721 @item @emph{Prototype}: @tab @code{void omp_destroy_nest_lock(omp_nest_lock_t *);}
724 @item @emph{Fortran}:
725 @multitable @columnfractions .20 .80
726 @item @emph{Interface}: @tab @code{subroutine omp_destroy_nest_lock(lock)}
727 @item @tab @code{integer(omp_nest_lock_kind), intent(inout) :: lock}
730 @item @emph{See also}:
733 @item @emph{Reference}:
734 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.3.2.
740 @section @code{omp_get_wtick} -- Get timer precision
742 @item @emph{Description}:
743 Gets the timer precision, i.e., the number of seconds between two
744 successive clock ticks.
747 @multitable @columnfractions .20 .80
748 @item @emph{Prototype}: @tab @code{double omp_get_wtick();}
751 @item @emph{Fortran}:
752 @multitable @columnfractions .20 .80
753 @item @emph{Interface}: @tab @code{double precision function omp_get_wtick()}
756 @item @emph{See also}:
759 @item @emph{Reference}:
760 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.4.2.
766 @section @code{omp_get_wtime} -- Elapsed wall clock time
768 @item @emph{Description}:
769 Elapsed wall clock time in seconds. The time is measured per thread, no
770 guarantee can bee made that two distinct threads measure the same time.
771 Time is measured from some "time in the past". On POSIX compliant systems
772 the seconds since the Epoch (00:00:00 UTC, January 1, 1970) are returned.
775 @multitable @columnfractions .20 .80
776 @item @emph{Prototype}: @tab @code{double omp_get_wtime();}
779 @item @emph{Fortran}:
780 @multitable @columnfractions .20 .80
781 @item @emph{Interface}: @tab @code{double precision function omp_get_wtime()}
784 @item @emph{See also}:
787 @item @emph{Reference}:
788 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.4.1.
793 @c ---------------------------------------------------------------------
794 @c Environment Variables
795 @c ---------------------------------------------------------------------
797 @node Environment Variables
798 @chapter Environment Variables
800 The variables @env{OMP_DYNAMIC}, @env{OMP_NESTED}, @env{OMP_NUM_THREADS} and
801 @env{OMP_SCHEDULE} are defined by section 4 of the OpenMP specifications in
802 version 2.5, while @env{GOMP_CPU_AFFINITY} and @env{GOMP_STACKSIZE} are GNU
806 * OMP_DYNAMIC:: Dynamic adjustment of threads
807 * OMP_NESTED:: Nested parallel regions
808 * OMP_NUM_THREADS:: Specifies the number of threads to use
809 * OMP_SCHEDULE:: How threads are scheduled
810 * GOMP_CPU_AFFINITY:: Bind threads to specific CPUs
811 * GOMP_STACKSIZE:: Set default thread stack size
816 @section @env{OMP_DYNAMIC} -- Dynamic adjustment of threads
817 @cindex Environment Variable
818 @cindex Implementation specific setting
820 @item @emph{Description}:
821 Enable or disable the dynamic adjustment of the number of threads
822 within a team. The value of this environment variable shall be
823 @code{TRUE} or @code{FALSE}. If undefined, dynamic adjustment is
826 @item @emph{See also}:
827 @ref{omp_set_dynamic}
829 @item @emph{Reference}:
830 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 4.3
836 @section @env{OMP_NESTED} -- Nested parallel regions
837 @cindex Environment Variable
838 @cindex Implementation specific setting
840 @item @emph{Description}:
841 Enable or disable nested parallel regions, i.e., whether team members
842 are allowed to create new teams. The value of this environment variable
843 shall be @code{TRUE} or @code{FALSE}. If undefined, nested parallel
844 regions are disabled by default.
846 @item @emph{See also}:
849 @item @emph{Reference}:
850 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 4.4
855 @node OMP_NUM_THREADS
856 @section @env{OMP_NUM_THREADS} -- Specifies the number of threads to use
857 @cindex Environment Variable
858 @cindex Implementation specific setting
860 @item @emph{Description}:
861 Specifies the default number of threads to use in parallel regions. The
862 value of this variable shall be positive integer. If undefined one thread
863 per CPU online is used.
865 @item @emph{See also}:
866 @ref{omp_set_num_threads}
868 @item @emph{Reference}:
869 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 4.2
875 @section @env{OMP_SCHEDULE} -- How threads are scheduled
876 @cindex Environment Variable
877 @cindex Implementation specific setting
879 @item @emph{Description}:
880 Allows to specify @code{schedule type} and @code{chunk size}.
881 The value of the variable shall have the form: @code{type[,chunk]} where
882 @code{type} is one of @code{static}, @code{dynamic} or @code{guided}.
883 The optional @code{chunk size} shall be a positive integer. If undefined,
884 dynamic scheduling and a chunk size of 1 is used.
886 @item @emph{Reference}:
887 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, sections 2.5.1 and 4.1
892 @node GOMP_CPU_AFFINITY
893 @section @env{GOMP_CPU_AFFINITY} -- Bind threads to specific CPUs
894 @cindex Environment Variable
896 @item @emph{Description}:
897 Binds threads to specific CPUs. The variable should contain a space- or
898 comma-separated list of CPUs. This list may contain different kind of
899 entries: either single CPU numbers in any order, a range of CPUs (M-N)
900 or a range with some stride (M-N:S). CPU numbers are zero based. For example,
901 @code{GOMP_CPU_AFFINITY="0 3 1-2 4-15:2"} will bind the initial thread
902 to CPU 0, the second to CPU 3, the third to CPU 1, the fourth to
903 CPU 2, the fifth to CPU 4, the sixth through tenth to CPUs 6, 8, 10, 12,
904 and 14 respectively and then start assigning back from the beginning of
905 the list. @code{GOMP_CPU_AFFINITY=0} binds all threads to CPU 0.
907 There is no GNU OpenMP library routine to determine whether a CPU affinity
908 specification is in effect. As a workaround, language-specific library
909 functions, e.g., @code{getenv} in C or @code{GET_ENVIRONMENT_VARIABLE} in
910 Fortran, may be used to query the setting of the @code{GOMP_CPU_AFFINITY}
911 environment variable. A defined CPU affinity on startup cannot be changed
912 or disabled during the runtime of the application.
914 If this environment variable is omitted, the host system will handle the
915 assignment of threads to CPUs.
921 @section @env{GOMP_STACKSIZE} -- Set default thread stack size
922 @cindex Environment Variable
923 @cindex Implementation specific setting
925 @item @emph{Description}:
926 Set the default thread stack size in kilobytes. This is in opposition
927 to @code{pthread_attr_setstacksize} which gets the number of bytes as an
928 argument. If the stacksize can not be set due to system constraints, an
929 error is reported and the initial stacksize is left unchanged. If undefined,
930 the stack size is system dependent.
932 @item @emph{Reference}:
933 @uref{http://gcc.gnu.org/ml/gcc-patches/2006-06/msg00493.html,
934 GCC Patches Mailinglist},
935 @uref{http://gcc.gnu.org/ml/gcc-patches/2006-06/msg00496.html,
936 GCC Patches Mailinglist}
941 @c ---------------------------------------------------------------------
943 @c ---------------------------------------------------------------------
945 @node The libgomp ABI
946 @chapter The libgomp ABI
948 The following sections present notes on the external ABI as
949 presented by libgomp. Only maintainers should need them.
952 * Implementing MASTER construct::
953 * Implementing CRITICAL construct::
954 * Implementing ATOMIC construct::
955 * Implementing FLUSH construct::
956 * Implementing BARRIER construct::
957 * Implementing THREADPRIVATE construct::
958 * Implementing PRIVATE clause::
959 * Implementing FIRSTPRIVATE LASTPRIVATE COPYIN and COPYPRIVATE clauses::
960 * Implementing REDUCTION clause::
961 * Implementing PARALLEL construct::
962 * Implementing FOR construct::
963 * Implementing ORDERED construct::
964 * Implementing SECTIONS construct::
965 * Implementing SINGLE construct::
969 @node Implementing MASTER construct
970 @section Implementing MASTER construct
973 if (omp_get_thread_num () == 0)
977 Alternately, we generate two copies of the parallel subfunction
978 and only include this in the version run by the master thread.
979 Surely that's not worthwhile though...
983 @node Implementing CRITICAL construct
984 @section Implementing CRITICAL construct
986 Without a specified name,
989 void GOMP_critical_start (void);
990 void GOMP_critical_end (void);
993 so that we don't get COPY relocations from libgomp to the main
996 With a specified name, use omp_set_lock and omp_unset_lock with
997 name being transformed into a variable declared like
1000 omp_lock_t gomp_critical_user_<name> __attribute__((common))
1003 Ideally the ABI would specify that all zero is a valid unlocked
1004 state, and so we wouldn't actually need to initialize this at
1009 @node Implementing ATOMIC construct
1010 @section Implementing ATOMIC construct
1012 The target should implement the @code{__sync} builtins.
1014 Failing that we could add
1017 void GOMP_atomic_enter (void)
1018 void GOMP_atomic_exit (void)
1021 which reuses the regular lock code, but with yet another lock
1022 object private to the library.
1026 @node Implementing FLUSH construct
1027 @section Implementing FLUSH construct
1029 Expands to the @code{__sync_synchronize} builtin.
1033 @node Implementing BARRIER construct
1034 @section Implementing BARRIER construct
1037 void GOMP_barrier (void)
1041 @node Implementing THREADPRIVATE construct
1042 @section Implementing THREADPRIVATE construct
1044 In _most_ cases we can map this directly to @code{__thread}. Except
1045 that OMP allows constructors for C++ objects. We can either
1046 refuse to support this (how often is it used?) or we can
1047 implement something akin to .ctors.
1049 Even more ideally, this ctor feature is handled by extensions
1050 to the main pthreads library. Failing that, we can have a set
1051 of entry points to register ctor functions to be called.
1055 @node Implementing PRIVATE clause
1056 @section Implementing PRIVATE clause
1058 In association with a PARALLEL, or within the lexical extent
1059 of a PARALLEL block, the variable becomes a local variable in
1060 the parallel subfunction.
1062 In association with FOR or SECTIONS blocks, create a new
1063 automatic variable within the current function. This preserves
1064 the semantic of new variable creation.
1068 @node Implementing FIRSTPRIVATE LASTPRIVATE COPYIN and COPYPRIVATE clauses
1069 @section Implementing FIRSTPRIVATE LASTPRIVATE COPYIN and COPYPRIVATE clauses
1071 Seems simple enough for PARALLEL blocks. Create a private
1072 struct for communicating between parent and subfunction.
1073 In the parent, copy in values for scalar and "small" structs;
1074 copy in addresses for others TREE_ADDRESSABLE types. In the
1075 subfunction, copy the value into the local variable.
1077 Not clear at all what to do with bare FOR or SECTION blocks.
1078 The only thing I can figure is that we do something like
1081 #pragma omp for firstprivate(x) lastprivate(y)
1082 for (int i = 0; i < n; ++i)
1099 where the "x=x" and "y=y" assignments actually have different
1100 uids for the two variables, i.e. not something you could write
1101 directly in C. Presumably this only makes sense if the "outer"
1102 x and y are global variables.
1104 COPYPRIVATE would work the same way, except the structure
1105 broadcast would have to happen via SINGLE machinery instead.
1109 @node Implementing REDUCTION clause
1110 @section Implementing REDUCTION clause
1112 The private struct mentioned in the previous section should have
1113 a pointer to an array of the type of the variable, indexed by the
1114 thread's @var{team_id}. The thread stores its final value into the
1115 array, and after the barrier the master thread iterates over the
1116 array to collect the values.
1119 @node Implementing PARALLEL construct
1120 @section Implementing PARALLEL construct
1123 #pragma omp parallel
1132 void subfunction (void *data)
1139 GOMP_parallel_start (subfunction, &data, num_threads);
1140 subfunction (&data);
1141 GOMP_parallel_end ();
1145 void GOMP_parallel_start (void (*fn)(void *), void *data, unsigned num_threads)
1148 The @var{FN} argument is the subfunction to be run in parallel.
1150 The @var{DATA} argument is a pointer to a structure used to
1151 communicate data in and out of the subfunction, as discussed
1152 above with respect to FIRSTPRIVATE et al.
1154 The @var{NUM_THREADS} argument is 1 if an IF clause is present
1155 and false, or the value of the NUM_THREADS clause, if
1158 The function needs to create the appropriate number of
1159 threads and/or launch them from the dock. It needs to
1160 create the team structure and assign team ids.
1163 void GOMP_parallel_end (void)
1166 Tears down the team and returns us to the previous @code{omp_in_parallel()} state.
1170 @node Implementing FOR construct
1171 @section Implementing FOR construct
1174 #pragma omp parallel for
1175 for (i = lb; i <= ub; i++)
1182 void subfunction (void *data)
1185 while (GOMP_loop_static_next (&_s0, &_e0))
1188 for (i = _s0; i < _e1; i++)
1191 GOMP_loop_end_nowait ();
1194 GOMP_parallel_loop_static (subfunction, NULL, 0, lb, ub+1, 1, 0);
1196 GOMP_parallel_end ();
1200 #pragma omp for schedule(runtime)
1201 for (i = 0; i < n; i++)
1210 if (GOMP_loop_runtime_start (0, n, 1, &_s0, &_e0))
1213 for (i = _s0, i < _e0; i++)
1215 @} while (GOMP_loop_runtime_next (&_s0, _&e0));
1220 Note that while it looks like there is trickyness to propagating
1221 a non-constant STEP, there isn't really. We're explicitly allowed
1222 to evaluate it as many times as we want, and any variables involved
1223 should automatically be handled as PRIVATE or SHARED like any other
1224 variables. So the expression should remain evaluable in the
1225 subfunction. We can also pull it into a local variable if we like,
1226 but since its supposed to remain unchanged, we can also not if we like.
1228 If we have SCHEDULE(STATIC), and no ORDERED, then we ought to be
1229 able to get away with no work-sharing context at all, since we can
1230 simply perform the arithmetic directly in each thread to divide up
1231 the iterations. Which would mean that we wouldn't need to call any
1234 There are separate routines for handling loops with an ORDERED
1235 clause. Bookkeeping for that is non-trivial...
1239 @node Implementing ORDERED construct
1240 @section Implementing ORDERED construct
1243 void GOMP_ordered_start (void)
1244 void GOMP_ordered_end (void)
1249 @node Implementing SECTIONS construct
1250 @section Implementing SECTIONS construct
1255 #pragma omp sections
1269 for (i = GOMP_sections_start (3); i != 0; i = GOMP_sections_next ())
1286 @node Implementing SINGLE construct
1287 @section Implementing SINGLE construct
1301 if (GOMP_single_start ())
1309 #pragma omp single copyprivate(x)
1316 datap = GOMP_single_copy_start ();
1321 GOMP_single_copy_end (&data);
1330 @c ---------------------------------------------------------------------
1332 @c ---------------------------------------------------------------------
1334 @node Reporting Bugs
1335 @chapter Reporting Bugs
1337 Bugs in the GNU OpenMP implementation should be reported via
1338 @uref{http://gcc.gnu.org/bugzilla/, bugzilla}. In all cases, please add
1339 "openmp" to the keywords field in the bug report.
1343 @c ---------------------------------------------------------------------
1344 @c GNU General Public License
1345 @c ---------------------------------------------------------------------
1351 @c ---------------------------------------------------------------------
1352 @c GNU Free Documentation License
1353 @c ---------------------------------------------------------------------
1359 @c ---------------------------------------------------------------------
1360 @c Funding Free Software
1361 @c ---------------------------------------------------------------------
1363 @include funding.texi
1365 @c ---------------------------------------------------------------------
1367 @c ---------------------------------------------------------------------