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