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, 2007, 2008, 2010 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.3 or
  14 any later version published by the Free Software Foundation; with the
  15 Invariant Sections being ``Funding Free Software'', the Front-Cover
  16 texts being (a) (see below), and with the Back-Cover Texts being (b)
  17 (see below).  A copy of the license is included in the section entitled
  18 ``GNU Free Documentation License''.
  19
  20 (a) The FSF's Front-Cover Text is:
  21
  22      A GNU Manual
  23
  24 (b) The FSF's Back-Cover Text is:
  25
  26      You have freedom to copy and modify this GNU Manual, like GNU
  27      software.  Copies published by the Free Software Foundation raise
  28      funds for GNU development.
  29 @end copying
  30
  31 @ifinfo
  32 @dircategory GNU Libraries
  33 @direntry
  34 * libgomp: (libgomp).                    GNU OpenMP runtime library
  35 @end direntry
  36
  37 This manual documents the GNU implementation of the OpenMP API for
  38 multi-platform shared-memory parallel programming in C/C++ and Fortran.
  39
  40 Published by the Free Software Foundation
  41 51 Franklin Street, Fifth Floor
  42 Boston, MA 02110-1301 USA
  43
  44 @insertcopying
  45 @end ifinfo
  46
  47
  48 @setchapternewpage odd
  49
  50 @titlepage
  51 @title The GNU OpenMP Implementation
  52 @page
  53 @vskip 0pt plus 1filll
  54 @comment For the @value{version-GCC} Version*
  55 @sp 1
  56 Published by the Free Software Foundation @*
  57 51 Franklin Street, Fifth Floor@*
  58 Boston, MA 02110-1301, USA@*
  59 @sp 1
  60 @insertcopying
  61 @end titlepage
  62
  63 @summarycontents
  64 @contents
  65 @page
  66
  67
  68 @node Top
  69 @top Introduction
  70 @cindex Introduction
  71
  72 This manual documents the usage of libgomp, the GNU implementation of the
  73 @uref{http://www.openmp.org, OpenMP} Application Programming Interface (API)
  74 for multi-platform shared-memory parallel programming in C/C++ and Fortran.
  75
  76
  77
  78 @comment
  79 @comment  When you add a new menu item, please keep the right hand
  80 @comment  aligned to the same column.  Do not use tabs.  This provides
  81 @comment  better formatting.
  82 @comment
  83 @menu
  84 * Enabling OpenMP::            How to enable OpenMP for your applications.
  85 * Runtime Library Routines::   The OpenMP runtime application programming
  86                                interface.
  87 * Environment Variables::      Influencing runtime behavior with environment
  88                                variables.
  89 * The libgomp ABI::            Notes on the external ABI presented by libgomp.
  90 * Reporting Bugs::             How to report bugs in GNU OpenMP.
  91 * Copying::                    GNU general public license says
  92                                how you can copy and share libgomp.
  93 * GNU Free Documentation License::
  94                                How you can copy and share this manual.
  95 * Funding::                    How to help assure continued work for free
  96                                software.
  97 * Index::                      Index of this documentation.
  98 @end menu
  99
 100
 101 @c ---------------------------------------------------------------------
 102 @c Enabling OpenMP
 103 @c ---------------------------------------------------------------------
 104
 105 @node Enabling OpenMP
 106 @chapter Enabling OpenMP
 107
 108 To activate the OpenMP extensions for C/C++ and Fortran, the compile-time
 109 flag @command{-fopenmp} must be specified. This enables the OpenMP directive
 110 @code{#pragma omp} in C/C++ and @code{!$omp} directives in free form,
 111 @code{c$omp}, @code{*$omp} and @code{!$omp} directives in fixed form,
 112 @code{!$} conditional compilation sentinels in free form and @code{c$},
 113 @code{*$} and @code{!$} sentinels in fixed form, for Fortran. The flag also
 114 arranges for automatic linking of the OpenMP runtime library
 115 (@ref{Runtime Library Routines}).
 116
 117 A complete description of all OpenMP directives accepted may be found in
 118 the @uref{http://www.openmp.org, OpenMP Application Program Interface} manual,
 119 version 3.0.
 120
 121
 122 @c ---------------------------------------------------------------------
 123 @c Runtime Library Routines
 124 @c ---------------------------------------------------------------------
 125
 126 @node Runtime Library Routines
 127 @chapter Runtime Library Routines
 128
 129 The runtime routines described here are defined by section 3 of the OpenMP
 130 specifications in version 3.0. The routines are structured in following
 131 three parts:
 132
 133 Control threads, processors and the parallel environment.
 134
 135 @menu
 136 * omp_get_active_level::        Number of active parallel regions
 137 * omp_get_ancestor_thread_num:: Ancestor thread ID
 138 * omp_get_dynamic::             Dynamic teams setting
 139 * omp_get_level::               Number of parallel regions
 140 * omp_get_max_active_levels::   Maximum number of active regions
 141 * omp_get_max_threads::         Maximum number of threads of parallel region
 142 * omp_get_nested::              Nested parallel regions
 143 * omp_get_num_procs::           Number of processors online
 144 * omp_get_num_threads::         Size of the active team
 145 * omp_get_schedule::            Obtain the runtime scheduling method
 146 * omp_get_team_size::           Number of threads in a team
 147 * omp_get_thread_limit::        Maximum number of threads
 148 * omp_get_thread_num::          Current thread ID
 149 * omp_in_parallel::             Whether a parallel region is active
 150 * omp_set_dynamic::             Enable/disable dynamic teams
 151 * omp_set_max_active_levels::   Limits the number of active parallel regions
 152 * omp_set_nested::              Enable/disable nested parallel regions
 153 * omp_set_num_threads::         Set upper team size limit
 154 * omp_set_schedule::            Set the runtime scheduling method
 155 @end menu
 156
 157 Initialize, set, test, unset and destroy simple and nested locks.
 158
 159 @menu
 160 * omp_init_lock::            Initialize simple lock
 161 * omp_set_lock::             Wait for and set simple lock
 162 * omp_test_lock::            Test and set simple lock if available
 163 * omp_unset_lock::           Unset simple lock
 164 * omp_destroy_lock::         Destroy simple lock
 165 * omp_init_nest_lock::       Initialize nested lock
 166 * omp_set_nest_lock::        Wait for and set simple lock
 167 * omp_test_nest_lock::       Test and set nested lock if available
 168 * omp_unset_nest_lock::      Unset nested lock
 169 * omp_destroy_nest_lock::    Destroy nested lock
 170 @end menu
 171
 172 Portable, thread-based, wall clock timer.
 173
 174 @menu
 175 * omp_get_wtick::            Get timer precision.
 176 * omp_get_wtime::            Elapsed wall clock time.
 177 @end menu
 178
 179
 180
 181 @node omp_get_active_level
 182 @section @code{omp_get_active_level} -- Number of parallel regions
 183 @table @asis
 184 @item @emph{Description}:
 185 This function returns the nesting level for the active parallel blocks,
 186 which enclose the calling call.
 187
 188 @item @emph{C/C++}
 189 @multitable @columnfractions .20 .80
 190 @item @emph{Prototype}: @tab @code{int omp_get_active_level(void);}
 191 @end multitable
 192
 193 @item @emph{Fortran}:
 194 @multitable @columnfractions .20 .80
 195 @item @emph{Interface}: @tab @code{integer omp_get_active_level()}
 196 @end multitable
 197
 198 @item @emph{See also}:
 199 @ref{omp_get_level}, @ref{omp_get_max_active_levels}, @ref{omp_set_max_active_levels}
 200
 201 @item @emph{Reference}:
 202 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, section 3.2.19.
 203 @end table
 204
 205
 206
 207 @node omp_get_ancestor_thread_num
 208 @section @code{omp_get_ancestor_thread_num} -- Ancestor thread ID
 209 @table @asis
 210 @item @emph{Description}:
 211 This function returns the thread identification number for the given
 212 nesting level of the current thread. For values of @var{level} outside
 213 zero to @code{omp_get_level} -1 is returned; if @var{level} is
 214 @code{omp_get_level} the result is identical to @code{omp_get_thread_num}.
 215
 216 @item @emph{C/C++}
 217 @multitable @columnfractions .20 .80
 218 @item @emph{Prototype}: @tab @code{int omp_get_ancestor_thread_num(int level);}
 219 @end multitable
 220
 221 @item @emph{Fortran}:
 222 @multitable @columnfractions .20 .80
 223 @item @emph{Interface}: @tab @code{integer omp_get_ancestor_thread_num(level)}
 224 @item                   @tab @code{integer level}
 225 @end multitable
 226
 227 @item @emph{See also}:
 228 @ref{omp_get_level}, @ref{omp_get_thread_num}, @ref{omp_get_team_size}
 229
 230 @item @emph{Reference}:
 231 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, section 3.2.17.
 232 @end table
 233
 234
 235
 236 @node omp_get_dynamic
 237 @section @code{omp_get_dynamic} -- Dynamic teams setting
 238 @table @asis
 239 @item @emph{Description}:
 240 This function returns @code{true} if enabled, @code{false} otherwise.
 241 Here, @code{true} and @code{false} represent their language-specific
 242 counterparts.
 243
 244 The dynamic team setting may be initialized at startup by the
 245 @code{OMP_DYNAMIC} environment variable or at runtime using
 246 @code{omp_set_dynamic}. If undefined, dynamic adjustment is
 247 disabled by default.
 248
 249 @item @emph{C/C++}:
 250 @multitable @columnfractions .20 .80
 251 @item @emph{Prototype}: @tab @code{int omp_get_dynamic(void);}
 252 @end multitable
 253
 254 @item @emph{Fortran}:
 255 @multitable @columnfractions .20 .80
 256 @item @emph{Interface}: @tab @code{logical function omp_get_dynamic()}
 257 @end multitable
 258
 259 @item @emph{See also}:
 260 @ref{omp_set_dynamic}, @ref{OMP_DYNAMIC}
 261
 262 @item @emph{Reference}:
 263 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, section 3.2.8.
 264 @end table
 265
 266
 267
 268 @node omp_get_level
 269 @section @code{omp_get_level} -- Obtain the current nesting level
 270 @table @asis
 271 @item @emph{Description}:
 272 This function returns the nesting level for the parallel blocks,
 273 which enclose the calling call.
 274
 275 @item @emph{C/C++}
 276 @multitable @columnfractions .20 .80
 277 @item @emph{Prototype}: @tab @code{int omp_get_level(void);}
 278 @end multitable
 279
 280 @item @emph{Fortran}:
 281 @multitable @columnfractions .20 .80
 282 @item @emph{Interface}: @tab @code{integer omp_level()}
 283 @end multitable
 284
 285 @item @emph{See also}:
 286 @ref{omp_get_active_level}
 287
 288 @item @emph{Reference}:
 289 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, section 3.2.16.
 290 @end table
 291
 292
 293
 294 @node omp_get_max_active_levels
 295 @section @code{omp_get_max_active_levels} -- Maximum number of active regions
 296 @table @asis
 297 @item @emph{Description}:
 298 This function obtains the maximum allowed number of nested, active parallel regions.
 299
 300 @item @emph{C/C++}
 301 @multitable @columnfractions .20 .80
 302 @item @emph{Prototype}: @tab @code{int omp_get_max_active_levels(void);}
 303 @end multitable
 304
 305 @item @emph{Fortran}:
 306 @multitable @columnfractions .20 .80
 307 @item @emph{Interface}: @tab @code{int omp_get_max_active_levels()}
 308 @end multitable
 309
 310 @item @emph{See also}:
 311 @ref{omp_set_max_active_levels}, @ref{omp_get_active_level}
 312
 313 @item @emph{Reference}:
 314 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, section 3.2.14.
 315 @end table
 316
 317
 318
 319 @node omp_get_max_threads
 320 @section @code{omp_get_max_threads} -- Maximum number of threads of parallel region
 321 @table @asis
 322 @item @emph{Description}:
 323 Return the maximum number of threads used for the current parallel region
 324 that does not use the clause @code{num_threads}.
 325
 326 @item @emph{C/C++}:
 327 @multitable @columnfractions .20 .80
 328 @item @emph{Prototype}: @tab @code{int omp_get_max_threads(void);}
 329 @end multitable
 330
 331 @item @emph{Fortran}:
 332 @multitable @columnfractions .20 .80
 333 @item @emph{Interface}: @tab @code{integer function omp_get_max_threads()}
 334 @end multitable
 335
 336 @item @emph{See also}:
 337 @ref{omp_set_num_threads}, @ref{omp_set_dynamic}, @ref{omp_get_thread_limit}
 338
 339 @item @emph{Reference}:
 340 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, section 3.2.3.
 341 @end table
 342
 343
 344
 345 @node omp_get_nested
 346 @section @code{omp_get_nested} -- Nested parallel regions
 347 @table @asis
 348 @item @emph{Description}:
 349 This function returns @code{true} if nested parallel regions are
 350 enabled, @code{false} otherwise. Here, @code{true} and @code{false}
 351 represent their language-specific counterparts.
 352
 353 Nested parallel regions may be initialized at startup by the
 354 @code{OMP_NESTED} environment variable or at runtime using
 355 @code{omp_set_nested}. If undefined, nested parallel regions are
 356 disabled by default.
 357
 358 @item @emph{C/C++}:
 359 @multitable @columnfractions .20 .80
 360 @item @emph{Prototype}: @tab @code{int omp_get_nested(void);}
 361 @end multitable
 362
 363 @item @emph{Fortran}:
 364 @multitable @columnfractions .20 .80
 365 @item @emph{Interface}: @tab @code{integer function omp_get_nested()}
 366 @end multitable
 367
 368 @item @emph{See also}:
 369 @ref{omp_set_nested}, @ref{OMP_NESTED}
 370
 371 @item @emph{Reference}:
 372 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, section 3.2.10.
 373 @end table
 374
 375
 376
 377 @node omp_get_num_procs
 378 @section @code{omp_get_num_procs} -- Number of processors online
 379 @table @asis
 380 @item @emph{Description}:
 381 Returns the number of processors online.
 382
 383 @item @emph{C/C++}:
 384 @multitable @columnfractions .20 .80
 385 @item @emph{Prototype}: @tab @code{int omp_get_num_procs(void);}
 386 @end multitable
 387
 388 @item @emph{Fortran}:
 389 @multitable @columnfractions .20 .80
 390 @item @emph{Interface}: @tab @code{integer function omp_get_num_procs()}
 391 @end multitable
 392
 393 @item @emph{Reference}:
 394 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, section 3.2.5.
 395 @end table
 396
 397
 398
 399 @node omp_get_num_threads
 400 @section @code{omp_get_num_threads} -- Size of the active team
 401 @table @asis
 402 @item @emph{Description}:
 403 Returns the number of threads in the current team. In a sequential section of
 404 the program @code{omp_get_num_threads} returns 1.
 405
 406 The default team size may be initialized at startup by the
 407 @code{OMP_NUM_THREADS} environment variable. At runtime, the size
 408 of the current team may be set either by the @code{NUM_THREADS}
 409 clause or by @code{omp_set_num_threads}. If none of the above were
 410 used to define a specific value and @code{OMP_DYNAMIC} is disabled,
 411 one thread per CPU online is used.
 412
 413 @item @emph{C/C++}:
 414 @multitable @columnfractions .20 .80
 415 @item @emph{Prototype}: @tab @code{int omp_get_num_threads(void);}
 416 @end multitable
 417
 418 @item @emph{Fortran}:
 419 @multitable @columnfractions .20 .80
 420 @item @emph{Interface}: @tab @code{integer function omp_get_num_threads()}
 421 @end multitable
 422
 423 @item @emph{See also}:
 424 @ref{omp_get_max_threads}, @ref{omp_set_num_threads}, @ref{OMP_NUM_THREADS}
 425
 426 @item @emph{Reference}:
 427 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, section 3.2.2.
 428 @end table
 429
 430
 431
 432 @node omp_get_schedule
 433 @section @code{omp_get_schedule} -- Obtain the runtime scheduling method
 434 @table @asis
 435 @item @emph{Description}:
 436 Obtain the runtime scheduling method. The @var{kind} argument will be
 437 set to the value @code{omp_sched_static}, @code{omp_sched_dynamic},
 438 @code{omp_sched_guided} or @code{omp_sched_auto}. The second argument,
 439 @var{modifier}, is set to the chunk size.
 440
 441 @item @emph{C/C++}
 442 @multitable @columnfractions .20 .80
 443 @item @emph{Prototype}: @tab @code{omp_schedule(omp_sched_t *kind, int *modifier);}
 444 @end multitable
 445
 446 @item @emph{Fortran}:
 447 @multitable @columnfractions .20 .80
 448 @item @emph{Interface}: @tab @code{subroutine omp_schedule(kind, modifier)}
 449 @item                   @tab @code{integer(kind=omp_sched_kind) kind}
 450 @item                   @tab @code{integer modifier}
 451 @end multitable
 452
 453 @item @emph{See also}:
 454 @ref{omp_set_schedule}, @ref{OMP_SCHEDULE}
 455
 456 @item @emph{Reference}:
 457 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, section 3.2.12.
 458 @end table
 459
 460
 461
 462 @node omp_get_team_size
 463 @section @code{omp_get_team_size} -- Number of threads in a team
 464 @table @asis
 465 @item @emph{Description}:
 466 This function returns the number of threads in a thread team to which
 467 either the current thread or its ancestor belongs. For values of @var{level}
 468 outside zero to @code{omp_get_level}, -1 is returned; if @var{level} is zero,
 469 1 is returned, and for @code{omp_get_level}, the result is identical
 470 to @code{omp_get_num_threads}.
 471
 472 @item @emph{C/C++}:
 473 @multitable @columnfractions .20 .80
 474 @item @emph{Prototype}: @tab @code{int omp_get_team_size(int level);}
 475 @end multitable
 476
 477 @item @emph{Fortran}:
 478 @multitable @columnfractions .20 .80
 479 @item @emph{Interface}: @tab @code{integer function omp_get_team_size(level)}
 480 @item                   @tab @code{integer level}
 481 @end multitable
 482
 483 @item @emph{See also}:
 484 @ref{omp_get_num_threads}, @ref{omp_get_level}, @ref{omp_get_ancestor_thread_num}
 485
 486 @item @emph{Reference}:
 487 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, section 3.2.18.
 488 @end table
 489
 490
 491
 492 @node omp_get_thread_limit
 493 @section @code{omp_get_thread_limit} -- Maximum number of threads
 494 @table @asis
 495 @item @emph{Description}:
 496 Return the maximum number of threads of the program.
 497
 498 @item @emph{C/C++}:
 499 @multitable @columnfractions .20 .80
 500 @item @emph{Prototype}: @tab @code{int omp_get_thread_limit(void);}
 501 @end multitable
 502
 503 @item @emph{Fortran}:
 504 @multitable @columnfractions .20 .80
 505 @item @emph{Interface}: @tab @code{integer function omp_get_thread_limit()}
 506 @end multitable
 507
 508 @item @emph{See also}:
 509 @ref{omp_get_max_threads}, @ref{OMP_THREAD_LIMIT}
 510
 511 @item @emph{Reference}:
 512 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, section 3.2.13.
 513 @end table
 514
 515
 516
 517 @node omp_get_thread_num
 518 @section @code{omp_get_thread_num} -- Current thread ID
 519 @table @asis
 520 @item @emph{Description}:
 521 Returns a unique thread identification number within the current team.
 522 In a sequential parts of the program, @code{omp_get_thread_num}
 523 always returns 0. In parallel regions the return value varies
 524 from 0 to @code{omp_get_num_threads}-1 inclusive. The return
 525 value of the master thread of a team is always 0.
 526
 527 @item @emph{C/C++}:
 528 @multitable @columnfractions .20 .80
 529 @item @emph{Prototype}: @tab @code{int omp_get_thread_num(void);}
 530 @end multitable
 531
 532 @item @emph{Fortran}:
 533 @multitable @columnfractions .20 .80
 534 @item @emph{Interface}: @tab @code{integer function omp_get_thread_num()}
 535 @end multitable
 536
 537 @item @emph{See also}:
 538 @ref{omp_get_num_threads}, @ref{omp_get_ancestor_thread_num}
 539
 540 @item @emph{Reference}:
 541 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, section 3.2.4.
 542 @end table
 543
 544
 545
 546 @node omp_in_parallel
 547 @section @code{omp_in_parallel} -- Whether a parallel region is active
 548 @table @asis
 549 @item @emph{Description}:
 550 This function returns @code{true} if currently running in parallel,
 551 @code{false} otherwise. Here, @code{true} and @code{false} represent
 552 their language-specific counterparts.
 553
 554 @item @emph{C/C++}:
 555 @multitable @columnfractions .20 .80
 556 @item @emph{Prototype}: @tab @code{int omp_in_parallel(void);}
 557 @end multitable
 558
 559 @item @emph{Fortran}:
 560 @multitable @columnfractions .20 .80
 561 @item @emph{Interface}: @tab @code{logical function omp_in_parallel()}
 562 @end multitable
 563
 564 @item @emph{Reference}:
 565 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, section 3.2.6.
 566 @end table
 567
 568
 569 @node omp_set_dynamic
 570 @section @code{omp_set_dynamic} -- Enable/disable dynamic teams
 571 @table @asis
 572 @item @emph{Description}:
 573 Enable or disable the dynamic adjustment of the number of threads
 574 within a team. The function takes the language-specific equivalent
 575 of @code{true} and @code{false}, where @code{true} enables dynamic
 576 adjustment of team sizes and @code{false} disables it.
 577
 578 @item @emph{C/C++}:
 579 @multitable @columnfractions .20 .80
 580 @item @emph{Prototype}: @tab @code{void omp_set_dynamic(int set);}
 581 @end multitable
 582
 583 @item @emph{Fortran}:
 584 @multitable @columnfractions .20 .80
 585 @item @emph{Interface}: @tab @code{subroutine omp_set_dynamic(set)}
 586 @item                   @tab @code{integer, intent(in) :: set}
 587 @end multitable
 588
 589 @item @emph{See also}:
 590 @ref{OMP_DYNAMIC}, @ref{omp_get_dynamic}
 591
 592 @item @emph{Reference}:
 593 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, section 3.2.7.
 594 @end table
 595
 596
 597
 598 @node omp_set_max_active_levels
 599 @section @code{omp_set_max_active_levels} -- Limits the number of active parallel regions
 600 @table @asis
 601 @item @emph{Description}:
 602 This function limits the maximum allowed number of nested, active
 603 parallel regions.
 604
 605 @item @emph{C/C++}
 606 @multitable @columnfractions .20 .80
 607 @item @emph{Prototype}: @tab @code{void omp_set_max_active_levels(int max_levels);}
 608 @end multitable
 609
 610 @item @emph{Fortran}:
 611 @multitable @columnfractions .20 .80
 612 @item @emph{Interface}: @tab @code{subroutine omp_set_max_active_levels(max_levels)}
 613 @item                   @tab @code{integer max_levels}
 614 @end multitable
 615
 616 @item @emph{See also}:
 617 @ref{omp_get_max_active_levels}, @ref{omp_get_active_level}
 618
 619 @item @emph{Reference}:
 620 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, section 3.2.14.
 621 @end table
 622
 623
 624
 625 @node omp_set_nested
 626 @section @code{omp_set_nested} -- Enable/disable nested parallel regions
 627 @table @asis
 628 @item @emph{Description}:
 629 Enable or disable nested parallel regions, i.e., whether team members
 630 are allowed to create new teams. The function takes the language-specific
 631 equivalent of @code{true} and @code{false}, where @code{true} enables
 632 dynamic adjustment of team sizes and @code{false} disables it.
 633
 634 @item @emph{C/C++}:
 635 @multitable @columnfractions .20 .80
 636 @item @emph{Prototype}: @tab @code{void omp_set_nested(int set);}
 637 @end multitable
 638
 639 @item @emph{Fortran}:
 640 @multitable @columnfractions .20 .80
 641 @item @emph{Interface}: @tab @code{subroutine omp_set_nested(set)}
 642 @item                   @tab @code{integer, intent(in) :: set}
 643 @end multitable
 644
 645 @item @emph{See also}:
 646 @ref{OMP_NESTED}, @ref{omp_get_nested}
 647
 648 @item @emph{Reference}:
 649 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, section 3.2.9.
 650 @end table
 651
 652
 653
 654 @node omp_set_num_threads
 655 @section @code{omp_set_num_threads} -- Set upper team size limit
 656 @table @asis
 657 @item @emph{Description}:
 658 Specifies the number of threads used by default in subsequent parallel
 659 sections, if those do not specify a @code{num_threads} clause. The
 660 argument of @code{omp_set_num_threads} shall be a positive integer.
 661
 662 @item @emph{C/C++}:
 663 @multitable @columnfractions .20 .80
 664 @item @emph{Prototype}: @tab @code{void omp_set_num_threads(int n);}
 665 @end multitable
 666
 667 @item @emph{Fortran}:
 668 @multitable @columnfractions .20 .80
 669 @item @emph{Interface}: @tab @code{subroutine omp_set_num_threads(n)}
 670 @item                   @tab @code{integer, intent(in) :: n}
 671 @end multitable
 672
 673 @item @emph{See also}:
 674 @ref{OMP_NUM_THREADS}, @ref{omp_get_num_threads}, @ref{omp_get_max_threads}
 675
 676 @item @emph{Reference}:
 677 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, section 3.2.1.
 678 @end table
 679
 680
 681
 682 @node omp_set_schedule
 683 @section @code{omp_set_schedule} -- Set the runtime scheduling method
 684 @table @asis
 685 @item @emph{Description}:
 686 Sets the runtime scheduling method. The @var{kind} argument can have the
 687 value @code{omp_sched_static}, @code{omp_sched_dynamic},
 688 @code{omp_sched_guided} or @code{omp_sched_auto}. Except for
 689 @code{omp_sched_auto}, the chunk size is set to the value of
 690 @var{modifier} if positive, or to the default value if zero or negative.
 691 For @code{omp_sched_auto} the @var{modifier} argument is ignored.
 692
 693 @item @emph{C/C++}
 694 @multitable @columnfractions .20 .80
 695 @item @emph{Prototype}: @tab @code{int omp_set_schedule(omp_sched_t *kind, int *modifier);}
 696 @end multitable
 697
 698 @item @emph{Fortran}:
 699 @multitable @columnfractions .20 .80
 700 @item @emph{Interface}: @tab @code{subroutine omp_set_schedule(kind, modifier)}
 701 @item                   @tab @code{integer(kind=omp_sched_kind) kind}
 702 @item                   @tab @code{integer modifier}
 703 @end multitable
 704
 705 @item @emph{See also}:
 706 @ref{omp_get_schedule}
 707 @ref{OMP_SCHEDULE}
 708
 709 @item @emph{Reference}:
 710 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, section 3.2.11.
 711 @end table
 712
 713
 714
 715 @node omp_init_lock
 716 @section @code{omp_init_lock} -- Initialize simple lock
 717 @table @asis
 718 @item @emph{Description}:
 719 Initialize a simple lock.  After initialization, the lock is in
 720 an unlocked state.
 721
 722 @item @emph{C/C++}:
 723 @multitable @columnfractions .20 .80
 724 @item @emph{Prototype}: @tab @code{void omp_init_lock(omp_lock_t *lock);}
 725 @end multitable
 726
 727 @item @emph{Fortran}:
 728 @multitable @columnfractions .20 .80
 729 @item @emph{Interface}: @tab @code{subroutine omp_init_lock(lock)}
 730 @item                   @tab @code{integer(omp_lock_kind), intent(out) :: lock}
 731 @end multitable
 732
 733 @item @emph{See also}:
 734 @ref{omp_destroy_lock}
 735
 736 @item @emph{Reference}:
 737 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, section 3.3.1.
 738 @end table
 739
 740
 741
 742 @node omp_set_lock
 743 @section @code{omp_set_lock} -- Wait for and set simple lock
 744 @table @asis
 745 @item @emph{Description}:
 746 Before setting a simple lock, the lock variable must be initialized by
 747 @code{omp_init_lock}. The calling thread is blocked until the lock
 748 is available. If the lock is already held by the current thread,
 749 a deadlock occurs.
 750
 751 @item @emph{C/C++}:
 752 @multitable @columnfractions .20 .80
 753 @item @emph{Prototype}: @tab @code{void omp_set_lock(omp_lock_t *lock);}
 754 @end multitable
 755
 756 @item @emph{Fortran}:
 757 @multitable @columnfractions .20 .80
 758 @item @emph{Interface}: @tab @code{subroutine omp_set_lock(lock)}
 759 @item                   @tab @code{integer(omp_lock_kind), intent(out) :: lock}
 760 @end multitable
 761
 762 @item @emph{See also}:
 763 @ref{omp_init_lock}, @ref{omp_test_lock}, @ref{omp_unset_lock}
 764
 765 @item @emph{Reference}:
 766 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, section 3.3.3.
 767 @end table
 768
 769
 770
 771 @node omp_test_lock
 772 @section @code{omp_test_lock} -- Test and set simple lock if available
 773 @table @asis
 774 @item @emph{Description}:
 775 Before setting a simple lock, the lock variable must be initialized by
 776 @code{omp_init_lock}. Contrary to @code{omp_set_lock}, @code{omp_test_lock}
 777 does not block if the lock is not available. This function returns
 778 @code{true} upon success, @code{false} otherwise. Here, @code{true} and
 779 @code{false} represent their language-specific counterparts.
 780
 781 @item @emph{C/C++}:
 782 @multitable @columnfractions .20 .80
 783 @item @emph{Prototype}: @tab @code{int omp_test_lock(omp_lock_t *lock);}
 784 @end multitable
 785
 786 @item @emph{Fortran}:
 787 @multitable @columnfractions .20 .80
 788 @item @emph{Interface}: @tab @code{subroutine omp_test_lock(lock)}
 789 @item                   @tab @code{logical(omp_logical_kind) :: omp_test_lock}
 790 @item                   @tab @code{integer(omp_lock_kind), intent(out) :: lock}
 791 @end multitable
 792
 793 @item @emph{See also}:
 794 @ref{omp_init_lock}, @ref{omp_set_lock}, @ref{omp_set_lock}
 795
 796 @item @emph{Reference}:
 797 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, section 3.3.5.
 798 @end table
 799
 800
 801
 802 @node omp_unset_lock
 803 @section @code{omp_unset_lock} -- Unset simple lock
 804 @table @asis
 805 @item @emph{Description}:
 806 A simple lock about to be unset must have been locked by @code{omp_set_lock}
 807 or @code{omp_test_lock} before. In addition, the lock must be held by the
 808 thread calling @code{omp_unset_lock}. Then, the lock becomes unlocked. If one
 809 or more threads attempted to set the lock before, one of them is chosen to,
 810 again, set the lock for itself.
 811
 812 @item @emph{C/C++}:
 813 @multitable @columnfractions .20 .80
 814 @item @emph{Prototype}: @tab @code{void omp_unset_lock(omp_lock_t *lock);}
 815 @end multitable
 816
 817 @item @emph{Fortran}:
 818 @multitable @columnfractions .20 .80
 819 @item @emph{Interface}: @tab @code{subroutine omp_unset_lock(lock)}
 820 @item                   @tab @code{integer(omp_lock_kind), intent(out) :: lock}
 821 @end multitable
 822
 823 @item @emph{See also}:
 824 @ref{omp_set_lock}, @ref{omp_test_lock}
 825
 826 @item @emph{Reference}:
 827 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, section 3.3.4.
 828 @end table
 829
 830
 831
 832 @node omp_destroy_lock
 833 @section @code{omp_destroy_lock} -- Destroy simple lock
 834 @table @asis
 835 @item @emph{Description}:
 836 Destroy a simple lock. In order to be destroyed, a simple lock must be
 837 in the unlocked state.
 838
 839 @item @emph{C/C++}:
 840 @multitable @columnfractions .20 .80
 841 @item @emph{Prototype}: @tab @code{void omp_destroy_lock(omp_lock_t *lock);}
 842 @end multitable
 843
 844 @item @emph{Fortran}:
 845 @multitable @columnfractions .20 .80
 846 @item @emph{Interface}: @tab @code{subroutine omp_destroy_lock(lock)}
 847 @item                   @tab @code{integer(omp_lock_kind), intent(inout) :: lock}
 848 @end multitable
 849
 850 @item @emph{See also}:
 851 @ref{omp_init_lock}
 852
 853 @item @emph{Reference}:
 854 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, section 3.3.2.
 855 @end table
 856
 857
 858
 859 @node omp_init_nest_lock
 860 @section @code{omp_init_nest_lock} -- Initialize nested lock
 861 @table @asis
 862 @item @emph{Description}:
 863 Initialize a nested lock.  After initialization, the lock is in
 864 an unlocked state and the nesting count is set to zero.
 865
 866 @item @emph{C/C++}:
 867 @multitable @columnfractions .20 .80
 868 @item @emph{Prototype}: @tab @code{void omp_init_nest_lock(omp_nest_lock_t *lock);}
 869 @end multitable
 870
 871 @item @emph{Fortran}:
 872 @multitable @columnfractions .20 .80
 873 @item @emph{Interface}: @tab @code{subroutine omp_init_nest_lock(lock)}
 874 @item                   @tab @code{integer(omp_nest_lock_kind), intent(out) :: lock}
 875 @end multitable
 876
 877 @item @emph{See also}:
 878 @ref{omp_destroy_nest_lock}
 879
 880 @item @emph{Reference}:
 881 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, section 3.3.1.
 882 @end table
 883
 884
 885 @node omp_set_nest_lock
 886 @section @code{omp_set_nest_lock} -- Wait for and set nested lock
 887 @table @asis
 888 @item @emph{Description}:
 889 Before setting a nested lock, the lock variable must be initialized by
 890 @code{omp_init_nest_lock}. The calling thread is blocked until the lock
 891 is available. If the lock is already held by the current thread, the
 892 nesting count for the lock in incremented.
 893
 894 @item @emph{C/C++}:
 895 @multitable @columnfractions .20 .80
 896 @item @emph{Prototype}: @tab @code{void omp_set_nest_lock(omp_nest_lock_t *lock);}
 897 @end multitable
 898
 899 @item @emph{Fortran}:
 900 @multitable @columnfractions .20 .80
 901 @item @emph{Interface}: @tab @code{subroutine omp_set_nest_lock(lock)}
 902 @item                   @tab @code{integer(omp_nest_lock_kind), intent(out) :: lock}
 903 @end multitable
 904
 905 @item @emph{See also}:
 906 @ref{omp_init_nest_lock}, @ref{omp_unset_nest_lock}
 907
 908 @item @emph{Reference}:
 909 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, section 3.3.3.
 910 @end table
 911
 912
 913
 914 @node omp_test_nest_lock
 915 @section @code{omp_test_nest_lock} -- Test and set nested lock if available
 916 @table @asis
 917 @item @emph{Description}:
 918 Before setting a nested lock, the lock variable must be initialized by
 919 @code{omp_init_nest_lock}. Contrary to @code{omp_set_nest_lock},
 920 @code{omp_test_nest_lock} does not block if the lock is not available.
 921 If the lock is already held by the current thread, the new nesting count
 922 is returned. Otherwise, the return value equals zero.
 923
 924 @item @emph{C/C++}:
 925 @multitable @columnfractions .20 .80
 926 @item @emph{Prototype}: @tab @code{int omp_test_nest_lock(omp_nest_lock_t *lock);}
 927 @end multitable
 928
 929 @item @emph{Fortran}:
 930 @multitable @columnfractions .20 .80
 931 @item @emph{Interface}: @tab @code{integer function omp_test_nest_lock(lock)}
 932 @item                   @tab @code{integer(omp_integer_kind) :: omp_test_nest_lock}
 933 @item                   @tab @code{integer(omp_nest_lock_kind), intent(inout) :: lock}
 934 @end multitable
 935
 936
 937 @item @emph{See also}:
 938 @ref{omp_init_lock}, @ref{omp_set_lock}, @ref{omp_set_lock}
 939
 940 @item @emph{Reference}:
 941 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, section 3.3.5.
 942 @end table
 943
 944
 945
 946 @node omp_unset_nest_lock
 947 @section @code{omp_unset_nest_lock} -- Unset nested lock
 948 @table @asis
 949 @item @emph{Description}:
 950 A nested lock about to be unset must have been locked by @code{omp_set_nested_lock}
 951 or @code{omp_test_nested_lock} before. In addition, the lock must be held by the
 952 thread calling @code{omp_unset_nested_lock}. If the nesting count drops to zero, the
 953 lock becomes unlocked. If one ore more threads attempted to set the lock before,
 954 one of them is chosen to, again, set the lock for itself.
 955
 956 @item @emph{C/C++}:
 957 @multitable @columnfractions .20 .80
 958 @item @emph{Prototype}: @tab @code{void omp_unset_nest_lock(omp_nest_lock_t *lock);}
 959 @end multitable
 960
 961 @item @emph{Fortran}:
 962 @multitable @columnfractions .20 .80
 963 @item @emph{Interface}: @tab @code{subroutine omp_unset_nest_lock(lock)}
 964 @item                   @tab @code{integer(omp_nest_lock_kind), intent(out) :: lock}
 965 @end multitable
 966
 967 @item @emph{See also}:
 968 @ref{omp_set_nest_lock}
 969
 970 @item @emph{Reference}:
 971 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, section 3.3.4.
 972 @end table
 973
 974
 975
 976 @node omp_destroy_nest_lock
 977 @section @code{omp_destroy_nest_lock} -- Destroy nested lock
 978 @table @asis
 979 @item @emph{Description}:
 980 Destroy a nested lock. In order to be destroyed, a nested lock must be
 981 in the unlocked state and its nesting count must equal zero.
 982
 983 @item @emph{C/C++}:
 984 @multitable @columnfractions .20 .80
 985 @item @emph{Prototype}: @tab @code{void omp_destroy_nest_lock(omp_nest_lock_t *);}
 986 @end multitable
 987
 988 @item @emph{Fortran}:
 989 @multitable @columnfractions .20 .80
 990 @item @emph{Interface}: @tab @code{subroutine omp_destroy_nest_lock(lock)}
 991 @item                   @tab @code{integer(omp_nest_lock_kind), intent(inout) :: lock}
 992 @end multitable
 993
 994 @item @emph{See also}:
 995 @ref{omp_init_lock}
 996
 997 @item @emph{Reference}:
 998 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, section 3.3.2.
 999 @end table
1000
1001
1002
1003 @node omp_get_wtick
1004 @section @code{omp_get_wtick} -- Get timer precision
1005 @table @asis
1006 @item @emph{Description}:
1007 Gets the timer precision, i.e., the number of seconds between two
1008 successive clock ticks.
1009
1010 @item @emph{C/C++}:
1011 @multitable @columnfractions .20 .80
1012 @item @emph{Prototype}: @tab @code{double omp_get_wtick(void);}
1013 @end multitable
1014
1015 @item @emph{Fortran}:
1016 @multitable @columnfractions .20 .80
1017 @item @emph{Interface}: @tab @code{double precision function omp_get_wtick()}
1018 @end multitable
1019
1020 @item @emph{See also}:
1021 @ref{omp_get_wtime}
1022
1023 @item @emph{Reference}:
1024 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, section 3.4.2.
1025 @end table
1026
1027
1028
1029 @node omp_get_wtime
1030 @section @code{omp_get_wtime} -- Elapsed wall clock time
1031 @table @asis
1032 @item @emph{Description}:
1033 Elapsed wall clock time in seconds. The time is measured per thread, no
1034 guarantee can be made that two distinct threads measure the same time.
1035 Time is measured from some "time in the past". On POSIX compliant systems
1036 the seconds since the Epoch (00:00:00 UTC, January 1, 1970) are returned.
1037
1038 @item @emph{C/C++}:
1039 @multitable @columnfractions .20 .80
1040 @item @emph{Prototype}: @tab @code{double omp_get_wtime(void);}
1041 @end multitable
1042
1043 @item @emph{Fortran}:
1044 @multitable @columnfractions .20 .80
1045 @item @emph{Interface}: @tab @code{double precision function omp_get_wtime()}
1046 @end multitable
1047
1048 @item @emph{See also}:
1049 @ref{omp_get_wtick}
1050
1051 @item @emph{Reference}:
1052 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, section 3.4.1.
1053 @end table
1054
1055
1056
1057 @c ---------------------------------------------------------------------
1058 @c Environment Variables
1059 @c ---------------------------------------------------------------------
1060
1061 @node Environment Variables
1062 @chapter Environment Variables
1063
1064 The variables @env{OMP_DYNAMIC}, @env{OMP_MAX_ACTIVE_LEVELS},
1065 @env{OMP_NESTED}, @env{OMP_NUM_THREADS}, @env{OMP_SCHEDULE},
1066 @env{OMP_STACKSIZE},@env{OMP_THREAD_LIMIT} and @env{OMP_WAIT_POLICY}
1067 are defined by section 4 of the OpenMP specifications in version 3.0,
1068 while @env{GOMP_CPU_AFFINITY} and @env{GOMP_STACKSIZE} are GNU
1069 extensions.
1070
1071 @menu
1072 * OMP_DYNAMIC::           Dynamic adjustment of threads
1073 * OMP_MAX_ACTIVE_LEVELS:: Set the maximum number of nested parallel regions
1074 * OMP_NESTED::            Nested parallel regions
1075 * OMP_NUM_THREADS::       Specifies the number of threads to use
1076 * OMP_STACKSIZE::         Set default thread stack size
1077 * OMP_SCHEDULE::          How threads are scheduled
1078 * OMP_THREAD_LIMIT::      Set the maximum number of threads
1079 * OMP_WAIT_POLICY::       How waiting threads are handled
1080 * GOMP_CPU_AFFINITY::     Bind threads to specific CPUs
1081 * GOMP_STACKSIZE::        Set default thread stack size
1082 @end menu
1083
1084
1085 @node OMP_DYNAMIC
1086 @section @env{OMP_DYNAMIC} -- Dynamic adjustment of threads
1087 @cindex Environment Variable
1088 @table @asis
1089 @item @emph{Description}:
1090 Enable or disable the dynamic adjustment of the number of threads
1091 within a team. The value of this environment variable shall be
1092 @code{TRUE} or @code{FALSE}. If undefined, dynamic adjustment is
1093 disabled by default.
1094
1095 @item @emph{See also}:
1096 @ref{omp_set_dynamic}
1097
1098 @item @emph{Reference}:
1099 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, section 4.3
1100 @end table
1101
1102
1103
1104 @node OMP_MAX_ACTIVE_LEVELS
1105 @section @env{OMP_MAX_ACTIVE_LEVELS} -- Set the maximum number of nested parallel regions
1106 @cindex Environment Variable
1107 @table @asis
1108 @item @emph{Description}:
1109 Specifies the initial value for the maximum number of nested parallel
1110 regions. The value of this variable shall be positive integer.
1111 If undefined, the number of active levels is unlimited.
1112
1113 @item @emph{See also}:
1114 @ref{omp_set_max_active_levels}
1115
1116 @item @emph{Reference}:
1117 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, section 4.7
1118 @end table
1119
1120
1121
1122 @node OMP_NESTED
1123 @section @env{OMP_NESTED} -- Nested parallel regions
1124 @cindex Environment Variable
1125 @cindex Implementation specific setting
1126 @table @asis
1127 @item @emph{Description}:
1128 Enable or disable nested parallel regions, i.e., whether team members
1129 are allowed to create new teams. The value of this environment variable
1130 shall be @code{TRUE} or @code{FALSE}. If undefined, nested parallel
1131 regions are disabled by default.
1132
1133 @item @emph{See also}:
1134 @ref{omp_set_nested}
1135
1136 @item @emph{Reference}:
1137 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, section 4.4
1138 @end table
1139
1140
1141
1142 @node OMP_NUM_THREADS
1143 @section @env{OMP_NUM_THREADS} -- Specifies the number of threads to use
1144 @cindex Environment Variable
1145 @cindex Implementation specific setting
1146 @table @asis
1147 @item @emph{Description}:
1148 Specifies the default number of threads to use in parallel regions. The
1149 value of this variable shall be a positive integer. If undefined one thread
1150 per CPU is used.
1151
1152 @item @emph{See also}:
1153 @ref{omp_set_num_threads}
1154
1155 @item @emph{Reference}:
1156 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, section 4.2
1157 @end table
1158
1159
1160
1161 @node OMP_SCHEDULE
1162 @section @env{OMP_SCHEDULE} -- How threads are scheduled
1163 @cindex Environment Variable
1164 @cindex Implementation specific setting
1165 @table @asis
1166 @item @emph{Description}:
1167 Allows to specify @code{schedule type} and @code{chunk size}.
1168 The value of the variable shall have the form: @code{type[,chunk]} where
1169 @code{type} is one of @code{static}, @code{dynamic}, @code{guided} or @code{auto}
1170 The optional @code{chunk} size shall be a positive integer. If undefined,
1171 dynamic scheduling and a chunk size of 1 is used.
1172
1173 @item @emph{See also}:
1174 @ref{omp_set_schedule}
1175
1176 @item @emph{Reference}:
1177 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, sections 2.5.1 and 4.1
1178 @end table
1179
1180
1181
1182 @node OMP_STACKSIZE
1183 @section @env{OMP_STACKSIZE} -- Set default thread stack size
1184 @cindex Environment Variable
1185 @table @asis
1186 @item @emph{Description}:
1187 Set the default thread stack size in kilobytes, unless the number
1188 is suffixed by @code{B}, @code{K}, @code{M} or @code{G}, in which
1189 case the size is, respectively, in bytes, kilobytes, megabytes
1190 or gigabytes. This is different from @code{pthread_attr_setstacksize}
1191 which gets the number of bytes as an argument. If the stacksize cannot
1192 be set due to system constraints, an error is reported and the initial
1193 stacksize is left unchanged. If undefined, the stack size is system
1194 dependent.
1195
1196 @item @emph{Reference}:
1197 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, sections 4.5
1198 @end table
1199
1200
1201
1202 @node OMP_THREAD_LIMIT
1203 @section @env{OMP_THREAD_LIMIT} -- Set the maximum number of threads
1204 @cindex Environment Variable
1205 @table @asis
1206 @item @emph{Description}:
1207 Specifies the number of threads to use for the whole program. The
1208 value of this variable shall be a positive integer. If undefined,
1209 the number of threads is not limited.
1210
1211 @item @emph{See also}:
1212 @ref{OMP_NUM_THREADS}
1213 @ref{omp_get_thread_limit}
1214
1215 @item @emph{Reference}:
1216 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, section 4.8
1217 @end table
1218
1219
1220
1221 @node OMP_WAIT_POLICY
1222 @section @env{OMP_WAIT_POLICY} -- How waiting threads are handled
1223 @cindex Environment Variable
1224 @table @asis
1225 @item @emph{Description}:
1226 Specifies whether waiting threads should be active or passive. If
1227 the value is @code{PASSIVE}, waiting threads should not consume CPU
1228 power while waiting; while the value is @code{ACTIVE} specifies that
1229 they should.
1230
1231 @item @emph{Reference}:
1232 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, sections 4.6
1233 @end table
1234
1235
1236
1237 @node GOMP_CPU_AFFINITY
1238 @section @env{GOMP_CPU_AFFINITY} -- Bind threads to specific CPUs
1239 @cindex Environment Variable
1240 @table @asis
1241 @item @emph{Description}:
1242 Binds threads to specific CPUs. The variable should contain a space-separated
1243 or comma-separated list of CPUs. This list may contain different kinds of
1244 entries: either single CPU numbers in any order, a range of CPUs (M-N)
1245 or a range with some stride (M-N:S).  CPU numbers are zero based. For example,
1246 @code{GOMP_CPU_AFFINITY="0 3 1-2 4-15:2"} will bind the initial thread
1247 to CPU 0, the second to CPU 3, the third to CPU 1, the fourth to
1248 CPU 2, the fifth to CPU 4, the sixth through tenth to CPUs 6, 8, 10, 12,
1249 and 14 respectively and then start assigning back from the beginning of
1250 the list.  @code{GOMP_CPU_AFFINITY=0} binds all threads to CPU 0.
1251
1252 There is no GNU OpenMP library routine to determine whether a CPU affinity
1253 specification is in effect. As a workaround, language-specific library
1254 functions, e.g., @code{getenv} in C or @code{GET_ENVIRONMENT_VARIABLE} in
1255 Fortran, may be used to query the setting of the @code{GOMP_CPU_AFFINITY}
1256 environment variable. A defined CPU affinity on startup cannot be changed
1257 or disabled during the runtime of the application.
1258
1259 If this environment variable is omitted, the host system will handle the
1260 assignment of threads to CPUs.
1261 @end table
1262
1263
1264
1265 @node GOMP_STACKSIZE
1266 @section @env{GOMP_STACKSIZE} -- Set default thread stack size
1267 @cindex Environment Variable
1268 @cindex Implementation specific setting
1269 @table @asis
1270 @item @emph{Description}:
1271 Set the default thread stack size in kilobytes. This is different from
1272 @code{pthread_attr_setstacksize} which gets the number of bytes as an
1273 argument. If the stacksize cannot be set due to system constraints, an
1274 error is reported and the initial stacksize is left unchanged. If undefined,
1275 the stack size is system dependent.
1276
1277 @item @emph{See also}:
1278 @ref{GOMP_STACKSIZE}
1279
1280 @item @emph{Reference}:
1281 @uref{http://gcc.gnu.org/ml/gcc-patches/2006-06/msg00493.html,
1282 GCC Patches Mailinglist},
1283 @uref{http://gcc.gnu.org/ml/gcc-patches/2006-06/msg00496.html,
1284 GCC Patches Mailinglist}
1285 @end table
1286
1287
1288
1289 @c ---------------------------------------------------------------------
1290 @c The libgomp ABI
1291 @c ---------------------------------------------------------------------
1292
1293 @node The libgomp ABI
1294 @chapter The libgomp ABI
1295
1296 The following sections present notes on the external ABI as
1297 presented by libgomp.  Only maintainers should need them.
1298
1299 @menu
1300 * Implementing MASTER construct::
1301 * Implementing CRITICAL construct::
1302 * Implementing ATOMIC construct::
1303 * Implementing FLUSH construct::
1304 * Implementing BARRIER construct::
1305 * Implementing THREADPRIVATE construct::
1306 * Implementing PRIVATE clause::
1307 * Implementing FIRSTPRIVATE LASTPRIVATE COPYIN and COPYPRIVATE clauses::
1308 * Implementing REDUCTION clause::
1309 * Implementing PARALLEL construct::
1310 * Implementing FOR construct::
1311 * Implementing ORDERED construct::
1312 * Implementing SECTIONS construct::
1313 * Implementing SINGLE construct::
1314 @end menu
1315
1316
1317 @node Implementing MASTER construct
1318 @section Implementing MASTER construct
1319
1320 @smallexample
1321 if (omp_get_thread_num () == 0)
1322   block
1323 @end smallexample
1324
1325 Alternately, we generate two copies of the parallel subfunction
1326 and only include this in the version run by the master thread.
1327 Surely this is not worthwhile though...
1328
1329
1330
1331 @node Implementing CRITICAL construct
1332 @section Implementing CRITICAL construct
1333
1334 Without a specified name,
1335
1336 @smallexample
1337   void GOMP_critical_start (void);
1338   void GOMP_critical_end (void);
1339 @end smallexample
1340
1341 so that we don't get COPY relocations from libgomp to the main
1342 application.
1343
1344 With a specified name, use omp_set_lock and omp_unset_lock with
1345 name being transformed into a variable declared like
1346
1347 @smallexample
1348   omp_lock_t gomp_critical_user_<name> __attribute__((common))
1349 @end smallexample
1350
1351 Ideally the ABI would specify that all zero is a valid unlocked
1352 state, and so we wouldn't need to initialize this at
1353 startup.
1354
1355
1356
1357 @node Implementing ATOMIC construct
1358 @section Implementing ATOMIC construct
1359
1360 The target should implement the @code{__sync} builtins.
1361
1362 Failing that we could add
1363
1364 @smallexample
1365   void GOMP_atomic_enter (void)
1366   void GOMP_atomic_exit (void)
1367 @end smallexample
1368
1369 which reuses the regular lock code, but with yet another lock
1370 object private to the library.
1371
1372
1373
1374 @node Implementing FLUSH construct
1375 @section Implementing FLUSH construct
1376
1377 Expands to the @code{__sync_synchronize} builtin.
1378
1379
1380
1381 @node Implementing BARRIER construct
1382 @section Implementing BARRIER construct
1383
1384 @smallexample
1385   void GOMP_barrier (void)
1386 @end smallexample
1387
1388
1389 @node Implementing THREADPRIVATE construct
1390 @section Implementing THREADPRIVATE construct
1391
1392 In _most_ cases we can map this directly to @code{__thread}.  Except
1393 that OMP allows constructors for C++ objects.  We can either
1394 refuse to support this (how often is it used?) or we can
1395 implement something akin to .ctors.
1396
1397 Even more ideally, this ctor feature is handled by extensions
1398 to the main pthreads library.  Failing that, we can have a set
1399 of entry points to register ctor functions to be called.
1400
1401
1402
1403 @node Implementing PRIVATE clause
1404 @section Implementing PRIVATE clause
1405
1406 In association with a PARALLEL, or within the lexical extent
1407 of a PARALLEL block, the variable becomes a local variable in
1408 the parallel subfunction.
1409
1410 In association with FOR or SECTIONS blocks, create a new
1411 automatic variable within the current function.  This preserves
1412 the semantic of new variable creation.
1413
1414
1415
1416 @node Implementing FIRSTPRIVATE LASTPRIVATE COPYIN and COPYPRIVATE clauses
1417 @section Implementing FIRSTPRIVATE LASTPRIVATE COPYIN and COPYPRIVATE clauses
1418
1419 This seems simple enough for PARALLEL blocks.  Create a private
1420 struct for communicating between the parent and subfunction.
1421 In the parent, copy in values for scalar and "small" structs;
1422 copy in addresses for others TREE_ADDRESSABLE types.  In the
1423 subfunction, copy the value into the local variable.
1424
1425 It is not clear what to do with bare FOR or SECTION blocks.
1426 The only thing I can figure is that we do something like:
1427
1428 @smallexample
1429 #pragma omp for firstprivate(x) lastprivate(y)
1430 for (int i = 0; i < n; ++i)
1431   body;
1432 @end smallexample
1433
1434 which becomes
1435
1436 @smallexample
1437 @{
1438   int x = x, y;
1439
1440   // for stuff
1441
1442   if (i == n)
1443     y = y;
1444 @}
1445 @end smallexample
1446
1447 where the "x=x" and "y=y" assignments actually have different
1448 uids for the two variables, i.e. not something you could write
1449 directly in C.  Presumably this only makes sense if the "outer"
1450 x and y are global variables.
1451
1452 COPYPRIVATE would work the same way, except the structure
1453 broadcast would have to happen via SINGLE machinery instead.
1454
1455
1456
1457 @node Implementing REDUCTION clause
1458 @section Implementing REDUCTION clause
1459
1460 The private struct mentioned in the previous section should have
1461 a pointer to an array of the type of the variable, indexed by the
1462 thread's @var{team_id}.  The thread stores its final value into the
1463 array, and after the barrier, the master thread iterates over the
1464 array to collect the values.
1465
1466
1467 @node Implementing PARALLEL construct
1468 @section Implementing PARALLEL construct
1469
1470 @smallexample
1471   #pragma omp parallel
1472   @{
1473     body;
1474   @}
1475 @end smallexample
1476
1477 becomes
1478
1479 @smallexample
1480   void subfunction (void *data)
1481   @{
1482     use data;
1483     body;
1484   @}
1485
1486   setup data;
1487   GOMP_parallel_start (subfunction, &data, num_threads);
1488   subfunction (&data);
1489   GOMP_parallel_end ();
1490 @end smallexample
1491
1492 @smallexample
1493   void GOMP_parallel_start (void (*fn)(void *), void *data, unsigned num_threads)
1494 @end smallexample
1495
1496 The @var{FN} argument is the subfunction to be run in parallel.
1497
1498 The @var{DATA} argument is a pointer to a structure used to
1499 communicate data in and out of the subfunction, as discussed
1500 above with respect to FIRSTPRIVATE et al.
1501
1502 The @var{NUM_THREADS} argument is 1 if an IF clause is present
1503 and false, or the value of the NUM_THREADS clause, if
1504 present, or 0.
1505
1506 The function needs to create the appropriate number of
1507 threads and/or launch them from the dock.  It needs to
1508 create the team structure and assign team ids.
1509
1510 @smallexample
1511   void GOMP_parallel_end (void)
1512 @end smallexample
1513
1514 Tears down the team and returns us to the previous @code{omp_in_parallel()} state.
1515
1516
1517
1518 @node Implementing FOR construct
1519 @section Implementing FOR construct
1520
1521 @smallexample
1522   #pragma omp parallel for
1523   for (i = lb; i <= ub; i++)
1524     body;
1525 @end smallexample
1526
1527 becomes
1528
1529 @smallexample
1530   void subfunction (void *data)
1531   @{
1532     long _s0, _e0;
1533     while (GOMP_loop_static_next (&_s0, &_e0))
1534     @{
1535       long _e1 = _e0, i;
1536       for (i = _s0; i < _e1; i++)
1537         body;
1538     @}
1539     GOMP_loop_end_nowait ();
1540   @}
1541
1542   GOMP_parallel_loop_static (subfunction, NULL, 0, lb, ub+1, 1, 0);
1543   subfunction (NULL);
1544   GOMP_parallel_end ();
1545 @end smallexample
1546
1547 @smallexample
1548   #pragma omp for schedule(runtime)
1549   for (i = 0; i < n; i++)
1550     body;
1551 @end smallexample
1552
1553 becomes
1554
1555 @smallexample
1556   @{
1557     long i, _s0, _e0;
1558     if (GOMP_loop_runtime_start (0, n, 1, &_s0, &_e0))
1559       do @{
1560         long _e1 = _e0;
1561         for (i = _s0, i < _e0; i++)
1562           body;
1563       @} while (GOMP_loop_runtime_next (&_s0, _&e0));
1564     GOMP_loop_end ();
1565   @}
1566 @end smallexample
1567
1568 Note that while it looks like there is trickiness to propagating
1569 a non-constant STEP, there isn't really.  We're explicitly allowed
1570 to evaluate it as many times as we want, and any variables involved
1571 should automatically be handled as PRIVATE or SHARED like any other
1572 variables.  So the expression should remain evaluable in the
1573 subfunction.  We can also pull it into a local variable if we like,
1574 but since its supposed to remain unchanged, we can also not if we like.
1575
1576 If we have SCHEDULE(STATIC), and no ORDERED, then we ought to be
1577 able to get away with no work-sharing context at all, since we can
1578 simply perform the arithmetic directly in each thread to divide up
1579 the iterations.  Which would mean that we wouldn't need to call any
1580 of these routines.
1581
1582 There are separate routines for handling loops with an ORDERED
1583 clause.  Bookkeeping for that is non-trivial...
1584
1585
1586
1587 @node Implementing ORDERED construct
1588 @section Implementing ORDERED construct
1589
1590 @smallexample
1591   void GOMP_ordered_start (void)
1592   void GOMP_ordered_end (void)
1593 @end smallexample
1594
1595
1596
1597 @node Implementing SECTIONS construct
1598 @section Implementing SECTIONS construct
1599
1600 A block as
1601
1602 @smallexample
1603   #pragma omp sections
1604   @{
1605     #pragma omp section
1606     stmt1;
1607     #pragma omp section
1608     stmt2;
1609     #pragma omp section
1610     stmt3;
1611   @}
1612 @end smallexample
1613
1614 becomes
1615
1616 @smallexample
1617   for (i = GOMP_sections_start (3); i != 0; i = GOMP_sections_next ())
1618     switch (i)
1619       @{
1620       case 1:
1621         stmt1;
1622         break;
1623       case 2:
1624         stmt2;
1625         break;
1626       case 3:
1627         stmt3;
1628         break;
1629       @}
1630   GOMP_barrier ();
1631 @end smallexample
1632
1633
1634 @node Implementing SINGLE construct
1635 @section Implementing SINGLE construct
1636
1637 A block like
1638
1639 @smallexample
1640   #pragma omp single
1641   @{
1642     body;
1643   @}
1644 @end smallexample
1645
1646 becomes
1647
1648 @smallexample
1649   if (GOMP_single_start ())
1650     body;
1651   GOMP_barrier ();
1652 @end smallexample
1653
1654 while
1655
1656 @smallexample
1657   #pragma omp single copyprivate(x)
1658     body;
1659 @end smallexample
1660
1661 becomes
1662
1663 @smallexample
1664   datap = GOMP_single_copy_start ();
1665   if (datap == NULL)
1666     @{
1667       body;
1668       data.x = x;
1669       GOMP_single_copy_end (&data);
1670     @}
1671   else
1672     x = datap->x;
1673   GOMP_barrier ();
1674 @end smallexample
1675
1676
1677
1678 @c ---------------------------------------------------------------------
1679 @c
1680 @c ---------------------------------------------------------------------
1681
1682 @node Reporting Bugs
1683 @chapter Reporting Bugs
1684
1685 Bugs in the GNU OpenMP implementation should be reported via
1686 @uref{http://gcc.gnu.org/bugzilla/, bugzilla}.  For all cases, please add
1687 "openmp" to the keywords field in the bug report.
1688
1689
1690
1691 @c ---------------------------------------------------------------------
1692 @c GNU General Public License
1693 @c ---------------------------------------------------------------------
1694
1695 @include gpl.texi
1696
1697
1698
1699 @c ---------------------------------------------------------------------
1700 @c GNU Free Documentation License
1701 @c ---------------------------------------------------------------------
1702
1703 @include fdl.texi
1704
1705
1706
1707 @c ---------------------------------------------------------------------
1708 @c Funding Free Software
1709 @c ---------------------------------------------------------------------
1710
1711 @include funding.texi
1712
1713 @c ---------------------------------------------------------------------
1714 @c Index
1715 @c ---------------------------------------------------------------------
1716
1717 @node Index
1718 @unnumbered Index
1719
1720 @printindex cp
1721
1722 @bye