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 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.2 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::   Maximal number of active regions
 141 * omp_get_max_threads::         Maximal 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::        Maximal 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();}
 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_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();}
 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();}
 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_set_max_active_levels} -- Maximal number of active regions
 296 @table @asis
 297 @item @emph{Description}:
 298 This function obtains the maximally 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();}
 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} -- Maximal number of threads of parallel region
 321 @table @asis
 322 @item @emph{Description}:
 323 Return the maximal 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();}
 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();}
 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();}
 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 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();}
 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 runtime the scheduling method. The @var{kind} argument will be
 437 set to the value @code{omp_sched_static}, @code{omp_sched_dynamic},
 438 @code{opm_sched_guided} or @code{auto}. The second argument, @var{modifier},
 439 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_time_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} -- Maximal number of threads
 494 @table @asis
 495 @item @emph{Description}:
 496 Return the maximal 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();}
 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 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();}
 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();}
 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);}
 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 maximally allowed number of nested, active parallel regions.
 603
 604 @item @emph{C/C++}
 605 @multitable @columnfractions .20 .80
 606 @item @emph{Prototype}: @tab @code{omp_set_max_active_levels(int max_levels);}
 607 @end multitable
 608
 609 @item @emph{Fortran}:
 610 @multitable @columnfractions .20 .80
 611 @item @emph{Interface}: @tab @code{omp_max_active_levels(max_levels)}
 612 @item                   @tab @code{integer max_levels}
 613 @end multitable
 614
 615 @item @emph{See also}:
 616 @ref{omp_get_max_active_levels}, @ref{omp_get_active_level}
 617
 618 @item @emph{Reference}:
 619 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, section 3.2.14.
 620 @end table
 621
 622
 623
 624 @node omp_set_nested
 625 @section @code{omp_set_nested} -- Enable/disable nested parallel regions
 626 @table @asis
 627 @item @emph{Description}:
 628 Enable or disable nested parallel regions, i.e., whether team members
 629 are allowed to create new teams. The function takes the language-specific
 630 equivalent of @code{true} and @code{false}, where @code{true} enables
 631 dynamic adjustment of team sizes and @code{false} disables it.
 632
 633 @item @emph{C/C++}:
 634 @multitable @columnfractions .20 .80
 635 @item @emph{Prototype}: @tab @code{void omp_set_dynamic(int);}
 636 @end multitable
 637
 638 @item @emph{Fortran}:
 639 @multitable @columnfractions .20 .80
 640 @item @emph{Interface}: @tab @code{subroutine omp_set_dynamic(set)}
 641 @item                   @tab @code{integer, intent(in) :: set}
 642 @end multitable
 643
 644 @item @emph{See also}:
 645 @ref{OMP_NESTED}, @ref{omp_get_nested}
 646
 647 @item @emph{Reference}:
 648 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, section 3.2.9.
 649 @end table
 650
 651
 652
 653 @node omp_set_num_threads
 654 @section @code{omp_set_num_threads} -- Set upper team size limit
 655 @table @asis
 656 @item @emph{Description}:
 657 Specifies the number of threads used by default in subsequent parallel
 658 sections, if those do not specify a @code{num_threads} clause. The
 659 argument of @code{omp_set_num_threads} shall be a positive integer.
 660
 661 @item @emph{C/C++}:
 662 @multitable @columnfractions .20 .80
 663 @item @emph{Prototype}: @tab @code{void omp_set_num_threads(int);}
 664 @end multitable
 665
 666 @item @emph{Fortran}:
 667 @multitable @columnfractions .20 .80
 668 @item @emph{Interface}: @tab @code{subroutine omp_set_num_threads(set)}
 669 @item                   @tab @code{integer, intent(in) :: set}
 670 @end multitable
 671
 672 @item @emph{See also}:
 673 @ref{OMP_NUM_THREADS}, @ref{omp_get_num_threads}, @ref{omp_get_max_threads}
 674
 675 @item @emph{Reference}:
 676 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, section 3.2.1.
 677 @end table
 678
 679
 680
 681 @node omp_set_schedule
 682 @section @code{omp_set_schedule} -- Set the runtime scheduling method
 683 @table @asis
 684 @item @emph{Description}:
 685 Sets the runtime scheduling method. The @var{kind} argument can have the
 686 value @code{omp_sched_static}, @code{omp_sched_dynamic},
 687 @code{opm_sched_guided} or @code{omp_sched_auto}. Except for
 688 @code{omp_sched_auto}, the chunk size is set to the value of
 689 @var{modifier} if positive or to the default value if zero or negative.
 690 For @code{omp_sched_auto} the @var{modifier} argument is ignored.
 691
 692 @item @emph{C/C++}
 693 @multitable @columnfractions .20 .80
 694 @item @emph{Prototype}: @tab @code{int omp_schedule(omp_sched_t * kind, int *modifier);}
 695 @end multitable
 696
 697 @item @emph{Fortran}:
 698 @multitable @columnfractions .20 .80
 699 @item @emph{Interface}: @tab @code{subroutine omp_schedule(kind, modifier)}
 700 @item                   @tab @code{integer(kind=omp_sched_kind) kind}
 701 @item                   @tab @code{integer modifier}
 702 @end multitable
 703
 704 @item @emph{See also}:
 705 @ref{omp_get_schedule}
 706 @ref{OMP_SCHEDULE}
 707
 708 @item @emph{Reference}:
 709 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, section 3.2.11.
 710 @end table
 711
 712
 713
 714 @node omp_init_lock
 715 @section @code{omp_init_lock} -- Initialize simple lock
 716 @table @asis
 717 @item @emph{Description}:
 718 Initialize a simple lock. After initialization, the lock is in
 719 an unlocked state.
 720
 721 @item @emph{C/C++}:
 722 @multitable @columnfractions .20 .80
 723 @item @emph{Prototype}: @tab @code{void omp_init_lock(omp_lock_t *lock);}
 724 @end multitable
 725
 726 @item @emph{Fortran}:
 727 @multitable @columnfractions .20 .80
 728 @item @emph{Interface}: @tab @code{subroutine omp_init_lock(lock)}
 729 @item                   @tab @code{integer(omp_lock_kind), intent(out) :: lock}
 730 @end multitable
 731
 732 @item @emph{See also}:
 733 @ref{omp_destroy_lock}
 734
 735 @item @emph{Reference}:
 736 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, section 3.3.1.
 737 @end table
 738
 739
 740
 741 @node omp_set_lock
 742 @section @code{omp_set_lock} -- Wait for and set simple lock
 743 @table @asis
 744 @item @emph{Description}:
 745 Before setting a simple lock, the lock variable must be initialized by
 746 @code{omp_init_lock}. The calling thread is blocked until the lock
 747 is available. If the lock is already held by the current thread,
 748 a deadlock occurs.
 749
 750 @item @emph{C/C++}:
 751 @multitable @columnfractions .20 .80
 752 @item @emph{Prototype}: @tab @code{void omp_set_lock(omp_lock_t *lock);}
 753 @end multitable
 754
 755 @item @emph{Fortran}:
 756 @multitable @columnfractions .20 .80
 757 @item @emph{Interface}: @tab @code{subroutine omp_set_lock(lock)}
 758 @item                   @tab @code{integer(omp_lock_kind), intent(out) :: lock}
 759 @end multitable
 760
 761 @item @emph{See also}:
 762 @ref{omp_init_lock}, @ref{omp_test_lock}, @ref{omp_unset_lock}
 763
 764 @item @emph{Reference}:
 765 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, section 3.3.3.
 766 @end table
 767
 768
 769
 770 @node omp_test_lock
 771 @section @code{omp_test_lock} -- Test and set simple lock if available
 772 @table @asis
 773 @item @emph{Description}:
 774 Before setting a simple lock, the lock variable must be initialized by
 775 @code{omp_init_lock}. Contrary to @code{omp_set_lock}, @code{omp_test_lock}
 776 does not block if the lock is not available. This function returns
 777 @code{true} upon success, @code{false} otherwise. Here, @code{true} and
 778 @code{false} represent their language-specific counterparts.
 779
 780 @item @emph{C/C++}:
 781 @multitable @columnfractions .20 .80
 782 @item @emph{Prototype}: @tab @code{int omp_test_lock(omp_lock_t *lock);}
 783 @end multitable
 784
 785 @item @emph{Fortran}:
 786 @multitable @columnfractions .20 .80
 787 @item @emph{Interface}: @tab @code{subroutine omp_test_lock(lock)}
 788 @item                   @tab @code{logical(omp_logical_kind) :: omp_test_lock}
 789 @item                   @tab @code{integer(omp_lock_kind), intent(out) :: lock}
 790 @end multitable
 791
 792 @item @emph{See also}:
 793 @ref{omp_init_lock}, @ref{omp_set_lock}, @ref{omp_set_lock}
 794
 795 @item @emph{Reference}:
 796 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, section 3.3.5.
 797 @end table
 798
 799
 800
 801 @node omp_unset_lock
 802 @section @code{omp_unset_lock} -- Unset simple lock
 803 @table @asis
 804 @item @emph{Description}:
 805 A simple lock about to be unset must have been locked by @code{omp_set_lock}
 806 or @code{omp_test_lock} before. In addition, the lock must be held by the
 807 thread calling @code{omp_unset_lock}. Then, the lock becomes unlocked. If one
 808 ore more threads attempted to set the lock before, one of them is chosen to,
 809 again, set the lock for itself.
 810
 811 @item @emph{C/C++}:
 812 @multitable @columnfractions .20 .80
 813 @item @emph{Prototype}: @tab @code{void omp_unset_lock(omp_lock_t *lock);}
 814 @end multitable
 815
 816 @item @emph{Fortran}:
 817 @multitable @columnfractions .20 .80
 818 @item @emph{Interface}: @tab @code{subroutine omp_unset_lock(lock)}
 819 @item                   @tab @code{integer(omp_lock_kind), intent(out) :: lock}
 820 @end multitable
 821
 822 @item @emph{See also}:
 823 @ref{omp_set_lock}, @ref{omp_test_lock}
 824
 825 @item @emph{Reference}:
 826 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, section 3.3.4.
 827 @end table
 828
 829
 830
 831 @node omp_destroy_lock
 832 @section @code{omp_destroy_lock} -- Destroy simple lock
 833 @table @asis
 834 @item @emph{Description}:
 835 Destroy a simple lock. In order to be destroyed, a simple lock must be
 836 in the unlocked state.
 837
 838 @item @emph{C/C++}:
 839 @multitable @columnfractions .20 .80
 840 @item @emph{Prototype}: @tab @code{void omp_destroy_lock(omp_lock_t *);}
 841 @end multitable
 842
 843 @item @emph{Fortran}:
 844 @multitable @columnfractions .20 .80
 845 @item @emph{Interface}: @tab @code{subroutine omp_destroy_lock(lock)}
 846 @item                   @tab @code{integer(omp_lock_kind), intent(inout) :: lock}
 847 @end multitable
 848
 849 @item @emph{See also}:
 850 @ref{omp_init_lock}
 851
 852 @item @emph{Reference}:
 853 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, section 3.3.2.
 854 @end table
 855
 856
 857
 858 @node omp_init_nest_lock
 859 @section @code{omp_init_nest_lock} -- Initialize nested lock
 860 @table @asis
 861 @item @emph{Description}:
 862 Initialize a nested lock. After initialization, the lock is in
 863 an unlocked state and the nesting count is set to zero.
 864
 865 @item @emph{C/C++}:
 866 @multitable @columnfractions .20 .80
 867 @item @emph{Prototype}: @tab @code{void omp_init_nest_lock(omp_nest_lock_t *lock);}
 868 @end multitable
 869
 870 @item @emph{Fortran}:
 871 @multitable @columnfractions .20 .80
 872 @item @emph{Interface}: @tab @code{subroutine omp_init_nest_lock(lock)}
 873 @item                   @tab @code{integer(omp_nest_lock_kind), intent(out) :: lock}
 874 @end multitable
 875
 876 @item @emph{See also}:
 877 @ref{omp_destroy_nest_lock}
 878
 879 @item @emph{Reference}:
 880 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, section 3.3.1.
 881 @end table
 882
 883
 884 @node omp_set_nest_lock
 885 @section @code{omp_set_nest_lock} -- Wait for and set simple lock
 886 @table @asis
 887 @item @emph{Description}:
 888 Before setting a nested lock, the lock variable must be initialized by
 889 @code{omp_init_nest_lock}. The calling thread is blocked until the lock
 890 is available. If the lock is already held by the current thread, the
 891 nesting count for the lock in incremented.
 892
 893 @item @emph{C/C++}:
 894 @multitable @columnfractions .20 .80
 895 @item @emph{Prototype}: @tab @code{void omp_set_nest_lock(omp_nest_lock_t *lock);}
 896 @end multitable
 897
 898 @item @emph{Fortran}:
 899 @multitable @columnfractions .20 .80
 900 @item @emph{Interface}: @tab @code{subroutine omp_set_nest_lock(lock)}
 901 @item                   @tab @code{integer(omp_nest_lock_kind), intent(out) :: lock}
 902 @end multitable
 903
 904 @item @emph{See also}:
 905 @ref{omp_init_nest_lock}, @ref{omp_unset_nest_lock}
 906
 907 @item @emph{Reference}:
 908 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, section 3.3.3.
 909 @end table
 910
 911
 912
 913 @node omp_test_nest_lock
 914 @section @code{omp_test_nest_lock} -- Test and set nested lock if available
 915 @table @asis
 916 @item @emph{Description}:
 917 Before setting a nested lock, the lock variable must be initialized by
 918 @code{omp_init_nest_lock}. Contrary to @code{omp_set_nest_lock},
 919 @code{omp_test_nest_lock} does not block if the lock is not available.
 920 If the lock is already held by the current thread, the new nesting count
 921 is returned. Otherwise, the return value equals zero.
 922
 923 @item @emph{C/C++}:
 924 @multitable @columnfractions .20 .80
 925 @item @emph{Prototype}: @tab @code{int omp_test_nest_lock(omp_nest_lock_t *lock);}
 926 @end multitable
 927
 928 @item @emph{Fortran}:
 929 @multitable @columnfractions .20 .80
 930 @item @emph{Interface}: @tab @code{integer function omp_test_nest_lock(lock)}
 931 @item                   @tab @code{integer(omp_integer_kind) :: omp_test_nest_lock}
 932 @item                   @tab @code{integer(omp_nest_lock_kind), intent(inout) :: lock}
 933 @end multitable
 934
 935
 936 @item @emph{See also}:
 937 @ref{omp_init_lock}, @ref{omp_set_lock}, @ref{omp_set_lock}
 938
 939 @item @emph{Reference}:
 940 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, section 3.3.5.
 941 @end table
 942
 943
 944
 945 @node omp_unset_nest_lock
 946 @section @code{omp_unset_nest_lock} -- Unset nested lock
 947 @table @asis
 948 @item @emph{Description}:
 949 A nested lock about to be unset must have been locked by @code{omp_set_nested_lock}
 950 or @code{omp_test_nested_lock} before. In addition, the lock must be held by the
 951 thread calling @code{omp_unset_nested_lock}. If the nesting count drops to zero, the
 952 lock becomes unlocked. If one ore more threads attempted to set the lock before,
 953 one of them is chosen to, again, set the lock for itself.
 954
 955 @item @emph{C/C++}:
 956 @multitable @columnfractions .20 .80
 957 @item @emph{Prototype}: @tab @code{void omp_unset_nest_lock(omp_nest_lock_t *lock);}
 958 @end multitable
 959
 960 @item @emph{Fortran}:
 961 @multitable @columnfractions .20 .80
 962 @item @emph{Interface}: @tab @code{subroutine omp_unset_nest_lock(lock)}
 963 @item                   @tab @code{integer(omp_nest_lock_kind), intent(out) :: lock}
 964 @end multitable
 965
 966 @item @emph{See also}:
 967 @ref{omp_set_nest_lock}
 968
 969 @item @emph{Reference}:
 970 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, section 3.3.4.
 971 @end table
 972
 973
 974
 975 @node omp_destroy_nest_lock
 976 @section @code{omp_destroy_nest_lock} -- Destroy nested lock
 977 @table @asis
 978 @item @emph{Description}:
 979 Destroy a nested lock. In order to be destroyed, a nested lock must be
 980 in the unlocked state and its nesting count must equal zero.
 981
 982 @item @emph{C/C++}:
 983 @multitable @columnfractions .20 .80
 984 @item @emph{Prototype}: @tab @code{void omp_destroy_nest_lock(omp_nest_lock_t *);}
 985 @end multitable
 986
 987 @item @emph{Fortran}:
 988 @multitable @columnfractions .20 .80
 989 @item @emph{Interface}: @tab @code{subroutine omp_destroy_nest_lock(lock)}
 990 @item                   @tab @code{integer(omp_nest_lock_kind), intent(inout) :: lock}
 991 @end multitable
 992
 993 @item @emph{See also}:
 994 @ref{omp_init_lock}
 995
 996 @item @emph{Reference}:
 997 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, section 3.3.2.
 998 @end table
 999
