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