1 \input texinfo @c -*-texinfo-*-
4 @setfilename libgomp.info
10 Copyright @copyright{} 2006 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.1 or
14 any later version published by the Free Software Foundation; with the
15 Invariant Sections being ``GNU General Public License'' and ``Funding
16 Free Software'', the Front-Cover
17 texts being (a) (see below), and with the Back-Cover Texts being (b)
18 (see below). A copy of the license is included in the section entitled
19 ``GNU Free Documentation License''.
21 (a) The FSF's Front-Cover Text is:
25 (b) The FSF's Back-Cover Text is:
27 You have freedom to copy and modify this GNU Manual, like GNU
28 software. Copies published by the Free Software Foundation raise
29 funds for GNU development.
33 @dircategory GNU Libraries
35 * libgomp: (libgomp). GNU OpenMP runtime library
38 This manual documents the GNU implementation of the OpenMP API for
39 multi-platform shared-memory parallel programming in C/C++ and Fortran.
41 Published by the Free Software Foundation
42 51 Franklin Street, Fifth Floor
43 Boston, MA 02110-1301 USA
49 @setchapternewpage odd
52 @title The GNU OpenMP Implementation
54 @vskip 0pt plus 1filll
55 @comment For the @value{version-GCC} Version*
57 Published by the Free Software Foundation @*
58 51 Franklin Street, Fifth Floor@*
59 Boston, MA 02110-1301, USA@*
73 This manual documents the usage of libgomp, the GNU implementation of the
74 @uref{http://www.openmp.org, OpenMP} Application Programming Interface (API)
75 for multi-platform shared-memory parallel programming in C/C++ and Fortran.
80 @comment When you add a new menu item, please keep the right hand
81 @comment aligned to the same column. Do not use tabs. This provides
82 @comment better formatting.
85 * Enabling OpenMP:: How to enable OpenMP for your applications.
86 * Runtime Library Routines:: The OpenMP runtime application programming
88 * Environment Variables:: Influencing runtime behavior with environment
90 * The libgomp ABI:: Notes on the external ABI presented by libgomp.
91 * Reporting Bugs:: How to report bugs in GNU OpenMP.
92 * Copying:: GNU general public license says
93 how you can copy and share libgomp.
94 * GNU Free Documentation License::
95 How you can copy and share this manual.
96 * Funding:: How to help assure continued work for free
98 * Index:: Index of this documentation.
102 @c ---------------------------------------------------------------------
104 @c ---------------------------------------------------------------------
106 @node Enabling OpenMP
107 @chapter Enabling OpenMP
109 To activate the OpenMP extensions for C/C++ and Fortran, the compile-time
110 flag @command{-fopenmp} must be specified. This enables the OpenMP directive
111 @code{#pragma omp} in C/C++ and @code{!$omp} directives in free form,
112 @code{c$omp}, @code{*$omp} and @code{!$omp} directives in fixed form,
113 @code{!$} conditional compilation sentinels in free form and @code{c$},
114 @code{*$} and @code{!$} sentinels in fixed form, for Fortran. The flag also
115 arranges for automatic linking of the OpenMP runtime library
116 (@ref{Runtime Library Routines}).
118 A complete description of all OpenMP directives accepted may be found in
119 the @uref{http://www.openmp.org, OpenMP Application Program Interface} manual,
123 @c ---------------------------------------------------------------------
124 @c Runtime Library Routines
125 @c ---------------------------------------------------------------------
127 @node Runtime Library Routines
128 @chapter Runtime Library Routines
130 The runtime routines described here are defined by section 3 of the OpenMP
131 specifications in version 2.5.
133 Control threads, processors and the parallel environment.
136 * omp_get_dynamic:: Dynamic teams setting
137 * omp_get_max_threads:: Maximum number of threads
138 * omp_get_nested:: Nested parallel regions
139 * omp_get_num_procs:: Number of processors online
140 * omp_get_num_threads:: Size of the active team
141 * omp_get_thread_num:: Current thread ID
142 * omp_in_parallel:: Whether a parallel region is active
143 * omp_set_dynamic:: Enable/disable dynamic teams
144 * omp_set_nested:: Enable/disable nested parallel regions
145 * omp_set_num_threads:: Set upper team size limit
148 Initialize, set, test, unset and destroy simple and nested locks.
151 * omp_init_lock:: Initialize simple lock
152 * omp_set_lock:: Wait for and set simple lock
153 * omp_test_lock:: Test and set simple lock if available
154 * omp_unset_lock:: Unset simple lock
155 * omp_destroy_lock:: Destroy simple lock
156 * omp_init_nest_lock:: Initialize nested lock
157 * omp_set_nest_lock:: Wait for and set simple lock
158 * omp_test_nest_lock:: Test and set nested lock if available
159 * omp_unset_nest_lock:: Unset nested lock
160 * omp_destroy_nest_lock:: Destroy nested lock
163 Portable, thread-based, wall clock timer.
166 * omp_get_wtick:: Get timer precision.
167 * omp_get_wtime:: Elapsed wall clock time.
170 @node omp_get_dynamic
171 @section @code{omp_get_dynamic} -- Dynamic teams setting
173 @item @emph{Description}:
174 This function returns @code{true} if enabled, @code{false} otherwise.
175 Here, @code{true} and @code{false} represent their language-specific
179 @multitable @columnfractions .20 .80
180 @item @emph{Prototype}: @tab @code{int omp_get_dynamic();}
183 @item @emph{Fortran}:
184 @multitable @columnfractions .20 .80
185 @item @emph{Interface}: @tab @code{logical function omp_get_dynamic()}
188 @item @emph{See also}:
189 @ref{omp_set_dynamic}
191 @item @emph{Reference}:
192 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.2.8.
197 @node omp_get_max_threads
198 @section @code{omp_get_max_threads} -- Maximum number of threads
200 @item @emph{Description}:
201 Return the maximum number of threads used for parallel regions that do
202 not use the clause @code{num_threads}.
205 @multitable @columnfractions .20 .80
206 @item @emph{Prototype}: @tab @code{int omp_get_max_threads();}
209 @item @emph{Fortran}:
210 @multitable @columnfractions .20 .80
211 @item @emph{Interface}: @tab @code{integer function omp_get_max_threads()}
214 @item @emph{See also}:
215 @ref{omp_set_num_threads}, @ref{omp_set_dynamic}
217 @item @emph{Reference}:
218 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.2.3.
224 @section @code{omp_get_nested} -- Nested parallel regions
226 @item @emph{Description}:
227 This function returns @code{true} if nested parallel regions are
228 enabled, @code{false} otherwise. Here, @code{true} and @code{false}
229 represent their language-specific counterparts.
232 @multitable @columnfractions .20 .80
233 @item @emph{Prototype}: @tab @code{int omp_get_nested();}
236 @item @emph{Fortran}:
237 @multitable @columnfractions .20 .80
238 @item @emph{Interface}: @tab @code{integer function omp_get_nested()}
241 @item @emph{See also}:
244 @item @emph{Reference}:
245 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.2.10.
250 @node omp_get_num_procs
251 @section @code{omp_get_num_procs} -- Number of processors online
253 @item @emph{Description}:
254 Returns the number of processors online.
257 @multitable @columnfractions .20 .80
258 @item @emph{Prototype}: @tab @code{int omp_get_num_procs();}
261 @item @emph{Fortran}:
262 @multitable @columnfractions .20 .80
263 @item @emph{Interface}: @tab @code{integer function omp_get_num_procs()}
266 @item @emph{Reference}:
267 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.2.5.
272 @node omp_get_num_threads
273 @section @code{omp_get_num_threads} -- Size of the active team
275 @item @emph{Description}:
276 The number of threads in the current team. In a sequential section of
277 the program @code{omp_get_num_threads} returns 1.
280 @multitable @columnfractions .20 .80
281 @item @emph{Prototype}: @tab @code{int omp_get_num_threads();}
284 @item @emph{Fortran}:
285 @multitable @columnfractions .20 .80
286 @item @emph{Interface}: @tab @code{integer function omp_get_num_threads()}
289 @item @emph{See also}:
290 @ref{omp_get_max_threads}, @ref{omp_set_num_threads}, @ref{OMP_NUM_THREADS}
292 @item @emph{Reference}:
293 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.2.2.
298 @node omp_get_thread_num
299 @section @code{omp_get_thread_num} -- Current thread ID
301 @item @emph{Description}:
302 Unique thread identification number. In a sequential parts of the program,
303 @code{omp_get_thread_num} always returns 0. In parallel regions the return
304 value varies from 0 to @code{omp_get_max_threads}-1 inclusive. The return
305 value of the master thread of a team is always 0.
308 @multitable @columnfractions .20 .80
309 @item @emph{Prototype}: @tab @code{int omp_get_thread_num();}
312 @item @emph{Fortran}:
313 @multitable @columnfractions .20 .80
314 @item @emph{Interface}: @tab @code{integer function omp_get_thread_num()}
317 @item @emph{See also}:
318 @ref{omp_get_max_threads}
320 @item @emph{Reference}:
321 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.2.4.
326 @node omp_in_parallel
327 @section @code{omp_in_parallel} -- Whether a parallel region is active
329 @item @emph{Description}:
330 This function returns @code{true} if currently running in parallel,
331 @code{false} otherwise. Here, @code{true} and @code{false} represent
332 their language-specific counterparts.
335 @multitable @columnfractions .20 .80
336 @item @emph{Prototype}: @tab @code{int omp_in_parallel();}
339 @item @emph{Fortran}:
340 @multitable @columnfractions .20 .80
341 @item @emph{Interface}: @tab @code{logical function omp_in_parallel()}
344 @item @emph{Reference}:
345 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.2.6.
349 @node omp_set_dynamic
350 @section @code{omp_set_dynamic} -- Enable/disable dynamic teams
352 @item @emph{Description}:
353 Enable or disable the dynamic adjustment of the number of threads
354 within a team. The function takes the language-specific equivalent
355 of @code{true} and @code{false}, where @code{true} enables dynamic
356 adjustment of team sizes and @code{false} disables it.
359 @multitable @columnfractions .20 .80
360 @item @emph{Prototype}: @tab @code{void omp_set_dynamic(int);}
363 @item @emph{Fortran}:
364 @multitable @columnfractions .20 .80
365 @item @emph{Interface}: @tab @code{subroutine omp_set_dynamic(set)}
366 @item @tab @code{integer, intent(in) :: set}
369 @item @emph{See also}:
370 @ref{OMP_DYNAMIC}, @ref{omp_get_dynamic}
372 @item @emph{Reference}:
373 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.2.7.
379 @section @code{omp_set_nested} -- Enable/disable nested parallel regions
381 @item @emph{Description}:
382 Enable or disable nested parallel regions, i. e. whether team members
383 are allowed to create new teams. The function takes the language-specific
384 equivalent of @code{true} and @code{false}, where @code{true} enables
385 dynamic adjustment of team sizes and @code{false} disables it.
388 @multitable @columnfractions .20 .80
389 @item @emph{Prototype}: @tab @code{void omp_set_dynamic(int);}
392 @item @emph{Fortran}:
393 @multitable @columnfractions .20 .80
394 @item @emph{Interface}: @tab @code{subroutine omp_set_dynamic(set)}
395 @item @tab @code{integer, intent(in) :: set}
398 @item @emph{See also}:
399 @ref{OMP_NESTED}, @ref{omp_get_nested}
401 @item @emph{Reference}:
402 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.2.9.
407 @node omp_set_num_threads
408 @section @code{omp_set_num_threads} -- Set upper team size limit
410 @item @emph{Description}:
411 Specifies the number of threads used by default in subsequent parallel
412 sections, if those do not specify a @code{num_threads} clause. The
413 argument of @code{omp_set_num_threads} shall be a positive integer.
416 @multitable @columnfractions .20 .80
417 @item @emph{Prototype}: @tab @code{void omp_set_num_threads(int);}
420 @item @emph{Fortran}:
421 @multitable @columnfractions .20 .80
422 @item @emph{Interface}: @tab @code{subroutine omp_set_num_threads(set)}
423 @item @tab @code{integer, intent(in) :: set}
426 @item @emph{See also}:
427 @ref{OMP_NUM_THREADS}, @ref{omp_get_num_threads}, @ref{omp_get_max_threads}
429 @item @emph{Reference}:
430 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.2.1.
436 @section @code{omp_init_lock} -- Initialize simple lock
438 @item @emph{Description}:
439 Initialize a simple lock. After initialization, the lock is in
443 @multitable @columnfractions .20 .80
444 @item @emph{Prototype}: @tab @code{void omp_init_lock(omp_lock_t *lock);}
447 @item @emph{Fortran}:
448 @multitable @columnfractions .20 .80
449 @item @emph{Interface}: @tab @code{subroutine omp_init_lock(lock)}
450 @item @tab @code{integer(omp_lock_kind), intent(out) :: lock}
453 @item @emph{See also}:
454 @ref{omp_destroy_lock}
456 @item @emph{Reference}:
457 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.3.1.
463 @section @code{omp_set_lock} -- Wait for and set simple lock
465 @item @emph{Description}:
466 Before setting a simple lock, the lock variable must be initialized by
467 @code{omp_init_lock}. The calling thread is blocked until the lock
468 is available. If the lock is already held by the current thread,
472 @multitable @columnfractions .20 .80
473 @item @emph{Prototype}: @tab @code{void omp_set_lock(omp_lock_t *lock);}
476 @item @emph{Fortran}:
477 @multitable @columnfractions .20 .80
478 @item @emph{Interface}: @tab @code{subroutine omp_set_lock(lock)}
479 @item @tab @code{integer(omp_lock_kind), intent(out) :: lock}
482 @item @emph{See also}:
483 @ref{omp_init_lock}, @ref{omp_test_lock}, @ref{omp_unset_lock}
485 @item @emph{Reference}:
486 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.3.3.
492 @section @code{omp_test_lock} -- Test and set simple lock if available
494 @item @emph{Description}:
495 Before setting a simple lock, the lock variable must be initialized by
496 @code{omp_init_lock}. Contrary to @code{omp_set_lock}, @code{omp_test_lock}
497 does not block if the lock is not available. This function returns
498 @code{true} upon success,@code{false} otherwise. Here, @code{true} and
499 @code{false} represent their language-specific counterparts.
502 @multitable @columnfractions .20 .80
503 @item @emph{Prototype}: @tab @code{int omp_test_lock(omp_lock_t *lock);}
506 @item @emph{Fortran}:
507 @multitable @columnfractions .20 .80
508 @item @emph{Interface}: @tab @code{subroutine omp_test_lock(lock)}
509 @item @tab @code{logical(omp_logical_kind) :: omp_test_lock}
510 @item @tab @code{integer(omp_lock_kind), intent(out) :: lock}
513 @item @emph{See also}:
514 @ref{omp_init_lock}, @ref{omp_set_lock}, @ref{omp_set_lock}
516 @item @emph{Reference}:
517 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.3.5.
523 @section @code{omp_unset_lock} -- Unset simple lock
525 @item @emph{Description}:
526 A simple lock about to be unset must have been locked by @code{omp_set_lock}
527 or @code{omp_test_lock} before. In addition, the lock must be held by the
528 thread calling @code{omp_unset_lock}. Then, the lock becomes unlocked. If one
529 ore more threads attempted to set the lock before, one of them is chosen to,
530 again, set the lock for itself.
533 @multitable @columnfractions .20 .80
534 @item @emph{Prototype}: @tab @code{void omp_unset_lock(omp_lock_t *lock);}
537 @item @emph{Fortran}:
538 @multitable @columnfractions .20 .80
539 @item @emph{Interface}: @tab @code{subroutine omp_unset_lock(lock)}
540 @item @tab @code{integer(omp_lock_kind), intent(out) :: lock}
543 @item @emph{See also}:
544 @ref{omp_set_lock}, @ref{omp_test_lock}
546 @item @emph{Reference}:
547 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.3.4.
552 @node omp_destroy_lock
553 @section @code{omp_destroy_lock} -- Destroy simple lock
555 @item @emph{Description}:
556 Destroy a simple lock. In order to be destroyed, a simple lock must be
557 in the unlocked state.
560 @multitable @columnfractions .20 .80
561 @item @emph{Prototype}: @tab @code{void omp_destroy_lock(omp_lock_t *);}
564 @item @emph{Fortran}:
565 @multitable @columnfractions .20 .80
566 @item @emph{Interface}: @tab @code{subroutine omp_destroy_lock(lock)}
567 @item @tab @code{integer(omp_lock_kind), intent(inout) :: lock}
570 @item @emph{See also}:
573 @item @emph{Reference}:
574 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.3.2.
579 @node omp_init_nest_lock
580 @section @code{omp_init_nest_lock} -- Initialize nested lock
582 @item @emph{Description}:
583 Initialize a nested lock. After initialization, the lock is in
584 an unlocked state and the nesting count is set to zero.
587 @multitable @columnfractions .20 .80
588 @item @emph{Prototype}: @tab @code{void omp_init_nest_lock(omp_nest_lock_t *lock);}
591 @item @emph{Fortran}:
592 @multitable @columnfractions .20 .80
593 @item @emph{Interface}: @tab @code{subroutine omp_init_nest_lock(lock)}
594 @item @tab @code{integer(omp_nest_lock_kind), intent(out) :: lock}
597 @item @emph{See also}:
598 @ref{omp_destroy_nest_lock}
600 @item @emph{Reference}:
601 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.3.1.
605 @node omp_set_nest_lock
606 @section @code{omp_set_nest_lock} -- Wait for and set simple lock
608 @item @emph{Description}:
609 Before setting a nested lock, the lock variable must be initialized by
610 @code{omp_init_nest_lock}. The calling thread is blocked until the lock
611 is available. If the lock is already held by the current thread, the
612 nesting count for the lock in incremented.
615 @multitable @columnfractions .20 .80
616 @item @emph{Prototype}: @tab @code{void omp_set_nest_lock(omp_nest_lock_t *lock);}
619 @item @emph{Fortran}:
620 @multitable @columnfractions .20 .80
621 @item @emph{Interface}: @tab @code{subroutine omp_set_nest_lock(lock)}
622 @item @tab @code{integer(omp_nest_lock_kind), intent(out) :: lock}
625 @item @emph{See also}:
626 @ref{omp_init_nest_lock}, @ref{omp_unset_nest_lock}
628 @item @emph{Reference}:
629 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.3.3.
634 @node omp_test_nest_lock
635 @section @code{omp_test_nest_lock} -- Test and set nested lock if available
637 @item @emph{Description}:
638 Before setting a nested lock, the lock variable must be initialized by
639 @code{omp_init_nest_lock}. Contrary to @code{omp_set_nest_lock},
640 @code{omp_test_nest_lock} does not block if the lock is not available.
641 If the lock is already held by the current thread, the new nesting count
642 is returned. Otherwise, the return value equals zero.
645 @multitable @columnfractions .20 .80
646 @item @emph{Prototype}: @tab @code{int omp_test_nest_lock(omp_nest_lock_t *lock);}
649 @item @emph{Fortran}:
650 @multitable @columnfractions .20 .80
651 @item @emph{Interface}: @tab @code{integer function omp_test_nest_lock(lock)}
652 @item @tab @code{integer(omp_integer_kind) :: omp_test_nest_lock}
653 @item @tab @code{integer(omp_nest_lock_kind), intent(inout) :: lock}
657 @item @emph{See also}:
658 @ref{omp_init_lock}, @ref{omp_set_lock}, @ref{omp_set_lock}
660 @item @emph{Reference}:
661 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.3.5.
666 @node omp_unset_nest_lock
667 @section @code{omp_unset_nest_lock} -- Unset nested lock
669 @item @emph{Description}:
670 A nested lock about to be unset must have been locked by @code{omp_set_nested_lock}
671 or @code{omp_test_nested_lock} before. In addition, the lock must be held by the
672 thread calling @code{omp_unset_nested_lock}. If the nesting count drops to zero, the
673 lock becomes unlocked. If one ore more threads attempted to set the lock before,
674 one of them is chosen to, again, set the lock for itself.
677 @multitable @columnfractions .20 .80
678 @item @emph{Prototype}: @tab @code{void omp_unset_nest_lock(omp_nest_lock_t *lock);}
681 @item @emph{Fortran}:
682 @multitable @columnfractions .20 .80
683 @item @emph{Interface}: @tab @code{subroutine omp_unset_nest_lock(lock)}
684 @item @tab @code{integer(omp_nest_lock_kind), intent(out) :: lock}
687 @item @emph{See also}:
688 @ref{omp_set_nest_lock}
690 @item @emph{Reference}:
691 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.3.4.
696 @node omp_destroy_nest_lock
697 @section @code{omp_destroy_nest_lock} -- Destroy nested lock
699 @item @emph{Description}:
700 Destroy a nested lock. In order to be destroyed, a nested lock must be
701 in the unlocked state and its nesting count must equal zero.
704 @multitable @columnfractions .20 .80
705 @item @emph{Prototype}: @tab @code{void omp_destroy_nest_lock(omp_nest_lock_t *);}
708 @item @emph{Fortran}:
709 @multitable @columnfractions .20 .80
710 @item @emph{Interface}: @tab @code{subroutine omp_destroy_nest_lock(lock)}
711 @item @tab @code{integer(omp_nest_lock_kind), intent(inout) :: lock}
714 @item @emph{See also}:
717 @item @emph{Reference}:
718 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.3.2.
724 @section @code{omp_get_wtick} -- Get timer precision
726 @item @emph{Description}:
727 Gets the timer precision, i. e. the number of seconds between two
728 successive clock ticks.
731 @multitable @columnfractions .20 .80
732 @item @emph{Prototype}: @tab @code{double omp_get_wtick();}
735 @item @emph{Fortran}:
736 @multitable @columnfractions .20 .80
737 @item @emph{Interface}: @tab @code{double precision function omp_get_wtick()}
740 @item @emph{See also}:
743 @item @emph{Reference}:
744 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.4.2.
750 @section @code{omp_get_wtime} -- Elapsed wall clock time
752 @item @emph{Description}:
753 Elapsed wall clock time in seconds. The time is measured per thread, no
754 guarantee can bee made that two distinct threads measure the same time.
755 Time is measured from some "time in the past". On POSIX compliant systems
756 the seconds since the Epoch (00:00:00 UTC, January 1, 1970) are returned.
759 @multitable @columnfractions .20 .80
760 @item @emph{Prototype}: @tab @code{double omp_get_wtime();}
763 @item @emph{Fortran}:
764 @multitable @columnfractions .20 .80
765 @item @emph{Interface}: @tab @code{double precision function omp_get_wtime()}
768 @item @emph{See also}:
771 @item @emph{Reference}:
772 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.4.1.
777 @c ---------------------------------------------------------------------
778 @c Environment Variables
779 @c ---------------------------------------------------------------------
781 @node Environment Variables
782 @chapter Environment Variables
784 The variables @env{OMP_DYNAMIC}, @env{OMP_NESTED}, @env{OMP_NUM_THREADS} and
785 @env{OMP_SCHEDULE} are defined by section 4 of the OpenMP specifications in
786 version 2.5, while @env{GOMP_CPU_AFFINITY} and @env{GOMP_STACKSIZE} are GNU
790 * OMP_DYNAMIC:: Dynamic adjustment of threads
791 * OMP_NESTED:: Nested parallel regions
792 * OMP_NUM_THREADS:: Specifies the number of threads to use
793 * OMP_SCHEDULE:: How threads are scheduled
794 * GOMP_CPU_AFFINITY:: Bind threads to specific CPUs
795 * GOMP_STACKSIZE:: Set default thread stack size
800 @section @env{OMP_DYNAMIC} -- Dynamic adjustment of threads
801 @cindex Environment Variable
803 @item @emph{Description}:
804 Enable or disable the dynamic adjustment of the number of threads
805 within a team. The value of this environment variable shall be
806 @code{TRUE} or @code{FALSE}. If undefined, dynamic adjustment is
809 @item @emph{See also}:
810 @ref{omp_set_dynamic}
812 @item @emph{Reference}:
813 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 4.3
819 @section @env{OMP_NESTED} -- Nested parallel regions
820 @cindex Environment Variable
822 @item @emph{Description}:
823 Enable or disable nested parallel regions, i. e. whether team members
824 are allowed to create new teams. The value of this environment variable
825 shall be @code{TRUE} or @code{FALSE}. If undefined, nested parallel
826 regions are disabled by default.
828 @item @emph{See also}:
831 @item @emph{Reference}:
832 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 4.4
837 @node OMP_NUM_THREADS
838 @section @env{OMP_NUM_THREADS} -- Specifies the number of threads to use
839 @cindex Environment Variable
841 @item @emph{Description}:
842 Specifies the number of threads to use in parallel regions. If undefined
843 one thread per CPU online is used. The value of this variable shall be
846 @item @emph{See also}:
847 @ref{omp_set_num_threads}
849 @item @emph{Reference}:
850 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 4.2
856 @section @env{OMP_SCHEDULE} -- How threads are scheduled
857 @cindex Environment Variable
859 @item @emph{Description}:
860 Allows to specify @code{schedule type} and @code{chunk size}.
861 The value of the variable shall have the form: @code{type[,chunk]} where
862 @code{type} is one of @code{static}, @code{dynamic} or @code{guided}.
863 The optional @code{chunk size} shall be a positive integer. If undefined,
864 dynamic scheduling and a chunk size of 1 is used.
866 @item @emph{Reference}:
867 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, sections 2.5.1 and 4.1
872 @node GOMP_CPU_AFFINITY
873 @section @env{GOMP_CPU_AFFINITY} -- Bind threads to specific CPUs
874 @cindex Environment Variable
876 @item @emph{Description}:
877 A patch for this extension has been submitted, but was not yet applied at the
880 @item @emph{Reference}:
881 @uref{http://gcc.gnu.org/ml/gcc-patches/2006-05/msg00982.html,
882 GCC Patches Mailinglist}
883 @uref{http://gcc.gnu.org/ml/gcc-patches/2006-05/msg01133.html,
884 GCC Patches Mailinglist}
890 @section @env{GOMP_STACKSIZE} -- Set default thread stack size
891 @cindex Environment Variable
893 @item @emph{Description}:
894 Set the default thread stack size in kilobytes. This is in opposition
895 to @code{pthread_attr_setstacksize} which gets the number of bytes as an
896 argument. If the stacksize can not be set due to system constraints, an
897 error is reported and the initial stacksize is left unchanged. If undefined,
898 the stack size is system dependent.
900 @item @emph{Reference}:
901 @uref{http://gcc.gnu.org/ml/gcc-patches/2006-06/msg00493.html,
902 GCC Patches Mailinglist},
903 @uref{http://gcc.gnu.org/ml/gcc-patches/2006-06/msg00496.html,
904 GCC Patches Mailinglist}
909 @c ---------------------------------------------------------------------
911 @c ---------------------------------------------------------------------
913 @node The libgomp ABI
914 @chapter The libgomp ABI
916 The following sections present notes on the external ABI as
917 presented by libgomp. Only maintainers should need them.
920 * Implementing MASTER construct::
921 * Implementing CRITICAL construct::
922 * Implementing ATOMIC construct::
923 * Implementing FLUSH construct::
924 * Implementing BARRIER construct::
925 * Implementing THREADPRIVATE construct::
926 * Implementing PRIVATE clause::
927 * Implementing FIRSTPRIVATE LASTPRIVATE COPYIN and COPYPRIVATE clauses::
928 * Implementing REDUCTION clause::
929 * Implementing PARALLEL construct::
930 * Implementing FOR construct::
931 * Implementing ORDERED construct::
932 * Implementing SECTIONS construct::
933 * Implementing SINGLE construct::
937 @node Implementing MASTER construct
938 @section Implementing MASTER construct
941 if (omp_get_thread_num () == 0)
945 Alternately, we generate two copies of the parallel subfunction
946 and only include this in the version run by the master thread.
947 Surely that's not worthwhile though...
951 @node Implementing CRITICAL construct
952 @section Implementing CRITICAL construct
954 Without a specified name,
957 void GOMP_critical_start (void);
958 void GOMP_critical_end (void);
961 so that we don't get COPY relocations from libgomp to the main
964 With a specified name, use omp_set_lock and omp_unset_lock with
965 name being transformed into a variable declared like
968 omp_lock_t gomp_critical_user_<name> __attribute__((common))
971 Ideally the ABI would specify that all zero is a valid unlocked
972 state, and so we wouldn't actually need to initialize this at
977 @node Implementing ATOMIC construct
978 @section Implementing ATOMIC construct
980 The target should implement the @code{__sync} builtins.
982 Failing that we could add
985 void GOMP_atomic_enter (void)
986 void GOMP_atomic_exit (void)
989 which reuses the regular lock code, but with yet another lock
990 object private to the library.
994 @node Implementing FLUSH construct
995 @section Implementing FLUSH construct
997 Expands to the @code{__sync_synchronize} builtin.
1001 @node Implementing BARRIER construct
1002 @section Implementing BARRIER construct
1005 void GOMP_barrier (void)
1009 @node Implementing THREADPRIVATE construct
1010 @section Implementing THREADPRIVATE construct
1012 In _most_ cases we can map this directly to @code{__thread}. Except
1013 that OMP allows constructors for C++ objects. We can either
1014 refuse to support this (how often is it used?) or we can
1015 implement something akin to .ctors.
1017 Even more ideally, this ctor feature is handled by extensions
1018 to the main pthreads library. Failing that, we can have a set
1019 of entry points to register ctor functions to be called.
1023 @node Implementing PRIVATE clause
1024 @section Implementing PRIVATE clause
1026 In association with a PARALLEL, or within the lexical extent
1027 of a PARALLEL block, the variable becomes a local variable in
1028 the parallel subfunction.
1030 In association with FOR or SECTIONS blocks, create a new
1031 automatic variable within the current function. This preserves
1032 the semantic of new variable creation.
1036 @node Implementing FIRSTPRIVATE LASTPRIVATE COPYIN and COPYPRIVATE clauses
1037 @section Implementing FIRSTPRIVATE LASTPRIVATE COPYIN and COPYPRIVATE clauses
1039 Seems simple enough for PARALLEL blocks. Create a private
1040 struct for communicating between parent and subfunction.
1041 In the parent, copy in values for scalar and "small" structs;
1042 copy in addresses for others TREE_ADDRESSABLE types. In the
1043 subfunction, copy the value into the local variable.
1045 Not clear at all what to do with bare FOR or SECTION blocks.
1046 The only thing I can figure is that we do something like
1049 #pragma omp for firstprivate(x) lastprivate(y)
1050 for (int i = 0; i < n; ++i)
1067 where the "x=x" and "y=y" assignments actually have different
1068 uids for the two variables, i.e. not something you could write
1069 directly in C. Presumably this only makes sense if the "outer"
1070 x and y are global variables.
1072 COPYPRIVATE would work the same way, except the structure
1073 broadcast would have to happen via SINGLE machinery instead.
1077 @node Implementing REDUCTION clause
1078 @section Implementing REDUCTION clause
1080 The private struct mentioned in the previous section should have
1081 a pointer to an array of the type of the variable, indexed by the
1082 thread's @var{team_id}. The thread stores its final value into the
1083 array, and after the barrier the master thread iterates over the
1084 array to collect the values.
1087 @node Implementing PARALLEL construct
1088 @section Implementing PARALLEL construct
1091 #pragma omp parallel
1100 void subfunction (void *data)
1107 GOMP_parallel_start (subfunction, &data, num_threads);
1108 subfunction (&data);
1109 GOMP_parallel_end ();
1113 void GOMP_parallel_start (void (*fn)(void *), void *data, unsigned num_threads)
1116 The @var{FN} argument is the subfunction to be run in parallel.
1118 The @var{DATA} argument is a pointer to a structure used to
1119 communicate data in and out of the subfunction, as discussed
1120 above wrt FIRSTPRIVATE et al.
1122 The @var{NUM_THREADS} argument is 1 if an IF clause is present
1123 and false, or the value of the NUM_THREADS clause, if
1126 The function needs to create the appropriate number of
1127 threads and/or launch them from the dock. It needs to
1128 create the team structure and assign team ids.
1131 void GOMP_parallel_end (void)
1134 Tears down the team and returns us to the previous @code{omp_in_parallel()} state.
1138 @node Implementing FOR construct
1139 @section Implementing FOR construct
1142 #pragma omp parallel for
1143 for (i = lb; i <= ub; i++)
1150 void subfunction (void *data)
1153 while (GOMP_loop_static_next (&_s0, &_e0))
1156 for (i = _s0; i < _e1; i++)
1159 GOMP_loop_end_nowait ();
1162 GOMP_parallel_loop_static (subfunction, NULL, 0, lb, ub+1, 1, 0);
1164 GOMP_parallel_end ();
1168 #pragma omp for schedule(runtime)
1169 for (i = 0; i < n; i++)
1178 if (GOMP_loop_runtime_start (0, n, 1, &_s0, &_e0))
1181 for (i = _s0, i < _e0; i++)
1183 @} while (GOMP_loop_runtime_next (&_s0, _&e0));
1188 Note that while it looks like there is trickyness to propagating
1189 a non-constant STEP, there isn't really. We're explicitly allowed
1190 to evaluate it as many times as we want, and any variables involved
1191 should automatically be handled as PRIVATE or SHARED like any other
1192 variables. So the expression should remain evaluable in the
1193 subfunction. We can also pull it into a local variable if we like,
1194 but since its supposed to remain unchanged, we can also not if we like.
1196 If we have SCHEDULE(STATIC), and no ORDERED, then we ought to be
1197 able to get away with no work-sharing context at all, since we can
1198 simply perform the arithmetic directly in each thread to divide up
1199 the iterations. Which would mean that we wouldn't need to call any
1202 There are separate routines for handling loops with an ORDERED
1203 clause. Bookkeeping for that is non-trivial...
1207 @node Implementing ORDERED construct
1208 @section Implementing ORDERED construct
1211 void GOMP_ordered_start (void)
1212 void GOMP_ordered_end (void)
1217 @node Implementing SECTIONS construct
1218 @section Implementing SECTIONS construct
1223 #pragma omp sections
1237 for (i = GOMP_sections_start (3); i != 0; i = GOMP_sections_next ())
1254 @node Implementing SINGLE construct
1255 @section Implementing SINGLE construct
1269 if (GOMP_single_start ())
1277 #pragma omp single copyprivate(x)
1284 datap = GOMP_single_copy_start ();
1289 GOMP_single_copy_end (&data);
1298 @c ---------------------------------------------------------------------
1300 @c ---------------------------------------------------------------------
1302 @node Reporting Bugs
1303 @chapter Reporting Bugs
1305 Bugs in the GNU OpenMP implementation should be reported via
1306 @uref{http://gcc.gnu.org/bugzilla/, bugzilla}. In all cases, please add
1307 "openmp" to the keywords field in the bug report.
1311 @c ---------------------------------------------------------------------
1312 @c GNU General Public License
1313 @c ---------------------------------------------------------------------
1319 @c ---------------------------------------------------------------------
1320 @c GNU Free Documentation License
1321 @c ---------------------------------------------------------------------
1327 @c ---------------------------------------------------------------------
1328 @c Funding Free Software
1329 @c ---------------------------------------------------------------------
1331 @include funding.texi
1333 @c ---------------------------------------------------------------------
1335 @c ---------------------------------------------------------------------