OSDN Git Service

2007-01-14 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 @item @emph{C/C++}:
416 @multitable @columnfractions .20 .80
417 @item @emph{Prototype}: @tab @code{void omp_set_num_threads(int);}
418 @end multitable
419
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}
424 @end multitable
425
426 @item @emph{See also}:
427 @ref{OMP_NUM_THREADS}, @ref{omp_get_num_threads}, @ref{omp_get_max_threads}
428
429 @item @emph{Reference}:
430 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.2.1.
431 @end table
432
433
434
435 @node omp_init_lock
436 @section @code{omp_init_lock} -- Initialize simple lock
437 @table @asis
438 @item @emph{Description}:
439 Initialize a simple lock. After initialization, the lock is in 
440 an unlocked state.
441
442 @item @emph{C/C++}:
443 @multitable @columnfractions .20 .80
444 @item @emph{Prototype}: @tab @code{void omp_init_lock(omp_lock_t *lock);}
445 @end multitable
446
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}
451 @end multitable
452
453 @item @emph{See also}:
454 @ref{omp_destroy_lock}
455
456 @item @emph{Reference}: 
457 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.3.1.
458 @end table
459
460
461
462 @node omp_set_lock
463 @section @code{omp_set_lock} -- Wait for and set simple lock
464 @table @asis
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, 
469 a deadlock occurs.
470
471 @item @emph{C/C++}:
472 @multitable @columnfractions .20 .80
473 @item @emph{Prototype}: @tab @code{void omp_set_lock(omp_lock_t *lock);}
474 @end multitable
475
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}
480 @end multitable
481
482 @item @emph{See also}:
483 @ref{omp_init_lock}, @ref{omp_test_lock}, @ref{omp_unset_lock}
484
485 @item @emph{Reference}: 
486 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.3.3.
487 @end table
488
489
490
491 @node omp_test_lock
492 @section @code{omp_test_lock} -- Test and set simple lock if available
493 @table @asis
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.
500
501 @item @emph{C/C++}:
502 @multitable @columnfractions .20 .80
503 @item @emph{Prototype}: @tab @code{int omp_test_lock(omp_lock_t *lock);}
504 @end multitable
505
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}
511 @end multitable
512
513 @item @emph{See also}:
514 @ref{omp_init_lock}, @ref{omp_set_lock}, @ref{omp_set_lock}
515
516 @item @emph{Reference}: 
517 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.3.5.
518 @end table
519
520
521
522 @node omp_unset_lock
523 @section @code{omp_unset_lock} -- Unset simple lock
524 @table @asis
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.
531
532 @item @emph{C/C++}:
533 @multitable @columnfractions .20 .80
534 @item @emph{Prototype}: @tab @code{void omp_unset_lock(omp_lock_t *lock);}
535 @end multitable
536
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}
541 @end multitable
542
543 @item @emph{See also}:
544 @ref{omp_set_lock}, @ref{omp_test_lock}
545
546 @item @emph{Reference}: 
547 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.3.4.
548 @end table
549
550
551
552 @node omp_destroy_lock
553 @section @code{omp_destroy_lock} -- Destroy simple lock
554 @table @asis
555 @item @emph{Description}:
556 Destroy a simple lock. In order to be destroyed, a simple lock must be 
557 in the unlocked state. 
558
559 @item @emph{C/C++}:
560 @multitable @columnfractions .20 .80
561 @item @emph{Prototype}: @tab @code{void omp_destroy_lock(omp_lock_t *);}
562 @end multitable
563
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}
568 @end multitable
569
570 @item @emph{See also}:
571 @ref{omp_init_lock}
572
573 @item @emph{Reference}: 
574 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.3.2.
575 @end table
576
577
578
579 @node omp_init_nest_lock
580 @section @code{omp_init_nest_lock} -- Initialize nested lock
581 @table @asis
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.
585
586 @item @emph{C/C++}:
587 @multitable @columnfractions .20 .80
588 @item @emph{Prototype}: @tab @code{void omp_init_nest_lock(omp_nest_lock_t *lock);}
589 @end multitable
590
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}
595 @end multitable
596
597 @item @emph{See also}:
598 @ref{omp_destroy_nest_lock}
599
600 @item @emph{Reference}:
601 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.3.1.
602 @end table
603
604
605 @node omp_set_nest_lock
606 @section @code{omp_set_nest_lock} -- Wait for and set simple lock
607 @table @asis
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.
613
614 @item @emph{C/C++}:
615 @multitable @columnfractions .20 .80
616 @item @emph{Prototype}: @tab @code{void omp_set_nest_lock(omp_nest_lock_t *lock);}
617 @end multitable
618
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}
623 @end multitable
624
625 @item @emph{See also}:
626 @ref{omp_init_nest_lock}, @ref{omp_unset_nest_lock}
627
628 @item @emph{Reference}: 
629 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.3.3.
630 @end table
631
632
633
634 @node omp_test_nest_lock
635 @section @code{omp_test_nest_lock} -- Test and set nested lock if available
636 @table @asis
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.
643
644 @item @emph{C/C++}:
645 @multitable @columnfractions .20 .80
646 @item @emph{Prototype}: @tab @code{int omp_test_nest_lock(omp_nest_lock_t *lock);}
647 @end multitable
648
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}
654 @end multitable
655
656
657 @item @emph{See also}:
658 @ref{omp_init_lock}, @ref{omp_set_lock}, @ref{omp_set_lock}
659
660 @item @emph{Reference}: 
661 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.3.5.
662 @end table
663
664
665
666 @node omp_unset_nest_lock
667 @section @code{omp_unset_nest_lock} -- Unset nested lock
668 @table @asis
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.
675
676 @item @emph{C/C++}:
677 @multitable @columnfractions .20 .80
678 @item @emph{Prototype}: @tab @code{void omp_unset_nest_lock(omp_nest_lock_t *lock);}
679 @end multitable
680
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}
685 @end multitable
686
687 @item @emph{See also}:
688 @ref{omp_set_nest_lock}
689
690 @item @emph{Reference}: 
691 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.3.4.
692 @end table
693
694
695
696 @node omp_destroy_nest_lock
697 @section @code{omp_destroy_nest_lock} -- Destroy nested lock
698 @table @asis
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.
702
703 @item @emph{C/C++}:
704 @multitable @columnfractions .20 .80
705 @item @emph{Prototype}: @tab @code{void omp_destroy_nest_lock(omp_nest_lock_t *);}
706 @end multitable
707
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}
712 @end multitable
713
714 @item @emph{See also}:
715 @ref{omp_init_lock}
716
717 @item @emph{Reference}: 
718 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.3.2.
719 @end table
720
721
722
723 @node omp_get_wtick
724 @section @code{omp_get_wtick} -- Get timer precision
725 @table @asis
726 @item @emph{Description}:
727 Gets the timer precision, i. e. the number of seconds between two 
728 successive clock ticks.
729
730 @item @emph{C/C++}:
731 @multitable @columnfractions .20 .80
732 @item @emph{Prototype}: @tab @code{double omp_get_wtick();}
733 @end multitable
734
735 @item @emph{Fortran}:
736 @multitable @columnfractions .20 .80
737 @item @emph{Interface}: @tab @code{double precision function omp_get_wtick()}
738 @end multitable
739
740 @item @emph{See also}:
741 @ref{omp_get_wtime}
742
743 @item @emph{Reference}: 
744 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.4.2.
745 @end table
746
747
748
749 @node omp_get_wtime
750 @section @code{omp_get_wtime} -- Elapsed wall clock time
751 @table @asis
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.
757
758 @item @emph{C/C++}:
759 @multitable @columnfractions .20 .80
760 @item @emph{Prototype}: @tab @code{double omp_get_wtime();}
761 @end multitable
762
763 @item @emph{Fortran}:
764 @multitable @columnfractions .20 .80
765 @item @emph{Interface}: @tab @code{double precision function omp_get_wtime()}
766 @end multitable
767
768 @item @emph{See also}:
769 @ref{omp_get_wtick}
770
771 @item @emph{Reference}: 
772 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.4.1.
773 @end table
774
775
776
777 @c ---------------------------------------------------------------------
778 @c Environment Variables
779 @c ---------------------------------------------------------------------
780
781 @node Environment Variables
782 @chapter Environment Variables
783
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 
787 extensions.
788
789 @menu
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
796 @end menu
797
798
799 @node OMP_DYNAMIC
800 @section @env{OMP_DYNAMIC} -- Dynamic adjustment of threads
801 @cindex Environment Variable
802 @table @asis
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
807 disabled by default.
808
809 @item @emph{See also}:
810 @ref{omp_set_dynamic}
811
812 @item @emph{Reference}: 
813 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 4.3
814 @end table
815
816
817
818 @node OMP_NESTED
819 @section @env{OMP_NESTED} -- Nested parallel regions
820 @cindex Environment Variable
821 @table @asis
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.
827
828 @item @emph{See also}:
829 @ref{omp_set_nested}
830
831 @item @emph{Reference}: 
832 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 4.4
833 @end table
834
835
836
837 @node OMP_NUM_THREADS
838 @section @env{OMP_NUM_THREADS} -- Specifies the number of threads to use
839 @cindex Environment Variable
840 @table @asis
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 
844 positive integer. 
845
846 @item @emph{See also}:
847 @ref{omp_set_num_threads}
848
849 @item @emph{Reference}: 
850 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 4.2
851 @end table
852
853
854
855 @node OMP_SCHEDULE
856 @section @env{OMP_SCHEDULE} -- How threads are scheduled
857 @cindex Environment Variable
858 @table @asis
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.
865
866 @item @emph{Reference}: 
867 @uref{http://www.openmp.org/, OpenMP specifications v2.5}, sections 2.5.1 and 4.1
868 @end table
869
870
871
872 @node GOMP_CPU_AFFINITY
873 @section @env{GOMP_CPU_AFFINITY} -- Bind threads to specific CPUs
874 @cindex Environment Variable
875 @table @asis
876 @item @emph{Description}:
877 A patch for this extension has been submitted, but was not yet applied at the
878 time of writing.
879
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}
885 @end table
886
887
888
889 @node GOMP_STACKSIZE
890 @section @env{GOMP_STACKSIZE} -- Set default thread stack size
891 @cindex Environment Variable
892 @table @asis
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.
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