OSDN Git Service

2006-12-21 Daniel Franke <franke.daniel@gmail.com>
[pf3gnuchains/gcc-fork.git] / libgomp / libgomp.texi
1 \input texinfo @c -*-texinfo-*-
2
3 @c %**start of header
4 @setfilename libgomp.info
5 @settitle GNU libgomp
6 @c %**end of header
7
8
9 @copying
10 Copyright @copyright{} 2006 Free Software Foundation, Inc.
11
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''.
20
21 (a) The FSF's Front-Cover Text is:
22
23      A GNU Manual
24
25 (b) The FSF's Back-Cover Text is:
26
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.
30 @end copying
31
32 @ifinfo
33 @dircategory GNU Libraries
34 @direntry
35 * libgomp: (libgomp).                    GNU OpenMP runtime library
36 @end direntry
37
38 This manual documents the GNU implementation of the OpenMP API for 
39 multi-platform shared-memory parallel programming in C/C++ and Fortran.
40
41 Published by the Free Software Foundation
42 51 Franklin Street, Fifth Floor
43 Boston, MA 02110-1301 USA
44
45 @insertcopying
46 @end ifinfo
47
48
49 @setchapternewpage odd
50
51 @titlepage
52 @title The GNU OpenMP Implementation
53 @page
54 @vskip 0pt plus 1filll
55 @comment For the @value{version-GCC} Version*
56 @sp 1
57 Published by the Free Software Foundation @*
58 51 Franklin Street, Fifth Floor@*
59 Boston, MA 02110-1301, USA@*
60 @sp 1
61 @insertcopying
62 @end titlepage
63
64 @summarycontents
65 @contents
66 @page
67
68
69 @node Top
70 @top Introduction
71 @cindex Introduction
72
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.
76
77
78
79 @comment
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.
83 @comment
84 @menu
85 * Enabling OpenMP::            How to enable OpenMP for your applications.
86 * Runtime Library Routines::   The OpenMP runtime application programming 
87                                interface.
88 * Environment Variables::      Influencing runtime behavior with environment 
89                                variables.
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 
97                                software.
98 * Index::                      Index of this documentation.
99 @end menu
100
101
102 @c ---------------------------------------------------------------------
103 @c Enabling OpenMP
104 @c ---------------------------------------------------------------------
105
106 @node Enabling OpenMP
107 @chapter Enabling OpenMP
108
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}).
117
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,
120 version 2.5.
121
122
123 @c ---------------------------------------------------------------------
124 @c Runtime Library Routines
125 @c ---------------------------------------------------------------------
126
127 @node Runtime Library Routines
128 @chapter Runtime Library Routines
129
130 The runtime routines described here are defined by section 3 of the OpenMP 
131 specifications in version 2.5.
132
133 Control threads, processors and the parallel environment.
134
135 @menu
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
146 @end menu
147
148 Initialize, set, test, unset and destroy simple and nested locks.
149
150 @menu
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
161 @end menu
162
163 Portable, thread-based, wall clock timer.
164
165 @menu
166 * omp_get_wtick::            Get timer precision.
167 * omp_get_wtime::            Elapsed wall clock time.
168 @end menu
169
170 @node omp_get_dynamic
171 @section @code{omp_get_dynamic} -- Dynamic teams setting
172 @table @asis
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 
176 counterparts.
177
178 @item @emph{C/C++}:
179 @multitable @columnfractions .20 .80
180 @item @emph{Prototype}: @tab @code{int omp_get_dynamic();}
181 @end multitable
182
183 @item @emph{Fortran}:
184 @multitable @columnfractions .20 .80
185 @item @emph{Interface}: @tab @code{logical function omp_get_dynamic()}
186 @end multitable
187
188 @item @emph{See also}:
189 @ref{omp_set_dynamic}
190
191 @item @emph{Reference}:
192 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.2.8.
193 @end table
194
195
196
197 @node omp_get_max_threads
198 @section @code{omp_get_max_threads} -- Maximum number of threads
199 @table @asis
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}.
203
204 @item @emph{C/C++}:
205 @multitable @columnfractions .20 .80
206 @item @emph{Prototype}: @tab @code{int omp_get_max_threads();}
207 @end multitable
208
209 @item @emph{Fortran}:
210 @multitable @columnfractions .20 .80
211 @item @emph{Interface}: @tab @code{integer function omp_get_max_threads()}
212 @end multitable
213
214 @item @emph{See also}:
215 @ref{omp_set_num_threads}, @ref{omp_set_dynamic}
216
217 @item @emph{Reference}:
218 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.2.3.
219 @end table
220
221
222
223 @node omp_get_nested
224 @section @code{omp_get_nested} -- Nested parallel regions
225 @table @asis
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.
230
231 @item @emph{C/C++}:
232 @multitable @columnfractions .20 .80
233 @item @emph{Prototype}: @tab @code{int omp_get_nested();}
234 @end multitable
235
236 @item @emph{Fortran}:
237 @multitable @columnfractions .20 .80
238 @item @emph{Interface}: @tab @code{integer function omp_get_nested()}
239 @end multitable
240
241 @item @emph{See also}:
242 @ref{omp_set_nested}
243
244 @item @emph{Reference}:
245 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.2.10.
246 @end table
247
248
249
250 @node omp_get_num_procs
251 @section @code{omp_get_num_procs} -- Number of processors online
252 @table @asis
253 @item @emph{Description}:
254 Returns the number of processors online.
255
256 @item @emph{C/C++}:
257 @multitable @columnfractions .20 .80
258 @item @emph{Prototype}: @tab @code{int omp_get_num_procs();}
259 @end multitable
260
261 @item @emph{Fortran}:
262 @multitable @columnfractions .20 .80
263 @item @emph{Interface}: @tab @code{integer function omp_get_num_procs()}
264 @end multitable
265
266 @item @emph{Reference}:
267 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.2.5.
268 @end table
269
270
271
272 @node omp_get_num_threads
273 @section @code{omp_get_num_threads} -- Size of the active team
274 @table @asis
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.
278
279 @item @emph{C/C++}:
280 @multitable @columnfractions .20 .80
281 @item @emph{Prototype}: @tab @code{int omp_get_num_threads();}
282 @end multitable
283
284 @item @emph{Fortran}:
285 @multitable @columnfractions .20 .80
286 @item @emph{Interface}: @tab @code{integer function omp_get_num_threads()}
287 @end multitable
288
289 @item @emph{See also}:
290 @ref{omp_get_max_threads}, @ref{omp_set_num_threads}, @ref{OMP_NUM_THREADS}
291
292 @item @emph{Reference}:
293 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.2.2.
294 @end table
295
296
297
298 @node omp_get_thread_num 
299 @section @code{omp_get_thread_num} -- Current thread ID
300 @table @asis
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.
306
307 @item @emph{C/C++}:
308 @multitable @columnfractions .20 .80
309 @item @emph{Prototype}: @tab @code{int omp_get_thread_num();}
310 @end multitable
311
312 @item @emph{Fortran}:
313 @multitable @columnfractions .20 .80
314 @item @emph{Interface}: @tab @code{integer function omp_get_thread_num()}
315 @end multitable
316
317 @item @emph{See also}:
318 @ref{omp_get_max_threads}
319
320 @item @emph{Reference}:
321 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.2.4.
322 @end table
323
324
325
326 @node omp_in_parallel
327 @section @code{omp_in_parallel} -- Whether a parallel region is active
328 @table @asis
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.
333
334 @item @emph{C/C++}:
335 @multitable @columnfractions .20 .80
336 @item @emph{Prototype}: @tab @code{int omp_in_parallel();}
337 @end multitable
338
339 @item @emph{Fortran}:
340 @multitable @columnfractions .20 .80
341 @item @emph{Interface}: @tab @code{logical function omp_in_parallel()}
342 @end multitable
343
344 @item @emph{Reference}:
345 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.2.6.
346 @end table
347
348
349 @node omp_set_dynamic
350 @section @code{omp_set_dynamic} -- Enable/disable dynamic teams
351 @table @asis
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.
357
358 @item @emph{C/C++}:
359 @multitable @columnfractions .20 .80
360 @item @emph{Prototype}: @tab @code{void omp_set_dynamic(int);}
361 @end multitable
362
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}
367 @end multitable
368
369 @item @emph{See also}:
370 @ref{OMP_DYNAMIC}, @ref{omp_get_dynamic}
371
372 @item @emph{Reference}:
373 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.2.7.
374 @end table
375
376
377
378 @node omp_set_nested
379 @section @code{omp_set_nested} -- Enable/disable nested parallel regions
380 @table @asis
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.
386
387 @item @emph{C/C++}:
388 @multitable @columnfractions .20 .80
389 @item @emph{Prototype}: @tab @code{void omp_set_dynamic(int);}
390 @end multitable
391
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}
396 @end multitable
397
398 @item @emph{See also}:
399 @ref{OMP_NESTED}, @ref{omp_get_nested}
400
401 @item @emph{Reference}:
402 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.2.9.
403 @end table
404
405
406
407 @node omp_set_num_threads
408 @section @code{omp_set_num_threads} -- Set upper team size limit
409 @table @asis
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. 
414
415 If the argument is negative integer or zero, the application will crash or
416 stop, respectively. An enhancement request was filed,
417 @uref{http://gcc.gnu.org/bugzilla/show_bug.cgi?id=29949, PR29949}.
418
419 @item @emph{C/C++}:
420 @multitable @columnfractions .20 .80
421 @item @emph{Prototype}: @tab @code{void omp_set_num_threads(int);}
422 @end multitable
423
424 @item @emph{Fortran}:
425 @multitable @columnfractions .20 .80
426 @item @emph{Interface}: @tab @code{subroutine omp_set_num_threads(set)}
427 @item                   @tab @code{integer, intent(in) :: set}
428 @end multitable
429
430 @item @emph{See also}:
431 @ref{OMP_NUM_THREADS}, @ref{omp_get_num_threads}, @ref{omp_get_max_threads}
432
433 @item @emph{Reference}:
434 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.2.1.
435 @end table
436
437
438
439 @node omp_init_lock
440 @section @code{omp_init_lock} -- Initialize simple lock
441 @table @asis
442 @item @emph{Description}:
443 Initialize a simple lock. After initialization, the lock is in 
444 an unlocked state.
445
446 @item @emph{C/C++}:
447 @multitable @columnfractions .20 .80
448 @item @emph{Prototype}: @tab @code{void omp_init_lock(omp_lock_t *lock);}
449 @end multitable
450
451 @item @emph{Fortran}:
452 @multitable @columnfractions .20 .80
453 @item @emph{Interface}: @tab @code{subroutine omp_init_lock(lock)}
454 @item                   @tab @code{integer(omp_lock_kind), intent(out) :: lock}
455 @end multitable
456
457 @item @emph{See also}:
458 @ref{omp_destroy_lock}
459
460 @item @emph{Reference}: 
461 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.3.1.
462 @end table
463
464
465
466 @node omp_set_lock
467 @section @code{omp_set_lock} -- Wait for and set simple lock
468 @table @asis
469 @item @emph{Description}:
470 Before setting a simple lock, the lock variable must be initialized by 
471 @code{omp_init_lock}. The calling thread is blocked until the lock 
472 is available. If the lock is already held by the current thread, 
473 a deadlock occurs.
474
475 @item @emph{C/C++}:
476 @multitable @columnfractions .20 .80
477 @item @emph{Prototype}: @tab @code{void omp_set_lock(omp_lock_t *lock);}
478 @end multitable
479
480 @item @emph{Fortran}:
481 @multitable @columnfractions .20 .80
482 @item @emph{Interface}: @tab @code{subroutine omp_set_lock(lock)}
483 @item                   @tab @code{integer(omp_lock_kind), intent(out) :: lock}
484 @end multitable
485
486 @item @emph{See also}:
487 @ref{omp_init_lock}, @ref{omp_test_lock}, @ref{omp_unset_lock}
488
489 @item @emph{Reference}: 
490 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.3.3.
491 @end table
492
493
494
495 @node omp_test_lock
496 @section @code{omp_test_lock} -- Test and set simple lock if available
497 @table @asis
498 @item @emph{Description}:
499 Before setting a simple lock, the lock variable must be initialized by 
500 @code{omp_init_lock}. Contrary to @code{omp_set_lock}, @code{omp_test_lock} 
501 does not block if the lock is not available. This function returns 
502 @code{true} upon success,@code{false} otherwise. Here, @code{true} and 
503 @code{false} represent their language-specific counterparts.
504
505 @item @emph{C/C++}:
506 @multitable @columnfractions .20 .80
507 @item @emph{Prototype}: @tab @code{int omp_test_lock(omp_lock_t *lock);}
508 @end multitable
509
510 @item @emph{Fortran}:
511 @multitable @columnfractions .20 .80
512 @item @emph{Interface}: @tab @code{subroutine omp_test_lock(lock)}
513 @item                   @tab @code{logical(omp_logical_kind) :: omp_test_lock}
514 @item                   @tab @code{integer(omp_lock_kind), intent(out) :: lock}
515 @end multitable
516
517 @item @emph{See also}:
518 @ref{omp_init_lock}, @ref{omp_set_lock}, @ref{omp_set_lock}
519
520 @item @emph{Reference}: 
521 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.3.5.
522 @end table
523
524
525
526 @node omp_unset_lock
527 @section @code{omp_unset_lock} -- Unset simple lock
528 @table @asis
529 @item @emph{Description}:
530 A simple lock about to be unset must have been locked by @code{omp_set_lock}
531 or @code{omp_test_lock} before. In addition, the lock must be held by the 
532 thread calling @code{omp_unset_lock}. Then, the lock becomes unlocked. If one 
533 ore more threads attempted to set the lock before, one of them is chosen to, 
534 again, set the lock for itself.
535
536 @item @emph{C/C++}:
537 @multitable @columnfractions .20 .80
538 @item @emph{Prototype}: @tab @code{void omp_unset_lock(omp_lock_t *lock);}
539 @end multitable
540
541 @item @emph{Fortran}:
542 @multitable @columnfractions .20 .80
543 @item @emph{Interface}: @tab @code{subroutine omp_unset_lock(lock)}
544 @item                   @tab @code{integer(omp_lock_kind), intent(out) :: lock}
545 @end multitable
546
547 @item @emph{See also}:
548 @ref{omp_set_lock}, @ref{omp_test_lock}
549
550 @item @emph{Reference}: 
551 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.3.4.
552 @end table
553
554
555
556 @node omp_destroy_lock
557 @section @code{omp_destroy_lock} -- Destroy simple lock
558 @table @asis
559 @item @emph{Description}:
560 Destroy a simple lock. In order to be destroyed, a simple lock must be 
561 in the unlocked state. 
562
563 @item @emph{C/C++}:
564 @multitable @columnfractions .20 .80
565 @item @emph{Prototype}: @tab @code{void omp_destroy_lock(omp_lock_t *);}
566 @end multitable
567
568 @item @emph{Fortran}:
569 @multitable @columnfractions .20 .80
570 @item @emph{Interface}: @tab @code{subroutine omp_destroy_lock(lock)}
571 @item                   @tab @code{integer(omp_lock_kind), intent(inout) :: lock}
572 @end multitable
573
574 @item @emph{See also}:
575 @ref{omp_init_lock}
576
577 @item @emph{Reference}: 
578 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.3.2.
579 @end table
580
581
582
583 @node omp_init_nest_lock
584 @section @code{omp_init_nest_lock} -- Initialize nested lock
585 @table @asis
586 @item @emph{Description}:
587 Initialize a nested lock. After initialization, the lock is in 
588 an unlocked state and the nesting count is set to zero.
589
590 @item @emph{C/C++}:
591 @multitable @columnfractions .20 .80
592 @item @emph{Prototype}: @tab @code{void omp_init_nest_lock(omp_nest_lock_t *lock);}
593 @end multitable
594
595 @item @emph{Fortran}:
596 @multitable @columnfractions .20 .80
597 @item @emph{Interface}: @tab @code{subroutine omp_init_nest_lock(lock)}
598 @item                   @tab @code{integer(omp_nest_lock_kind), intent(out) :: lock}
599 @end multitable
600
601 @item @emph{See also}:
602 @ref{omp_destroy_nest_lock}
603
604 @item @emph{Reference}:
605 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.3.1.
606 @end table
607
608
609 @node omp_set_nest_lock
610 @section @code{omp_set_nest_lock} -- Wait for and set simple lock
611 @table @asis
612 @item @emph{Description}:
613 Before setting a nested lock, the lock variable must be initialized by 
614 @code{omp_init_nest_lock}. The calling thread is blocked until the lock 
615 is available. If the lock is already held by the current thread, the 
616 nesting count for the lock in incremented.
617
618 @item @emph{C/C++}:
619 @multitable @columnfractions .20 .80
620 @item @emph{Prototype}: @tab @code{void omp_set_nest_lock(omp_nest_lock_t *lock);}
621 @end multitable
622
623 @item @emph{Fortran}:
624 @multitable @columnfractions .20 .80
625 @item @emph{Interface}: @tab @code{subroutine omp_set_nest_lock(lock)}
626 @item                   @tab @code{integer(omp_nest_lock_kind), intent(out) :: lock}
627 @end multitable
628
629 @item @emph{See also}:
630 @ref{omp_init_nest_lock}, @ref{omp_unset_nest_lock}
631
632 @item @emph{Reference}: 
633 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.3.3.
634 @end table
635
636
637
638 @node omp_test_nest_lock
639 @section @code{omp_test_nest_lock} -- Test and set nested lock if available
640 @table @asis
641 @item @emph{Description}:
642 Before setting a nested lock, the lock variable must be initialized by 
643 @code{omp_init_nest_lock}. Contrary to @code{omp_set_nest_lock}, 
644 @code{omp_test_nest_lock} does not block if the lock is not available. 
645 If the lock is already held by the current thread, the new nesting count 
646 is returned. Otherwise, the return value equals zero.
647
648 @item @emph{C/C++}:
649 @multitable @columnfractions .20 .80
650 @item @emph{Prototype}: @tab @code{int omp_test_nest_lock(omp_nest_lock_t *lock);}
651 @end multitable
652
653 @item @emph{Fortran}:
654 @multitable @columnfractions .20 .80
655 @item @emph{Interface}: @tab @code{integer function omp_test_nest_lock(lock)}
656 @item                   @tab @code{integer(omp_integer_kind) :: omp_test_nest_lock}
657 @item                   @tab @code{integer(omp_nest_lock_kind), intent(inout) :: lock}
658 @end multitable
659
660
661 @item @emph{See also}:
662 @ref{omp_init_lock}, @ref{omp_set_lock}, @ref{omp_set_lock}
663
664 @item @emph{Reference}: 
665 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.3.5.
666 @end table
667
668
669
670 @node omp_unset_nest_lock
671 @section @code{omp_unset_nest_lock} -- Unset nested lock
672 @table @asis
673 @item @emph{Description}:
674 A nested lock about to be unset must have been locked by @code{omp_set_nested_lock}
675 or @code{omp_test_nested_lock} before. In addition, the lock must be held by the 
676 thread calling @code{omp_unset_nested_lock}. If the nesting count drops to zero, the 
677 lock becomes unlocked. If one ore more threads attempted to set the lock before, 
678 one of them is chosen to, again, set the lock for itself.
679
680 @item @emph{C/C++}:
681 @multitable @columnfractions .20 .80
682 @item @emph{Prototype}: @tab @code{void omp_unset_nest_lock(omp_nest_lock_t *lock);}
683 @end multitable
684
685 @item @emph{Fortran}:
686 @multitable @columnfractions .20 .80
687 @item @emph{Interface}: @tab @code{subroutine omp_unset_nest_lock(lock)}
688 @item                   @tab @code{integer(omp_nest_lock_kind), intent(out) :: lock}
689 @end multitable
690
691 @item @emph{See also}:
692 @ref{omp_set_nest_lock}
693
694 @item @emph{Reference}: 
695 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.3.4.
696 @end table
697
698
699
700 @node omp_destroy_nest_lock
701 @section @code{omp_destroy_nest_lock} -- Destroy nested lock
702 @table @asis
703 @item @emph{Description}:
704 Destroy a nested lock. In order to be destroyed, a nested lock must be 
705 in the unlocked state and its nesting count must equal zero.
706
707 @item @emph{C/C++}:
708 @multitable @columnfractions .20 .80
709 @item @emph{Prototype}: @tab @code{void omp_destroy_nest_lock(omp_nest_lock_t *);}
710 @end multitable
711
712 @item @emph{Fortran}:
713 @multitable @columnfractions .20 .80
714 @item @emph{Interface}: @tab @code{subroutine omp_destroy_nest_lock(lock)}
715 @item                   @tab @code{integer(omp_nest_lock_kind), intent(inout) :: lock}
716 @end multitable
717
718 @item @emph{See also}:
719 @ref{omp_init_lock}
720
721 @item @emph{Reference}: 
722 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.3.2.
723 @end table
724
725
726
727 @node omp_get_wtick
728 @section @code{omp_get_wtick} -- Get timer precision
729 @table @asis
730 @item @emph{Description}:
731 Gets the timer precision, i. e. the number of seconds between two 
732 successive clock ticks.
733
734 @item @emph{C/C++}:
735 @multitable @columnfractions .20 .80
736 @item @emph{Prototype}: @tab @code{double omp_get_wtick();}
737 @end multitable
738
739 @item @emph{Fortran}:
740 @multitable @columnfractions .20 .80
741 @item @emph{Interface}: @tab @code{double precision function omp_get_wtick()}
742 @end multitable
743
744 @item @emph{See also}:
745 @ref{omp_get_wtime}
746
747 @item @emph{Reference}: 
748 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.4.2.
749 @end table
750
751
752
753 @node omp_get_wtime
754 @section @code{omp_get_wtime} -- Elapsed wall clock time
755 @table @asis
756 @item @emph{Description}:
757 Elapsed wall clock time in seconds. The time is measured per thread, no 
758 guarantee can bee made that two distinct threads measure the same time.
759 Time is measured from some "time in the past". On POSIX compliant systems 
760 the seconds since the Epoch (00:00:00 UTC, January 1, 1970) are returned.
761
762 @item @emph{C/C++}:
763 @multitable @columnfractions .20 .80
764 @item @emph{Prototype}: @tab @code{double omp_get_wtime();}
765 @end multitable
766
767 @item @emph{Fortran}:
768 @multitable @columnfractions .20 .80
769 @item @emph{Interface}: @tab @code{double precision function omp_get_wtime()}
770 @end multitable
771
772 @item @emph{See also}:
773 @ref{omp_get_wtick}
774
775 @item @emph{Reference}: 
776 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.4.1.
777 @end table
778
779
780
781 @c ---------------------------------------------------------------------
782 @c Environment Variables
783 @c ---------------------------------------------------------------------
784
785 @node Environment Variables
786 @chapter Environment Variables
787
788 The variables @env{OMP_DYNAMIC}, @env{OMP_NESTED}, @env{OMP_NUM_THREADS} and 
789 @env{OMP_SCHEDULE} are defined by section 4 of the OpenMP specifications in 
790 version 2.5, while @env{GOMP_CPU_AFFINITY} and @env{GOMP_STACKSIZE} are GNU 
791 extensions.
792
793 @menu
794 * OMP_DYNAMIC::        Dynamic adjustment of threads
795 * OMP_NESTED::         Nested parallel regions
796 * OMP_NUM_THREADS::    Specifies the number of threads to use
797 * OMP_SCHEDULE::       How threads are scheduled
798 * GOMP_CPU_AFFINITY::  Bind threads to specific CPUs
799 * GOMP_STACKSIZE::     Set default thread stack size
800 @end menu
801
802
803 @node OMP_DYNAMIC
804 @section @env{OMP_DYNAMIC} -- Dynamic adjustment of threads
805 @cindex Environment Variable
806 @table @asis
807 @item @emph{Description}:
808 Enable or disable the dynamic adjustment of the number of threads 
809 within a team. The value of this environment variable shall be 
810 @code{TRUE} or @code{FALSE}.
811
812 @item @emph{See also}:
813 @ref{omp_set_dynamic}
814
815 @item @emph{Reference}: 
816 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 4.3
817 @end table
818
819
820
821 @node OMP_NESTED
822 @section @env{OMP_NESTED} -- Nested parallel regions
823 @cindex Environment Variable
824 @table @asis
825 @item @emph{Description}:
826 Enable or disable nested parallel regions, i. e. whether team members
827 are allowed to create new teams. The value of this environment variable 
828 shall be @code{TRUE} or @code{FALSE}.
829
830 @item @emph{See also}:
831 @ref{omp_set_nested}
832
833 @item @emph{Reference}: 
834 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 4.4
835 @end table
836
837
838
839 @node OMP_NUM_THREADS
840 @section @env{OMP_NUM_THREADS} -- Specifies the number of threads to use
841 @cindex Environment Variable
842 @table @asis
843 @item @emph{Description}:
844 Specifies the number of threads to use in parallel regions. If undefined
845 one thread per CPU online is used. The value of this variable shall be 
846 positive integer. 
847
848 @item @emph{See also}:
849 @ref{omp_set_num_threads}
850
851 @item @emph{Reference}: 
852 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 4.2
853 @end table
854
855
856
857 @node OMP_SCHEDULE
858 @section @env{OMP_SCHEDULE} -- How threads are scheduled
859 @cindex Environment Variable
860 @table @asis
861 @item @emph{Description}:
862 Allows to specify @code{schedule type} and @code{chunk size}. 
863 The value of the variable shall have the form: @code{type[,chunk]} where
864 @code{type} is one of @code{static}, @code{dynamic} or @code{guided}. 
865 The optional @code{chunk size} shall be a positive integer. 
866
867 @item @emph{Reference}: 
868 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 4.1
869 @end table
870
871
872
873 @node GOMP_CPU_AFFINITY
874 @section @env{GOMP_CPU_AFFINITY} -- Bind threads to specific CPUs
875 @cindex Environment Variable
876 @table @asis
877 @item @emph{Description}:
878 A patch for this extension has been submitted, but was not yet applied at the
879 time of writing.
880
881 @item @emph{Reference}: 
882 @uref{http://gcc.gnu.org/ml/gcc-patches/2006-05/msg00982.html, 
883 GCC Patches Mailinglist}
884 @uref{http://gcc.gnu.org/ml/gcc-patches/2006-05/msg01133.html,
885 GCC Patches Mailinglist}
886 @end table
887
888
889
890 @node GOMP_STACKSIZE
891 @section @env{GOMP_STACKSIZE} -- Set default thread stack size
892 @cindex Environment Variable
893 @table @asis
894 @item @emph{Description}:
895 Set the default thread stack size in kilobytes. This is in opposition 
896 to @code{pthread_attr_setstacksize} which gets the number of bytes as an 
897 argument. If the stacksize can not be set due to system constraints, an 
898 error is reported and the initial stacksize is left unchanged.
899
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}
905 @end table
906
907
908
909 @c ---------------------------------------------------------------------
910 @c The libgomp ABI
911 @c ---------------------------------------------------------------------
912
913 @node The libgomp ABI
914 @chapter The libgomp ABI
915
916 The following sections present notes on the external ABI as 
917 presented by libgomp. Only maintainers should need them.
918
919 @menu
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::
934 @end menu
935
936
937 @node Implementing MASTER construct
938 @section Implementing MASTER construct
939
940 @smallexample
941 if (omp_get_thread_num () == 0)
942   block
943 @end smallexample
944
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...
948
949
950
951 @node Implementing CRITICAL construct
952 @section Implementing CRITICAL construct
953
954 Without a specified name,
955
956 @smallexample
957   void GOMP_critical_start (void);
958   void GOMP_critical_end (void);
959 @end smallexample
960
961 so that we don't get COPY relocations from libgomp to the main
962 application.
963
964 With a specified name, use omp_set_lock and omp_unset_lock with
965 name being transformed into a variable declared like
966
967 @smallexample
968   omp_lock_t gomp_critical_user_<name> __attribute__((common))
969 @end smallexample
970
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
973 startup.
974
975
976
977 @node Implementing ATOMIC construct
978 @section Implementing ATOMIC construct
979
980 The target should implement the @code{__sync} builtins.
981
982 Failing that we could add
983
984 @smallexample
985   void GOMP_atomic_enter (void)
986   void GOMP_atomic_exit (void)
987 @end smallexample
988
989 which reuses the regular lock code, but with yet another lock
990 object private to the library.
991
992
993
994 @node Implementing FLUSH construct
995 @section Implementing FLUSH construct
996
997 Expands to the @code{__sync_synchronize} builtin.
998
999
1000
1001 @node Implementing BARRIER construct
1002 @section Implementing BARRIER construct
1003
1004 @smallexample
1005   void GOMP_barrier (void)
1006 @end smallexample
1007
1008
1009 @node Implementing THREADPRIVATE construct
1010 @section Implementing THREADPRIVATE construct
1011
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.
1016
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.
1020
1021
1022
1023 @node Implementing PRIVATE clause
1024 @section Implementing PRIVATE clause
1025
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.
1029
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.
1033
1034
1035
1036 @node Implementing FIRSTPRIVATE LASTPRIVATE COPYIN and COPYPRIVATE clauses
1037 @section Implementing FIRSTPRIVATE LASTPRIVATE COPYIN and COPYPRIVATE clauses
1038
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.
1044
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
1047
1048 @smallexample
1049 #pragma omp for firstprivate(x) lastprivate(y)
1050 for (int i = 0; i < n; ++i)
1051   body;
1052 @end smallexample
1053
1054 which becomes
1055
1056 @smallexample
1057 @{
1058   int x = x, y;
1059
1060   // for stuff
1061
1062   if (i == n)
1063     y = y;
1064 @}
1065 @end smallexample
1066
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.
1071
1072 COPYPRIVATE would work the same way, except the structure 
1073 broadcast would have to happen via SINGLE machinery instead.
1074
1075
1076
1077 @node Implementing REDUCTION clause
1078 @section Implementing REDUCTION clause
1079
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.
1085
1086
1087 @node Implementing PARALLEL construct
1088 @section Implementing PARALLEL construct
1089
1090 @smallexample
1091   #pragma omp parallel
1092   @{
1093     body;
1094   @}
1095 @end smallexample
1096
1097 becomes
1098
1099 @smallexample
1100   void subfunction (void *data)
1101   @{
1102     use data;
1103     body;
1104   @}
1105
1106   setup data;
1107   GOMP_parallel_start (subfunction, &data, num_threads);
1108   subfunction (&data);
1109   GOMP_parallel_end ();
1110 @end smallexample
1111
1112 @smallexample
1113   void GOMP_parallel_start (void (*fn)(void *), void *data, unsigned num_threads)
1114 @end smallexample
1115
1116 The @var{FN} argument is the subfunction to be run in parallel.
1117
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.
1121
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
1124 present, or 0.
1125
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.
1129
1130 @smallexample
1131   void GOMP_parallel_end (void)
1132 @end smallexample
1133
1134 Tears down the team and returns us to the previous @code{omp_in_parallel()} state.
1135
1136
1137
1138 @node Implementing FOR construct
1139 @section Implementing FOR construct
1140
1141 @smallexample
1142   #pragma omp parallel for
1143   for (i = lb; i <= ub; i++)
1144     body;
1145 @end smallexample
1146
1147 becomes
1148
1149 @smallexample
1150   void subfunction (void *data)
1151   @{
1152     long _s0, _e0;
1153     while (GOMP_loop_static_next (&_s0, &_e0))
1154     @{
1155       long _e1 = _e0, i;
1156       for (i = _s0; i < _e1; i++)
1157         body;
1158     @}
1159     GOMP_loop_end_nowait ();
1160   @}
1161
1162   GOMP_parallel_loop_static (subfunction, NULL, 0, lb, ub+1, 1, 0);
1163   subfunction (NULL);
1164   GOMP_parallel_end ();
1165 @end smallexample
1166
1167 @smallexample
1168   #pragma omp for schedule(runtime)
1169   for (i = 0; i < n; i++)
1170     body;
1171 @end smallexample
1172
1173 becomes
1174
1175 @smallexample
1176   @{
1177     long i, _s0, _e0;
1178     if (GOMP_loop_runtime_start (0, n, 1, &_s0, &_e0))
1179       do @{
1180         long _e1 = _e0;
1181         for (i = _s0, i < _e0; i++)
1182           body;
1183       @} while (GOMP_loop_runtime_next (&_s0, _&e0));
1184     GOMP_loop_end ();
1185   @}
1186 @end smallexample
1187
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.
1195
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
1200 of these routines.
1201
1202 There are separate routines for handling loops with an ORDERED
1203 clause.  Bookkeeping for that is non-trivial...
1204
1205
1206
1207 @node Implementing ORDERED construct
1208 @section Implementing ORDERED construct
1209
1210 @smallexample
1211   void GOMP_ordered_start (void)
1212   void GOMP_ordered_end (void)
1213 @end smallexample
1214
1215
1216
1217 @node Implementing SECTIONS construct
1218 @section Implementing SECTIONS construct
1219
1220 A block as 
1221
1222 @smallexample
1223   #pragma omp sections
1224   @{
1225     #pragma omp section
1226     stmt1;
1227     #pragma omp section
1228     stmt2;
1229     #pragma omp section
1230     stmt3;
1231   @}
1232 @end smallexample
1233
1234 becomes
1235
1236 @smallexample
1237   for (i = GOMP_sections_start (3); i != 0; i = GOMP_sections_next ())
1238     switch (i)
1239       @{
1240       case 1:
1241         stmt1;
1242         break;
1243       case 2:
1244         stmt2;
1245         break;
1246       case 3:
1247         stmt3;
1248         break;
1249       @}
1250   GOMP_barrier ();
1251 @end smallexample
1252
1253
1254 @node Implementing SINGLE construct
1255 @section Implementing SINGLE construct
1256
1257 A block like 
1258
1259 @smallexample
1260   #pragma omp single
1261   @{
1262     body;
1263   @}
1264 @end smallexample
1265
1266 becomes
1267
1268 @smallexample
1269   if (GOMP_single_start ())
1270     body;
1271   GOMP_barrier ();
1272 @end smallexample
1273
1274 while 
1275
1276 @smallexample
1277   #pragma omp single copyprivate(x)
1278     body;
1279 @end smallexample
1280
1281 becomes
1282
1283 @smallexample
1284   datap = GOMP_single_copy_start ();
1285   if (datap == NULL)
1286     @{
1287       body;
1288       data.x = x;
1289       GOMP_single_copy_end (&data);
1290     @}
1291   else
1292     x = datap->x;
1293   GOMP_barrier ();
1294 @end smallexample
1295
1296
1297
1298 @c ---------------------------------------------------------------------
1299 @c 
1300 @c ---------------------------------------------------------------------
1301
1302 @node Reporting Bugs
1303 @chapter Reporting Bugs
1304
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.
1308
1309
1310
1311 @c ---------------------------------------------------------------------
1312 @c GNU General Public License
1313 @c ---------------------------------------------------------------------
1314
1315 @include gpl.texi
1316
1317
1318
1319 @c ---------------------------------------------------------------------
1320 @c GNU Free Documentation License
1321 @c ---------------------------------------------------------------------
1322
1323 @include fdl.texi
1324
1325
1326
1327 @c ---------------------------------------------------------------------
1328 @c Funding Free Software
1329 @c ---------------------------------------------------------------------
1330
1331 @include funding.texi
1332
1333 @c ---------------------------------------------------------------------
1334 @c Index
1335 @c ---------------------------------------------------------------------
1336
1337 @node Index
1338 @unnumbered Index
1339
1340 @printindex cp
1341
1342 @bye