1000
1001
1002 @node omp_get_wtick
1003 @section @code{omp_get_wtick} -- Get timer precision
1004 @table @asis
1005 @item @emph{Description}:
1006 Gets the timer precision, i.e., the number of seconds between two
1007 successive clock ticks.
1008
1009 @item @emph{C/C++}:
1010 @multitable @columnfractions .20 .80
1011 @item @emph{Prototype}: @tab @code{double omp_get_wtick();}
1012 @end multitable
1013
1014 @item @emph{Fortran}:
1015 @multitable @columnfractions .20 .80
1016 @item @emph{Interface}: @tab @code{double precision function omp_get_wtick()}
1017 @end multitable
1018
1019 @item @emph{See also}:
1020 @ref{omp_get_wtime}
1021
1022 @item @emph{Reference}:
1023 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, section 3.4.2.
1024 @end table
1025
1026
1027
1028 @node omp_get_wtime
1029 @section @code{omp_get_wtime} -- Elapsed wall clock time
1030 @table @asis
1031 @item @emph{Description}:
1032 Elapsed wall clock time in seconds. The time is measured per thread, no
1033 guarantee can bee made that two distinct threads measure the same time.
1034 Time is measured from some "time in the past". On POSIX compliant systems
1035 the seconds since the Epoch (00:00:00 UTC, January 1, 1970) are returned.
1036
1037 @item @emph{C/C++}:
1038 @multitable @columnfractions .20 .80
1039 @item @emph{Prototype}: @tab @code{double omp_get_wtime();}
1040 @end multitable
1041
1042 @item @emph{Fortran}:
1043 @multitable @columnfractions .20 .80
1044 @item @emph{Interface}: @tab @code{double precision function omp_get_wtime()}
1045 @end multitable
1046
1047 @item @emph{See also}:
1048 @ref{omp_get_wtick}
1049
1050 @item @emph{Reference}:
1051 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, section 3.4.1.
1052 @end table
1053
1054
1055
1056 @c ---------------------------------------------------------------------
1057 @c Environment Variables
1058 @c ---------------------------------------------------------------------
1059
1060 @node Environment Variables
1061 @chapter Environment Variables
1062
1063 The variables @env{OMP_DYNAMIC}, @env{OMP_MAX_ACTIVE_LEVELS},
1064 @env{OMP_NESTED}, @env{OMP_NUM_THREADS}, @env{OMP_SCHEDULE},
1065 @env{OMP_STACKSIZE},@env{OMP_THREAD_LIMIT} and @env{OMP_WAIT_POLICY}
1066 are defined by section 4 of the OpenMP specifications in version 3.0,
1067 while @env{GOMP_CPU_AFFINITY} and @env{GOMP_STACKSIZE} are GNU
1068 extensions.
1069
1070 @menu
1071 * OMP_DYNAMIC::           Dynamic adjustment of threads
1072 * OMP_MAX_ACTIVE_LEVELS:: Set the maximal number of nested parallel regions
1073 * OMP_NESTED::            Nested parallel regions
1074 * OMP_NUM_THREADS::       Specifies the number of threads to use
1075 * OMP_STACKSIZE::         Set default thread stack size
1076 * OMP_SCHEDULE::          How threads are scheduled
1077 * OMP_THREAD_LIMIT::      Set the maximal number of threads
1078 * OMP_WAIT_POLICY::       How waiting threads are handled
1079 * GOMP_CPU_AFFINITY::     Bind threads to specific CPUs
1080 * GOMP_STACKSIZE::        Set default thread stack size
1081 @end menu
1082
1083
1084 @node OMP_DYNAMIC
1085 @section @env{OMP_DYNAMIC} -- Dynamic adjustment of threads
1086 @cindex Environment Variable
1087 @table @asis
1088 @item @emph{Description}:
1089 Enable or disable the dynamic adjustment of the number of threads
1090 within a team. The value of this environment variable shall be
1091 @code{TRUE} or @code{FALSE}. If undefined, dynamic adjustment is
1092 disabled by default.
1093
1094 @item @emph{See also}:
1095 @ref{omp_set_dynamic}
1096
1097 @item @emph{Reference}:
1098 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, section 4.3
1099 @end table
1100
1101
1102
1103 @node OMP_MAX_ACTIVE_LEVELS
1104 @section @env{OMP_MAX_ACTIVE_LEVELS} -- Set the maximal number of nested parallel regions
1105 @cindex Environment Variable
1106 @table @asis
1107 @item @emph{Description}:
1108 Specifies the initial value for the maximal number of nested parallel
1109 regions. The value of this variable shall be positive integer.
1110 If undefined, the number of active levels is unlimited.
1111
1112 @item @emph{See also}:
1113 @ref{omp_set_max_active_levels}
1114
1115 @item @emph{Reference}:
1116 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, section 4.7
1117 @end table
1118
1119
1120
1121 @node OMP_NESTED
1122 @section @env{OMP_NESTED} -- Nested parallel regions
1123 @cindex Environment Variable
1124 @cindex Implementation specific setting
1125 @table @asis
1126 @item @emph{Description}:
1127 Enable or disable nested parallel regions, i.e., whether team members
1128 are allowed to create new teams. The value of this environment variable
1129 shall be @code{TRUE} or @code{FALSE}. If undefined, nested parallel
1130 regions are disabled by default.
1131
1132 @item @emph{See also}:
1133 @ref{omp_set_nested}
1134
1135 @item @emph{Reference}:
1136 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, section 4.4
1137 @end table
1138
1139
1140
1141 @node OMP_NUM_THREADS
1142 @section @env{OMP_NUM_THREADS} -- Specifies the number of threads to use
1143 @cindex Environment Variable
1144 @cindex Implementation specific setting
1145 @table @asis
1146 @item @emph{Description}:
1147 Specifies the default number of threads to use in parallel regions. The
1148 value of this variable shall be positive integer. If undefined one thread
1149 per CPU online is used.
1150
1151 @item @emph{See also}:
1152 @ref{omp_set_num_threads}
1153
1154 @item @emph{Reference}:
1155 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, section 4.2
1156 @end table
1157
1158
1159
1160 @node OMP_SCHEDULE
1161 @section @env{OMP_SCHEDULE} -- How threads are scheduled
1162 @cindex Environment Variable
1163 @cindex Implementation specific setting
1164 @table @asis
1165 @item @emph{Description}:
1166 Allows to specify @code{schedule type} and @code{chunk size}.
1167 The value of the variable shall have the form: @code{type[,chunk]} where
1168 @code{type} is one of @code{static}, @code{dynamic}, @code{guided} or @code{auto}
1169 The optional @code{chunk} size shall be a positive integer. If undefined,
1170 dynamic scheduling and a chunk size of 1 is used.
1171
1172 @item @emph{See also}:
1173 @ref{omp_set_schedule}
1174
1175 @item @emph{Reference}:
1176 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, sections 2.5.1 and 4.1
1177 @end table
1178
1179
1180
1181 @node OMP_STACKSIZE
1182 @section @env{OMP_STACKSIZE} -- Set default thread stack size
1183 @cindex Environment Variable
1184 @table @asis
1185 @item @emph{Description}:
1186 Set the default thread stack size in kilobytes, unless the number
1187 is suffixed by @code{B}, @code{K}, @code{M} or @code{G}, in which
1188 case the size is, respectively, in bytes, kilobytes, megabytes
1189 or gigabytes. This is different from @code{pthread_attr_setstacksize}
1190 which gets the number of bytes as an argument. If the stacksize can not
1191 be set due to system constraints, an error is reported and the initial
1192 stacksize is left unchanged. If undefined, the stack size is system
1193 dependent.
1194
1195 @item @emph{Reference}:
1196 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, sections 4.5
1197 @end table
1198
1199
1200
1201 @node OMP_THREAD_LIMIT
1202 @section @env{OMP_THREAD_LIMIT} -- Set the maximal number of threads
1203 @cindex Environment Variable
1204 @table @asis
1205 @item @emph{Description}:
1206 Specifies the number of threads to use for the whole program. The
1207 value of this variable shall be positive integer. If undefined,
1208 the number of threads is not limited.
1209
1210 @item @emph{See also}:
1211 @ref{OMP_NUM_THREADS}
1212 @ref{omp_get_thread_limit}
1213
1214 @item @emph{Reference}:
1215 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, section 4.8
1216 @end table
1217
1218
1219
1220 @node OMP_WAIT_POLICY
1221 @section @env{OMP_WAIT_POLICY} -- How waiting threads are handled
1222 @cindex Environment Variable
1223 @table @asis
1224 @item @emph{Description}:
1225 Specifies whether waiting threads should be active or passive. If
1226 the value is @code{PASSIVE}, waiting threads should not consume CPU
1227 power while waiting; while the value is @code{ACTIVE} specifies that
1228 they should.
1229
1230 @item @emph{Reference}:
1231 @uref{http://www.openmp.org/, OpenMP specifications v3.0}, sections 4.6
1232 @end table
1233
1234
1235
1236 @node GOMP_CPU_AFFINITY
1237 @section @env{GOMP_CPU_AFFINITY} -- Bind threads to specific CPUs
1238 @cindex Environment Variable
1239 @table @asis
1240 @item @emph{Description}:
1241 Binds threads to specific CPUs. The variable should contain a space- or
1242 comma-separated list of CPUs. This list may contain different kind of
1243 entries: either single CPU numbers in any order, a range of CPUs (M-N)
1244 or a range with some stride (M-N:S). CPU numbers are zero based. For example,
1245 @code{GOMP_CPU_AFFINITY="0 3 1-2 4-15:2"} will bind the initial thread
1246 to CPU 0, the second to CPU 3, the third to CPU 1, the fourth to
1247 CPU 2, the fifth to CPU 4, the sixth through tenth to CPUs 6, 8, 10, 12,
1248 and 14 respectively and then start assigning back from the beginning of
1249 the list. @code{GOMP_CPU_AFFINITY=0} binds all threads to CPU 0.
1250
1251 There is no GNU OpenMP library routine to determine whether a CPU affinity
1252 specification is in effect. As a workaround, language-specific library
1253 functions, e.g., @code{getenv} in C or @code{GET_ENVIRONMENT_VARIABLE} in
1254 Fortran, may be used to query the setting of the @code{GOMP_CPU_AFFINITY}
1255 environment variable. A defined CPU affinity on startup cannot be changed
1256 or disabled during the runtime of the application.
1257
1258 If this environment variable is omitted, the host system will handle the
1259 assignment of threads to CPUs.
1260 @end table
1261
1262
1263
1264 @node GOMP_STACKSIZE
1265 @section @env{GOMP_STACKSIZE} -- Set default thread stack size
1266 @cindex Environment Variable
1267 @cindex Implementation specific setting
1268 @table @asis
1269 @item @emph{Description}:
1270 Set the default thread stack size in kilobytes. This is different from
1271 @code{pthread_attr_setstacksize} which gets the number of bytes as an
1272 argument. If the stacksize can not be set due to system constraints, an
1273 error is reported and the initial stacksize is left unchanged. If undefined,
1274 the stack size is system dependent.
1275
1276 @item @emph{See also}:
1277 @ref{GOMP_STACKSIZE}
1278
1279 @item @emph{Reference}:
1280 @uref{http://gcc.gnu.org/ml/gcc-patches/2006-06/msg00493.html,
1281 GCC Patches Mailinglist},
1282 @uref{http://gcc.gnu.org/ml/gcc-patches/2006-06/msg00496.html,
1283 GCC Patches Mailinglist}
1284 @end table
1285
1286
1287
1288 @c ---------------------------------------------------------------------
1289 @c The libgomp ABI
1290 @c ---------------------------------------------------------------------
1291
1292 @node The libgomp ABI
1293 @chapter The libgomp ABI
1294
1295 The following sections present notes on the external ABI as
1296 presented by libgomp. Only maintainers should need them.
1297
1298 @menu
1299 * Implementing MASTER construct::
1300 * Implementing CRITICAL construct::
1301 * Implementing ATOMIC construct::
1302 * Implementing FLUSH construct::
1303 * Implementing BARRIER construct::
1304 * Implementing THREADPRIVATE construct::
1305 * Implementing PRIVATE clause::
1306 * Implementing FIRSTPRIVATE LASTPRIVATE COPYIN and COPYPRIVATE clauses::
1307 * Implementing REDUCTION clause::
1308 * Implementing PARALLEL construct::
1309 * Implementing FOR construct::
1310 * Implementing ORDERED construct::
1311 * Implementing SECTIONS construct::
1312 * Implementing SINGLE construct::
1313 @end menu
1314
1315
1316 @node Implementing MASTER construct
1317 @section Implementing MASTER construct
1318
1319 @smallexample
1320 if (omp_get_thread_num () == 0)
1321   block
1322 @end smallexample
1323
1324 Alternately, we generate two copies of the parallel subfunction
1325 and only include this in the version run by the master thread.
1326 Surely that's not worthwhile though...
1327
1328
1329
1330 @node Implementing CRITICAL construct
1331 @section Implementing CRITICAL construct
1332
1333 Without a specified name,
1334
1335 @smallexample
1336   void GOMP_critical_start (void);
1337   void GOMP_critical_end (void);
1338 @end smallexample
1339
1340 so that we don't get COPY relocations from libgomp to the main
1341 application.
1342
1343 With a specified name, use omp_set_lock and omp_unset_lock with
1344 name being transformed into a variable declared like
1345
1346 @smallexample
1347   omp_lock_t gomp_critical_user_<name> __attribute__((common))
1348 @end smallexample
1349
1350 Ideally the ABI would specify that all zero is a valid unlocked
1351 state, and so we wouldn't actually need to initialize this at
1352 startup.
1353
1354
1355
1356 @node Implementing ATOMIC construct
1357 @section Implementing ATOMIC construct
1358
1359 The target should implement the @code{__sync} builtins.
1360
1361 Failing that we could add
1362
1363 @smallexample
1364   void GOMP_atomic_enter (void)
1365   void GOMP_atomic_exit (void)
1366 @end smallexample
1367
1368 which reuses the regular lock code, but with yet another lock
1369 object private to the library.
1370
1371
1372
1373 @node Implementing FLUSH construct
1374 @section Implementing FLUSH construct
1375
1376 Expands to the @code{__sync_synchronize} builtin.
1377
1378
1379
1380 @node Implementing BARRIER construct
1381 @section Implementing BARRIER construct
1382
1383 @smallexample
1384   void GOMP_barrier (void)
1385 @end smallexample
1386
1387
1388 @node Implementing THREADPRIVATE construct
1389 @section Implementing THREADPRIVATE construct
1390
1391 In _most_ cases we can map this directly to @code{__thread}.  Except
1392 that OMP allows constructors for C++ objects.  We can either
1393 refuse to support this (how often is it used?) or we can
1394 implement something akin to .ctors.
1395
1396 Even more ideally, this ctor feature is handled by extensions
1397 to the main pthreads library.  Failing that, we can have a set
1398 of entry points to register ctor functions to be called.
1399
1400
1401
1402 @node Implementing PRIVATE clause
1403 @section Implementing PRIVATE clause
1404
1405 In association with a PARALLEL, or within the lexical extent
1406 of a PARALLEL block, the variable becomes a local variable in
1407 the parallel subfunction.
1408
1409 In association with FOR or SECTIONS blocks, create a new
1410 automatic variable within the current function.  This preserves
1411 the semantic of new variable creation.
1412
1413
1414
1415 @node Implementing FIRSTPRIVATE LASTPRIVATE COPYIN and COPYPRIVATE clauses
1416 @section Implementing FIRSTPRIVATE LASTPRIVATE COPYIN and COPYPRIVATE clauses
1417
1418 Seems simple enough for PARALLEL blocks.  Create a private
1419 struct for communicating between parent and subfunction.
1420 In the parent, copy in values for scalar and "small" structs;
1421 copy in addresses for others TREE_ADDRESSABLE types.  In the
1422 subfunction, copy the value into the local variable.
1423
1424 Not clear at all what to do with bare FOR or SECTION blocks.
1425 The only thing I can figure is that we do something like
1426
1427 @smallexample
1428 #pragma omp for firstprivate(x) lastprivate(y)
1429 for (int i = 0; i < n; ++i)
1430   body;
1431 @end smallexample
1432
1433 which becomes
1434
1435 @smallexample
1436 @{
1437   int x = x, y;
1438
1439   // for stuff
1440
1441   if (i == n)
1442     y = y;
1443 @}
1444 @end smallexample
1445
1446 where the "x=x" and "y=y" assignments actually have different
1447 uids for the two variables, i.e. not something you could write
1448 directly in C.  Presumably this only makes sense if the "outer"
1449 x and y are global variables.
1450
1451 COPYPRIVATE would work the same way, except the structure
1452 broadcast would have to happen via SINGLE machinery instead.
1453
1454
1455
1456 @node Implementing REDUCTION clause
1457 @section Implementing REDUCTION clause
1458
1459 The private struct mentioned in the previous section should have
1460 a pointer to an array of the type of the variable, indexed by the
1461 thread's @var{team_id}.  The thread stores its final value into the
1462 array, and after the barrier the master thread iterates over the
1463 array to collect the values.
1464
1465
1466 @node Implementing PARALLEL construct
1467 @section Implementing PARALLEL construct
1468
1469 @smallexample
1470   #pragma omp parallel
1471   @{
1472     body;
1473   @}
1474 @end smallexample
1475
1476 becomes
1477
1478 @smallexample
1479   void subfunction (void *data)
1480   @{
1481     use data;
1482     body;
1483   @}
1484
1485   setup data;
1486   GOMP_parallel_start (subfunction, &data, num_threads);
1487   subfunction (&data);
1488   GOMP_parallel_end ();
1489 @end smallexample
1490
1491 @smallexample
1492   void GOMP_parallel_start (void (*fn)(void *), void *data, unsigned num_threads)
1493 @end smallexample
1494
1495 The @var{FN} argument is the subfunction to be run in parallel.
1496
1497 The @var{DATA} argument is a pointer to a structure used to
1498 communicate data in and out of the subfunction, as discussed
1499 above with respect to FIRSTPRIVATE et al.
1500
1501 The @var{NUM_THREADS} argument is 1 if an IF clause is present
1502 and false, or the value of the NUM_THREADS clause, if
1503 present, or 0.
1504
1505 The function needs to create the appropriate number of
1506 threads and/or launch them from the dock.  It needs to
1507 create the team structure and assign team ids.
1508
1509 @smallexample
1510   void GOMP_parallel_end (void)
1511 @end smallexample
1512
1513 Tears down the team and returns us to the previous @code{omp_in_parallel()} state.
1514
1515
1516
1517 @node Implementing FOR construct
1518 @section Implementing FOR construct
1519
1520 @smallexample
1521   #pragma omp parallel for
1522   for (i = lb; i <= ub; i++)
1523     body;
1524 @end smallexample
1525
1526 becomes
1527
1528 @smallexample
1529   void subfunction (void *data)
1530   @{
1531     long _s0, _e0;
1532     while (GOMP_loop_static_next (&_s0, &_e0))
1533     @{
1534       long _e1 = _e0, i;
1535       for (i = _s0; i < _e1; i++)
1536         body;
1537     @}
1538     GOMP_loop_end_nowait ();
1539   @}
1540
1541   GOMP_parallel_loop_static (subfunction, NULL, 0, lb, ub+1, 1, 0);
1542   subfunction (NULL);
1543   GOMP_parallel_end ();
1544 @end smallexample
1545
1546 @smallexample
1547   #pragma omp for schedule(runtime)
1548   for (i = 0; i < n; i++)
1549     body;
1550 @end smallexample
1551
1552 becomes
1553
1554 @smallexample
1555   @{
1556     long i, _s0, _e0;
1557     if (GOMP_loop_runtime_start (0, n, 1, &_s0, &_e0))
1558       do @{
1559         long _e1 = _e0;
1560         for (i = _s0, i < _e0; i++)
1561           body;
1562       @} while (GOMP_loop_runtime_next (&_s0, _&e0));
1563     GOMP_loop_end ();
1564   @}
1565 @end smallexample
1566
1567 Note that while it looks like there is trickyness to propagating
1568 a non-constant STEP, there isn't really.  We're explicitly allowed
1569 to evaluate it as many times as we want, and any variables involved
1570 should automatically be handled as PRIVATE or SHARED like any other
1571 variables.  So the expression should remain evaluable in the
1572 subfunction.  We can also pull it into a local variable if we like,
1573 but since its supposed to remain unchanged, we can also not if we like.
1574
1575 If we have SCHEDULE(STATIC), and no ORDERED, then we ought to be
1576 able to get away with no work-sharing context at all, since we can
1577 simply perform the arithmetic directly in each thread to divide up
1578 the iterations.  Which would mean that we wouldn't need to call any
1579 of these routines.
1580
1581 There are separate routines for handling loops with an ORDERED
1582 clause.  Bookkeeping for that is non-trivial...
1583
1584
1585
1586 @node Implementing ORDERED construct
1587 @section Implementing ORDERED construct
1588
1589 @smallexample
1590   void GOMP_ordered_start (void)
1591   void GOMP_ordered_end (void)
1592 @end smallexample
1593
1594
1595
1596 @node Implementing SECTIONS construct
1597 @section Implementing SECTIONS construct
1598
1599 A block as
1600
1601 @smallexample
1602   #pragma omp sections
1603   @{
1604     #pragma omp section
1605     stmt1;
1606     #pragma omp section
1607     stmt2;
1608     #pragma omp section
1609     stmt3;
1610   @}
1611 @end smallexample
1612
1613 becomes
1614
1615 @smallexample
1616   for (i = GOMP_sections_start (3); i != 0; i = GOMP_sections_next ())
1617     switch (i)
1618       @{
1619       case 1:
1620         stmt1;
1621         break;
1622       case 2:
1623         stmt2;
1624         break;
1625       case 3:
1626         stmt3;
1627         break;
1628       @}
1629   GOMP_barrier ();
1630 @end smallexample
1631
1632
1633 @node Implementing SINGLE construct
1634 @section Implementing SINGLE construct
1635
1636 A block like
1637
1638 @smallexample
1639   #pragma omp single
1640   @{
1641     body;
1642   @}
1643 @end smallexample
1644
1645 becomes
1646
1647 @smallexample
1648   if (GOMP_single_start ())
1649     body;
1650   GOMP_barrier ();
1651 @end smallexample
1652
1653 while
1654
1655 @smallexample
1656   #pragma omp single copyprivate(x)
1657     body;
1658 @end smallexample
1659
1660 becomes
1661
1662 @smallexample
1663   datap = GOMP_single_copy_start ();
1664   if (datap == NULL)
1665     @{
1666       body;
1667       data.x = x;
1668       GOMP_single_copy_end (&data);
1669     @}
1670   else
1671     x = datap->x;
1672   GOMP_barrier ();
1673 @end smallexample
1674
1675
1676
1677 @c ---------------------------------------------------------------------
1678 @c
1679 @c ---------------------------------------------------------------------
1680
1681 @node Reporting Bugs
1682 @chapter Reporting Bugs
1683
1684 Bugs in the GNU OpenMP implementation should be reported via
1685 @uref{http://gcc.gnu.org/bugzilla/, bugzilla}. In all cases, please add
1686 "openmp" to the keywords field in the bug report.
1687
1688
1689
1690 @c ---------------------------------------------------------------------
1691 @c GNU General Public License
1692 @c ---------------------------------------------------------------------
1693
1694 @include gpl.texi
1695
1696
1697
1698 @c ---------------------------------------------------------------------
1699 @c GNU Free Documentation License
1700 @c ---------------------------------------------------------------------
1701
1702 @include fdl.texi
1703
1704
1705
1706 @c ---------------------------------------------------------------------
1707 @c Funding Free Software
1708 @c ---------------------------------------------------------------------
1709
1710 @include funding.texi
1711
1712 @c ---------------------------------------------------------------------
1713 @c Index
1714 @c ---------------------------------------------------------------------
1715
1716 @node Index
1717 @unnumbered Index
1718
1719 @printindex cp
1720
1721 @bye