1 This is libgomp.info, produced by makeinfo version 6.5 from 2 libgomp.texi. 3 4 Copyright (C) 2006-2024 Free Software Foundation, Inc. 5 6 Permission is granted to copy, distribute and/or modify this document 7 under the terms of the GNU Free Documentation License, Version 1.3 or 8 any later version published by the Free Software Foundation; with the 9 Invariant Sections being "Funding Free Software", the Front-Cover texts 10 being (a) (see below), and with the Back-Cover Texts being (b) (see 11 below). A copy of the license is included in the section entitled "GNU 12 Free Documentation License". 13 14 (a) The FSF's Front-Cover Text is: 15 16 A GNU Manual 17 18 (b) The FSF's Back-Cover Text is: 19 20 You have freedom to copy and modify this GNU Manual, like GNU 21 software. Copies published by the Free Software Foundation raise funds 22 for GNU development. 23 INFO-DIR-SECTION GNU Libraries 24 START-INFO-DIR-ENTRY 25 * libgomp: (libgomp). GNU Offloading and Multi Processing Runtime Library. 26 END-INFO-DIR-ENTRY 27 28 This manual documents libgomp, the GNU Offloading and Multi 29 Processing Runtime library. This is the GNU implementation of the 30 OpenMP and OpenACC APIs for parallel and accelerator programming in 31 C/C++ and Fortran. 32 33 Published by the Free Software Foundation 51 Franklin Street, Fifth 34 Floor Boston, MA 02110-1301 USA 35 36 Copyright (C) 2006-2024 Free Software Foundation, Inc. 37 38 Permission is granted to copy, distribute and/or modify this document 39 under the terms of the GNU Free Documentation License, Version 1.3 or 40 any later version published by the Free Software Foundation; with the 41 Invariant Sections being "Funding Free Software", the Front-Cover texts 42 being (a) (see below), and with the Back-Cover Texts being (b) (see 43 below). A copy of the license is included in the section entitled "GNU 44 Free Documentation License". 45 46 (a) The FSF's Front-Cover Text is: 47 48 A GNU Manual 49 50 (b) The FSF's Back-Cover Text is: 51 52 You have freedom to copy and modify this GNU Manual, like GNU 53 software. Copies published by the Free Software Foundation raise funds 54 for GNU development. 55 56 57 File: libgomp.info, Node: Top, Next: Enabling OpenMP 58 59 Introduction 60 ************ 61 62 This manual documents the usage of libgomp, the GNU Offloading and Multi 63 Processing Runtime Library. This includes the GNU implementation of the 64 OpenMP (https://www.openmp.org) Application Programming Interface (API) 65 for multi-platform shared-memory parallel programming in C/C++ and 66 Fortran, and the GNU implementation of the OpenACC 67 (https://www.openacc.org) Application Programming Interface (API) for 68 offloading of code to accelerator devices in C/C++ and Fortran. 69 70 Originally, libgomp implemented the GNU OpenMP Runtime Library. 71 Based on this, support for OpenACC and offloading (both OpenACC and 72 OpenMP 4's target construct) has been added later on, and the library's 73 name changed to GNU Offloading and Multi Processing Runtime Library. 74 75 * Menu: 76 77 * Enabling OpenMP:: How to enable OpenMP for your applications. 78 * OpenMP Implementation Status:: List of implemented features by OpenMP version 79 * OpenMP Runtime Library Routines: Runtime Library Routines. 80 The OpenMP runtime application programming 81 interface. 82 * OpenMP Environment Variables: Environment Variables. 83 Influencing OpenMP runtime behavior with 84 environment variables. 85 * Enabling OpenACC:: How to enable OpenACC for your 86 applications. 87 * OpenACC Runtime Library Routines:: The OpenACC runtime application 88 programming interface. 89 * OpenACC Environment Variables:: Influencing OpenACC runtime behavior with 90 environment variables. 91 * CUDA Streams Usage:: Notes on the implementation of 92 asynchronous operations. 93 * OpenACC Library Interoperability:: OpenACC library interoperability with the 94 NVIDIA CUBLAS library. 95 * OpenACC Profiling Interface:: 96 * OpenMP-Implementation Specifics:: Notes specifics of this OpenMP 97 implementation 98 * Offload-Target Specifics:: Notes on offload-target specific internals 99 * The libgomp ABI:: Notes on the external ABI presented by libgomp. 100 * Reporting Bugs:: How to report bugs in the GNU Offloading and 101 Multi Processing Runtime Library. 102 * Copying:: GNU general public license says 103 how you can copy and share libgomp. 104 * GNU Free Documentation License:: 105 How you can copy and share this manual. 106 * Funding:: How to help assure continued work for free 107 software. 108 * Library Index:: Index of this documentation. 109 110 111 File: libgomp.info, Node: Enabling OpenMP, Next: OpenMP Implementation Status, Up: Top 112 113 1 Enabling OpenMP 114 ***************** 115 116 To activate the OpenMP extensions for C/C++ and Fortran, the 117 compile-time flag '-fopenmp' must be specified. For C and C++, this 118 enables the handling of the OpenMP directives using '#pragma omp' and 119 the '[[omp::directive(...)]]', '[[omp::sequence(...)]]' and 120 '[[omp::decl(...)]]' attributes. For Fortran, it enables for free 121 source form the '!$omp' sentinel for directives and the '!$' conditional 122 compilation sentinel and for fixed source form the 'c$omp', '*$omp' and 123 '!$omp' sentinels for directives and the 'c$', '*$' and '!$' conditional 124 compilation sentinels. The flag also arranges for automatic linking of 125 the OpenMP runtime library (*note Runtime Library Routines::). 126 127 The '-fopenmp-simd' flag can be used to enable a subset of OpenMP 128 directives that do not require the linking of either the OpenMP runtime 129 library or the POSIX threads library. 130 131 A complete description of all OpenMP directives may be found in the 132 OpenMP Application Program Interface (https://www.openmp.org) manuals. 133 See also *note OpenMP Implementation Status::. 134 135 136 File: libgomp.info, Node: OpenMP Implementation Status, Next: Runtime Library Routines, Prev: Enabling OpenMP, Up: Top 137 138 2 OpenMP Implementation Status 139 ****************************** 140 141 * Menu: 142 143 * OpenMP 4.5:: Feature completion status to 4.5 specification 144 * OpenMP 5.0:: Feature completion status to 5.0 specification 145 * OpenMP 5.1:: Feature completion status to 5.1 specification 146 * OpenMP 5.2:: Feature completion status to 5.2 specification 147 * OpenMP Technical Report 12:: Feature completion status to second 6.0 preview 148 149 The '_OPENMP' preprocessor macro and Fortran's 'openmp_version' 150 parameter, provided by 'omp_lib.h' and the 'omp_lib' module, have the 151 value '201511' (i.e. OpenMP 4.5). 152 153 154 File: libgomp.info, Node: OpenMP 4.5, Next: OpenMP 5.0, Up: OpenMP Implementation Status 155 156 2.1 OpenMP 4.5 157 ============== 158 159 The OpenMP 4.5 specification is fully supported. 160 161 162 File: libgomp.info, Node: OpenMP 5.0, Next: OpenMP 5.1, Prev: OpenMP 4.5, Up: OpenMP Implementation Status 163 164 2.2 OpenMP 5.0 165 ============== 166 167 New features listed in Appendix B of the OpenMP specification 168 ------------------------------------------------------------- 169 170 Description Status Comments 171 ----------------------------------------------------------------------- 172 Array shaping N 173 Array sections with non-unit strides in C N 174 and C++ 175 Iterators Y 176 'metadirective' directive N 177 'declare variant' directive P _simd_ traits 178 not handled 179 correctly 180 TARGET-OFFLOAD-VAR ICV and Y 181 'OMP_TARGET_OFFLOAD' env variable 182 Nested-parallel changes to Y 183 MAX-ACTIVE-LEVELS-VAR ICV 184 'requires' directive P complete but no 185 non-host device 186 provides 187 'unified_shared_memory' 188 'teams' construct outside an enclosing Y 189 target region 190 Non-rectangular loop nests P Full support for 191 C/C++, partial 192 for Fortran 193 (PR110735 194 (https://gcc.gnu.org/PR110735)) 195 '!=' as relational-op in canonical loop Y 196 form for C/C++ 197 'nonmonotonic' as default loop schedule Y 198 modifier for worksharing-loop constructs 199 Collapse of associated loops that are Y 200 imperfectly nested loops 201 Clauses 'if', 'nontemporal' and Y 202 'order(concurrent)' in 'simd' construct 203 'atomic' constructs in 'simd' Y 204 'loop' construct Y 205 'order(concurrent)' clause Y 206 'scan' directive and 'in_scan' modifier Y 207 for the 'reduction' clause 208 'in_reduction' clause on 'task' Y 209 constructs 210 'in_reduction' clause on 'target' P 'nowait' only 211 constructs stub 212 'task_reduction' clause with 'taskgroup' Y 213 'task' modifier to 'reduction' clause Y 214 'affinity' clause to 'task' construct Y Stub only 215 'detach' clause to 'task' construct Y 216 'omp_fulfill_event' runtime routine Y 217 'reduction' and 'in_reduction' clauses on Y 218 'taskloop' and 'taskloop simd' constructs 219 'taskloop' construct cancelable by Y 220 'cancel' construct 221 'mutexinoutset' _dependence-type_ for Y 222 'depend' clause 223 Predefined memory spaces, memory Y See also 224 allocators, allocator traits *note Memory allocation:: 225 Memory management routines Y 226 'allocate' directive P Only C for 227 stack/automatic 228 and Fortran for 229 stack/automatic 230 and 231 allocatable/pointer 232 variables 233 'allocate' clause P Initial support 234 'use_device_addr' clause on 'target data' Y 235 'ancestor' modifier on 'device' clause Y 236 Implicit declare target directive Y 237 Discontiguous array section with 'target N 238 update' construct 239 C/C++'s lvalue expressions in 'to', Y 240 'from' and 'map' clauses 241 C/C++'s lvalue expressions in 'depend' Y 242 clauses 243 Nested 'declare target' directive Y 244 Combined 'master' constructs Y 245 'depend' clause on 'taskwait' Y 246 Weak memory ordering clauses on 'atomic' Y 247 and 'flush' construct 248 'hint' clause on the 'atomic' construct Y Stub only 249 'depobj' construct and depend objects Y 250 Lock hints were renamed to Y 251 synchronization hints 252 'conditional' modifier to 'lastprivate' Y 253 clause 254 Map-order clarifications P 255 'close' _map-type-modifier_ Y 256 Mapping C/C++ pointer variables and to P 257 assign the address of device memory 258 mapped by an array section 259 Mapping of Fortran pointer and P Mapping of vars 260 allocatable variables, including pointer with allocatable 261 and allocatable components of variables components 262 unsupported 263 'defaultmap' extensions Y 264 'declare mapper' directive N 265 'omp_get_supported_active_levels' routine Y 266 Runtime routines and environment Y 267 variables to display runtime thread 268 affinity information 269 'omp_pause_resource' and Y 270 'omp_pause_resource_all' runtime routines 271 'omp_get_device_num' runtime routine Y 272 OMPT interface N 273 OMPD interface N 274 275 Other new OpenMP 5.0 features 276 ----------------------------- 277 278 Description Status Comments 279 ----------------------------------------------------------------------- 280 Supporting C++'s range-based for loop Y 281 282 283 File: libgomp.info, Node: OpenMP 5.1, Next: OpenMP 5.2, Prev: OpenMP 5.0, Up: OpenMP Implementation Status 284 285 2.3 OpenMP 5.1 286 ============== 287 288 New features listed in Appendix B of the OpenMP specification 289 ------------------------------------------------------------- 290 291 Description Status Comments 292 ----------------------------------------------------------------------- 293 OpenMP directive as C++ attribute Y 294 specifiers 295 'omp_all_memory' reserved locator Y 296 _target_device trait_ in OpenMP Context N 297 'target_device' selector set in context N 298 selectors 299 C/C++'s 'declare variant' directive: N 300 elision support of preprocessed code 301 'declare variant': new clauses N 302 'adjust_args' and 'append_args' 303 'dispatch' construct N 304 device-specific ICV settings with Y 305 environment variables 306 'assume' and 'assumes' directives Y 307 'nothing' directive Y 308 'error' directive Y 309 'masked' construct Y 310 'scope' directive Y 311 Loop transformation constructs N 312 'strict' modifier in the 'grainsize' and Y 313 'num_tasks' clauses of the 'taskloop' 314 construct 315 'align' clause in 'allocate' directive P Only C and 316 Fortran (and not 317 for static 318 variables) 319 'align' modifier in 'allocate' clause Y 320 'thread_limit' clause to 'target' Y 321 construct 322 'has_device_addr' clause to 'target' Y 323 construct 324 Iterators in 'target update' motion N 325 clauses and 'map' clauses 326 Indirect calls to the device version of a Y 327 procedure or function in 'target' regions 328 'interop' directive N 329 'omp_interop_t' object support in runtime N 330 routines 331 'nowait' clause in 'taskwait' directive Y 332 Extensions to the 'atomic' directive Y 333 'seq_cst' clause on a 'flush' construct Y 334 'inoutset' argument to the 'depend' Y 335 clause 336 'private' and 'firstprivate' argument to Y 337 'default' clause in C and C++ 338 'present' argument to 'defaultmap' clause Y 339 'omp_set_num_teams', Y 340 'omp_set_teams_thread_limit', 341 'omp_get_max_teams', 342 'omp_get_teams_thread_limit' runtime 343 routines 344 'omp_target_is_accessible' runtime Y 345 routine 346 'omp_target_memcpy_async' and Y 347 'omp_target_memcpy_rect_async' runtime 348 routines 349 'omp_get_mapped_ptr' runtime routine Y 350 'omp_calloc', 'omp_realloc', Y 351 'omp_aligned_alloc' and 352 'omp_aligned_calloc' runtime routines 353 'omp_alloctrait_key_t' enum: Y 354 'omp_atv_serialized' added, 355 'omp_atv_default' changed 356 'omp_display_env' runtime routine Y 357 'ompt_scope_endpoint_t' enum: N 358 'ompt_scope_beginend' 359 'ompt_sync_region_t' enum additions N 360 'ompt_state_t' enum: N 361 'ompt_state_wait_barrier_implementation' 362 and 'ompt_state_wait_barrier_teams' 363 'ompt_callback_target_data_op_emi_t', N 364 'ompt_callback_target_emi_t', 365 'ompt_callback_target_map_emi_t' and 366 'ompt_callback_target_submit_emi_t' 367 'ompt_callback_error_t' type N 368 'OMP_PLACES' syntax extensions Y 369 'OMP_NUM_TEAMS' and Y 370 'OMP_TEAMS_THREAD_LIMIT' environment 371 variables 372 373 Other new OpenMP 5.1 features 374 ----------------------------- 375 376 Description Status Comments 377 ----------------------------------------------------------------------- 378 Support of strictly structured blocks in Y 379 Fortran 380 Support of structured block sequences in Y 381 C/C++ 382 'unconstrained' and 'reproducible' Y 383 modifiers on 'order' clause 384 Support 'begin/end declare target' syntax Y 385 in C/C++ 386 Pointer predetermined firstprivate N 387 getting initialized to address of 388 matching mapped list item per 5.1, Sect. 389 2.21.7.2 390 For Fortran, diagnose placing declarative N 391 before/between 'USE', 'IMPORT', and 392 'IMPLICIT' as invalid 393 Optional comma between directive and Y 394 clause in the '#pragma' form 395 'indirect' clause in 'declare target' Y 396 'device_type(nohost)'/'device_type(host)' N 397 for variables 398 'present' modifier to the 'map', 'to' and Y 399 'from' clauses 400 401 402 File: libgomp.info, Node: OpenMP 5.2, Next: OpenMP Technical Report 12, Prev: OpenMP 5.1, Up: OpenMP Implementation Status 403 404 2.4 OpenMP 5.2 405 ============== 406 407 New features listed in Appendix B of the OpenMP specification 408 ------------------------------------------------------------- 409 410 Description Status Comments 411 ----------------------------------------------------------------------- 412 'omp_in_explicit_task' routine and Y 413 EXPLICIT-TASK-VAR ICV 414 'omp'/'ompx'/'omx' sentinels and N/A warning for 415 'omp_'/'ompx_' namespaces 'ompx/omx' 416 sentinels(1) 417 Clauses on 'end' directive can be on Y 418 directive 419 'destroy' clause with destroy-var Y 420 argument on 'depobj' 421 Deprecation of no-argument 'destroy' N 422 clause on 'depobj' 423 'linear' clause syntax changes and 'step' Y 424 modifier 425 Deprecation of minus operator for N 426 reductions 427 Deprecation of separating 'map' modifiers N 428 without comma 429 'declare mapper' with iterator and N 430 'present' modifiers 431 If a matching mapped list item is not Y 432 found in the data environment, the 433 pointer retains its original value 434 New 'enter' clause as alias for 'to' on Y 435 declare target directive 436 Deprecation of 'to' clause on declare N 437 target directive 438 Extended list of directives permitted in Y 439 Fortran pure procedures 440 New 'allocators' directive for Fortran Y 441 Deprecation of 'allocate' directive for N 442 Fortran allocatables/pointers 443 Optional paired 'end' directive with N 444 'dispatch' 445 New 'memspace' and 'traits' modifiers for N 446 'uses_allocators' 447 Deprecation of traits array following the N 448 allocator_handle expression in 449 'uses_allocators' 450 New 'otherwise' clause as alias for N 451 'default' on metadirectives 452 Deprecation of 'default' clause on N 453 metadirectives 454 Deprecation of delimited form of 'declare N 455 target' 456 Reproducible semantics changed for N 457 'order(concurrent)' 458 'allocate' and 'firstprivate' clauses on Y 459 'scope' 460 'ompt_callback_work' N 461 Default map-type for the 'map' clause in Y 462 'target enter/exit data' 463 New 'doacross' clause as alias for Y 464 'depend' with 'source'/'sink' modifier 465 Deprecation of 'depend' with N 466 'source'/'sink' modifier 467 'omp_cur_iteration' keyword Y 468 469 Other new OpenMP 5.2 features 470 ----------------------------- 471 472 Description Status Comments 473 ----------------------------------------------------------------------- 474 For Fortran, optional comma between N 475 directive and clause 476 Conforming device numbers and Y 477 'omp_initial_device' and 478 'omp_invalid_device' enum/PARAMETER 479 Initial value of DEFAULT-DEVICE-VAR ICV Y 480 with 'OMP_TARGET_OFFLOAD=mandatory' 481 'all' as _implicit-behavior_ for Y 482 'defaultmap' 483 _interop_types_ in any position of the N 484 modifier list for the 'init' clause of 485 the 'interop' construct 486 Invoke virtual member functions of C++ N 487 objects created on the host device on 488 other devices 489 490 ---------- Footnotes ---------- 491 492 (1) The 'ompx' sentinel as C/C++ pragma and C++ attributes are warned 493 for with '-Wunknown-pragmas' (implied by '-Wall') and '-Wattributes' 494 (enabled by default), respectively; for Fortran free-source code, there 495 is a warning enabled by default and, for fixed-source code, the 'omx' 496 sentinel is warned for with '-Wsurprising' (enabled by '-Wall'). 497 Unknown clauses are always rejected with an error. 498 499 500 File: libgomp.info, Node: OpenMP Technical Report 12, Prev: OpenMP 5.2, Up: OpenMP Implementation Status 501 502 2.5 OpenMP Technical Report 12 503 ============================== 504 505 Technical Report (TR) 12 is the second preview for OpenMP 6.0. 506 507 New features listed in Appendix B of the OpenMP specification 508 ------------------------------------------------------------- 509 510 Features deprecated in versions 5.2, 5.1 N/A Backward 511 and 5.0 were removed compatibility 512 Full support for C23 was added P 513 Full support for C++23 was added P 514 '_ALL' suffix to the device-scope P Host device 515 environment variables number wrongly 516 accepted 517 'num_threads' now accepts a list N 518 Supporting increments with abstract names N 519 in 'OMP_PLACES' 520 Extension of 'OMP_DEFAULT_DEVICE' and new N 521 'OMP_AVAILABLE_DEVICES' environment vars 522 New 'OMP_THREADS_RESERVE' environment N 523 variable 524 The 'decl' attribute was added to the C++ Y 525 attribute syntax 526 The OpenMP directive syntax was extended Y 527 to include C 23 attribute specifiers 528 All inarguable clauses take now an N 529 optional Boolean argument 530 For Fortran, _locator list_ can be also N 531 function reference with data pointer 532 result 533 Concept of _assumed-size arrays_ in C and N 534 C++ 535 _directive-name-modifier_ accepted in all N 536 clauses 537 For Fortran, atomic with BLOCK construct N 538 and, for C/C++, with unlimited curly 539 braces supported 540 For Fortran, atomic compare with storing N 541 the comparison result 542 New 'looprange' clause N 543 Ref-count change for N 544 'use_device_ptr'/'use_device_addr' 545 Support for inductions N 546 Implicit reduction identifiers of C++ N 547 classes 548 Change of the _map-type_ property from N 549 _ultimate_ to _default_ 550 'self' modifier to 'map' and 'self' as N 551 'defaultmap' argument 552 Mapping of _assumed-size arrays_ in C, N 553 C++ and Fortran 554 'groupprivate' directive N 555 'local' clause to 'declare target' N 556 directive 557 'part_size' allocator trait N 558 'pin_device', 'preferred_device' and N 559 'target_access' allocator traits 560 'access' allocator trait changes N 561 Extension of 'interop' operation of N 562 'append_args', allowing all modifiers of 563 the 'init' clause 564 'interop' clause to 'dispatch' N 565 'message' and 'severity' clauses to N 566 'parallel' directive 567 'self' clause to 'requires' directive N 568 'no_openmp_constructs' assumptions clause N 569 'reverse' loop-transformation construct N 570 'interchange' loop-transformation N 571 construct 572 'fuse' loop-transformation construct N 573 'apply' code to loop-transforming N 574 constructs 575 'omp_curr_progress_width' identifier N 576 'safesync' clause to the 'parallel' N 577 construct 578 'omp_get_max_progress_width' runtime N 579 routine 580 'strict' modifier keyword to N 581 'num_threads' 582 'atomic' permitted in a construct with N 583 'order(concurrent)' 584 'workdistribute' directive for Fortran N Renamed just 585 after TR12; 586 added in TR12 as 587 'coexecute' 588 Fortran DO CONCURRENT as associated loop N 589 in a 'loop' construct 590 'threadset' clause in task-generating N 591 constructs 592 'nowait' clause with reverse-offload N 593 'target' directives 594 Boolean argument to 'nowait' and N 595 'nogroup' may be non constant 596 'memscope' clause to 'atomic' and 'flush' N 597 'omp_is_free_agent' and N 598 'omp_ancestor_is_free_agent' routines 599 'omp_target_memset' and N 600 'omp_target_memset_rect_async' routines 601 Routines for obtaining memory N 602 spaces/allocators for shared/device 603 memory 604 'omp_get_memspace_num_resources' routine N 605 'omp_get_submemspace' routine N 606 'ompt_target_data_transfer' and N 607 'ompt_target_data_transfer_async' values 608 in 'ompt_target_data_op_t' enum 609 'ompt_get_buffer_limits' OMPT routine N 610 611 Other new TR 12 features 612 ------------------------ 613 614 Canonical loop nest enclosed in N 615 (multiple) curly braces (C/C++) or BLOCK 616 constructs (Fortran) 617 Relaxed Fortran restrictions to the N 618 'aligned' clause 619 Mapping lambda captures N 620 New 'omp_pause_stop_tool' constant for N 621 omp_pause_resource 622 623 624 File: libgomp.info, Node: Runtime Library Routines, Next: Environment Variables, Prev: OpenMP Implementation Status, Up: Top 625 626 3 OpenMP Runtime Library Routines 627 ********************************* 628 629 The runtime routines described here are defined by Section 18 of the 630 OpenMP specification in version 5.2. 631 632 * Menu: 633 634 * Thread Team Routines:: 635 * Thread Affinity Routines:: 636 * Teams Region Routines:: 637 * Tasking Routines:: 638 * Resource Relinquishing Routines:: 639 * Device Information Routines:: 640 * Device Memory Routines:: 641 * Lock Routines:: 642 * Timing Routines:: 643 * Event Routine:: 644 * Memory Management Routines:: 645 * Environment Display Routine:: 646 647 648 File: libgomp.info, Node: Thread Team Routines, Next: Thread Affinity Routines, Up: Runtime Library Routines 649 650 3.1 Thread Team Routines 651 ======================== 652 653 Routines controlling threads in the current contention group. They have 654 C linkage and do not throw exceptions. 655 656 * Menu: 657 658 * omp_set_num_threads:: Set upper team size limit 659 * omp_get_num_threads:: Size of the active team 660 * omp_get_max_threads:: Maximum number of threads of parallel region 661 * omp_get_thread_num:: Current thread ID 662 * omp_in_parallel:: Whether a parallel region is active 663 * omp_set_dynamic:: Enable/disable dynamic teams 664 * omp_get_dynamic:: Dynamic teams setting 665 * omp_get_cancellation:: Whether cancellation support is enabled 666 * omp_set_nested:: Enable/disable nested parallel regions 667 * omp_get_nested:: Nested parallel regions 668 * omp_set_schedule:: Set the runtime scheduling method 669 * omp_get_schedule:: Obtain the runtime scheduling method 670 * omp_get_teams_thread_limit:: Maximum number of threads imposed by teams 671 * omp_get_supported_active_levels:: Maximum number of active regions supported 672 * omp_set_max_active_levels:: Limits the number of active parallel regions 673 * omp_get_max_active_levels:: Current maximum number of active regions 674 * omp_get_level:: Number of parallel regions 675 * omp_get_ancestor_thread_num:: Ancestor thread ID 676 * omp_get_team_size:: Number of threads in a team 677 * omp_get_active_level:: Number of active parallel regions 678 679 680 File: libgomp.info, Node: omp_set_num_threads, Next: omp_get_num_threads, Up: Thread Team Routines 681 682 3.1.1 'omp_set_num_threads' - Set upper team size limit 683 ------------------------------------------------------- 684 685 _Description_: 686 Specifies the number of threads used by default in subsequent 687 parallel sections, if those do not specify a 'num_threads' clause. 688 The argument of 'omp_set_num_threads' shall be a positive integer. 689 690 _C/C++_: 691 _Prototype_: 'void omp_set_num_threads(int num_threads);' 692 693 _Fortran_: 694 _Interface_: 'subroutine omp_set_num_threads(num_threads)' 695 'integer, intent(in) :: num_threads' 696 697 _See also_: 698 *note OMP_NUM_THREADS::, *note omp_get_num_threads::, *note 699 omp_get_max_threads:: 700 701 _Reference_: 702 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.1. 703 704 705 File: libgomp.info, Node: omp_get_num_threads, Next: omp_get_max_threads, Prev: omp_set_num_threads, Up: Thread Team Routines 706 707 3.1.2 'omp_get_num_threads' - Size of the active team 708 ----------------------------------------------------- 709 710 _Description_: 711 Returns the number of threads in the current team. In a sequential 712 section of the program 'omp_get_num_threads' returns 1. 713 714 The default team size may be initialized at startup by the 715 'OMP_NUM_THREADS' environment variable. At runtime, the size of 716 the current team may be set either by the 'NUM_THREADS' clause or 717 by 'omp_set_num_threads'. If none of the above were used to define 718 a specific value and 'OMP_DYNAMIC' is disabled, one thread per CPU 719 online is used. 720 721 _C/C++_: 722 _Prototype_: 'int omp_get_num_threads(void);' 723 724 _Fortran_: 725 _Interface_: 'integer function omp_get_num_threads()' 726 727 _See also_: 728 *note omp_get_max_threads::, *note omp_set_num_threads::, *note 729 OMP_NUM_THREADS:: 730 731 _Reference_: 732 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.2. 733 734 735 File: libgomp.info, Node: omp_get_max_threads, Next: omp_get_thread_num, Prev: omp_get_num_threads, Up: Thread Team Routines 736 737 3.1.3 'omp_get_max_threads' - Maximum number of threads of parallel region 738 -------------------------------------------------------------------------- 739 740 _Description_: 741 Return the maximum number of threads used for the current parallel 742 region that does not use the clause 'num_threads'. 743 744 _C/C++_: 745 _Prototype_: 'int omp_get_max_threads(void);' 746 747 _Fortran_: 748 _Interface_: 'integer function omp_get_max_threads()' 749 750 _See also_: 751 *note omp_set_num_threads::, *note omp_set_dynamic::, *note 752 omp_get_thread_limit:: 753 754 _Reference_: 755 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.3. 756 757 758 File: libgomp.info, Node: omp_get_thread_num, Next: omp_in_parallel, Prev: omp_get_max_threads, Up: Thread Team Routines 759 760 3.1.4 'omp_get_thread_num' - Current thread ID 761 ---------------------------------------------- 762 763 _Description_: 764 Returns a unique thread identification number within the current 765 team. In a sequential parts of the program, 'omp_get_thread_num' 766 always returns 0. In parallel regions the return value varies from 767 0 to 'omp_get_num_threads'-1 inclusive. The return value of the 768 primary thread of a team is always 0. 769 770 _C/C++_: 771 _Prototype_: 'int omp_get_thread_num(void);' 772 773 _Fortran_: 774 _Interface_: 'integer function omp_get_thread_num()' 775 776 _See also_: 777 *note omp_get_num_threads::, *note omp_get_ancestor_thread_num:: 778 779 _Reference_: 780 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.4. 781 782 783 File: libgomp.info, Node: omp_in_parallel, Next: omp_set_dynamic, Prev: omp_get_thread_num, Up: Thread Team Routines 784 785 3.1.5 'omp_in_parallel' - Whether a parallel region is active 786 ------------------------------------------------------------- 787 788 _Description_: 789 This function returns 'true' if currently running in parallel, 790 'false' otherwise. Here, 'true' and 'false' represent their 791 language-specific counterparts. 792 793 _C/C++_: 794 _Prototype_: 'int omp_in_parallel(void);' 795 796 _Fortran_: 797 _Interface_: 'logical function omp_in_parallel()' 798 799 _Reference_: 800 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.6. 801 802 803 File: libgomp.info, Node: omp_set_dynamic, Next: omp_get_dynamic, Prev: omp_in_parallel, Up: Thread Team Routines 804 805 3.1.6 'omp_set_dynamic' - Enable/disable dynamic teams 806 ------------------------------------------------------ 807 808 _Description_: 809 Enable or disable the dynamic adjustment of the number of threads 810 within a team. The function takes the language-specific equivalent 811 of 'true' and 'false', where 'true' enables dynamic adjustment of 812 team sizes and 'false' disables it. 813 814 _C/C++_: 815 _Prototype_: 'void omp_set_dynamic(int dynamic_threads);' 816 817 _Fortran_: 818 _Interface_: 'subroutine omp_set_dynamic(dynamic_threads)' 819 'logical, intent(in) :: dynamic_threads' 820 821 _See also_: 822 *note OMP_DYNAMIC::, *note omp_get_dynamic:: 823 824 _Reference_: 825 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.7. 826 827 828 File: libgomp.info, Node: omp_get_dynamic, Next: omp_get_cancellation, Prev: omp_set_dynamic, Up: Thread Team Routines 829 830 3.1.7 'omp_get_dynamic' - Dynamic teams setting 831 ----------------------------------------------- 832 833 _Description_: 834 This function returns 'true' if enabled, 'false' otherwise. Here, 835 'true' and 'false' represent their language-specific counterparts. 836 837 The dynamic team setting may be initialized at startup by the 838 'OMP_DYNAMIC' environment variable or at runtime using 839 'omp_set_dynamic'. If undefined, dynamic adjustment is disabled by 840 default. 841 842 _C/C++_: 843 _Prototype_: 'int omp_get_dynamic(void);' 844 845 _Fortran_: 846 _Interface_: 'logical function omp_get_dynamic()' 847 848 _See also_: 849 *note omp_set_dynamic::, *note OMP_DYNAMIC:: 850 851 _Reference_: 852 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.8. 853 854 855 File: libgomp.info, Node: omp_get_cancellation, Next: omp_set_nested, Prev: omp_get_dynamic, Up: Thread Team Routines 856 857 3.1.8 'omp_get_cancellation' - Whether cancellation support is enabled 858 ---------------------------------------------------------------------- 859 860 _Description_: 861 This function returns 'true' if cancellation is activated, 'false' 862 otherwise. Here, 'true' and 'false' represent their 863 language-specific counterparts. Unless 'OMP_CANCELLATION' is set 864 true, cancellations are deactivated. 865 866 _C/C++_: 867 _Prototype_: 'int omp_get_cancellation(void);' 868 869 _Fortran_: 870 _Interface_: 'logical function omp_get_cancellation()' 871 872 _See also_: 873 *note OMP_CANCELLATION:: 874 875 _Reference_: 876 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.9. 877 878 879 File: libgomp.info, Node: omp_set_nested, Next: omp_get_nested, Prev: omp_get_cancellation, Up: Thread Team Routines 880 881 3.1.9 'omp_set_nested' - Enable/disable nested parallel regions 882 --------------------------------------------------------------- 883 884 _Description_: 885 Enable or disable nested parallel regions, i.e., whether team 886 members are allowed to create new teams. The function takes the 887 language-specific equivalent of 'true' and 'false', where 'true' 888 enables dynamic adjustment of team sizes and 'false' disables it. 889 890 Enabling nested parallel regions also sets the maximum number of 891 active nested regions to the maximum supported. Disabling nested 892 parallel regions sets the maximum number of active nested regions 893 to one. 894 895 Note that the 'omp_set_nested' API routine was deprecated in the 896 OpenMP specification 5.2 in favor of 'omp_set_max_active_levels'. 897 898 _C/C++_: 899 _Prototype_: 'void omp_set_nested(int nested);' 900 901 _Fortran_: 902 _Interface_: 'subroutine omp_set_nested(nested)' 903 'logical, intent(in) :: nested' 904 905 _See also_: 906 *note omp_get_nested::, *note omp_set_max_active_levels::, *note 907 OMP_MAX_ACTIVE_LEVELS::, *note OMP_NESTED:: 908 909 _Reference_: 910 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.10. 911 912 913 File: libgomp.info, Node: omp_get_nested, Next: omp_set_schedule, Prev: omp_set_nested, Up: Thread Team Routines 914 915 3.1.10 'omp_get_nested' - Nested parallel regions 916 ------------------------------------------------- 917 918 _Description_: 919 This function returns 'true' if nested parallel regions are 920 enabled, 'false' otherwise. Here, 'true' and 'false' represent 921 their language-specific counterparts. 922 923 The state of nested parallel regions at startup depends on several 924 environment variables. If 'OMP_MAX_ACTIVE_LEVELS' is defined and 925 is set to greater than one, then nested parallel regions will be 926 enabled. If not defined, then the value of the 'OMP_NESTED' 927 environment variable will be followed if defined. If neither are 928 defined, then if either 'OMP_NUM_THREADS' or 'OMP_PROC_BIND' are 929 defined with a list of more than one value, then nested parallel 930 regions are enabled. If none of these are defined, then nested 931 parallel regions are disabled by default. 932 933 Nested parallel regions can be enabled or disabled at runtime using 934 'omp_set_nested', or by setting the maximum number of nested 935 regions with 'omp_set_max_active_levels' to one to disable, or 936 above one to enable. 937 938 Note that the 'omp_get_nested' API routine was deprecated in the 939 OpenMP specification 5.2 in favor of 'omp_get_max_active_levels'. 940 941 _C/C++_: 942 _Prototype_: 'int omp_get_nested(void);' 943 944 _Fortran_: 945 _Interface_: 'logical function omp_get_nested()' 946 947 _See also_: 948 *note omp_get_max_active_levels::, *note omp_set_nested::, *note 949 OMP_MAX_ACTIVE_LEVELS::, *note OMP_NESTED:: 950 951 _Reference_: 952 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.11. 953 954 955 File: libgomp.info, Node: omp_set_schedule, Next: omp_get_schedule, Prev: omp_get_nested, Up: Thread Team Routines 956 957 3.1.11 'omp_set_schedule' - Set the runtime scheduling method 958 ------------------------------------------------------------- 959 960 _Description_: 961 Sets the runtime scheduling method. The KIND argument can have the 962 value 'omp_sched_static', 'omp_sched_dynamic', 'omp_sched_guided' 963 or 'omp_sched_auto'. Except for 'omp_sched_auto', the chunk size 964 is set to the value of CHUNK_SIZE if positive, or to the default 965 value if zero or negative. For 'omp_sched_auto' the CHUNK_SIZE 966 argument is ignored. 967 968 _C/C++_ 969 _Prototype_: 'void omp_set_schedule(omp_sched_t kind, int 970 chunk_size);' 971 972 _Fortran_: 973 _Interface_: 'subroutine omp_set_schedule(kind, chunk_size)' 974 'integer(kind=omp_sched_kind) kind' 975 'integer chunk_size' 976 977 _See also_: 978 *note omp_get_schedule:: *note OMP_SCHEDULE:: 979 980 _Reference_: 981 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.12. 982 983 984 File: libgomp.info, Node: omp_get_schedule, Next: omp_get_teams_thread_limit, Prev: omp_set_schedule, Up: Thread Team Routines 985 986 3.1.12 'omp_get_schedule' - Obtain the runtime scheduling method 987 ---------------------------------------------------------------- 988 989 _Description_: 990 Obtain the runtime scheduling method. The KIND argument is set to 991 'omp_sched_static', 'omp_sched_dynamic', 'omp_sched_guided' or 992 'omp_sched_auto'. The second argument, CHUNK_SIZE, is set to the 993 chunk size. 994 995 _C/C++_ 996 _Prototype_: 'void omp_get_schedule(omp_sched_t *kind, int 997 *chunk_size);' 998 999 _Fortran_: 1000 _Interface_: 'subroutine omp_get_schedule(kind, chunk_size)' 1001 'integer(kind=omp_sched_kind) kind' 1002 'integer chunk_size' 1003 1004 _See also_: 1005 *note omp_set_schedule::, *note OMP_SCHEDULE:: 1006 1007 _Reference_: 1008 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.13. 1009 1010 1011 File: libgomp.info, Node: omp_get_teams_thread_limit, Next: omp_get_supported_active_levels, Prev: omp_get_schedule, Up: Thread Team Routines 1012 1013 3.1.13 'omp_get_teams_thread_limit' - Maximum number of threads imposed by teams 1014 -------------------------------------------------------------------------------- 1015 1016 _Description_: 1017 Return the maximum number of threads that are able to participate 1018 in each team created by a teams construct. 1019 1020 _C/C++_: 1021 _Prototype_: 'int omp_get_teams_thread_limit(void);' 1022 1023 _Fortran_: 1024 _Interface_: 'integer function omp_get_teams_thread_limit()' 1025 1026 _See also_: 1027 *note omp_set_teams_thread_limit::, *note OMP_TEAMS_THREAD_LIMIT:: 1028 1029 _Reference_: 1030 OpenMP specification v5.1 (https://www.openmp.org), Section 3.4.6. 1031 1032 1033 File: libgomp.info, Node: omp_get_supported_active_levels, Next: omp_set_max_active_levels, Prev: omp_get_teams_thread_limit, Up: Thread Team Routines 1034 1035 3.1.14 'omp_get_supported_active_levels' - Maximum number of active regions supported 1036 ------------------------------------------------------------------------------------- 1037 1038 _Description_: 1039 This function returns the maximum number of nested, active parallel 1040 regions supported by this implementation. 1041 1042 _C/C++_ 1043 _Prototype_: 'int omp_get_supported_active_levels(void);' 1044 1045 _Fortran_: 1046 _Interface_: 'integer function omp_get_supported_active_levels()' 1047 1048 _See also_: 1049 *note omp_get_max_active_levels::, *note 1050 omp_set_max_active_levels:: 1051 1052 _Reference_: 1053 OpenMP specification v5.0 (https://www.openmp.org), Section 3.2.15. 1054 1055 1056 File: libgomp.info, Node: omp_set_max_active_levels, Next: omp_get_max_active_levels, Prev: omp_get_supported_active_levels, Up: Thread Team Routines 1057 1058 3.1.15 'omp_set_max_active_levels' - Limits the number of active parallel regions 1059 --------------------------------------------------------------------------------- 1060 1061 _Description_: 1062 This function limits the maximum allowed number of nested, active 1063 parallel regions. MAX_LEVELS must be less or equal to the value 1064 returned by 'omp_get_supported_active_levels'. 1065 1066 _C/C++_ 1067 _Prototype_: 'void omp_set_max_active_levels(int max_levels);' 1068 1069 _Fortran_: 1070 _Interface_: 'subroutine omp_set_max_active_levels(max_levels)' 1071 'integer max_levels' 1072 1073 _See also_: 1074 *note omp_get_max_active_levels::, *note omp_get_active_level::, 1075 *note omp_get_supported_active_levels:: 1076 1077 _Reference_: 1078 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.15. 1079 1080 1081 File: libgomp.info, Node: omp_get_max_active_levels, Next: omp_get_level, Prev: omp_set_max_active_levels, Up: Thread Team Routines 1082 1083 3.1.16 'omp_get_max_active_levels' - Current maximum number of active regions 1084 ----------------------------------------------------------------------------- 1085 1086 _Description_: 1087 This function obtains the maximum allowed number of nested, active 1088 parallel regions. 1089 1090 _C/C++_ 1091 _Prototype_: 'int omp_get_max_active_levels(void);' 1092 1093 _Fortran_: 1094 _Interface_: 'integer function omp_get_max_active_levels()' 1095 1096 _See also_: 1097 *note omp_set_max_active_levels::, *note omp_get_active_level:: 1098 1099 _Reference_: 1100 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.16. 1101 1102 1103 File: libgomp.info, Node: omp_get_level, Next: omp_get_ancestor_thread_num, Prev: omp_get_max_active_levels, Up: Thread Team Routines 1104 1105 3.1.17 'omp_get_level' - Obtain the current nesting level 1106 --------------------------------------------------------- 1107 1108 _Description_: 1109 This function returns the nesting level for the parallel blocks, 1110 which enclose the calling call. 1111 1112 _C/C++_ 1113 _Prototype_: 'int omp_get_level(void);' 1114 1115 _Fortran_: 1116 _Interface_: 'integer function omp_level()' 1117 1118 _See also_: 1119 *note omp_get_active_level:: 1120 1121 _Reference_: 1122 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.17. 1123 1124 1125 File: libgomp.info, Node: omp_get_ancestor_thread_num, Next: omp_get_team_size, Prev: omp_get_level, Up: Thread Team Routines 1126 1127 3.1.18 'omp_get_ancestor_thread_num' - Ancestor thread ID 1128 --------------------------------------------------------- 1129 1130 _Description_: 1131 This function returns the thread identification number for the 1132 given nesting level of the current thread. For values of LEVEL 1133 outside zero to 'omp_get_level' -1 is returned; if LEVEL is 1134 'omp_get_level' the result is identical to 'omp_get_thread_num'. 1135 1136 _C/C++_ 1137 _Prototype_: 'int omp_get_ancestor_thread_num(int level);' 1138 1139 _Fortran_: 1140 _Interface_: 'integer function omp_get_ancestor_thread_num(level)' 1141 'integer level' 1142 1143 _See also_: 1144 *note omp_get_level::, *note omp_get_thread_num::, *note 1145 omp_get_team_size:: 1146 1147 _Reference_: 1148 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.18. 1149 1150 1151 File: libgomp.info, Node: omp_get_team_size, Next: omp_get_active_level, Prev: omp_get_ancestor_thread_num, Up: Thread Team Routines 1152 1153 3.1.19 'omp_get_team_size' - Number of threads in a team 1154 -------------------------------------------------------- 1155 1156 _Description_: 1157 This function returns the number of threads in a thread team to 1158 which either the current thread or its ancestor belongs. For 1159 values of LEVEL outside zero to 'omp_get_level', -1 is returned; if 1160 LEVEL is zero, 1 is returned, and for 'omp_get_level', the result 1161 is identical to 'omp_get_num_threads'. 1162 1163 _C/C++_: 1164 _Prototype_: 'int omp_get_team_size(int level);' 1165 1166 _Fortran_: 1167 _Interface_: 'integer function omp_get_team_size(level)' 1168 'integer level' 1169 1170 _See also_: 1171 *note omp_get_num_threads::, *note omp_get_level::, *note 1172 omp_get_ancestor_thread_num:: 1173 1174 _Reference_: 1175 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.19. 1176 1177 1178 File: libgomp.info, Node: omp_get_active_level, Prev: omp_get_team_size, Up: Thread Team Routines 1179 1180 3.1.20 'omp_get_active_level' - Number of parallel regions 1181 ---------------------------------------------------------- 1182 1183 _Description_: 1184 This function returns the nesting level for the active parallel 1185 blocks, which enclose the calling call. 1186 1187 _C/C++_ 1188 _Prototype_: 'int omp_get_active_level(void);' 1189 1190 _Fortran_: 1191 _Interface_: 'integer function omp_get_active_level()' 1192 1193 _See also_: 1194 *note omp_get_level::, *note omp_get_max_active_levels::, *note 1195 omp_set_max_active_levels:: 1196 1197 _Reference_: 1198 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.20. 1199 1200 1201 File: libgomp.info, Node: Thread Affinity Routines, Next: Teams Region Routines, Prev: Thread Team Routines, Up: Runtime Library Routines 1202 1203 3.2 Thread Affinity Routines 1204 ============================ 1205 1206 Routines controlling and accessing thread-affinity policies. They have 1207 C linkage and do not throw exceptions. 1208 1209 * Menu: 1210 1211 * omp_get_proc_bind:: Whether threads may be moved between CPUs 1212 1213 1214 File: libgomp.info, Node: omp_get_proc_bind, Up: Thread Affinity Routines 1215 1216 3.2.1 'omp_get_proc_bind' - Whether threads may be moved between CPUs 1217 --------------------------------------------------------------------- 1218 1219 _Description_: 1220 This functions returns the currently active thread affinity policy, 1221 which is set via 'OMP_PROC_BIND'. Possible values are 1222 'omp_proc_bind_false', 'omp_proc_bind_true', 1223 'omp_proc_bind_primary', 'omp_proc_bind_master', 1224 'omp_proc_bind_close' and 'omp_proc_bind_spread', where 1225 'omp_proc_bind_master' is an alias for 'omp_proc_bind_primary'. 1226 1227 _C/C++_: 1228 _Prototype_: 'omp_proc_bind_t omp_get_proc_bind(void);' 1229 1230 _Fortran_: 1231 _Interface_: 'integer(kind=omp_proc_bind_kind) function 1232 omp_get_proc_bind()' 1233 1234 _See also_: 1235 *note OMP_PROC_BIND::, *note OMP_PLACES::, *note 1236 GOMP_CPU_AFFINITY::, 1237 1238 _Reference_: 1239 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.22. 1240 1241 1242 File: libgomp.info, Node: Teams Region Routines, Next: Tasking Routines, Prev: Thread Affinity Routines, Up: Runtime Library Routines 1243 1244 3.3 Teams Region Routines 1245 ========================= 1246 1247 Routines controlling the league of teams that are executed in a 'teams' 1248 region. They have C linkage and do not throw exceptions. 1249 1250 * Menu: 1251 1252 * omp_get_num_teams:: Number of teams 1253 * omp_get_team_num:: Get team number 1254 * omp_set_num_teams:: Set upper teams limit for teams region 1255 * omp_get_max_teams:: Maximum number of teams for teams region 1256 * omp_set_teams_thread_limit:: Set upper thread limit for teams construct 1257 * omp_get_thread_limit:: Maximum number of threads 1258 1259 1260 File: libgomp.info, Node: omp_get_num_teams, Next: omp_get_team_num, Up: Teams Region Routines 1261 1262 3.3.1 'omp_get_num_teams' - Number of teams 1263 ------------------------------------------- 1264 1265 _Description_: 1266 Returns the number of teams in the current team region. 1267 1268 _C/C++_: 1269 _Prototype_: 'int omp_get_num_teams(void);' 1270 1271 _Fortran_: 1272 _Interface_: 'integer function omp_get_num_teams()' 1273 1274 _Reference_: 1275 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.32. 1276 1277 1278 File: libgomp.info, Node: omp_get_team_num, Next: omp_set_num_teams, Prev: omp_get_num_teams, Up: Teams Region Routines 1279 1280 3.3.2 'omp_get_team_num' - Get team number 1281 ------------------------------------------ 1282 1283 _Description_: 1284 Returns the team number of the calling thread. 1285 1286 _C/C++_: 1287 _Prototype_: 'int omp_get_team_num(void);' 1288 1289 _Fortran_: 1290 _Interface_: 'integer function omp_get_team_num()' 1291 1292 _Reference_: 1293 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.33. 1294 1295 1296 File: libgomp.info, Node: omp_set_num_teams, Next: omp_get_max_teams, Prev: omp_get_team_num, Up: Teams Region Routines 1297 1298 3.3.3 'omp_set_num_teams' - Set upper teams limit for teams construct 1299 --------------------------------------------------------------------- 1300 1301 _Description_: 1302 Specifies the upper bound for number of teams created by the teams 1303 construct which does not specify a 'num_teams' clause. The 1304 argument of 'omp_set_num_teams' shall be a positive integer. 1305 1306 _C/C++_: 1307 _Prototype_: 'void omp_set_num_teams(int num_teams);' 1308 1309 _Fortran_: 1310 _Interface_: 'subroutine omp_set_num_teams(num_teams)' 1311 'integer, intent(in) :: num_teams' 1312 1313 _See also_: 1314 *note OMP_NUM_TEAMS::, *note omp_get_num_teams::, *note 1315 omp_get_max_teams:: 1316 1317 _Reference_: 1318 OpenMP specification v5.1 (https://www.openmp.org), Section 3.4.3. 1319 1320 1321 File: libgomp.info, Node: omp_get_max_teams, Next: omp_set_teams_thread_limit, Prev: omp_set_num_teams, Up: Teams Region Routines 1322 1323 3.3.4 'omp_get_max_teams' - Maximum number of teams of teams region 1324 ------------------------------------------------------------------- 1325 1326 _Description_: 1327 Return the maximum number of teams used for the teams region that 1328 does not use the clause 'num_teams'. 1329 1330 _C/C++_: 1331 _Prototype_: 'int omp_get_max_teams(void);' 1332 1333 _Fortran_: 1334 _Interface_: 'integer function omp_get_max_teams()' 1335 1336 _See also_: 1337 *note omp_set_num_teams::, *note omp_get_num_teams:: 1338 1339 _Reference_: 1340 OpenMP specification v5.1 (https://www.openmp.org), Section 3.4.4. 1341 1342 1343 File: libgomp.info, Node: omp_set_teams_thread_limit, Next: omp_get_thread_limit, Prev: omp_get_max_teams, Up: Teams Region Routines 1344 1345 3.3.5 'omp_set_teams_thread_limit' - Set upper thread limit for teams construct 1346 ------------------------------------------------------------------------------- 1347 1348 _Description_: 1349 Specifies the upper bound for number of threads that are available 1350 for each team created by the teams construct which does not specify 1351 a 'thread_limit' clause. The argument of 1352 'omp_set_teams_thread_limit' shall be a positive integer. 1353 1354 _C/C++_: 1355 _Prototype_: 'void omp_set_teams_thread_limit(int thread_limit);' 1356 1357 _Fortran_: 1358 _Interface_: 'subroutine omp_set_teams_thread_limit(thread_limit)' 1359 'integer, intent(in) :: thread_limit' 1360 1361 _See also_: 1362 *note OMP_TEAMS_THREAD_LIMIT::, *note omp_get_teams_thread_limit::, 1363 *note omp_get_thread_limit:: 1364 1365 _Reference_: 1366 OpenMP specification v5.1 (https://www.openmp.org), Section 3.4.5. 1367 1368 1369 File: libgomp.info, Node: omp_get_thread_limit, Prev: omp_set_teams_thread_limit, Up: Teams Region Routines 1370 1371 3.3.6 'omp_get_thread_limit' - Maximum number of threads 1372 -------------------------------------------------------- 1373 1374 _Description_: 1375 Return the maximum number of threads of the program. 1376 1377 _C/C++_: 1378 _Prototype_: 'int omp_get_thread_limit(void);' 1379 1380 _Fortran_: 1381 _Interface_: 'integer function omp_get_thread_limit()' 1382 1383 _See also_: 1384 *note omp_get_max_threads::, *note OMP_THREAD_LIMIT:: 1385 1386 _Reference_: 1387 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.14. 1388 1389 1390 File: libgomp.info, Node: Tasking Routines, Next: Resource Relinquishing Routines, Prev: Teams Region Routines, Up: Runtime Library Routines 1391 1392 3.4 Tasking Routines 1393 ==================== 1394 1395 Routines relating to explicit tasks. They have C linkage and do not 1396 throw exceptions. 1397 1398 * Menu: 1399 1400 * omp_get_max_task_priority:: Maximum task priority value that can be set 1401 * omp_in_explicit_task:: Whether a given task is an explicit task 1402 * omp_in_final:: Whether in final or included task region 1403 1404 1405 File: libgomp.info, Node: omp_get_max_task_priority, Next: omp_in_explicit_task, Up: Tasking Routines 1406 1407 3.4.1 'omp_get_max_task_priority' - Maximum priority value 1408 ---------------------------------------------------------- 1409 1410 that can be set for tasks. 1411 _Description_: 1412 This function obtains the maximum allowed priority number for 1413 tasks. 1414 1415 _C/C++_ 1416 _Prototype_: 'int omp_get_max_task_priority(void);' 1417 1418 _Fortran_: 1419 _Interface_: 'integer function omp_get_max_task_priority()' 1420 1421 _Reference_: 1422 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.29. 1423 1424 1425 File: libgomp.info, Node: omp_in_explicit_task, Next: omp_in_final, Prev: omp_get_max_task_priority, Up: Tasking Routines 1426 1427 3.4.2 'omp_in_explicit_task' - Whether a given task is an explicit task 1428 ----------------------------------------------------------------------- 1429 1430 _Description_: 1431 The function returns the EXPLICIT-TASK-VAR ICV; it returns true 1432 when the encountering task was generated by a task-generating 1433 construct such as 'target', 'task' or 'taskloop'. Otherwise, the 1434 encountering task is in an implicit task region such as generated 1435 by the implicit or explicit 'parallel' region and 1436 'omp_in_explicit_task' returns false. 1437 1438 _C/C++_ 1439 _Prototype_: 'int omp_in_explicit_task(void);' 1440 1441 _Fortran_: 1442 _Interface_: 'logical function omp_in_explicit_task()' 1443 1444 _Reference_: 1445 OpenMP specification v5.2 (https://www.openmp.org), Section 18.5.2. 1446 1447 1448 File: libgomp.info, Node: omp_in_final, Prev: omp_in_explicit_task, Up: Tasking Routines 1449 1450 3.4.3 'omp_in_final' - Whether in final or included task region 1451 --------------------------------------------------------------- 1452 1453 _Description_: 1454 This function returns 'true' if currently running in a final or 1455 included task region, 'false' otherwise. Here, 'true' and 'false' 1456 represent their language-specific counterparts. 1457 1458 _C/C++_: 1459 _Prototype_: 'int omp_in_final(void);' 1460 1461 _Fortran_: 1462 _Interface_: 'logical function omp_in_final()' 1463 1464 _Reference_: 1465 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.21. 1466 1467 1468 File: libgomp.info, Node: Resource Relinquishing Routines, Next: Device Information Routines, Prev: Tasking Routines, Up: Runtime Library Routines 1469 1470 3.5 Resource Relinquishing Routines 1471 =================================== 1472 1473 Routines releasing resources used by the OpenMP runtime. They have C 1474 linkage and do not throw exceptions. 1475 1476 * Menu: 1477 1478 * omp_pause_resource:: Release OpenMP resources on a device 1479 * omp_pause_resource_all:: Release OpenMP resources on all devices 1480 1481 1482 File: libgomp.info, Node: omp_pause_resource, Next: omp_pause_resource_all, Up: Resource Relinquishing Routines 1483 1484 3.5.1 'omp_pause_resource' - Release OpenMP resources on a device 1485 ----------------------------------------------------------------- 1486 1487 _Description_: 1488 Free resources used by the OpenMP program and the runtime library 1489 on and for the device specified by DEVICE_NUM; on success, zero is 1490 returned and non-zero otherwise. 1491 1492 The value of DEVICE_NUM must be a conforming device number. The 1493 routine may not be called from within any explicit region and all 1494 explicit threads that do not bind to the implicit parallel region 1495 have finalized execution. 1496 1497 _C/C++_: 1498 _Prototype_: 'int omp_pause_resource(omp_pause_resource_t kind, int 1499 device_num);' 1500 1501 _Fortran_: 1502 _Interface_: 'integer function omp_pause_resource(kind, device_num)' 1503 'integer (kind=omp_pause_resource_kind) kind' 1504 'integer device_num' 1505 1506 _Reference_: 1507 OpenMP specification v5.0 (https://www.openmp.org), Section 3.2.43. 1508 1509 1510 File: libgomp.info, Node: omp_pause_resource_all, Prev: omp_pause_resource, Up: Resource Relinquishing Routines 1511 1512 3.5.2 'omp_pause_resource_all' - Release OpenMP resources on all devices 1513 ------------------------------------------------------------------------ 1514 1515 _Description_: 1516 Free resources used by the OpenMP program and the runtime library 1517 on all devices, including the host. On success, zero is returned 1518 and non-zero otherwise. 1519 1520 The routine may not be called from within any explicit region and 1521 all explicit threads that do not bind to the implicit parallel 1522 region have finalized execution. 1523 1524 _C/C++_: 1525 _Prototype_: 'int omp_pause_resource(omp_pause_resource_t kind);' 1526 1527 _Fortran_: 1528 _Interface_: 'integer function omp_pause_resource(kind)' 1529 'integer (kind=omp_pause_resource_kind) kind' 1530 1531 _See also_: 1532 *note omp_pause_resource:: 1533 1534 _Reference_: 1535 OpenMP specification v5.0 (https://www.openmp.org), Section 3.2.44. 1536 1537 1538 File: libgomp.info, Node: Device Information Routines, Next: Device Memory Routines, Prev: Resource Relinquishing Routines, Up: Runtime Library Routines 1539 1540 3.6 Device Information Routines 1541 =============================== 1542 1543 Routines related to devices available to an OpenMP program. They have C 1544 linkage and do not throw exceptions. 1545 1546 * Menu: 1547 1548 * omp_get_num_procs:: Number of processors online 1549 * omp_set_default_device:: Set the default device for target regions 1550 * omp_get_default_device:: Get the default device for target regions 1551 * omp_get_num_devices:: Number of target devices 1552 * omp_get_device_num:: Get device that current thread is running on 1553 * omp_is_initial_device:: Whether executing on the host device 1554 * omp_get_initial_device:: Device number of host device 1555 1556 1557 File: libgomp.info, Node: omp_get_num_procs, Next: omp_set_default_device, Up: Device Information Routines 1558 1559 3.6.1 'omp_get_num_procs' - Number of processors online 1560 ------------------------------------------------------- 1561 1562 _Description_: 1563 Returns the number of processors online on that device. 1564 1565 _C/C++_: 1566 _Prototype_: 'int omp_get_num_procs(void);' 1567 1568 _Fortran_: 1569 _Interface_: 'integer function omp_get_num_procs()' 1570 1571 _Reference_: 1572 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.5. 1573 1574 1575 File: libgomp.info, Node: omp_set_default_device, Next: omp_get_default_device, Prev: omp_get_num_procs, Up: Device Information Routines 1576 1577 3.6.2 'omp_set_default_device' - Set the default device for target regions 1578 -------------------------------------------------------------------------- 1579 1580 _Description_: 1581 Set the default device for target regions without device clause. 1582 The argument shall be a nonnegative device number. 1583 1584 _C/C++_: 1585 _Prototype_: 'void omp_set_default_device(int device_num);' 1586 1587 _Fortran_: 1588 _Interface_: 'subroutine omp_set_default_device(device_num)' 1589 'integer device_num' 1590 1591 _See also_: 1592 *note OMP_DEFAULT_DEVICE::, *note omp_get_default_device:: 1593 1594 _Reference_: 1595 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.29. 1596 1597 1598 File: libgomp.info, Node: omp_get_default_device, Next: omp_get_num_devices, Prev: omp_set_default_device, Up: Device Information Routines 1599 1600 3.6.3 'omp_get_default_device' - Get the default device for target regions 1601 -------------------------------------------------------------------------- 1602 1603 _Description_: 1604 Get the default device for target regions without device clause. 1605 1606 _C/C++_: 1607 _Prototype_: 'int omp_get_default_device(void);' 1608 1609 _Fortran_: 1610 _Interface_: 'integer function omp_get_default_device()' 1611 1612 _See also_: 1613 *note OMP_DEFAULT_DEVICE::, *note omp_set_default_device:: 1614 1615 _Reference_: 1616 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.30. 1617 1618 1619 File: libgomp.info, Node: omp_get_num_devices, Next: omp_get_device_num, Prev: omp_get_default_device, Up: Device Information Routines 1620 1621 3.6.4 'omp_get_num_devices' - Number of target devices 1622 ------------------------------------------------------ 1623 1624 _Description_: 1625 Returns the number of target devices. 1626 1627 _C/C++_: 1628 _Prototype_: 'int omp_get_num_devices(void);' 1629 1630 _Fortran_: 1631 _Interface_: 'integer function omp_get_num_devices()' 1632 1633 _Reference_: 1634 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.31. 1635 1636 1637 File: libgomp.info, Node: omp_get_device_num, Next: omp_is_initial_device, Prev: omp_get_num_devices, Up: Device Information Routines 1638 1639 3.6.5 'omp_get_device_num' - Return device number of current device 1640 ------------------------------------------------------------------- 1641 1642 _Description_: 1643 This function returns a device number that represents the device 1644 that the current thread is executing on. For OpenMP 5.0, this must 1645 be equal to the value returned by the 'omp_get_initial_device' 1646 function when called from the host. 1647 1648 _C/C++_ 1649 _Prototype_: 'int omp_get_device_num(void);' 1650 1651 _Fortran_: 1652 _Interface_: 'integer function omp_get_device_num()' 1653 1654 _See also_: 1655 *note omp_get_initial_device:: 1656 1657 _Reference_: 1658 OpenMP specification v5.0 (https://www.openmp.org), Section 3.2.37. 1659 1660 1661 File: libgomp.info, Node: omp_is_initial_device, Next: omp_get_initial_device, Prev: omp_get_device_num, Up: Device Information Routines 1662 1663 3.6.6 'omp_is_initial_device' - Whether executing on the host device 1664 -------------------------------------------------------------------- 1665 1666 _Description_: 1667 This function returns 'true' if currently running on the host 1668 device, 'false' otherwise. Here, 'true' and 'false' represent 1669 their language-specific counterparts. 1670 1671 _C/C++_: 1672 _Prototype_: 'int omp_is_initial_device(void);' 1673 1674 _Fortran_: 1675 _Interface_: 'logical function omp_is_initial_device()' 1676 1677 _Reference_: 1678 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.34. 1679 1680 1681 File: libgomp.info, Node: omp_get_initial_device, Prev: omp_is_initial_device, Up: Device Information Routines 1682 1683 3.6.7 'omp_get_initial_device' - Return device number of initial device 1684 ----------------------------------------------------------------------- 1685 1686 _Description_: 1687 This function returns a device number that represents the host 1688 device. For OpenMP 5.1, this must be equal to the value returned 1689 by the 'omp_get_num_devices' function. 1690 1691 _C/C++_ 1692 _Prototype_: 'int omp_get_initial_device(void);' 1693 1694 _Fortran_: 1695 _Interface_: 'integer function omp_get_initial_device()' 1696 1697 _See also_: 1698 *note omp_get_num_devices:: 1699 1700 _Reference_: 1701 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.35. 1702 1703 1704 File: libgomp.info, Node: Device Memory Routines, Next: Lock Routines, Prev: Device Information Routines, Up: Runtime Library Routines 1705 1706 3.7 Device Memory Routines 1707 ========================== 1708 1709 Routines related to memory allocation and managing corresponding 1710 pointers on devices. They have C linkage and do not throw exceptions. 1711 1712 * Menu: 1713 1714 * omp_target_alloc:: Allocate device memory 1715 * omp_target_free:: Free device memory 1716 * omp_target_is_present:: Check whether storage is mapped 1717 * omp_target_is_accessible:: Check whether memory is device accessible 1718 * omp_target_memcpy:: Copy data between devices 1719 * omp_target_memcpy_async:: Copy data between devices asynchronously 1720 * omp_target_memcpy_rect:: Copy a subvolume of data between devices 1721 * omp_target_memcpy_rect_async:: Copy a subvolume of data between devices asynchronously 1722 * omp_target_associate_ptr:: Associate a device pointer with a host pointer 1723 * omp_target_disassociate_ptr:: Remove device-host pointer association 1724 * omp_get_mapped_ptr:: Return device pointer to a host pointer 1725 1726 1727 File: libgomp.info, Node: omp_target_alloc, Next: omp_target_free, Up: Device Memory Routines 1728 1729 3.7.1 'omp_target_alloc' - Allocate device memory 1730 ------------------------------------------------- 1731 1732 _Description_: 1733 This routine allocates SIZE bytes of memory in the device 1734 environment associated with the device number DEVICE_NUM. If 1735 successful, a device pointer is returned, otherwise a null pointer. 1736 1737 In GCC, when the device is the host or the device shares memory 1738 with the host, the memory is allocated on the host; in that case, 1739 when SIZE is zero, either NULL or a unique pointer value that can 1740 later be successfully passed to 'omp_target_free' is returned. 1741 When the allocation is not performed on the host, a null pointer is 1742 returned when SIZE is zero; in that case, additionally a diagnostic 1743 might be printed to standard error (stderr). 1744 1745 Running this routine in a 'target' region except on the initial 1746 device is not supported. 1747 1748 _C/C++_ 1749 _Prototype_: 'void *omp_target_alloc(size_t size, int device_num)' 1750 1751 _Fortran_: 1752 _Interface_: 'type(c_ptr) function omp_target_alloc(size, device_num) 1753 bind(C)' 1754 'use, intrinsic :: iso_c_binding, only: c_ptr, c_int, 1755 c_size_t' 1756 'integer(c_size_t), value :: size' 1757 'integer(c_int), value :: device_num' 1758 1759 _See also_: 1760 *note omp_target_free::, *note omp_target_associate_ptr:: 1761 1762 _Reference_: 1763 OpenMP specification v5.1 (https://www.openmp.org), Section 3.8.1 1764 1765 1766 File: libgomp.info, Node: omp_target_free, Next: omp_target_is_present, Prev: omp_target_alloc, Up: Device Memory Routines 1767 1768 3.7.2 'omp_target_free' - Free device memory 1769 -------------------------------------------- 1770 1771 _Description_: 1772 This routine frees memory allocated by the 'omp_target_alloc' 1773 routine. The DEVICE_PTR argument must be either a null pointer or 1774 a device pointer returned by 'omp_target_alloc' for the specified 1775 'device_num'. The device number DEVICE_NUM must be a conforming 1776 device number. 1777 1778 Running this routine in a 'target' region except on the initial 1779 device is not supported. 1780 1781 _C/C++_ 1782 _Prototype_: 'void omp_target_free(void *device_ptr, int device_num)' 1783 1784 _Fortran_: 1785 _Interface_: 'subroutine omp_target_free(device_ptr, device_num) 1786 bind(C)' 1787 'use, intrinsic :: iso_c_binding, only: c_ptr, c_int' 1788 'type(c_ptr), value :: device_ptr' 1789 'integer(c_int), value :: device_num' 1790 1791 _See also_: 1792 *note omp_target_alloc::, *note omp_target_disassociate_ptr:: 1793 1794 _Reference_: 1795 OpenMP specification v5.1 (https://www.openmp.org), Section 3.8.2 1796 1797 1798 File: libgomp.info, Node: omp_target_is_present, Next: omp_target_is_accessible, Prev: omp_target_free, Up: Device Memory Routines 1799 1800 3.7.3 'omp_target_is_present' - Check whether storage is mapped 1801 --------------------------------------------------------------- 1802 1803 _Description_: 1804 This routine tests whether storage, identified by the host pointer 1805 PTR is mapped to the device specified by DEVICE_NUM. If so, it 1806 returns a nonzero value and otherwise zero. 1807 1808 In GCC, this includes self mapping such that 1809 'omp_target_is_present' returns _true_ when DEVICE_NUM specifies 1810 the host or when the host and the device share memory. If PTR is a 1811 null pointer, TRUE is returned and if DEVICE_NUM is an invalid 1812 device number, FALSE is returned. 1813 1814 If those conditions do not apply, _true_ is returned if the 1815 association has been established by an explicit or implicit 'map' 1816 clause, the 'declare target' directive or a call to the 1817 'omp_target_associate_ptr' routine. 1818 1819 Running this routine in a 'target' region except on the initial 1820 device is not supported. 1821 1822 _C/C++_ 1823 _Prototype_: 'int omp_target_is_present(const void *ptr,' 1824 ' int device_num)' 1825 1826 _Fortran_: 1827 _Interface_: 'integer(c_int) function omp_target_is_present(ptr, &' 1828 ' device_num) bind(C)' 1829 'use, intrinsic :: iso_c_binding, only: c_ptr, c_int' 1830 'type(c_ptr), value :: ptr' 1831 'integer(c_int), value :: device_num' 1832 1833 _See also_: 1834 *note omp_target_associate_ptr:: 1835 1836 _Reference_: 1837 OpenMP specification v5.1 (https://www.openmp.org), Section 3.8.3 1838 1839 1840 File: libgomp.info, Node: omp_target_is_accessible, Next: omp_target_memcpy, Prev: omp_target_is_present, Up: Device Memory Routines 1841 1842 3.7.4 'omp_target_is_accessible' - Check whether memory is device accessible 1843 ---------------------------------------------------------------------------- 1844 1845 _Description_: 1846 This routine tests whether memory, starting at the address given by 1847 PTR and extending SIZE bytes, is accessibly on the device specified 1848 by DEVICE_NUM. If so, it returns a nonzero value and otherwise 1849 zero. 1850 1851 The address given by PTR is interpreted to be in the address space 1852 of the device and SIZE must be positive. 1853 1854 Note that GCC's current implementation assumes that PTR is a valid 1855 host pointer. Therefore, all addresses given by PTR are assumed to 1856 be accessible on the initial device. And, to err on the safe side, 1857 this memory is only available on a non-host device that can access 1858 all host memory ([uniform] shared memory access). 1859 1860 Running this routine in a 'target' region except on the initial 1861 device is not supported. 1862 1863 _C/C++_ 1864 _Prototype_: 'int omp_target_is_accessible(const void *ptr,' 1865 ' size_t size,' 1866 ' int device_num)' 1867 1868 _Fortran_: 1869 _Interface_: 'integer(c_int) function omp_target_is_accessible(ptr, 1870 &' 1871 ' size, device_num) bind(C)' 1872 'use, intrinsic :: iso_c_binding, only: c_ptr, c_size_t, 1873 c_int' 1874 'type(c_ptr), value :: ptr' 1875 'integer(c_size_t), value :: size' 1876 'integer(c_int), value :: device_num' 1877 1878 _See also_: 1879 *note omp_target_associate_ptr:: 1880 1881 _Reference_: 1882 OpenMP specification v5.1 (https://www.openmp.org), Section 3.8.4 1883 1884 1885 File: libgomp.info, Node: omp_target_memcpy, Next: omp_target_memcpy_async, Prev: omp_target_is_accessible, Up: Device Memory Routines 1886 1887 3.7.5 'omp_target_memcpy' - Copy data between devices 1888 ----------------------------------------------------- 1889 1890 _Description_: 1891 This routine copies LENGTH of bytes of data from the device 1892 identified by device number SRC_DEVICE_NUM to device 1893 DST_DEVICE_NUM. The data is copied from the source device from the 1894 address provided by SRC, shifted by the offset of SRC_OFFSET bytes, 1895 to the destination device's DST address shifted by DST_OFFSET. The 1896 routine returns zero on success and non-zero otherwise. 1897 1898 Running this routine in a 'target' region except on the initial 1899 device is not supported. 1900 1901 _C/C++_ 1902 _Prototype_: 'int omp_target_memcpy(void *dst,' 1903 ' const void *src,' 1904 ' size_t length,' 1905 ' size_t dst_offset,' 1906 ' size_t src_offset,' 1907 ' int dst_device_num,' 1908 ' int src_device_num)' 1909 1910 _Fortran_: 1911 _Interface_: 'integer(c_int) function omp_target_memcpy( &' 1912 ' dst, src, length, dst_offset, src_offset, &' 1913 ' dst_device_num, src_device_num) bind(C)' 1914 'use, intrinsic :: iso_c_binding, only: c_ptr, c_size_t, 1915 c_int' 1916 'type(c_ptr), value :: dst, src' 1917 'integer(c_size_t), value :: length, dst_offset, 1918 src_offset' 1919 'integer(c_int), value :: dst_device_num, 1920 src_device_num' 1921 1922 _See also_: 1923 *note omp_target_memcpy_async::, *note omp_target_memcpy_rect:: 1924 1925 _Reference_: 1926 OpenMP specification v5.1 (https://www.openmp.org), Section 3.8.5 1927 1928 1929 File: libgomp.info, Node: omp_target_memcpy_async, Next: omp_target_memcpy_rect, Prev: omp_target_memcpy, Up: Device Memory Routines 1930 1931 3.7.6 'omp_target_memcpy_async' - Copy data between devices asynchronously 1932 -------------------------------------------------------------------------- 1933 1934 _Description_: 1935 This routine copies asynchronously LENGTH of bytes of data from the 1936 device identified by device number SRC_DEVICE_NUM to device 1937 DST_DEVICE_NUM. The data is copied from the source device from the 1938 address provided by SRC, shifted by the offset of SRC_OFFSET bytes, 1939 to the destination device's DST address shifted by DST_OFFSET. 1940 Task dependence is expressed by passing an array of depend objects 1941 to DEPOBJ_LIST, where the number of array elements is passed as 1942 DEPOBJ_COUNT; if the count is zero, the DEPOBJ_LIST argument is 1943 ignored. The routine returns zero if the copying process has 1944 successfully been started and non-zero otherwise. 1945 1946 Running this routine in a 'target' region except on the initial 1947 device is not supported. 1948 1949 _C/C++_ 1950 _Prototype_: 'int omp_target_memcpy_async(void *dst,' 1951 ' const void *src,' 1952 ' size_t length,' 1953 ' size_t dst_offset,' 1954 ' size_t src_offset,' 1955 ' int dst_device_num,' 1956 ' int src_device_num,' 1957 ' int depobj_count,' 1958 ' omp_depend_t *depobj_list)' 1959 1960 _Fortran_: 1961 _Interface_: 'integer(c_int) function omp_target_memcpy_async( &' 1962 ' dst, src, length, dst_offset, src_offset, &' 1963 ' dst_device_num, src_device_num, &' 1964 ' depobj_count, depobj_list) bind(C)' 1965 'use, intrinsic :: iso_c_binding, only: c_ptr, c_size_t, 1966 c_int' 1967 'type(c_ptr), value :: dst, src' 1968 'integer(c_size_t), value :: length, dst_offset, 1969 src_offset' 1970 'integer(c_int), value :: dst_device_num, 1971 src_device_num, depobj_count' 1972 'integer(omp_depend_kind), optional :: depobj_list(*)' 1973 1974 _See also_: 1975 *note omp_target_memcpy::, *note omp_target_memcpy_rect_async:: 1976 1977 _Reference_: 1978 OpenMP specification v5.1 (https://www.openmp.org), Section 3.8.7 1979 1980 1981 File: libgomp.info, Node: omp_target_memcpy_rect, Next: omp_target_memcpy_rect_async, Prev: omp_target_memcpy_async, Up: Device Memory Routines 1982 1983 3.7.7 'omp_target_memcpy_rect' - Copy a subvolume of data between devices 1984 ------------------------------------------------------------------------- 1985 1986 _Description_: 1987 This routine copies a subvolume of data from the device identified 1988 by device number SRC_DEVICE_NUM to device DST_DEVICE_NUM. The 1989 array has NUM_DIMS dimensions and each array element has a size of 1990 ELEMENT_SIZE bytes. The VOLUME array specifies how many elements 1991 per dimension are copied. The full sizes of the destination and 1992 source arrays are given by the DST_DIMENSIONS and SRC_DIMENSIONS 1993 arguments, respectively. The offset per dimension to the first 1994 element to be copied is given by the DST_OFFSET and SRC_OFFSET 1995 arguments. The routine returns zero on success and non-zero 1996 otherwise. 1997 1998 The OpenMP specification only requires that NUM_DIMS up to three is 1999 supported. In order to find implementation-specific maximally 2000 supported number of dimensions, the routine returns this value when 2001 invoked with a null pointer to both the DST and SRC arguments. As 2002 GCC supports arbitrary dimensions, it returns 'INT_MAX'. 2003 2004 The device-number arguments must be conforming device numbers, the 2005 SRC and DST must be either both null pointers or all of the 2006 following must be fulfilled: ELEMENT_SIZE and NUM_DIMS must be 2007 positive and the VOLUME, offset and dimension arrays must have at 2008 least NUM_DIMS dimensions. 2009 2010 Running this routine in a 'target' region is not supported except 2011 on the initial device. 2012 2013 _C/C++_ 2014 _Prototype_: 'int omp_target_memcpy_rect(void *dst,' 2015 ' const void *src,' 2016 ' size_t element_size,' 2017 ' int num_dims,' 2018 ' const size_t *volume,' 2019 ' const size_t *dst_offset,' 2020 ' const size_t *src_offset,' 2021 ' const size_t *dst_dimensions,' 2022 ' const size_t *src_dimensions,' 2023 ' int dst_device_num,' 2024 ' int src_device_num)' 2025 2026 _Fortran_: 2027 _Interface_: 'integer(c_int) function omp_target_memcpy_rect( &' 2028 ' dst, src, element_size, num_dims, volume, &' 2029 ' dst_offset, src_offset, dst_dimensions, &' 2030 ' src_dimensions, dst_device_num, src_device_num) 2031 bind(C)' 2032 'use, intrinsic :: iso_c_binding, only: c_ptr, c_size_t, 2033 c_int' 2034 'type(c_ptr), value :: dst, src' 2035 'integer(c_size_t), value :: element_size, dst_offset, 2036 src_offset' 2037 'integer(c_size_t), value :: volume, dst_dimensions, 2038 src_dimensions' 2039 'integer(c_int), value :: num_dims, dst_device_num, 2040 src_device_num' 2041 2042 _See also_: 2043 *note omp_target_memcpy_rect_async::, *note omp_target_memcpy:: 2044 2045 _Reference_: 2046 OpenMP specification v5.1 (https://www.openmp.org), Section 3.8.6 2047 2048 2049 File: libgomp.info, Node: omp_target_memcpy_rect_async, Next: omp_target_associate_ptr, Prev: omp_target_memcpy_rect, Up: Device Memory Routines 2050 2051 3.7.8 'omp_target_memcpy_rect_async' - Copy a subvolume of data between devices asynchronously 2052 ---------------------------------------------------------------------------------------------- 2053 2054 _Description_: 2055 This routine copies asynchronously a subvolume of data from the 2056 device identified by device number SRC_DEVICE_NUM to device 2057 DST_DEVICE_NUM. The array has NUM_DIMS dimensions and each array 2058 element has a size of ELEMENT_SIZE bytes. The VOLUME array 2059 specifies how many elements per dimension are copied. The full 2060 sizes of the destination and source arrays are given by the 2061 DST_DIMENSIONS and SRC_DIMENSIONS arguments, respectively. The 2062 offset per dimension to the first element to be copied is given by 2063 the DST_OFFSET and SRC_OFFSET arguments. Task dependence is 2064 expressed by passing an array of depend objects to DEPOBJ_LIST, 2065 where the number of array elements is passed as DEPOBJ_COUNT; if 2066 the count is zero, the DEPOBJ_LIST argument is ignored. The 2067 routine returns zero on success and non-zero otherwise. 2068 2069 The OpenMP specification only requires that NUM_DIMS up to three is 2070 supported. In order to find implementation-specific maximally 2071 supported number of dimensions, the routine returns this value when 2072 invoked with a null pointer to both the DST and SRC arguments. As 2073 GCC supports arbitrary dimensions, it returns 'INT_MAX'. 2074 2075 The device-number arguments must be conforming device numbers, the 2076 SRC and DST must be either both null pointers or all of the 2077 following must be fulfilled: ELEMENT_SIZE and NUM_DIMS must be 2078 positive and the VOLUME, offset and dimension arrays must have at 2079 least NUM_DIMS dimensions. 2080 2081 Running this routine in a 'target' region is not supported except 2082 on the initial device. 2083 2084 _C/C++_ 2085 _Prototype_: 'int omp_target_memcpy_rect_async(void *dst,' 2086 ' const void *src,' 2087 ' size_t element_size,' 2088 ' int num_dims,' 2089 ' const size_t *volume,' 2090 ' const size_t *dst_offset,' 2091 ' const size_t *src_offset,' 2092 ' const size_t *dst_dimensions,' 2093 ' const size_t *src_dimensions,' 2094 ' int dst_device_num,' 2095 ' int src_device_num,' 2096 ' int depobj_count,' 2097 ' omp_depend_t *depobj_list)' 2098 2099 _Fortran_: 2100 _Interface_: 'integer(c_int) function omp_target_memcpy_rect_async( 2101 &' 2102 ' dst, src, element_size, num_dims, volume, &' 2103 ' dst_offset, src_offset, dst_dimensions, &' 2104 ' src_dimensions, dst_device_num, src_device_num, &' 2105 ' depobj_count, depobj_list) bind(C)' 2106 'use, intrinsic :: iso_c_binding, only: c_ptr, c_size_t, 2107 c_int' 2108 'type(c_ptr), value :: dst, src' 2109 'integer(c_size_t), value :: element_size, dst_offset, 2110 src_offset' 2111 'integer(c_size_t), value :: volume, dst_dimensions, 2112 src_dimensions' 2113 'integer(c_int), value :: num_dims, dst_device_num, 2114 src_device_num' 2115 'integer(c_int), value :: depobj_count' 2116 'integer(omp_depend_kind), optional :: depobj_list(*)' 2117 2118 _See also_: 2119 *note omp_target_memcpy_rect::, *note omp_target_memcpy_async:: 2120 2121 _Reference_: 2122 OpenMP specification v5.1 (https://www.openmp.org), Section 3.8.8 2123 2124 2125 File: libgomp.info, Node: omp_target_associate_ptr, Next: omp_target_disassociate_ptr, Prev: omp_target_memcpy_rect_async, Up: Device Memory Routines 2126 2127 3.7.9 'omp_target_associate_ptr' - Associate a device pointer with a host pointer 2128 --------------------------------------------------------------------------------- 2129 2130 _Description_: 2131 This routine associates storage on the host with storage on a 2132 device identified by DEVICE_NUM. The device pointer is usually 2133 obtained by calling 'omp_target_alloc' or by other means (but not 2134 by using the 'map' clauses or the 'declare target' directive). The 2135 host pointer should point to memory that has a storage size of at 2136 least SIZE. 2137 2138 The DEVICE_OFFSET parameter specifies the offset into DEVICE_PTR 2139 that is used as the base address for the device side of the 2140 mapping; the storage size should be at least DEVICE_OFFSET plus 2141 SIZE. 2142 2143 After the association, the host pointer can be used in a 'map' 2144 clause and in the 'to' and 'from' clauses of the 'target update' 2145 directive to transfer data between the associated pointers. The 2146 reference count of such associated storage is infinite. The 2147 association can be removed by calling 'omp_target_disassociate_ptr' 2148 which should be done before the lifetime of either storage ends. 2149 2150 The routine returns nonzero ('EINVAL') when the DEVICE_NUM invalid, 2151 for when the initial device or the associated device shares memory 2152 with the host. 'omp_target_associate_ptr' returns zero if HOST_PTR 2153 points into already associated storage that is fully inside of a 2154 previously associated memory. Otherwise, if the association was 2155 successful zero is returned; if none of the cases above apply, 2156 nonzero ('EINVAL') is returned. 2157 2158 The 'omp_target_is_present' routine can be used to test whether 2159 associated storage for a device pointer exists. 2160 2161 Running this routine in a 'target' region except on the initial 2162 device is not supported. 2163 2164 _C/C++_ 2165 _Prototype_: 'int omp_target_associate_ptr(const void *host_ptr,' 2166 ' const void *device_ptr,' 2167 ' size_t size,' 2168 ' size_t device_offset,' 2169 ' int device_num)' 2170 2171 _Fortran_: 2172 _Interface_: 'integer(c_int) function 2173 omp_target_associate_ptr(host_ptr, &' 2174 ' device_ptr, size, device_offset, device_num) bind(C)' 2175 'use, intrinsic :: iso_c_binding, only: c_ptr, c_int, 2176 c_size_t' 2177 'type(c_ptr), value :: host_ptr, device_ptr' 2178 'integer(c_size_t), value :: size, device_offset' 2179 'integer(c_int), value :: device_num' 2180 2181 _See also_: 2182 *note omp_target_disassociate_ptr::, *note omp_target_is_present::, 2183 *note omp_target_alloc:: 2184 2185 _Reference_: 2186 OpenMP specification v5.1 (https://www.openmp.org), Section 3.8.9 2187 2188 2189 File: libgomp.info, Node: omp_target_disassociate_ptr, Next: omp_get_mapped_ptr, Prev: omp_target_associate_ptr, Up: Device Memory Routines 2190 2191 3.7.10 'omp_target_disassociate_ptr' - Remove device-host pointer association 2192 ----------------------------------------------------------------------------- 2193 2194 _Description_: 2195 This routine removes the storage association established by calling 2196 'omp_target_associate_ptr' and sets the reference count to zero, 2197 even if 'omp_target_associate_ptr' was invoked multiple times for 2198 for host pointer 'ptr'. If applicable, the device memory needs to 2199 be freed by the user. 2200 2201 If an associated device storage location for the DEVICE_NUM was 2202 found and has infinite reference count, the association is removed 2203 and zero is returned. In all other cases, nonzero ('EINVAL') is 2204 returned and no other action is taken. 2205 2206 Note that passing a host pointer where the association to the 2207 device pointer was established with the 'declare target' directive 2208 yields undefined behavior. 2209 2210 Running this routine in a 'target' region except on the initial 2211 device is not supported. 2212 2213 _C/C++_ 2214 _Prototype_: 'int omp_target_disassociate_ptr(const void *ptr,' 2215 ' int device_num)' 2216 2217 _Fortran_: 2218 _Interface_: 'integer(c_int) function 2219 omp_target_disassociate_ptr(ptr, &' 2220 ' device_num) bind(C)' 2221 'use, intrinsic :: iso_c_binding, only: c_ptr, c_int' 2222 'type(c_ptr), value :: ptr' 2223 'integer(c_int), value :: device_num' 2224 2225 _See also_: 2226 *note omp_target_associate_ptr:: 2227 2228 _Reference_: 2229 OpenMP specification v5.1 (https://www.openmp.org), Section 3.8.10 2230 2231 2232 File: libgomp.info, Node: omp_get_mapped_ptr, Prev: omp_target_disassociate_ptr, Up: Device Memory Routines 2233 2234 3.7.11 'omp_get_mapped_ptr' - Return device pointer to a host pointer 2235 --------------------------------------------------------------------- 2236 2237 _Description_: 2238 If the device number is refers to the initial device or to a device 2239 with memory accessible from the host (shared memory), the 2240 'omp_get_mapped_ptr' routines returns the value of the passed PTR. 2241 Otherwise, if associated storage to the passed host pointer PTR 2242 exists on device associated with DEVICE_NUM, it returns that 2243 pointer. In all other cases and in cases of an error, a null 2244 pointer is returned. 2245 2246 The association of storage location is established either via an 2247 explicit or implicit 'map' clause, the 'declare target' directive 2248 or the 'omp_target_associate_ptr' routine. 2249 2250 Running this routine in a 'target' region except on the initial 2251 device is not supported. 2252 2253 _C/C++_ 2254 _Prototype_: 'void *omp_get_mapped_ptr(const void *ptr, int 2255 device_num);' 2256 2257 _Fortran_: 2258 _Interface_: 'type(c_ptr) function omp_get_mapped_ptr(ptr, 2259 device_num) bind(C)' 2260 'use, intrinsic :: iso_c_binding, only: c_ptr, c_int' 2261 'type(c_ptr), value :: ptr' 2262 'integer(c_int), value :: device_num' 2263 2264 _See also_: 2265 *note omp_target_associate_ptr:: 2266 2267 _Reference_: 2268 OpenMP specification v5.1 (https://www.openmp.org), Section 3.8.11 2269 2270 2271 File: libgomp.info, Node: Lock Routines, Next: Timing Routines, Prev: Device Memory Routines, Up: Runtime Library Routines 2272 2273 3.8 Lock Routines 2274 ================= 2275 2276 Initialize, set, test, unset and destroy simple and nested locks. The 2277 routines have C linkage and do not throw exceptions. 2278 2279 * Menu: 2280 2281 * omp_init_lock:: Initialize simple lock 2282 * omp_init_nest_lock:: Initialize nested lock 2283 * omp_destroy_lock:: Destroy simple lock 2284 * omp_destroy_nest_lock:: Destroy nested lock 2285 * omp_set_lock:: Wait for and set simple lock 2286 * omp_set_nest_lock:: Wait for and set simple lock 2287 * omp_unset_lock:: Unset simple lock 2288 * omp_unset_nest_lock:: Unset nested lock 2289 * omp_test_lock:: Test and set simple lock if available 2290 * omp_test_nest_lock:: Test and set nested lock if available 2291 2292 2293 File: libgomp.info, Node: omp_init_lock, Next: omp_init_nest_lock, Up: Lock Routines 2294 2295 3.8.1 'omp_init_lock' - Initialize simple lock 2296 ---------------------------------------------- 2297 2298 _Description_: 2299 Initialize a simple lock. After initialization, the lock is in an 2300 unlocked state. 2301 2302 _C/C++_: 2303 _Prototype_: 'void omp_init_lock(omp_lock_t *lock);' 2304 2305 _Fortran_: 2306 _Interface_: 'subroutine omp_init_lock(svar)' 2307 'integer(omp_lock_kind), intent(out) :: svar' 2308 2309 _See also_: 2310 *note omp_destroy_lock:: 2311 2312 _Reference_: 2313 OpenMP specification v4.5 (https://www.openmp.org), Section 3.3.1. 2314 2315 2316 File: libgomp.info, Node: omp_init_nest_lock, Next: omp_destroy_lock, Prev: omp_init_lock, Up: Lock Routines 2317 2318 3.8.2 'omp_init_nest_lock' - Initialize nested lock 2319 --------------------------------------------------- 2320 2321 _Description_: 2322 Initialize a nested lock. After initialization, the lock is in an 2323 unlocked state and the nesting count is set to zero. 2324 2325 _C/C++_: 2326 _Prototype_: 'void omp_init_nest_lock(omp_nest_lock_t *lock);' 2327 2328 _Fortran_: 2329 _Interface_: 'subroutine omp_init_nest_lock(nvar)' 2330 'integer(omp_nest_lock_kind), intent(out) :: nvar' 2331 2332 _See also_: 2333 *note omp_destroy_nest_lock:: 2334 2335 _Reference_: 2336 OpenMP specification v4.5 (https://www.openmp.org), Section 3.3.1. 2337 2338 2339 File: libgomp.info, Node: omp_destroy_lock, Next: omp_destroy_nest_lock, Prev: omp_init_nest_lock, Up: Lock Routines 2340 2341 3.8.3 'omp_destroy_lock' - Destroy simple lock 2342 ---------------------------------------------- 2343 2344 _Description_: 2345 Destroy a simple lock. In order to be destroyed, a simple lock 2346 must be in the unlocked state. 2347 2348 _C/C++_: 2349 _Prototype_: 'void omp_destroy_lock(omp_lock_t *lock);' 2350 2351 _Fortran_: 2352 _Interface_: 'subroutine omp_destroy_lock(svar)' 2353 'integer(omp_lock_kind), intent(inout) :: svar' 2354 2355 _See also_: 2356 *note omp_init_lock:: 2357 2358 _Reference_: 2359 OpenMP specification v4.5 (https://www.openmp.org), Section 3.3.3. 2360 2361 2362 File: libgomp.info, Node: omp_destroy_nest_lock, Next: omp_set_lock, Prev: omp_destroy_lock, Up: Lock Routines 2363 2364 3.8.4 'omp_destroy_nest_lock' - Destroy nested lock 2365 --------------------------------------------------- 2366 2367 _Description_: 2368 Destroy a nested lock. In order to be destroyed, a nested lock 2369 must be in the unlocked state and its nesting count must equal 2370 zero. 2371 2372 _C/C++_: 2373 _Prototype_: 'void omp_destroy_nest_lock(omp_nest_lock_t *);' 2374 2375 _Fortran_: 2376 _Interface_: 'subroutine omp_destroy_nest_lock(nvar)' 2377 'integer(omp_nest_lock_kind), intent(inout) :: nvar' 2378 2379 _See also_: 2380 *note omp_init_lock:: 2381 2382 _Reference_: 2383 OpenMP specification v4.5 (https://www.openmp.org), Section 3.3.3. 2384 2385 2386 File: libgomp.info, Node: omp_set_lock, Next: omp_set_nest_lock, Prev: omp_destroy_nest_lock, Up: Lock Routines 2387 2388 3.8.5 'omp_set_lock' - Wait for and set simple lock 2389 --------------------------------------------------- 2390 2391 _Description_: 2392 Before setting a simple lock, the lock variable must be initialized 2393 by 'omp_init_lock'. The calling thread is blocked until the lock 2394 is available. If the lock is already held by the current thread, a 2395 deadlock occurs. 2396 2397 _C/C++_: 2398 _Prototype_: 'void omp_set_lock(omp_lock_t *lock);' 2399 2400 _Fortran_: 2401 _Interface_: 'subroutine omp_set_lock(svar)' 2402 'integer(omp_lock_kind), intent(inout) :: svar' 2403 2404 _See also_: 2405 *note omp_init_lock::, *note omp_test_lock::, *note 2406 omp_unset_lock:: 2407 2408 _Reference_: 2409 OpenMP specification v4.5 (https://www.openmp.org), Section 3.3.4. 2410 2411 2412 File: libgomp.info, Node: omp_set_nest_lock, Next: omp_unset_lock, Prev: omp_set_lock, Up: Lock Routines 2413 2414 3.8.6 'omp_set_nest_lock' - Wait for and set nested lock 2415 -------------------------------------------------------- 2416 2417 _Description_: 2418 Before setting a nested lock, the lock variable must be initialized 2419 by 'omp_init_nest_lock'. The calling thread is blocked until the 2420 lock is available. If the lock is already held by the current 2421 thread, the nesting count for the lock is incremented. 2422 2423 _C/C++_: 2424 _Prototype_: 'void omp_set_nest_lock(omp_nest_lock_t *lock);' 2425 2426 _Fortran_: 2427 _Interface_: 'subroutine omp_set_nest_lock(nvar)' 2428 'integer(omp_nest_lock_kind), intent(inout) :: nvar' 2429 2430 _See also_: 2431 *note omp_init_nest_lock::, *note omp_unset_nest_lock:: 2432 2433 _Reference_: 2434 OpenMP specification v4.5 (https://www.openmp.org), Section 3.3.4. 2435 2436 2437 File: libgomp.info, Node: omp_unset_lock, Next: omp_unset_nest_lock, Prev: omp_set_nest_lock, Up: Lock Routines 2438 2439 3.8.7 'omp_unset_lock' - Unset simple lock 2440 ------------------------------------------ 2441 2442 _Description_: 2443 A simple lock about to be unset must have been locked by 2444 'omp_set_lock' or 'omp_test_lock' before. In addition, the lock 2445 must be held by the thread calling 'omp_unset_lock'. Then, the 2446 lock becomes unlocked. If one or more threads attempted to set the 2447 lock before, one of them is chosen to, again, set the lock to 2448 itself. 2449 2450 _C/C++_: 2451 _Prototype_: 'void omp_unset_lock(omp_lock_t *lock);' 2452 2453 _Fortran_: 2454 _Interface_: 'subroutine omp_unset_lock(svar)' 2455 'integer(omp_lock_kind), intent(inout) :: svar' 2456 2457 _See also_: 2458 *note omp_set_lock::, *note omp_test_lock:: 2459 2460 _Reference_: 2461 OpenMP specification v4.5 (https://www.openmp.org), Section 3.3.5. 2462 2463 2464 File: libgomp.info, Node: omp_unset_nest_lock, Next: omp_test_lock, Prev: omp_unset_lock, Up: Lock Routines 2465 2466 3.8.8 'omp_unset_nest_lock' - Unset nested lock 2467 ----------------------------------------------- 2468 2469 _Description_: 2470 A nested lock about to be unset must have been locked by 2471 'omp_set_nested_lock' or 'omp_test_nested_lock' before. In 2472 addition, the lock must be held by the thread calling 2473 'omp_unset_nested_lock'. If the nesting count drops to zero, the 2474 lock becomes unlocked. If one ore more threads attempted to set 2475 the lock before, one of them is chosen to, again, set the lock to 2476 itself. 2477 2478 _C/C++_: 2479 _Prototype_: 'void omp_unset_nest_lock(omp_nest_lock_t *lock);' 2480 2481 _Fortran_: 2482 _Interface_: 'subroutine omp_unset_nest_lock(nvar)' 2483 'integer(omp_nest_lock_kind), intent(inout) :: nvar' 2484 2485 _See also_: 2486 *note omp_set_nest_lock:: 2487 2488 _Reference_: 2489 OpenMP specification v4.5 (https://www.openmp.org), Section 3.3.5. 2490 2491 2492 File: libgomp.info, Node: omp_test_lock, Next: omp_test_nest_lock, Prev: omp_unset_nest_lock, Up: Lock Routines 2493 2494 3.8.9 'omp_test_lock' - Test and set simple lock if available 2495 ------------------------------------------------------------- 2496 2497 _Description_: 2498 Before setting a simple lock, the lock variable must be initialized 2499 by 'omp_init_lock'. Contrary to 'omp_set_lock', 'omp_test_lock' 2500 does not block if the lock is not available. This function returns 2501 'true' upon success, 'false' otherwise. Here, 'true' and 'false' 2502 represent their language-specific counterparts. 2503 2504 _C/C++_: 2505 _Prototype_: 'int omp_test_lock(omp_lock_t *lock);' 2506 2507 _Fortran_: 2508 _Interface_: 'logical function omp_test_lock(svar)' 2509 'integer(omp_lock_kind), intent(inout) :: svar' 2510 2511 _See also_: 2512 *note omp_init_lock::, *note omp_set_lock::, *note omp_set_lock:: 2513 2514 _Reference_: 2515 OpenMP specification v4.5 (https://www.openmp.org), Section 3.3.6. 2516 2517 2518 File: libgomp.info, Node: omp_test_nest_lock, Prev: omp_test_lock, Up: Lock Routines 2519 2520 3.8.10 'omp_test_nest_lock' - Test and set nested lock if available 2521 ------------------------------------------------------------------- 2522 2523 _Description_: 2524 Before setting a nested lock, the lock variable must be initialized 2525 by 'omp_init_nest_lock'. Contrary to 'omp_set_nest_lock', 2526 'omp_test_nest_lock' does not block if the lock is not available. 2527 If the lock is already held by the current thread, the new nesting 2528 count is returned. Otherwise, the return value equals zero. 2529 2530 _C/C++_: 2531 _Prototype_: 'int omp_test_nest_lock(omp_nest_lock_t *lock);' 2532 2533 _Fortran_: 2534 _Interface_: 'logical function omp_test_nest_lock(nvar)' 2535 'integer(omp_nest_lock_kind), intent(inout) :: nvar' 2536 2537 _See also_: 2538 *note omp_init_lock::, *note omp_set_lock::, *note omp_set_lock:: 2539 2540 _Reference_: 2541 OpenMP specification v4.5 (https://www.openmp.org), Section 3.3.6. 2542 2543 2544 File: libgomp.info, Node: Timing Routines, Next: Event Routine, Prev: Lock Routines, Up: Runtime Library Routines 2545 2546 3.9 Timing Routines 2547 =================== 2548 2549 Portable, thread-based, wall clock timer. The routines have C linkage 2550 and do not throw exceptions. 2551 2552 * Menu: 2553 2554 * omp_get_wtick:: Get timer precision. 2555 * omp_get_wtime:: Elapsed wall clock time. 2556 2557 2558 File: libgomp.info, Node: omp_get_wtick, Next: omp_get_wtime, Up: Timing Routines 2559 2560 3.9.1 'omp_get_wtick' - Get timer precision 2561 ------------------------------------------- 2562 2563 _Description_: 2564 Gets the timer precision, i.e., the number of seconds between two 2565 successive clock ticks. 2566 2567 _C/C++_: 2568 _Prototype_: 'double omp_get_wtick(void);' 2569 2570 _Fortran_: 2571 _Interface_: 'double precision function omp_get_wtick()' 2572 2573 _See also_: 2574 *note omp_get_wtime:: 2575 2576 _Reference_: 2577 OpenMP specification v4.5 (https://www.openmp.org), Section 3.4.2. 2578 2579 2580 File: libgomp.info, Node: omp_get_wtime, Prev: omp_get_wtick, Up: Timing Routines 2581 2582 3.9.2 'omp_get_wtime' - Elapsed wall clock time 2583 ----------------------------------------------- 2584 2585 _Description_: 2586 Elapsed wall clock time in seconds. The time is measured per 2587 thread, no guarantee can be made that two distinct threads measure 2588 the same time. Time is measured from some "time in the past", 2589 which is an arbitrary time guaranteed not to change during the 2590 execution of the program. 2591 2592 _C/C++_: 2593 _Prototype_: 'double omp_get_wtime(void);' 2594 2595 _Fortran_: 2596 _Interface_: 'double precision function omp_get_wtime()' 2597 2598 _See also_: 2599 *note omp_get_wtick:: 2600 2601 _Reference_: 2602 OpenMP specification v4.5 (https://www.openmp.org), Section 3.4.1. 2603 2604 2605 File: libgomp.info, Node: Event Routine, Next: Memory Management Routines, Prev: Timing Routines, Up: Runtime Library Routines 2606 2607 3.10 Event Routine 2608 ================== 2609 2610 Support for event objects. The routine has C linkage and do not throw 2611 exceptions. 2612 2613 * Menu: 2614 2615 * omp_fulfill_event:: Fulfill and destroy an OpenMP event. 2616 2617 2618 File: libgomp.info, Node: omp_fulfill_event, Up: Event Routine 2619 2620 3.10.1 'omp_fulfill_event' - Fulfill and destroy an OpenMP event 2621 ---------------------------------------------------------------- 2622 2623 _Description_: 2624 Fulfill the event associated with the event handle argument. 2625 Currently, it is only used to fulfill events generated by detach 2626 clauses on task constructs - the effect of fulfilling the event is 2627 to allow the task to complete. 2628 2629 The result of calling 'omp_fulfill_event' with an event handle 2630 other than that generated by a detach clause is undefined. Calling 2631 it with an event handle that has already been fulfilled is also 2632 undefined. 2633 2634 _C/C++_: 2635 _Prototype_: 'void omp_fulfill_event(omp_event_handle_t event);' 2636 2637 _Fortran_: 2638 _Interface_: 'subroutine omp_fulfill_event(event)' 2639 'integer (kind=omp_event_handle_kind) :: event' 2640 2641 _Reference_: 2642 OpenMP specification v5.0 (https://www.openmp.org), Section 3.5.1. 2643 2644 2645 File: libgomp.info, Node: Memory Management Routines, Next: Environment Display Routine, Prev: Event Routine, Up: Runtime Library Routines 2646 2647 3.11 Memory Management Routines 2648 =============================== 2649 2650 Routines to manage and allocate memory on the current device. They have 2651 C linkage and do not throw exceptions. 2652 2653 * Menu: 2654 2655 * omp_init_allocator:: Create an allocator 2656 * omp_destroy_allocator:: Destroy an allocator 2657 * omp_set_default_allocator:: Set the default allocator 2658 * omp_get_default_allocator:: Get the default allocator 2659 * omp_alloc:: Memory allocation with an allocator 2660 * omp_aligned_alloc:: Memory allocation with an allocator and alignment 2661 * omp_free:: Freeing memory allocated with OpenMP routines 2662 * omp_calloc:: Allocate nullified memory with an allocator 2663 * omp_aligned_calloc:: Allocate nullified aligned memory with an allocator 2664 * omp_realloc:: Reallocate memory allocated with OpenMP routines 2665 2666 2667 File: libgomp.info, Node: omp_init_allocator, Next: omp_destroy_allocator, Up: Memory Management Routines 2668 2669 3.11.1 'omp_init_allocator' - Create an allocator 2670 ------------------------------------------------- 2671 2672 _Description_: 2673 Create an allocator that uses the specified memory space and has 2674 the specified traits; if an allocator that fulfills the 2675 requirements cannot be created, 'omp_null_allocator' is returned. 2676 2677 The predefined memory spaces and available traits can be found at 2678 *note OMP_ALLOCATOR::, where the trait names have to be prefixed by 2679 'omp_atk_' (e.g. 'omp_atk_pinned') and the named trait values by 2680 'omp_atv_' (e.g. 'omp_atv_true'); additionally, 'omp_atv_default' 2681 may be used as trait value to specify that the default value should 2682 be used. 2683 2684 _C/C++_: 2685 _Prototype_: 'omp_allocator_handle_t omp_init_allocator(' 2686 ' omp_memspace_handle_t memspace,' 2687 ' int ntraits,' 2688 ' const omp_alloctrait_t traits[]);' 2689 2690 _Fortran_: 2691 _Interface_: 'function omp_init_allocator(memspace, ntraits, traits)' 2692 'integer (omp_allocator_handle_kind) :: 2693 omp_init_allocator' 2694 'integer (omp_memspace_handle_kind), intent(in) :: 2695 memspace' 2696 'integer, intent(in) :: ntraits' 2697 'type (omp_alloctrait), intent(in) :: traits(*)' 2698 2699 _See also_: 2700 *note OMP_ALLOCATOR::, *note Memory allocation::, *note 2701 omp_destroy_allocator:: 2702 2703 _Reference_: 2704 OpenMP specification v5.0 (https://www.openmp.org), Section 3.7.2 2705 2706 2707 File: libgomp.info, Node: omp_destroy_allocator, Next: omp_set_default_allocator, Prev: omp_init_allocator, Up: Memory Management Routines 2708 2709 3.11.2 'omp_destroy_allocator' - Destroy an allocator 2710 ----------------------------------------------------- 2711 2712 _Description_: 2713 Releases all resources used by a memory allocator, which must not 2714 represent a predefined memory allocator. Accessing memory after 2715 its allocator has been destroyed has unspecified behavior. Passing 2716 'omp_null_allocator' to the routine is permitted but has no effect. 2717 2718 _C/C++_: 2719 _Prototype_: 'void omp_destroy_allocator (omp_allocator_handle_t 2720 allocator);' 2721 2722 _Fortran_: 2723 _Interface_: 'subroutine omp_destroy_allocator(allocator)' 2724 'integer (omp_allocator_handle_kind), intent(in) :: 2725 allocator' 2726 2727 _See also_: 2728 *note omp_init_allocator:: 2729 2730 _Reference_: 2731 OpenMP specification v5.0 (https://www.openmp.org), Section 3.7.3 2732 2733 2734 File: libgomp.info, Node: omp_set_default_allocator, Next: omp_get_default_allocator, Prev: omp_destroy_allocator, Up: Memory Management Routines 2735 2736 3.11.3 'omp_set_default_allocator' - Set the default allocator 2737 -------------------------------------------------------------- 2738 2739 _Description_: 2740 Sets the default allocator that is used when no allocator has been 2741 specified in the 'allocate' or 'allocator' clause or if an OpenMP 2742 memory routine is invoked with the 'omp_null_allocator' allocator. 2743 2744 _C/C++_: 2745 _Prototype_: 'void omp_set_default_allocator(omp_allocator_handle_t 2746 allocator);' 2747 2748 _Fortran_: 2749 _Interface_: 'subroutine omp_set_default_allocator(allocator)' 2750 'integer (omp_allocator_handle_kind), intent(in) :: 2751 allocator' 2752 2753 _See also_: 2754 *note omp_get_default_allocator::, *note omp_init_allocator::, 2755 *note OMP_ALLOCATOR::, *note Memory allocation:: 2756 2757 _Reference_: 2758 OpenMP specification v5.0 (https://www.openmp.org), Section 3.7.4 2759 2760 2761 File: libgomp.info, Node: omp_get_default_allocator, Next: omp_alloc, Prev: omp_set_default_allocator, Up: Memory Management Routines 2762 2763 3.11.4 'omp_get_default_allocator' - Get the default allocator 2764 -------------------------------------------------------------- 2765 2766 _Description_: 2767 The routine returns the default allocator that is used when no 2768 allocator has been specified in the 'allocate' or 'allocator' 2769 clause or if an OpenMP memory routine is invoked with the 2770 'omp_null_allocator' allocator. 2771 2772 _C/C++_: 2773 _Prototype_: 'omp_allocator_handle_t omp_get_default_allocator();' 2774 2775 _Fortran_: 2776 _Interface_: 'function omp_get_default_allocator()' 2777 'integer (omp_allocator_handle_kind) :: 2778 omp_get_default_allocator' 2779 2780 _See also_: 2781 *note omp_set_default_allocator::, *note OMP_ALLOCATOR:: 2782 2783 _Reference_: 2784 OpenMP specification v5.0 (https://www.openmp.org), Section 3.7.5 2785 2786 2787 File: libgomp.info, Node: omp_alloc, Next: omp_aligned_alloc, Prev: omp_get_default_allocator, Up: Memory Management Routines 2788 2789 3.11.5 'omp_alloc' - Memory allocation with an allocator 2790 -------------------------------------------------------- 2791 2792 _Description_: 2793 Allocate memory with the specified allocator, which can either be a 2794 predefined allocator, an allocator handle or 'omp_null_allocator'. 2795 If the allocators is 'omp_null_allocator', the allocator specified 2796 by the DEF-ALLOCATOR-VAR ICV is used. SIZE must be a nonnegative 2797 number denoting the number of bytes to be allocated; if SIZE is 2798 zero, 'omp_alloc' will return a null pointer. If successful, a 2799 pointer to the allocated memory is returned, otherwise the 2800 'fallback' trait of the allocator determines the behavior. The 2801 content of the allocated memory is unspecified. 2802 2803 In 'target' regions, either the 'dynamic_allocators' clause must 2804 appear on a 'requires' directive in the same compilation unit - or 2805 the ALLOCATOR argument may only be a constant expression with the 2806 value of one of the predefined allocators and may not be 2807 'omp_null_allocator'. 2808 2809 Memory allocated by 'omp_alloc' must be freed using 'omp_free'. 2810 2811 _C_: 2812 _Prototype_: 'void* omp_alloc(size_t size,' 2813 ' omp_allocator_handle_t allocator)' 2814 2815 _C++_: 2816 _Prototype_: 'void* omp_alloc(size_t size,' 2817 ' omp_allocator_handle_t allocator=omp_null_allocator)' 2818 2819 _Fortran_: 2820 _Interface_: 'type(c_ptr) function omp_alloc(size, allocator) 2821 bind(C)' 2822 'use, intrinsic :: iso_c_binding, only : c_ptr, 2823 c_size_t' 2824 'integer (c_size_t), value :: size' 2825 'integer (omp_allocator_handle_kind), value :: 2826 allocator' 2827 2828 _See also_: 2829 *note OMP_ALLOCATOR::, *note Memory allocation::, *note 2830 omp_set_default_allocator::, *note omp_free::, *note 2831 omp_init_allocator:: 2832 2833 _Reference_: 2834 OpenMP specification v5.0 (https://www.openmp.org), Section 3.7.6 2835 2836 2837 File: libgomp.info, Node: omp_aligned_alloc, Next: omp_free, Prev: omp_alloc, Up: Memory Management Routines 2838 2839 3.11.6 'omp_aligned_alloc' - Memory allocation with an allocator and alignment 2840 ------------------------------------------------------------------------------ 2841 2842 _Description_: 2843 Allocate memory with the specified allocator, which can either be a 2844 predefined allocator, an allocator handle or 'omp_null_allocator'. 2845 If the allocators is 'omp_null_allocator', the allocator specified 2846 by the DEF-ALLOCATOR-VAR ICV is used. ALIGNMENT must be a positive 2847 power of two and SIZE must be a nonnegative number that is a 2848 multiple of the alignment and denotes the number of bytes to be 2849 allocated; if SIZE is zero, 'omp_aligned_alloc' will return a null 2850 pointer. The alignment will be at least the maximal value required 2851 by 'alignment' trait of the allocator and the value of the passed 2852 ALIGNMENT argument. If successful, a pointer to the allocated 2853 memory is returned, otherwise the 'fallback' trait of the allocator 2854 determines the behavior. The content of the allocated memory is 2855 unspecified. 2856 2857 In 'target' regions, either the 'dynamic_allocators' clause must 2858 appear on a 'requires' directive in the same compilation unit - or 2859 the ALLOCATOR argument may only be a constant expression with the 2860 value of one of the predefined allocators and may not be 2861 'omp_null_allocator'. 2862 2863 Memory allocated by 'omp_aligned_alloc' must be freed using 2864 'omp_free'. 2865 2866 _C_: 2867 _Prototype_: 'void* omp_aligned_alloc(size_t alignment,' 2868 ' size_t size,' 2869 ' omp_allocator_handle_t allocator)' 2870 2871 _C++_: 2872 _Prototype_: 'void* omp_aligned_alloc(size_t alignment,' 2873 ' size_t size,' 2874 ' omp_allocator_handle_t allocator=omp_null_allocator)' 2875 2876 _Fortran_: 2877 _Interface_: 'type(c_ptr) function omp_aligned_alloc(alignment, size, 2878 allocator) bind(C)' 2879 'use, intrinsic :: iso_c_binding, only : c_ptr, 2880 c_size_t' 2881 'integer (c_size_t), value :: alignment, size' 2882 'integer (omp_allocator_handle_kind), value :: 2883 allocator' 2884 2885 _See also_: 2886 *note OMP_ALLOCATOR::, *note Memory allocation::, *note 2887 omp_set_default_allocator::, *note omp_free::, *note 2888 omp_init_allocator:: 2889 2890 _Reference_: 2891 OpenMP specification v5.1 (https://www.openmp.org), Section 3.13.6 2892 2893 2894 File: libgomp.info, Node: omp_free, Next: omp_calloc, Prev: omp_aligned_alloc, Up: Memory Management Routines 2895 2896 3.11.7 'omp_free' - Freeing memory allocated with OpenMP routines 2897 ----------------------------------------------------------------- 2898 2899 _Description_: 2900 The 'omp_free' routine deallocates memory previously allocated by 2901 an OpenMP memory-management routine. The PTR argument must point 2902 to such memory or be a null pointer; if it is a null pointer, no 2903 operation is performed. If specified, the ALLOCATOR argument must 2904 be either the memory allocator that was used for the allocation or 2905 'omp_null_allocator'; if it is 'omp_null_allocator', the 2906 implementation will determine the value automatically. 2907 2908 Calling 'omp_free' invokes undefined behavior if the memory was 2909 already deallocated or when the used allocator has already been 2910 destroyed. 2911 2912 _C_: 2913 _Prototype_: 'void omp_free(void *ptr,' 2914 ' omp_allocator_handle_t allocator)' 2915 2916 _C++_: 2917 _Prototype_: 'void omp_free(void *ptr,' 2918 ' omp_allocator_handle_t allocator=omp_null_allocator)' 2919 2920 _Fortran_: 2921 _Interface_: 'subroutine omp_free(ptr, allocator) bind(C)' 2922 'use, intrinsic :: iso_c_binding, only : c_ptr' 2923 'type (c_ptr), value :: ptr' 2924 'integer (omp_allocator_handle_kind), value :: 2925 allocator' 2926 2927 _See also_: 2928 *note omp_alloc::, *note omp_aligned_alloc::, *note omp_calloc::, 2929 *note omp_aligned_calloc::, *note omp_realloc:: 2930 2931 _Reference_: 2932 OpenMP specification v5.0 (https://www.openmp.org), Section 3.7.7 2933 2934 2935 File: libgomp.info, Node: omp_calloc, Next: omp_aligned_calloc, Prev: omp_free, Up: Memory Management Routines 2936 2937 3.11.8 'omp_calloc' - Allocate nullified memory with an allocator 2938 ----------------------------------------------------------------- 2939 2940 _Description_: 2941 Allocate zero-initialized memory with the specified allocator, 2942 which can either be a predefined allocator, an allocator handle or 2943 'omp_null_allocator'. If the allocators is 'omp_null_allocator', 2944 the allocator specified by the DEF-ALLOCATOR-VAR ICV is used. The 2945 to-be allocated memory is for an array with NMEMB elements, each 2946 having a size of SIZE bytes. Both NMEMB and SIZE must be 2947 nonnegative numbers; if either of them is zero, 'omp_calloc' will 2948 return a null pointer. If successful, a pointer to the 2949 zero-initialized allocated memory is returned, otherwise the 2950 'fallback' trait of the allocator determines the behavior. 2951 2952 In 'target' regions, either the 'dynamic_allocators' clause must 2953 appear on a 'requires' directive in the same compilation unit - or 2954 the ALLOCATOR argument may only be a constant expression with the 2955 value of one of the predefined allocators and may not be 2956 'omp_null_allocator'. 2957 2958 Memory allocated by 'omp_calloc' must be freed using 'omp_free'. 2959 2960 _C_: 2961 _Prototype_: 'void* omp_calloc(size_t nmemb, size_t size,' 2962 ' omp_allocator_handle_t allocator)' 2963 2964 _C++_: 2965 _Prototype_: 'void* omp_calloc(size_t nmemb, size_t size,' 2966 ' omp_allocator_handle_t allocator=omp_null_allocator)' 2967 2968 _Fortran_: 2969 _Interface_: 'type(c_ptr) function omp_calloc(nmemb, size, allocator) 2970 bind(C)' 2971 'use, intrinsic :: iso_c_binding, only : c_ptr, 2972 c_size_t' 2973 'integer (c_size_t), value :: nmemb, size' 2974 'integer (omp_allocator_handle_kind), value :: 2975 allocator' 2976 2977 _See also_: 2978 *note OMP_ALLOCATOR::, *note Memory allocation::, *note 2979 omp_set_default_allocator::, *note omp_free::, *note 2980 omp_init_allocator:: 2981 2982 _Reference_: 2983 OpenMP specification v5.1 (https://www.openmp.org), Section 3.13.8 2984 2985 2986 File: libgomp.info, Node: omp_aligned_calloc, Next: omp_realloc, Prev: omp_calloc, Up: Memory Management Routines 2987 2988 3.11.9 'omp_aligned_calloc' - Allocate aligned nullified memory with an allocator 2989 --------------------------------------------------------------------------------- 2990 2991 _Description_: 2992 Allocate zero-initialized memory with the specified allocator, 2993 which can either be a predefined allocator, an allocator handle or 2994 'omp_null_allocator'. If the allocators is 'omp_null_allocator', 2995 the allocator specified by the DEF-ALLOCATOR-VAR ICV is used. The 2996 to-be allocated memory is for an array with NMEMB elements, each 2997 having a size of SIZE bytes. Both NMEMB and SIZE must be 2998 nonnegative numbers; if either of them is zero, 2999 'omp_aligned_calloc' will return a null pointer. ALIGNMENT must be 3000 a positive power of two and SIZE must be a multiple of the 3001 alignment; the alignment will be at least the maximal value 3002 required by 'alignment' trait of the allocator and the value of the 3003 passed ALIGNMENT argument. If successful, a pointer to the 3004 zero-initialized allocated memory is returned, otherwise the 3005 'fallback' trait of the allocator determines the behavior. 3006 3007 In 'target' regions, either the 'dynamic_allocators' clause must 3008 appear on a 'requires' directive in the same compilation unit - or 3009 the ALLOCATOR argument may only be a constant expression with the 3010 value of one of the predefined allocators and may not be 3011 'omp_null_allocator'. 3012 3013 Memory allocated by 'omp_aligned_calloc' must be freed using 3014 'omp_free'. 3015 3016 _C_: 3017 _Prototype_: 'void* omp_aligned_calloc(size_t nmemb, size_t size,' 3018 ' omp_allocator_handle_t allocator)' 3019 3020 _C++_: 3021 _Prototype_: 'void* omp_aligned_calloc(size_t nmemb, size_t size,' 3022 ' omp_allocator_handle_t allocator=omp_null_allocator)' 3023 3024 _Fortran_: 3025 _Interface_: 'type(c_ptr) function omp_aligned_calloc(nmemb, size, 3026 allocator) bind(C)' 3027 'use, intrinsic :: iso_c_binding, only : c_ptr, 3028 c_size_t' 3029 'integer (c_size_t), value :: nmemb, size' 3030 'integer (omp_allocator_handle_kind), value :: 3031 allocator' 3032 3033 _See also_: 3034 *note OMP_ALLOCATOR::, *note Memory allocation::, *note 3035 omp_set_default_allocator::, *note omp_free::, *note 3036 omp_init_allocator:: 3037 3038 _Reference_: 3039 OpenMP specification v5.1 (https://www.openmp.org), Section 3.13.8 3040 3041 3042 File: libgomp.info, Node: omp_realloc, Prev: omp_aligned_calloc, Up: Memory Management Routines 3043 3044 3.11.10 'omp_realloc' - Reallocate memory allocated with OpenMP routines 3045 ------------------------------------------------------------------------ 3046 3047 _Description_: 3048 The 'omp_realloc' routine deallocates memory to which PTR points to 3049 and allocates new memory with the specified ALLOCATOR argument; the 3050 new memory will have the content of the old memory up to the 3051 minimum of the old size and the new SIZE, otherwise the content of 3052 the returned memory is unspecified. If the new allocator is the 3053 same as the old one, the routine tries to resize the existing 3054 memory allocation, returning the same address as PTR if successful. 3055 PTR must point to memory allocated by an OpenMP memory-management 3056 routine. 3057 3058 The ALLOCATOR and FREE_ALLOCATOR arguments must be a predefined 3059 allocator, an allocator handle or 'omp_null_allocator'. If 3060 FREE_ALLOCATOR is 'omp_null_allocator', the implementation 3061 automatically determines the allocator used for the allocation of 3062 PTR. If ALLOCATOR is 'omp_null_allocator' and PTR is not a null 3063 pointer, the same allocator as 'free_allocator' is used and when 3064 PTR is a null pointer the allocator specified by the 3065 DEF-ALLOCATOR-VAR ICV is used. 3066 3067 The SIZE must be a nonnegative number denoting the number of bytes 3068 to be allocated; if SIZE is zero, 'omp_realloc' will return free 3069 the memory and return a null pointer. When SIZE is nonzero: if 3070 successful, a pointer to the allocated memory is returned, 3071 otherwise the 'fallback' trait of the allocator determines the 3072 behavior. 3073 3074 In 'target' regions, either the 'dynamic_allocators' clause must 3075 appear on a 'requires' directive in the same compilation unit - or 3076 the FREE_ALLOCATOR and ALLOCATOR arguments may only be a constant 3077 expression with the value of one of the predefined allocators and 3078 may not be 'omp_null_allocator'. 3079 3080 Memory allocated by 'omp_realloc' must be freed using 'omp_free'. 3081 Calling 'omp_free' invokes undefined behavior if the memory was 3082 already deallocated or when the used allocator has already been 3083 destroyed. 3084 3085 _C_: 3086 _Prototype_: 'void* omp_realloc(void *ptr, size_t size,' 3087 ' omp_allocator_handle_t allocator,' 3088 ' omp_allocator_handle_t free_allocator)' 3089 3090 _C++_: 3091 _Prototype_: 'void* omp_realloc(void *ptr, size_t size,' 3092 ' omp_allocator_handle_t allocator=omp_null_allocator,' 3093 ' omp_allocator_handle_t 3094 free_allocator=omp_null_allocator)' 3095 3096 _Fortran_: 3097 _Interface_: 'type(c_ptr) function omp_realloc(ptr, size, allocator, 3098 free_allocator) bind(C)' 3099 'use, intrinsic :: iso_c_binding, only : c_ptr, 3100 c_size_t' 3101 'type(C_ptr), value :: ptr' 3102 'integer (c_size_t), value :: size' 3103 'integer (omp_allocator_handle_kind), value :: 3104 allocator, free_allocator' 3105 3106 _See also_: 3107 *note OMP_ALLOCATOR::, *note Memory allocation::, *note 3108 omp_set_default_allocator::, *note omp_free::, *note 3109 omp_init_allocator:: 3110 3111 _Reference_: 3112 OpenMP specification v5.0 (https://www.openmp.org), Section 3.7.9 3113 3114 3115 File: libgomp.info, Node: Environment Display Routine, Prev: Memory Management Routines, Up: Runtime Library Routines 3116 3117 3.12 Environment Display Routine 3118 ================================ 3119 3120 Routine to display the OpenMP version number and the initial value of 3121 ICVs. It has C linkage and does not throw exceptions. 3122 3123 * Menu: 3124 3125 * omp_display_env:: print the initial ICV values 3126 3127 3128 File: libgomp.info, Node: omp_display_env, Up: Environment Display Routine 3129 3130 3.12.1 'omp_display_env' - print the initial ICV values 3131 ------------------------------------------------------- 3132 3133 _Description_: 3134 Each time this routine is invoked, the OpenMP version number and 3135 initial value of internal control variables (ICVs) is printed on 3136 'stderr'. The displayed values are those at startup after 3137 evaluating the environment variables; later calls to API routines 3138 or clauses used in enclosing constructs do not affect the output. 3139 3140 If the VERBOSE argument is 'false', only the OpenMP version and 3141 standard OpenMP ICVs are shown; if it is 'true', additionally, the 3142 GCC-specific ICVs are shown. 3143 3144 The output consists of multiple lines and starts with 'OPENMP 3145 DISPLAY ENVIRONMENT BEGIN' followed by the name-value lines and 3146 ends with 'OPENMP DISPLAY ENVIRONMENT END'. The NAME is followed 3147 by an equal sign and the VALUE is enclosed in single quotes. 3148 3149 The first line has as NAME either '_OPENMP' or 'openmp_version' and 3150 shows as value the supported OpenMP version number (4-digit year, 3151 2-digit month) of the implementation, matching the value of the 3152 '_OPENMP' macro and, in Fortran, the named constant 3153 'openmp_version'. 3154 3155 In each of the succeeding lines, the NAME matches the 3156 environment-variable name of an ICV and shows its value. Those 3157 line are might be prefixed by pair of brackets and a space, where 3158 the brackets enclose a comma-separated list of devices to which the 3159 ICV-value combination applies to; the value can either be a numeric 3160 device number or an abstract name denoting all devices ('all'), the 3161 initial host device ('host') or all devices but the host 3162 ('device'). Note that the same ICV might be printed multiple times 3163 for multiple devices, even if all have the same value. 3164 3165 The effect when invoked from within a 'target' region is 3166 unspecified. 3167 3168 _C/C++_: 3169 _Prototype_: 'void omp_display_env(int verbose)' 3170 3171 _Fortran_: 3172 _Interface_: 'subroutine omp_display_env(vebose)' 3173 'logical, intent(in) :: verbose' 3174 3175 _Example_: 3176 Note that the GCC-specific ICVs, such as the shown 3177 'GOMP_SPINCOUNT', are only printed when VARBOSE set to 'true'. 3178 3179 OPENMP DISPLAY ENVIRONMENT BEGIN 3180 _OPENMP = '201511' 3181 [host] OMP_DYNAMIC = 'FALSE' 3182 [host] OMP_NESTED = 'FALSE' 3183 [all] OMP_CANCELLATION = 'FALSE' 3184 ... 3185 [host] GOMP_SPINCOUNT = '300000' 3186 OPENMP DISPLAY ENVIRONMENT END 3187 3188 _See also_: 3189 *note OMP_DISPLAY_ENV::, *note Environment Variables::, *note 3190 Implementation-defined ICV Initialization:: 3191 3192 _Reference_: 3193 OpenMP specification v5.1 (https://www.openmp.org), Section 3.15 3194 3195 3196 File: libgomp.info, Node: Environment Variables, Next: Enabling OpenACC, Prev: Runtime Library Routines, Up: Top 3197 3198 4 OpenMP Environment Variables 3199 ****************************** 3200 3201 The environment variables which beginning with 'OMP_' are defined by 3202 section 4 of the OpenMP specification in version 4.5 or in a later 3203 version of the specification, while those beginning with 'GOMP_' are GNU 3204 extensions. Most 'OMP_' environment variables have an associated 3205 internal control variable (ICV). 3206 3207 For any OpenMP environment variable that sets an ICV and is neither 3208 'OMP_DEFAULT_DEVICE' nor has global ICV scope, associated 3209 device-specific environment variables exist. For them, the environment 3210 variable without suffix affects the host. The suffix '_DEV_' followed 3211 by a non-negative device number less that the number of available 3212 devices sets the ICV for the corresponding device. The suffix '_DEV' 3213 sets the ICV of all non-host devices for which a device-specific 3214 corresponding environment variable has not been set while the '_ALL' 3215 suffix sets the ICV of all host and non-host devices for which a more 3216 specific corresponding environment variable is not set. 3217 3218 * Menu: 3219 3220 * OMP_ALLOCATOR:: Set the default allocator 3221 * OMP_AFFINITY_FORMAT:: Set the format string used for affinity display 3222 * OMP_CANCELLATION:: Set whether cancellation is activated 3223 * OMP_DISPLAY_AFFINITY:: Display thread affinity information 3224 * OMP_DISPLAY_ENV:: Show OpenMP version and environment variables 3225 * OMP_DEFAULT_DEVICE:: Set the device used in target regions 3226 * OMP_DYNAMIC:: Dynamic adjustment of threads 3227 * OMP_MAX_ACTIVE_LEVELS:: Set the maximum number of nested parallel regions 3228 * OMP_MAX_TASK_PRIORITY:: Set the maximum task priority value 3229 * OMP_NESTED:: Nested parallel regions 3230 * OMP_NUM_TEAMS:: Specifies the number of teams to use by teams region 3231 * OMP_NUM_THREADS:: Specifies the number of threads to use 3232 * OMP_PROC_BIND:: Whether threads may be moved between CPUs 3233 * OMP_PLACES:: Specifies on which CPUs the threads should be placed 3234 * OMP_STACKSIZE:: Set default thread stack size 3235 * OMP_SCHEDULE:: How threads are scheduled 3236 * OMP_TARGET_OFFLOAD:: Controls offloading behavior 3237 * OMP_TEAMS_THREAD_LIMIT:: Set the maximum number of threads imposed by teams 3238 * OMP_THREAD_LIMIT:: Set the maximum number of threads 3239 * OMP_WAIT_POLICY:: How waiting threads are handled 3240 * GOMP_CPU_AFFINITY:: Bind threads to specific CPUs 3241 * GOMP_DEBUG:: Enable debugging output 3242 * GOMP_STACKSIZE:: Set default thread stack size 3243 * GOMP_SPINCOUNT:: Set the busy-wait spin count 3244 * GOMP_RTEMS_THREAD_POOLS:: Set the RTEMS specific thread pools 3245 3246 3247 File: libgomp.info, Node: OMP_ALLOCATOR, Next: OMP_AFFINITY_FORMAT, Up: Environment Variables 3248 3249 4.1 'OMP_ALLOCATOR' - Set the default allocator 3250 =============================================== 3251 3252 _ICV:_ DEF-ALLOCATOR-VAR 3253 _Scope:_ data environment 3254 _Description_: 3255 Sets the default allocator that is used when no allocator has been 3256 specified in the 'allocate' or 'allocator' clause or if an OpenMP 3257 memory routine is invoked with the 'omp_null_allocator' allocator. 3258 If unset, 'omp_default_mem_alloc' is used. 3259 3260 The value can either be a predefined allocator or a predefined 3261 memory space or a predefined memory space followed by a colon and a 3262 comma-separated list of memory trait and value pairs, separated by 3263 '='. 3264 3265 Note: The corresponding device environment variables are currently 3266 not supported. Therefore, the non-host DEF-ALLOCATOR-VAR ICVs are 3267 always initialized to 'omp_default_mem_alloc'. However, on all 3268 devices, the 'omp_set_default_allocator' API routine can be used to 3269 change value. 3270 3271 Predefined allocators Associated predefined memory 3272 spaces 3273 ------------------------------------------------------------------ 3274 omp_default_mem_alloc omp_default_mem_space 3275 omp_large_cap_mem_alloc omp_large_cap_mem_space 3276 omp_const_mem_alloc omp_const_mem_space 3277 omp_high_bw_mem_alloc omp_high_bw_mem_space 3278 omp_low_lat_mem_alloc omp_low_lat_mem_space 3279 omp_cgroup_mem_alloc omp_low_lat_mem_space 3280 (implementation defined) 3281 omp_pteam_mem_alloc omp_low_lat_mem_space 3282 (implementation defined) 3283 omp_thread_mem_alloc omp_low_lat_mem_space 3284 (implementation defined) 3285 3286 The predefined allocators use the default values for the traits, as 3287 listed below. Except that the last three allocators have the 3288 'access' trait set to 'cgroup', 'pteam', and 'thread', 3289 respectively. 3290 3291 Trait Allowed values Default value 3292 -------------------------------------------------------------------- 3293 'sync_hint' 'contended', 'uncontended', 'contended' 3294 'serialized', 'private' 3295 'alignment' Positive integer being a 1 byte 3296 power of two 3297 'access' 'all', 'cgroup', 'pteam', 'all' 3298 'thread' 3299 'pool_size' Positive integer See 3300 *note Memory allocation:: 3301 'fallback' 'default_mem_fb', See below 3302 'null_fb', 'abort_fb', 3303 'allocator_fb' 3304 'fb_data' _unsupported as it needs an (none) 3305 allocator handle_ 3306 'pinned' 'true', 'false' 'false' 3307 'partition' 'environment', 'nearest', 'environment' 3308 'blocked', 'interleaved' 3309 3310 For the 'fallback' trait, the default value is 'null_fb' for the 3311 'omp_default_mem_alloc' allocator and any allocator that is 3312 associated with device memory; for all other allocators, it is 3313 'default_mem_fb' by default. 3314 3315 Examples: 3316 OMP_ALLOCATOR=omp_high_bw_mem_alloc 3317 OMP_ALLOCATOR=omp_large_cap_mem_space 3318 OMP_ALLOCATOR=omp_low_lat_mem_space:pinned=true,partition=nearest 3319 3320 _See also_: 3321 *note Memory allocation::, *note omp_get_default_allocator::, *note 3322 omp_set_default_allocator::, *note Offload-Target Specifics:: 3323 3324 _Reference_: 3325 OpenMP specification v5.0 (https://www.openmp.org), Section 6.21 3326 3327 3328 File: libgomp.info, Node: OMP_AFFINITY_FORMAT, Next: OMP_CANCELLATION, Prev: OMP_ALLOCATOR, Up: Environment Variables 3329 3330 4.2 'OMP_AFFINITY_FORMAT' - Set the format string used for affinity display 3331 =========================================================================== 3332 3333 _ICV:_ AFFINITY-FORMAT-VAR 3334 _Scope:_ device 3335 _Description_: 3336 Sets the format string used when displaying OpenMP thread affinity 3337 information. Special values are output using '%' followed by an 3338 optional size specification and then either the single-character 3339 field type or its long name enclosed in curly braces; using '%%' 3340 displays a literal percent. The size specification consists of an 3341 optional '0.' or '.' followed by a positive integer, specifying the 3342 minimal width of the output. With '0.' and numerical values, the 3343 output is padded with zeros on the left; with '.', the output is 3344 padded by spaces on the left; otherwise, the output is padded by 3345 spaces on the right. If unset, the value is "'level %L thread %i 3346 affinity %A'". 3347 3348 Supported field types are: 3349 3350 t team_num value returned by 'omp_get_team_num' 3351 T num_teams value returned by 'omp_get_num_teams' 3352 L nesting_level value returned by 'omp_get_level' 3353 n thread_num value returned by 'omp_get_thread_num' 3354 N num_threads value returned by 'omp_get_num_threads' 3355 a ancestor_tnum value returned by 3356 'omp_get_ancestor_thread_num(omp_get_level()-1)' 3357 H host name of the host that executes the thread 3358 P process_id process identifier 3359 i native_thread_id native thread identifier 3360 A thread_affinity comma separated list of integer values or 3361 ranges, representing the processors on 3362 which a process might execute, subject to 3363 affinity mechanisms 3364 3365 For instance, after setting 3366 3367 OMP_AFFINITY_FORMAT="%0.2a!%n!%.4L!%N;%.2t;%0.2T;%{team_num};%{num_teams};%A" 3368 3369 with either 'OMP_DISPLAY_AFFINITY' being set or when calling 3370 'omp_display_affinity' with 'NULL' or an empty string, the program 3371 might display the following: 3372 3373 00!0! 1!4; 0;01;0;1;0-11 3374 00!3! 1!4; 0;01;0;1;0-11 3375 00!2! 1!4; 0;01;0;1;0-11 3376 00!1! 1!4; 0;01;0;1;0-11 3377 3378 _See also_: 3379 *note OMP_DISPLAY_AFFINITY:: 3380 3381 _Reference_: 3382 OpenMP specification v5.0 (https://www.openmp.org), Section 6.14 3383 3384 3385 File: libgomp.info, Node: OMP_CANCELLATION, Next: OMP_DISPLAY_AFFINITY, Prev: OMP_AFFINITY_FORMAT, Up: Environment Variables 3386 3387 4.3 'OMP_CANCELLATION' - Set whether cancellation is activated 3388 ============================================================== 3389 3390 _ICV:_ CANCEL-VAR 3391 _Scope:_ global 3392 _Description_: 3393 If set to 'TRUE', the cancellation is activated. If set to 'FALSE' 3394 or if unset, cancellation is disabled and the 'cancel' construct is 3395 ignored. 3396 3397 _See also_: 3398 *note omp_get_cancellation:: 3399 3400 _Reference_: 3401 OpenMP specification v4.5 (https://www.openmp.org), Section 4.11 3402 3403 3404 File: libgomp.info, Node: OMP_DISPLAY_AFFINITY, Next: OMP_DISPLAY_ENV, Prev: OMP_CANCELLATION, Up: Environment Variables 3405 3406 4.4 'OMP_DISPLAY_AFFINITY' - Display thread affinity information 3407 ================================================================ 3408 3409 _ICV:_ DISPLAY-AFFINITY-VAR 3410 _Scope:_ global 3411 _Description_: 3412 If set to 'FALSE' or if unset, affinity displaying is disabled. If 3413 set to 'TRUE', the runtime displays affinity information about 3414 OpenMP threads in a parallel region upon entering the region and 3415 every time any change occurs. 3416 3417 _See also_: 3418 *note OMP_AFFINITY_FORMAT:: 3419 3420 _Reference_: 3421 OpenMP specification v5.0 (https://www.openmp.org), Section 6.13 3422 3423 3424 File: libgomp.info, Node: OMP_DISPLAY_ENV, Next: OMP_DEFAULT_DEVICE, Prev: OMP_DISPLAY_AFFINITY, Up: Environment Variables 3425 3426 4.5 'OMP_DISPLAY_ENV' - Show OpenMP version and environment variables 3427 ===================================================================== 3428 3429 _ICV:_ none 3430 _Scope:_ not applicable 3431 _Description_: 3432 If set to 'TRUE', the runtime displays the same information to 3433 'stderr' as shown by the 'omp_display_env' routine invoked with 3434 VERBOSE argument set to 'false'. If set to 'VERBOSE', the same 3435 information is shown as invoking the routine with VERBOSE set to 3436 'true'. If unset or set to 'FALSE', this information is not shown. 3437 The result for any other value is unspecified. 3438 3439 _See also_: 3440 *note omp_display_env:: 3441 3442 _Reference_: 3443 OpenMP specification v4.5 (https://www.openmp.org), Section 4.12 3444 3445 3446 File: libgomp.info, Node: OMP_DEFAULT_DEVICE, Next: OMP_DYNAMIC, Prev: OMP_DISPLAY_ENV, Up: Environment Variables 3447 3448 4.6 'OMP_DEFAULT_DEVICE' - Set the device used in target regions 3449 ================================================================ 3450 3451 _ICV:_ DEFAULT-DEVICE-VAR 3452 _Scope:_ data environment 3453 _Description_: 3454 Set to choose the device which is used in a 'target' region, unless 3455 the value is overridden by 'omp_set_default_device' or by a 3456 'device' clause. The value shall be the nonnegative device number. 3457 If no device with the given device number exists, the code is 3458 executed on the host. If unset, 'OMP_TARGET_OFFLOAD' is 3459 'mandatory' and no non-host devices are available, it is set to 3460 'omp_invalid_device'. Otherwise, if unset, device number 0 is 3461 used. 3462 3463 _See also_: 3464 *note omp_get_default_device::, *note omp_set_default_device::, 3465 *note OMP_TARGET_OFFLOAD:: 3466 3467 _Reference_: 3468 OpenMP specification v5.2 (https://www.openmp.org), Section 21.2.7 3469 3470 3471 File: libgomp.info, Node: OMP_DYNAMIC, Next: OMP_MAX_ACTIVE_LEVELS, Prev: OMP_DEFAULT_DEVICE, Up: Environment Variables 3472 3473 4.7 'OMP_DYNAMIC' - Dynamic adjustment of threads 3474 ================================================= 3475 3476 _ICV:_ DYN-VAR 3477 _Scope:_ global 3478 _Description_: 3479 Enable or disable the dynamic adjustment of the number of threads 3480 within a team. The value of this environment variable shall be 3481 'TRUE' or 'FALSE'. If undefined, dynamic adjustment is disabled by 3482 default. 3483 3484 _See also_: 3485 *note omp_set_dynamic:: 3486 3487 _Reference_: 3488 OpenMP specification v4.5 (https://www.openmp.org), Section 4.3 3489 3490 3491 File: libgomp.info, Node: OMP_MAX_ACTIVE_LEVELS, Next: OMP_MAX_TASK_PRIORITY, Prev: OMP_DYNAMIC, Up: Environment Variables 3492 3493 4.8 'OMP_MAX_ACTIVE_LEVELS' - Set the maximum number of nested parallel regions 3494 =============================================================================== 3495 3496 _ICV:_ MAX-ACTIVE-LEVELS-VAR 3497 _Scope:_ data environment 3498 _Description_: 3499 Specifies the initial value for the maximum number of nested 3500 parallel regions. The value of this variable shall be a positive 3501 integer. If undefined, then if 'OMP_NESTED' is defined and set to 3502 true, or if 'OMP_NUM_THREADS' or 'OMP_PROC_BIND' are defined and 3503 set to a list with more than one item, the maximum number of nested 3504 parallel regions is initialized to the largest number supported, 3505 otherwise it is set to one. 3506 3507 _See also_: 3508 *note omp_set_max_active_levels::, *note OMP_NESTED::, *note 3509 OMP_PROC_BIND::, *note OMP_NUM_THREADS:: 3510 3511 _Reference_: 3512 OpenMP specification v4.5 (https://www.openmp.org), Section 4.9 3513 3514 3515 File: libgomp.info, Node: OMP_MAX_TASK_PRIORITY, Next: OMP_NESTED, Prev: OMP_MAX_ACTIVE_LEVELS, Up: Environment Variables 3516 3517 4.9 'OMP_MAX_TASK_PRIORITY' - Set the maximum priority 3518 ====================================================== 3519 3520 number that can be set for a task. 3521 _ICV:_ MAX-TASK-PRIORITY-VAR 3522 _Scope:_ global 3523 _Description_: 3524 Specifies the initial value for the maximum priority value that can 3525 be set for a task. The value of this variable shall be a 3526 non-negative integer, and zero is allowed. If undefined, the 3527 default priority is 0. 3528 3529 _See also_: 3530 *note omp_get_max_task_priority:: 3531 3532 _Reference_: 3533 OpenMP specification v4.5 (https://www.openmp.org), Section 4.14 3534 3535 3536 File: libgomp.info, Node: OMP_NESTED, Next: OMP_NUM_TEAMS, Prev: OMP_MAX_TASK_PRIORITY, Up: Environment Variables 3537 3538 4.10 'OMP_NESTED' - Nested parallel regions 3539 =========================================== 3540 3541 _ICV:_ MAX-ACTIVE-LEVELS-VAR 3542 _Scope:_ data environment 3543 _Description_: 3544 Enable or disable nested parallel regions, i.e., whether team 3545 members are allowed to create new teams. The value of this 3546 environment variable shall be 'TRUE' or 'FALSE'. If set to 'TRUE', 3547 the number of maximum active nested regions supported is by default 3548 set to the maximum supported, otherwise it is set to one. If 3549 'OMP_MAX_ACTIVE_LEVELS' is defined, its setting overrides this 3550 setting. If both are undefined, nested parallel regions are 3551 enabled if 'OMP_NUM_THREADS' or 'OMP_PROC_BINDS' are defined to a 3552 list with more than one item, otherwise they are disabled by 3553 default. 3554 3555 Note that the 'OMP_NESTED' environment variable was deprecated in 3556 the OpenMP specification 5.2 in favor of 'OMP_MAX_ACTIVE_LEVELS'. 3557 3558 _See also_: 3559 *note omp_set_max_active_levels::, *note omp_set_nested::, *note 3560 OMP_MAX_ACTIVE_LEVELS:: 3561 3562 _Reference_: 3563 OpenMP specification v4.5 (https://www.openmp.org), Section 4.6 3564 3565 3566 File: libgomp.info, Node: OMP_NUM_TEAMS, Next: OMP_NUM_THREADS, Prev: OMP_NESTED, Up: Environment Variables 3567 3568 4.11 'OMP_NUM_TEAMS' - Specifies the number of teams to use by teams region 3569 =========================================================================== 3570 3571 _ICV:_ NTEAMS-VAR 3572 _Scope:_ device 3573 _Description_: 3574 Specifies the upper bound for number of teams to use in teams 3575 regions without explicit 'num_teams' clause. The value of this 3576 variable shall be a positive integer. If undefined it defaults to 3577 0 which means implementation defined upper bound. 3578 3579 _See also_: 3580 *note omp_set_num_teams:: 3581 3582 _Reference_: 3583 OpenMP specification v5.1 (https://www.openmp.org), Section 6.23 3584 3585 3586 File: libgomp.info, Node: OMP_NUM_THREADS, Next: OMP_PROC_BIND, Prev: OMP_NUM_TEAMS, Up: Environment Variables 3587 3588 4.12 'OMP_NUM_THREADS' - Specifies the number of threads to use 3589 =============================================================== 3590 3591 _ICV:_ NTHREADS-VAR 3592 _Scope:_ data environment 3593 _Description_: 3594 Specifies the default number of threads to use in parallel regions. 3595 The value of this variable shall be a comma-separated list of 3596 positive integers; the value specifies the number of threads to use 3597 for the corresponding nested level. Specifying more than one item 3598 in the list automatically enables nesting by default. If undefined 3599 one thread per CPU is used. 3600 3601 When a list with more than value is specified, it also affects the 3602 MAX-ACTIVE-LEVELS-VAR ICV as described in *note 3603 OMP_MAX_ACTIVE_LEVELS::. 3604 3605 _See also_: 3606 *note omp_set_num_threads::, *note OMP_MAX_ACTIVE_LEVELS:: 3607 3608 _Reference_: 3609 OpenMP specification v4.5 (https://www.openmp.org), Section 4.2 3610 3611 3612 File: libgomp.info, Node: OMP_PROC_BIND, Next: OMP_PLACES, Prev: OMP_NUM_THREADS, Up: Environment Variables 3613 3614 4.13 'OMP_PROC_BIND' - Whether threads may be moved between CPUs 3615 ================================================================ 3616 3617 _ICV:_ BIND-VAR 3618 _Scope:_ data environment 3619 _Description_: 3620 Specifies whether threads may be moved between processors. If set 3621 to 'TRUE', OpenMP threads should not be moved; if set to 'FALSE' 3622 they may be moved. Alternatively, a comma separated list with the 3623 values 'PRIMARY', 'MASTER', 'CLOSE' and 'SPREAD' can be used to 3624 specify the thread affinity policy for the corresponding nesting 3625 level. With 'PRIMARY' and 'MASTER' the worker threads are in the 3626 same place partition as the primary thread. With 'CLOSE' those are 3627 kept close to the primary thread in contiguous place partitions. 3628 And with 'SPREAD' a sparse distribution across the place partitions 3629 is used. Specifying more than one item in the list automatically 3630 enables nesting by default. 3631 3632 When a list is specified, it also affects the MAX-ACTIVE-LEVELS-VAR 3633 ICV as described in *note OMP_MAX_ACTIVE_LEVELS::. 3634 3635 When undefined, 'OMP_PROC_BIND' defaults to 'TRUE' when 3636 'OMP_PLACES' or 'GOMP_CPU_AFFINITY' is set and 'FALSE' otherwise. 3637 3638 _See also_: 3639 *note omp_get_proc_bind::, *note GOMP_CPU_AFFINITY::, *note 3640 OMP_PLACES::, *note OMP_MAX_ACTIVE_LEVELS:: 3641 3642 _Reference_: 3643 OpenMP specification v4.5 (https://www.openmp.org), Section 4.4 3644 3645 3646 File: libgomp.info, Node: OMP_PLACES, Next: OMP_STACKSIZE, Prev: OMP_PROC_BIND, Up: Environment Variables 3647 3648 4.14 'OMP_PLACES' - Specifies on which CPUs the threads should be placed 3649 ======================================================================== 3650 3651 _ICV:_ PLACE-PARTITION-VAR 3652 _Scope:_ implicit tasks 3653 _Description_: 3654 The thread placement can be either specified using an abstract name 3655 or by an explicit list of the places. The abstract names 3656 'threads', 'cores', 'sockets', 'll_caches' and 'numa_domains' can 3657 be optionally followed by a positive number in parentheses, which 3658 denotes the how many places shall be created. With 'threads' each 3659 place corresponds to a single hardware thread; 'cores' to a single 3660 core with the corresponding number of hardware threads; with 3661 'sockets' the place corresponds to a single socket; with 3662 'll_caches' to a set of cores that shares the last level cache on 3663 the device; and 'numa_domains' to a set of cores for which their 3664 closest memory on the device is the same memory and at a similar 3665 distance from the cores. The resulting placement can be shown by 3666 setting the 'OMP_DISPLAY_ENV' environment variable. 3667 3668 Alternatively, the placement can be specified explicitly as 3669 comma-separated list of places. A place is specified by set of 3670 nonnegative numbers in curly braces, denoting the hardware threads. 3671 The curly braces can be omitted when only a single number has been 3672 specified. The hardware threads belonging to a place can either be 3673 specified as comma-separated list of nonnegative thread numbers or 3674 using an interval. Multiple places can also be either specified by 3675 a comma-separated list of places or by an interval. To specify an 3676 interval, a colon followed by the count is placed after the 3677 hardware thread number or the place. Optionally, the length can be 3678 followed by a colon and the stride number - otherwise a unit stride 3679 is assumed. Placing an exclamation mark ('!') directly before a 3680 curly brace or numbers inside the curly braces (excluding 3681 intervals) excludes those hardware threads. 3682 3683 For instance, the following specifies the same places list: 3684 '"{0,1,2}, {3,4,6}, {7,8,9}, {10,11,12}"'; '"{0:3}, {3:3}, {7:3}, 3685 {10:3}"'; and '"{0:2}:4:3"'. 3686 3687 If 'OMP_PLACES' and 'GOMP_CPU_AFFINITY' are unset and 3688 'OMP_PROC_BIND' is either unset or 'false', threads may be moved 3689 between CPUs following no placement policy. 3690 3691 _See also_: 3692 *note OMP_PROC_BIND::, *note GOMP_CPU_AFFINITY::, *note 3693 omp_get_proc_bind::, *note OMP_DISPLAY_ENV:: 3694 3695 _Reference_: 3696 OpenMP specification v4.5 (https://www.openmp.org), Section 4.5 3697 3698 3699 File: libgomp.info, Node: OMP_STACKSIZE, Next: OMP_SCHEDULE, Prev: OMP_PLACES, Up: Environment Variables 3700 3701 4.15 'OMP_STACKSIZE' - Set default thread stack size 3702 ==================================================== 3703 3704 _ICV:_ STACKSIZE-VAR 3705 _Scope:_ device 3706 _Description_: 3707 Set the default thread stack size in kilobytes, unless the number 3708 is suffixed by 'B', 'K', 'M' or 'G', in which case the size is, 3709 respectively, in bytes, kilobytes, megabytes or gigabytes. This is 3710 different from 'pthread_attr_setstacksize' which gets the number of 3711 bytes as an argument. If the stack size cannot be set due to 3712 system constraints, an error is reported and the initial stack size 3713 is left unchanged. If undefined, the stack size is system 3714 dependent. 3715 3716 _See also_: 3717 *note GOMP_STACKSIZE:: 3718 3719 _Reference_: 3720 OpenMP specification v4.5 (https://www.openmp.org), Section 4.7 3721 3722 3723 File: libgomp.info, Node: OMP_SCHEDULE, Next: OMP_TARGET_OFFLOAD, Prev: OMP_STACKSIZE, Up: Environment Variables 3724 3725 4.16 'OMP_SCHEDULE' - How threads are scheduled 3726 =============================================== 3727 3728 _ICV:_ RUN-SCHED-VAR 3729 _Scope:_ data environment 3730 _Description_: 3731 Allows to specify 'schedule type' and 'chunk size'. The value of 3732 the variable shall have the form: 'type[,chunk]' where 'type' is 3733 one of 'static', 'dynamic', 'guided' or 'auto' The optional 'chunk' 3734 size shall be a positive integer. If undefined, dynamic scheduling 3735 and a chunk size of 1 is used. 3736 3737 _See also_: 3738 *note omp_set_schedule:: 3739 3740 _Reference_: 3741 OpenMP specification v4.5 (https://www.openmp.org), Sections 3742 2.7.1.1 and 4.1 3743 3744 3745 File: libgomp.info, Node: OMP_TARGET_OFFLOAD, Next: OMP_TEAMS_THREAD_LIMIT, Prev: OMP_SCHEDULE, Up: Environment Variables 3746 3747 4.17 'OMP_TARGET_OFFLOAD' - Controls offloading behavior 3748 ======================================================== 3749 3750 _ICV:_ TARGET-OFFLOAD-VAR 3751 _Scope:_ global 3752 _Description_: 3753 Specifies the behavior with regard to offloading code to a device. 3754 This variable can be set to one of three values - 'MANDATORY', 3755 'DISABLED' or 'DEFAULT'. 3756 3757 If set to 'MANDATORY', the program terminates with an error if any 3758 device construct or device memory routine uses a device that is 3759 unavailable or not supported by the implementation, or uses a 3760 non-conforming device number. If set to 'DISABLED', then 3761 offloading is disabled and all code runs on the host. If set to 3762 'DEFAULT', the program tries offloading to the device first, then 3763 falls back to running code on the host if it cannot. 3764 3765 If undefined, then the program behaves as if 'DEFAULT' was set. 3766 3767 Note: Even with 'MANDATORY', no run-time termination is performed 3768 when the device number in a 'device' clause or argument to a device 3769 memory routine is for host, which includes using the device number 3770 in the DEFAULT-DEVICE-VAR ICV. However, the initial value of the 3771 DEFAULT-DEVICE-VAR ICV is affected by 'MANDATORY'. 3772 3773 _See also_: 3774 *note OMP_DEFAULT_DEVICE:: 3775 3776 _Reference_: 3777 OpenMP specification v5.2 (https://www.openmp.org), Section 21.2.8 3778 3779 3780 File: libgomp.info, Node: OMP_TEAMS_THREAD_LIMIT, Next: OMP_THREAD_LIMIT, Prev: OMP_TARGET_OFFLOAD, Up: Environment Variables 3781 3782 4.18 'OMP_TEAMS_THREAD_LIMIT' - Set the maximum number of threads imposed by teams 3783 ================================================================================== 3784 3785 _ICV:_ TEAMS-THREAD-LIMIT-VAR 3786 _Scope:_ device 3787 _Description_: 3788 Specifies an upper bound for the number of threads to use by each 3789 contention group created by a teams construct without explicit 3790 'thread_limit' clause. The value of this variable shall be a 3791 positive integer. If undefined, the value of 0 is used which 3792 stands for an implementation defined upper limit. 3793 3794 _See also_: 3795 *note OMP_THREAD_LIMIT::, *note omp_set_teams_thread_limit:: 3796 3797 _Reference_: 3798 OpenMP specification v5.1 (https://www.openmp.org), Section 6.24 3799 3800 3801 File: libgomp.info, Node: OMP_THREAD_LIMIT, Next: OMP_WAIT_POLICY, Prev: OMP_TEAMS_THREAD_LIMIT, Up: Environment Variables 3802 3803 4.19 'OMP_THREAD_LIMIT' - Set the maximum number of threads 3804 =========================================================== 3805 3806 _ICV:_ THREAD-LIMIT-VAR 3807 _Scope:_ data environment 3808 _Description_: 3809 Specifies the number of threads to use for the whole program. The 3810 value of this variable shall be a positive integer. If undefined, 3811 the number of threads is not limited. 3812 3813 _See also_: 3814 *note OMP_NUM_THREADS::, *note omp_get_thread_limit:: 3815 3816 _Reference_: 3817 OpenMP specification v4.5 (https://www.openmp.org), Section 4.10 3818 3819 3820 File: libgomp.info, Node: OMP_WAIT_POLICY, Next: GOMP_CPU_AFFINITY, Prev: OMP_THREAD_LIMIT, Up: Environment Variables 3821 3822 4.20 'OMP_WAIT_POLICY' - How waiting threads are handled 3823 ======================================================== 3824 3825 _Description_: 3826 Specifies whether waiting threads should be active or passive. If 3827 the value is 'PASSIVE', waiting threads should not consume CPU 3828 power while waiting; while the value is 'ACTIVE' specifies that 3829 they should. If undefined, threads wait actively for a short time 3830 before waiting passively. 3831 3832 _See also_: 3833 *note GOMP_SPINCOUNT:: 3834 3835 _Reference_: 3836 OpenMP specification v4.5 (https://www.openmp.org), Section 4.8 3837 3838 3839 File: libgomp.info, Node: GOMP_CPU_AFFINITY, Next: GOMP_DEBUG, Prev: OMP_WAIT_POLICY, Up: Environment Variables 3840 3841 4.21 'GOMP_CPU_AFFINITY' - Bind threads to specific CPUs 3842 ======================================================== 3843 3844 _Description_: 3845 Binds threads to specific CPUs. The variable should contain a 3846 space-separated or comma-separated list of CPUs. This list may 3847 contain different kinds of entries: either single CPU numbers in 3848 any order, a range of CPUs (M-N) or a range with some stride 3849 (M-N:S). CPU numbers are zero based. For example, 3850 'GOMP_CPU_AFFINITY="0 3 1-2 4-15:2"' binds the initial thread to 3851 CPU 0, the second to CPU 3, the third to CPU 1, the fourth to CPU 3852 2, the fifth to CPU 4, the sixth through tenth to CPUs 6, 8, 10, 3853 12, and 14 respectively and then starts assigning back from the 3854 beginning of the list. 'GOMP_CPU_AFFINITY=0' binds all threads to 3855 CPU 0. 3856 3857 There is no libgomp library routine to determine whether a CPU 3858 affinity specification is in effect. As a workaround, 3859 language-specific library functions, e.g., 'getenv' in C or 3860 'GET_ENVIRONMENT_VARIABLE' in Fortran, may be used to query the 3861 setting of the 'GOMP_CPU_AFFINITY' environment variable. A defined 3862 CPU affinity on startup cannot be changed or disabled during the 3863 runtime of the application. 3864 3865 If both 'GOMP_CPU_AFFINITY' and 'OMP_PROC_BIND' are set, 3866 'OMP_PROC_BIND' has a higher precedence. If neither has been set 3867 and 'OMP_PROC_BIND' is unset, or when 'OMP_PROC_BIND' is set to 3868 'FALSE', the host system handles the assignment of threads to CPUs. 3869 3870 _See also_: 3871 *note OMP_PLACES::, *note OMP_PROC_BIND:: 3872 3873 3874 File: libgomp.info, Node: GOMP_DEBUG, Next: GOMP_STACKSIZE, Prev: GOMP_CPU_AFFINITY, Up: Environment Variables 3875 3876 4.22 'GOMP_DEBUG' - Enable debugging output 3877 =========================================== 3878 3879 _Description_: 3880 Enable debugging output. The variable should be set to '0' 3881 (disabled, also the default if not set), or '1' (enabled). 3882 3883 If enabled, some debugging output is printed during execution. 3884 This is currently not specified in more detail, and subject to 3885 change. 3886 3887 3888 File: libgomp.info, Node: GOMP_STACKSIZE, Next: GOMP_SPINCOUNT, Prev: GOMP_DEBUG, Up: Environment Variables 3889 3890 4.23 'GOMP_STACKSIZE' - Set default thread stack size 3891 ===================================================== 3892 3893 _Description_: 3894 Set the default thread stack size in kilobytes. This is different 3895 from 'pthread_attr_setstacksize' which gets the number of bytes as 3896 an argument. If the stack size cannot be set due to system 3897 constraints, an error is reported and the initial stack size is 3898 left unchanged. If undefined, the stack size is system dependent. 3899 3900 _See also_: 3901 *note OMP_STACKSIZE:: 3902 3903 _Reference_: 3904 GCC Patches Mailinglist 3905 (https://gcc.gnu.org/ml/gcc-patches/2006-06/msg00493.html), GCC 3906 Patches Mailinglist 3907 (https://gcc.gnu.org/ml/gcc-patches/2006-06/msg00496.html) 3908 3909 3910 File: libgomp.info, Node: GOMP_SPINCOUNT, Next: GOMP_RTEMS_THREAD_POOLS, Prev: GOMP_STACKSIZE, Up: Environment Variables 3911 3912 4.24 'GOMP_SPINCOUNT' - Set the busy-wait spin count 3913 ==================================================== 3914 3915 _Description_: 3916 Determines how long a threads waits actively with consuming CPU 3917 power before waiting passively without consuming CPU power. The 3918 value may be either 'INFINITE', 'INFINITY' to always wait actively 3919 or an integer which gives the number of spins of the busy-wait 3920 loop. The integer may optionally be followed by the following 3921 suffixes acting as multiplication factors: 'k' (kilo, thousand), 3922 'M' (mega, million), 'G' (giga, billion), or 'T' (tera, trillion). 3923 If undefined, 0 is used when 'OMP_WAIT_POLICY' is 'PASSIVE', 3924 300,000 is used when 'OMP_WAIT_POLICY' is undefined and 30 billion 3925 is used when 'OMP_WAIT_POLICY' is 'ACTIVE'. If there are more 3926 OpenMP threads than available CPUs, 1000 and 100 spins are used for 3927 'OMP_WAIT_POLICY' being 'ACTIVE' or undefined, respectively; unless 3928 the 'GOMP_SPINCOUNT' is lower or 'OMP_WAIT_POLICY' is 'PASSIVE'. 3929 3930 _See also_: 3931 *note OMP_WAIT_POLICY:: 3932 3933 3934 File: libgomp.info, Node: GOMP_RTEMS_THREAD_POOLS, Prev: GOMP_SPINCOUNT, Up: Environment Variables 3935 3936 4.25 'GOMP_RTEMS_THREAD_POOLS' - Set the RTEMS specific thread pools 3937 ==================================================================== 3938 3939 _Description_: 3940 This environment variable is only used on the RTEMS real-time 3941 operating system. It determines the scheduler instance specific 3942 thread pools. The format for 'GOMP_RTEMS_THREAD_POOLS' is a list 3943 of optional '<thread-pool-count>[$<priority>]@<scheduler-name>' 3944 configurations separated by ':' where: 3945 * '<thread-pool-count>' is the thread pool count for this 3946 scheduler instance. 3947 * '$<priority>' is an optional priority for the worker threads 3948 of a thread pool according to 'pthread_setschedparam'. In 3949 case a priority value is omitted, then a worker thread 3950 inherits the priority of the OpenMP primary thread that 3951 created it. The priority of the worker thread is not changed 3952 after creation, even if a new OpenMP primary thread using the 3953 worker has a different priority. 3954 * '@<scheduler-name>' is the scheduler instance name according 3955 to the RTEMS application configuration. 3956 In case no thread pool configuration is specified for a scheduler 3957 instance, then each OpenMP primary thread of this scheduler 3958 instance uses its own dynamically allocated thread pool. To limit 3959 the worker thread count of the thread pools, each OpenMP primary 3960 thread must call 'omp_set_num_threads'. 3961 _Example_: 3962 Lets suppose we have three scheduler instances 'IO', 'WRK0', and 3963 'WRK1' with 'GOMP_RTEMS_THREAD_POOLS' set to '"1@WRK0:3$4@WRK1"'. 3964 Then there are no thread pool restrictions for scheduler instance 3965 'IO'. In the scheduler instance 'WRK0' there is one thread pool 3966 available. Since no priority is specified for this scheduler 3967 instance, the worker thread inherits the priority of the OpenMP 3968 primary thread that created it. In the scheduler instance 'WRK1' 3969 there are three thread pools available and their worker threads run 3970 at priority four. 3971 3972 3973 File: libgomp.info, Node: Enabling OpenACC, Next: OpenACC Runtime Library Routines, Prev: Environment Variables, Up: Top 3974 3975 5 Enabling OpenACC 3976 ****************** 3977 3978 To activate the OpenACC extensions for C/C++ and Fortran, the 3979 compile-time flag '-fopenacc' must be specified. This enables the 3980 OpenACC directive '#pragma acc' in C/C++ and, in Fortran, the '!$acc' 3981 sentinel in free source form and the 'c$acc', '*$acc' and '!$acc' 3982 sentinels in fixed source form. The flag also arranges for automatic 3983 linking of the OpenACC runtime library (*note OpenACC Runtime Library 3984 Routines::). 3985 3986 See <https://gcc.gnu.org/wiki/OpenACC> for more information. 3987 3988 A complete description of all OpenACC directives accepted may be 3989 found in the OpenACC (https://www.openacc.org) Application Programming 3990 Interface manual, version 2.6. 3991 3992 3993 File: libgomp.info, Node: OpenACC Runtime Library Routines, Next: OpenACC Environment Variables, Prev: Enabling OpenACC, Up: Top 3994 3995 6 OpenACC Runtime Library Routines 3996 ********************************** 3997 3998 The runtime routines described here are defined by section 3 of the 3999 OpenACC specifications in version 2.6. They have C linkage, and do not 4000 throw exceptions. Generally, they are available only for the host, with 4001 the exception of 'acc_on_device', which is available for both the host 4002 and the acceleration device. 4003 4004 * Menu: 4005 4006 * acc_get_num_devices:: Get number of devices for the given device 4007 type. 4008 * acc_set_device_type:: Set type of device accelerator to use. 4009 * acc_get_device_type:: Get type of device accelerator to be used. 4010 * acc_set_device_num:: Set device number to use. 4011 * acc_get_device_num:: Get device number to be used. 4012 * acc_get_property:: Get device property. 4013 * acc_async_test:: Tests for completion of a specific asynchronous 4014 operation. 4015 * acc_async_test_all:: Tests for completion of all asynchronous 4016 operations. 4017 * acc_wait:: Wait for completion of a specific asynchronous 4018 operation. 4019 * acc_wait_all:: Waits for completion of all asynchronous 4020 operations. 4021 * acc_wait_all_async:: Wait for completion of all asynchronous 4022 operations. 4023 * acc_wait_async:: Wait for completion of asynchronous operations. 4024 * acc_init:: Initialize runtime for a specific device type. 4025 * acc_shutdown:: Shuts down the runtime for a specific device 4026 type. 4027 * acc_on_device:: Whether executing on a particular device 4028 * acc_malloc:: Allocate device memory. 4029 * acc_free:: Free device memory. 4030 * acc_copyin:: Allocate device memory and copy host memory to 4031 it. 4032 * acc_present_or_copyin:: If the data is not present on the device, 4033 allocate device memory and copy from host 4034 memory. 4035 * acc_create:: Allocate device memory and map it to host 4036 memory. 4037 * acc_present_or_create:: If the data is not present on the device, 4038 allocate device memory and map it to host 4039 memory. 4040 * acc_copyout:: Copy device memory to host memory. 4041 * acc_delete:: Free device memory. 4042 * acc_update_device:: Update device memory from mapped host memory. 4043 * acc_update_self:: Update host memory from mapped device memory. 4044 * acc_map_data:: Map previously allocated device memory to host 4045 memory. 4046 * acc_unmap_data:: Unmap device memory from host memory. 4047 * acc_deviceptr:: Get device pointer associated with specific 4048 host address. 4049 * acc_hostptr:: Get host pointer associated with specific 4050 device address. 4051 * acc_is_present:: Indicate whether host variable / array is 4052 present on device. 4053 * acc_memcpy_to_device:: Copy host memory to device memory. 4054 * acc_memcpy_from_device:: Copy device memory to host memory. 4055 * acc_attach:: Let device pointer point to device-pointer target. 4056 * acc_detach:: Let device pointer point to host-pointer target. 4057 4058 API routines for target platforms. 4059 4060 * acc_get_current_cuda_device:: Get CUDA device handle. 4061 * acc_get_current_cuda_context::Get CUDA context handle. 4062 * acc_get_cuda_stream:: Get CUDA stream handle. 4063 * acc_set_cuda_stream:: Set CUDA stream handle. 4064 4065 API routines for the OpenACC Profiling Interface. 4066 4067 * acc_prof_register:: Register callbacks. 4068 * acc_prof_unregister:: Unregister callbacks. 4069 * acc_prof_lookup:: Obtain inquiry functions. 4070 * acc_register_library:: Library registration. 4071 4072 4073 File: libgomp.info, Node: acc_get_num_devices, Next: acc_set_device_type, Up: OpenACC Runtime Library Routines 4074 4075 6.1 'acc_get_num_devices' - Get number of devices for given device type 4076 ======================================================================= 4077 4078 _Description_ 4079 This function returns a value indicating the number of devices 4080 available for the device type specified in DEVICETYPE. 4081 4082 _C/C++_: 4083 _Prototype_: 'int acc_get_num_devices(acc_device_t devicetype);' 4084 4085 _Fortran_: 4086 _Interface_: 'integer function acc_get_num_devices(devicetype)' 4087 'integer(kind=acc_device_kind) devicetype' 4088 4089 _Reference_: 4090 OpenACC specification v2.6 (https://www.openacc.org), section 4091 3.2.1. 4092 4093 4094 File: libgomp.info, Node: acc_set_device_type, Next: acc_get_device_type, Prev: acc_get_num_devices, Up: OpenACC Runtime Library Routines 4095 4096 6.2 'acc_set_device_type' - Set type of device accelerator to use. 4097 ================================================================== 4098 4099 _Description_ 4100 This function indicates to the runtime library which device type, 4101 specified in DEVICETYPE, to use when executing a parallel or 4102 kernels region. 4103 4104 _C/C++_: 4105 _Prototype_: 'acc_set_device_type(acc_device_t devicetype);' 4106 4107 _Fortran_: 4108 _Interface_: 'subroutine acc_set_device_type(devicetype)' 4109 'integer(kind=acc_device_kind) devicetype' 4110 4111 _Reference_: 4112 OpenACC specification v2.6 (https://www.openacc.org), section 4113 3.2.2. 4114 4115 4116 File: libgomp.info, Node: acc_get_device_type, Next: acc_set_device_num, Prev: acc_set_device_type, Up: OpenACC Runtime Library Routines 4117 4118 6.3 'acc_get_device_type' - Get type of device accelerator to be used. 4119 ====================================================================== 4120 4121 _Description_ 4122 This function returns what device type will be used when executing 4123 a parallel or kernels region. 4124 4125 This function returns 'acc_device_none' if 'acc_get_device_type' is 4126 called from 'acc_ev_device_init_start', 'acc_ev_device_init_end' 4127 callbacks of the OpenACC Profiling Interface (*note OpenACC 4128 Profiling Interface::), that is, if the device is currently being 4129 initialized. 4130 4131 _C/C++_: 4132 _Prototype_: 'acc_device_t acc_get_device_type(void);' 4133 4134 _Fortran_: 4135 _Interface_: 'function acc_get_device_type(void)' 4136 'integer(kind=acc_device_kind) acc_get_device_type' 4137 4138 _Reference_: 4139 OpenACC specification v2.6 (https://www.openacc.org), section 4140 3.2.3. 4141 4142 4143 File: libgomp.info, Node: acc_set_device_num, Next: acc_get_device_num, Prev: acc_get_device_type, Up: OpenACC Runtime Library Routines 4144 4145 6.4 'acc_set_device_num' - Set device number to use. 4146 ==================================================== 4147 4148 _Description_ 4149 This function will indicate to the runtime which device number, 4150 specified by DEVICENUM, associated with the specified device type 4151 DEVICETYPE. 4152 4153 _C/C++_: 4154 _Prototype_: 'acc_set_device_num(int devicenum, acc_device_t 4155 devicetype);' 4156 4157 _Fortran_: 4158 _Interface_: 'subroutine acc_set_device_num(devicenum, devicetype)' 4159 'integer devicenum' 4160 'integer(kind=acc_device_kind) devicetype' 4161 4162 _Reference_: 4163 OpenACC specification v2.6 (https://www.openacc.org), section 4164 3.2.4. 4165 4166 4167 File: libgomp.info, Node: acc_get_device_num, Next: acc_get_property, Prev: acc_set_device_num, Up: OpenACC Runtime Library Routines 4168 4169 6.5 'acc_get_device_num' - Get device number to be used. 4170 ======================================================== 4171 4172 _Description_ 4173 This function returns which device number associated with the 4174 specified device type DEVICETYPE, will be used when executing a 4175 parallel or kernels region. 4176 4177 _C/C++_: 4178 _Prototype_: 'int acc_get_device_num(acc_device_t devicetype);' 4179 4180 _Fortran_: 4181 _Interface_: 'function acc_get_device_num(devicetype)' 4182 'integer(kind=acc_device_kind) devicetype' 4183 'integer acc_get_device_num' 4184 4185 _Reference_: 4186 OpenACC specification v2.6 (https://www.openacc.org), section 4187 3.2.5. 4188 4189 4190 File: libgomp.info, Node: acc_get_property, Next: acc_async_test, Prev: acc_get_device_num, Up: OpenACC Runtime Library Routines 4191 4192 6.6 'acc_get_property' - Get device property. 4193 ============================================= 4194 4195 _Description_ 4196 These routines return the value of the specified PROPERTY for the 4197 device being queried according to DEVICENUM and DEVICETYPE. 4198 Integer-valued and string-valued properties are returned by 4199 'acc_get_property' and 'acc_get_property_string' respectively. The 4200 Fortran 'acc_get_property_string' subroutine returns the string 4201 retrieved in its fourth argument while the remaining entry points 4202 are functions, which pass the return value as their result. 4203 4204 Note for Fortran, only: the OpenACC technical committee corrected 4205 and, hence, modified the interface introduced in OpenACC 2.6. The 4206 kind-value parameter 'acc_device_property' has been renamed to 4207 'acc_device_property_kind' for consistency and the return type of 4208 the 'acc_get_property' function is now a 'c_size_t' integer instead 4209 of a 'acc_device_property' integer. The parameter 4210 'acc_device_property' is still provided, but might be removed in a 4211 future version of GCC. 4212 4213 _C/C++_: 4214 _Prototype_: 'size_t acc_get_property(int devicenum, acc_device_t 4215 devicetype, acc_device_property_t property);' 4216 _Prototype_: 'const char *acc_get_property_string(int devicenum, 4217 acc_device_t devicetype, acc_device_property_t 4218 property);' 4219 4220 _Fortran_: 4221 _Interface_: 'function acc_get_property(devicenum, devicetype, 4222 property)' 4223 _Interface_: 'subroutine acc_get_property_string(devicenum, 4224 devicetype, property, string)' 4225 'use ISO_C_Binding, only: c_size_t' 4226 'integer devicenum' 4227 'integer(kind=acc_device_kind) devicetype' 4228 'integer(kind=acc_device_property_kind) property' 4229 'integer(kind=c_size_t) acc_get_property' 4230 'character(*) string' 4231 4232 _Reference_: 4233 OpenACC specification v2.6 (https://www.openacc.org), section 4234 3.2.6. 4235 4236 4237 File: libgomp.info, Node: acc_async_test, Next: acc_async_test_all, Prev: acc_get_property, Up: OpenACC Runtime Library Routines 4238 4239 6.7 'acc_async_test' - Test for completion of a specific asynchronous operation. 4240 ================================================================================ 4241 4242 _Description_ 4243 This function tests for completion of the asynchronous operation 4244 specified in ARG. In C/C++, a non-zero value is returned to 4245 indicate the specified asynchronous operation has completed while 4246 Fortran returns 'true'. If the asynchronous operation has not 4247 completed, C/C++ returns zero and Fortran returns 'false'. 4248 4249 _C/C++_: 4250 _Prototype_: 'int acc_async_test(int arg);' 4251 4252 _Fortran_: 4253 _Interface_: 'function acc_async_test(arg)' 4254 'integer(kind=acc_handle_kind) arg' 4255 'logical acc_async_test' 4256 4257 _Reference_: 4258 OpenACC specification v2.6 (https://www.openacc.org), section 4259 3.2.9. 4260 4261 4262 File: libgomp.info, Node: acc_async_test_all, Next: acc_wait, Prev: acc_async_test, Up: OpenACC Runtime Library Routines 4263 4264 6.8 'acc_async_test_all' - Tests for completion of all asynchronous operations. 4265 =============================================================================== 4266 4267 _Description_ 4268 This function tests for completion of all asynchronous operations. 4269 In C/C++, a non-zero value is returned to indicate all asynchronous 4270 operations have completed while Fortran returns 'true'. If any 4271 asynchronous operation has not completed, C/C++ returns zero and 4272 Fortran returns 'false'. 4273 4274 _C/C++_: 4275 _Prototype_: 'int acc_async_test_all(void);' 4276 4277 _Fortran_: 4278 _Interface_: 'function acc_async_test()' 4279 'logical acc_get_device_num' 4280 4281 _Reference_: 4282 OpenACC specification v2.6 (https://www.openacc.org), section 4283 3.2.10. 4284 4285 4286 File: libgomp.info, Node: acc_wait, Next: acc_wait_all, Prev: acc_async_test_all, Up: OpenACC Runtime Library Routines 4287 4288 6.9 'acc_wait' - Wait for completion of a specific asynchronous operation. 4289 ========================================================================== 4290 4291 _Description_ 4292 This function waits for completion of the asynchronous operation 4293 specified in ARG. 4294 4295 _C/C++_: 4296 _Prototype_: 'acc_wait(arg);' 4297 _Prototype 'acc_async_wait(arg);' 4298 (OpenACC 1.0 4299 compatibility)_: 4300 4301 _Fortran_: 4302 _Interface_: 'subroutine acc_wait(arg)' 4303 'integer(acc_handle_kind) arg' 4304 _Interface 'subroutine acc_async_wait(arg)' 4305 (OpenACC 1.0 4306 compatibility)_: 4307 'integer(acc_handle_kind) arg' 4308 4309 _Reference_: 4310 OpenACC specification v2.6 (https://www.openacc.org), section 4311 3.2.11. 4312 4313 4314 File: libgomp.info, Node: acc_wait_all, Next: acc_wait_all_async, Prev: acc_wait, Up: OpenACC Runtime Library Routines 4315 4316 6.10 'acc_wait_all' - Waits for completion of all asynchronous operations. 4317 ========================================================================== 4318 4319 _Description_ 4320 This function waits for the completion of all asynchronous 4321 operations. 4322 4323 _C/C++_: 4324 _Prototype_: 'acc_wait_all(void);' 4325 _Prototype 'acc_async_wait_all(void);' 4326 (OpenACC 1.0 4327 compatibility)_: 4328 4329 _Fortran_: 4330 _Interface_: 'subroutine acc_wait_all()' 4331 _Interface 'subroutine acc_async_wait_all()' 4332 (OpenACC 1.0 4333 compatibility)_: 4334 4335 _Reference_: 4336 OpenACC specification v2.6 (https://www.openacc.org), section 4337 3.2.13. 4338 4339 4340 File: libgomp.info, Node: acc_wait_all_async, Next: acc_wait_async, Prev: acc_wait_all, Up: OpenACC Runtime Library Routines 4341 4342 6.11 'acc_wait_all_async' - Wait for completion of all asynchronous operations. 4343 =============================================================================== 4344 4345 _Description_ 4346 This function enqueues a wait operation on the queue ASYNC for any 4347 and all asynchronous operations that have been previously enqueued 4348 on any queue. 4349 4350 _C/C++_: 4351 _Prototype_: 'acc_wait_all_async(int async);' 4352 4353 _Fortran_: 4354 _Interface_: 'subroutine acc_wait_all_async(async)' 4355 'integer(acc_handle_kind) async' 4356 4357 _Reference_: 4358 OpenACC specification v2.6 (https://www.openacc.org), section 4359 3.2.14. 4360 4361 4362 File: libgomp.info, Node: acc_wait_async, Next: acc_init, Prev: acc_wait_all_async, Up: OpenACC Runtime Library Routines 4363 4364 6.12 'acc_wait_async' - Wait for completion of asynchronous operations. 4365 ======================================================================= 4366 4367 _Description_ 4368 This function enqueues a wait operation on queue ASYNC for any and 4369 all asynchronous operations enqueued on queue ARG. 4370 4371 _C/C++_: 4372 _Prototype_: 'acc_wait_async(int arg, int async);' 4373 4374 _Fortran_: 4375 _Interface_: 'subroutine acc_wait_async(arg, async)' 4376 'integer(acc_handle_kind) arg, async' 4377 4378 _Reference_: 4379 OpenACC specification v2.6 (https://www.openacc.org), section 4380 3.2.12. 4381 4382 4383 File: libgomp.info, Node: acc_init, Next: acc_shutdown, Prev: acc_wait_async, Up: OpenACC Runtime Library Routines 4384 4385 6.13 'acc_init' - Initialize runtime for a specific device type. 4386 ================================================================ 4387 4388 _Description_ 4389 This function initializes the runtime for the device type specified 4390 in DEVICETYPE. 4391 4392 _C/C++_: 4393 _Prototype_: 'acc_init(acc_device_t devicetype);' 4394 4395 _Fortran_: 4396 _Interface_: 'subroutine acc_init(devicetype)' 4397 'integer(acc_device_kind) devicetype' 4398 4399 _Reference_: 4400 OpenACC specification v2.6 (https://www.openacc.org), section 4401 3.2.7. 4402 4403 4404 File: libgomp.info, Node: acc_shutdown, Next: acc_on_device, Prev: acc_init, Up: OpenACC Runtime Library Routines 4405 4406 6.14 'acc_shutdown' - Shuts down the runtime for a specific device type. 4407 ======================================================================== 4408 4409 _Description_ 4410 This function shuts down the runtime for the device type specified 4411 in DEVICETYPE. 4412 4413 _C/C++_: 4414 _Prototype_: 'acc_shutdown(acc_device_t devicetype);' 4415 4416 _Fortran_: 4417 _Interface_: 'subroutine acc_shutdown(devicetype)' 4418 'integer(acc_device_kind) devicetype' 4419 4420 _Reference_: 4421 OpenACC specification v2.6 (https://www.openacc.org), section 4422 3.2.8. 4423 4424 4425 File: libgomp.info, Node: acc_on_device, Next: acc_malloc, Prev: acc_shutdown, Up: OpenACC Runtime Library Routines 4426 4427 6.15 'acc_on_device' - Whether executing on a particular device 4428 =============================================================== 4429 4430 _Description_: 4431 This function returns whether the program is executing on a 4432 particular device specified in DEVICETYPE. In C/C++ a non-zero 4433 value is returned to indicate the device is executing on the 4434 specified device type. In Fortran, 'true' is returned. If the 4435 program is not executing on the specified device type C/C++ returns 4436 zero, while Fortran returns 'false'. 4437 4438 _C/C++_: 4439 _Prototype_: 'acc_on_device(acc_device_t devicetype);' 4440 4441 _Fortran_: 4442 _Interface_: 'function acc_on_device(devicetype)' 4443 'integer(acc_device_kind) devicetype' 4444 'logical acc_on_device' 4445 4446 _Reference_: 4447 OpenACC specification v2.6 (https://www.openacc.org), section 4448 3.2.17. 4449 4450 4451 File: libgomp.info, Node: acc_malloc, Next: acc_free, Prev: acc_on_device, Up: OpenACC Runtime Library Routines 4452 4453 6.16 'acc_malloc' - Allocate device memory. 4454 =========================================== 4455 4456 _Description_ 4457 This function allocates BYTES bytes of device memory. It returns 4458 the device address of the allocated memory. 4459 4460 _C/C++_: 4461 _Prototype_: 'd_void* acc_malloc(size_t bytes);' 4462 4463 _Fortran_: 4464 _Interface_: 'type(c_ptr) function acc_malloc(bytes)' 4465 'integer(c_size_t), value :: bytes' 4466 4467 _Reference_: 4468 OpenACC specification v2.6 (https://www.openacc.org), section 4469 3.2.18. openacc specification v3.3 (https://www.openacc.org), 4470 section 3.2.16. 4471 4472 4473 File: libgomp.info, Node: acc_free, Next: acc_copyin, Prev: acc_malloc, Up: OpenACC Runtime Library Routines 4474 4475 6.17 'acc_free' - Free device memory. 4476 ===================================== 4477 4478 _Description_ 4479 Free previously allocated device memory at the device address 4480 'data_dev'. 4481 4482 _C/C++_: 4483 _Prototype_: 'void acc_free(d_void *data_dev);' 4484 4485 _Fortran_: 4486 _Interface_: 'subroutine acc_free(data_dev)' 4487 'type(c_ptr), value :: data_dev' 4488 4489 _Reference_: 4490 OpenACC specification v2.6 (https://www.openacc.org), section 4491 3.2.19. openacc specification v3.3 (https://www.openacc.org), 4492 section 3.2.17. 4493 4494 4495 File: libgomp.info, Node: acc_copyin, Next: acc_present_or_copyin, Prev: acc_free, Up: OpenACC Runtime Library Routines 4496 4497 6.18 'acc_copyin' - Allocate device memory and copy host memory to it. 4498 ====================================================================== 4499 4500 _Description_ 4501 In C/C++, this function allocates LEN bytes of device memory and 4502 maps it to the specified host address in A. The device address of 4503 the newly allocated device memory is returned. 4504 4505 In Fortran, two (2) forms are supported. In the first form, A 4506 specifies a contiguous array section. The second form A specifies 4507 a variable or array element and LEN specifies the length in bytes. 4508 4509 _C/C++_: 4510 _Prototype_: 'void *acc_copyin(h_void *a, size_t len);' 4511 _Prototype_: 'void *acc_copyin_async(h_void *a, size_t len, int 4512 async);' 4513 4514 _Fortran_: 4515 _Interface_: 'subroutine acc_copyin(a)' 4516 'type, dimension(:[,:]...) :: a' 4517 _Interface_: 'subroutine acc_copyin(a, len)' 4518 'type, dimension(:[,:]...) :: a' 4519 'integer len' 4520 _Interface_: 'subroutine acc_copyin_async(a, async)' 4521 'type, dimension(:[,:]...) :: a' 4522 'integer(acc_handle_kind) :: async' 4523 _Interface_: 'subroutine acc_copyin_async(a, len, async)' 4524 'type, dimension(:[,:]...) :: a' 4525 'integer len' 4526 'integer(acc_handle_kind) :: async' 4527 4528 _Reference_: 4529 OpenACC specification v2.6 (https://www.openacc.org), section 4530 3.2.20. 4531 4532 4533 File: libgomp.info, Node: acc_present_or_copyin, Next: acc_create, Prev: acc_copyin, Up: OpenACC Runtime Library Routines 4534 4535 6.19 'acc_present_or_copyin' - If the data is not present on the device, allocate device memory and copy from host memory. 4536 ========================================================================================================================== 4537 4538 _Description_ 4539 This function tests if the host data specified by A and of length 4540 LEN is present or not. If it is not present, device memory is 4541 allocated and the host memory copied. The device address of the 4542 newly allocated device memory is returned. 4543 4544 In Fortran, two (2) forms are supported. In the first form, A 4545 specifies a contiguous array section. The second form A specifies 4546 a variable or array element and LEN specifies the length in bytes. 4547 4548 Note that 'acc_present_or_copyin' and 'acc_pcopyin' exist for 4549 backward compatibility with OpenACC 2.0; use *note acc_copyin:: 4550 instead. 4551 4552 _C/C++_: 4553 _Prototype_: 'void *acc_present_or_copyin(h_void *a, size_t len);' 4554 _Prototype_: 'void *acc_pcopyin(h_void *a, size_t len);' 4555 4556 _Fortran_: 4557 _Interface_: 'subroutine acc_present_or_copyin(a)' 4558 'type, dimension(:[,:]...) :: a' 4559 _Interface_: 'subroutine acc_present_or_copyin(a, len)' 4560 'type, dimension(:[,:]...) :: a' 4561 'integer len' 4562 _Interface_: 'subroutine acc_pcopyin(a)' 4563 'type, dimension(:[,:]...) :: a' 4564 _Interface_: 'subroutine acc_pcopyin(a, len)' 4565 'type, dimension(:[,:]...) :: a' 4566 'integer len' 4567 4568 _Reference_: 4569 OpenACC specification v2.6 (https://www.openacc.org), section 4570 3.2.20. 4571 4572 4573 File: libgomp.info, Node: acc_create, Next: acc_present_or_create, Prev: acc_present_or_copyin, Up: OpenACC Runtime Library Routines 4574 4575 6.20 'acc_create' - Allocate device memory and map it to host memory. 4576 ===================================================================== 4577 4578 _Description_ 4579 This function allocates device memory and maps it to host memory 4580 specified by the host address A with a length of LEN bytes. In 4581 C/C++, the function returns the device address of the allocated 4582 device memory. 4583 4584 In Fortran, two (2) forms are supported. In the first form, A 4585 specifies a contiguous array section. The second form A specifies 4586 a variable or array element and LEN specifies the length in bytes. 4587 4588 _C/C++_: 4589 _Prototype_: 'void *acc_create(h_void *a, size_t len);' 4590 _Prototype_: 'void *acc_create_async(h_void *a, size_t len, int 4591 async);' 4592 4593 _Fortran_: 4594 _Interface_: 'subroutine acc_create(a)' 4595 'type, dimension(:[,:]...) :: a' 4596 _Interface_: 'subroutine acc_create(a, len)' 4597 'type, dimension(:[,:]...) :: a' 4598 'integer len' 4599 _Interface_: 'subroutine acc_create_async(a, async)' 4600 'type, dimension(:[,:]...) :: a' 4601 'integer(acc_handle_kind) :: async' 4602 _Interface_: 'subroutine acc_create_async(a, len, async)' 4603 'type, dimension(:[,:]...) :: a' 4604 'integer len' 4605 'integer(acc_handle_kind) :: async' 4606 4607 _Reference_: 4608 OpenACC specification v2.6 (https://www.openacc.org), section 4609 3.2.21. 4610 4611 4612 File: libgomp.info, Node: acc_present_or_create, Next: acc_copyout, Prev: acc_create, Up: OpenACC Runtime Library Routines 4613 4614 6.21 'acc_present_or_create' - If the data is not present on the device, allocate device memory and map it to host memory. 4615 ========================================================================================================================== 4616 4617 _Description_ 4618 This function tests if the host data specified by A and of length 4619 LEN is present or not. If it is not present, device memory is 4620 allocated and mapped to host memory. In C/C++, the device address 4621 of the newly allocated device memory is returned. 4622 4623 In Fortran, two (2) forms are supported. In the first form, A 4624 specifies a contiguous array section. The second form A specifies 4625 a variable or array element and LEN specifies the length in bytes. 4626 4627 Note that 'acc_present_or_create' and 'acc_pcreate' exist for 4628 backward compatibility with OpenACC 2.0; use *note acc_create:: 4629 instead. 4630 4631 _C/C++_: 4632 _Prototype_: 'void *acc_present_or_create(h_void *a, size_t len)' 4633 _Prototype_: 'void *acc_pcreate(h_void *a, size_t len)' 4634 4635 _Fortran_: 4636 _Interface_: 'subroutine acc_present_or_create(a)' 4637 'type, dimension(:[,:]...) :: a' 4638 _Interface_: 'subroutine acc_present_or_create(a, len)' 4639 'type, dimension(:[,:]...) :: a' 4640 'integer len' 4641 _Interface_: 'subroutine acc_pcreate(a)' 4642 'type, dimension(:[,:]...) :: a' 4643 _Interface_: 'subroutine acc_pcreate(a, len)' 4644 'type, dimension(:[,:]...) :: a' 4645 'integer len' 4646 4647 _Reference_: 4648 OpenACC specification v2.6 (https://www.openacc.org), section 4649 3.2.21. 4650 4651 4652 File: libgomp.info, Node: acc_copyout, Next: acc_delete, Prev: acc_present_or_create, Up: OpenACC Runtime Library Routines 4653 4654 6.22 'acc_copyout' - Copy device memory to host memory. 4655 ======================================================= 4656 4657 _Description_ 4658 This function copies mapped device memory to host memory which is 4659 specified by host address A for a length LEN bytes in C/C++. 4660 4661 In Fortran, two (2) forms are supported. In the first form, A 4662 specifies a contiguous array section. The second form A specifies 4663 a variable or array element and LEN specifies the length in bytes. 4664 4665 _C/C++_: 4666 _Prototype_: 'acc_copyout(h_void *a, size_t len);' 4667 _Prototype_: 'acc_copyout_async(h_void *a, size_t len, int async);' 4668 _Prototype_: 'acc_copyout_finalize(h_void *a, size_t len);' 4669 _Prototype_: 'acc_copyout_finalize_async(h_void *a, size_t len, int 4670 async);' 4671 4672 _Fortran_: 4673 _Interface_: 'subroutine acc_copyout(a)' 4674 'type, dimension(:[,:]...) :: a' 4675 _Interface_: 'subroutine acc_copyout(a, len)' 4676 'type, dimension(:[,:]...) :: a' 4677 'integer len' 4678 _Interface_: 'subroutine acc_copyout_async(a, async)' 4679 'type, dimension(:[,:]...) :: a' 4680 'integer(acc_handle_kind) :: async' 4681 _Interface_: 'subroutine acc_copyout_async(a, len, async)' 4682 'type, dimension(:[,:]...) :: a' 4683 'integer len' 4684 'integer(acc_handle_kind) :: async' 4685 _Interface_: 'subroutine acc_copyout_finalize(a)' 4686 'type, dimension(:[,:]...) :: a' 4687 _Interface_: 'subroutine acc_copyout_finalize(a, len)' 4688 'type, dimension(:[,:]...) :: a' 4689 'integer len' 4690 _Interface_: 'subroutine acc_copyout_finalize_async(a, async)' 4691 'type, dimension(:[,:]...) :: a' 4692 'integer(acc_handle_kind) :: async' 4693 _Interface_: 'subroutine acc_copyout_finalize_async(a, len, async)' 4694 'type, dimension(:[,:]...) :: a' 4695 'integer len' 4696 'integer(acc_handle_kind) :: async' 4697 4698 _Reference_: 4699 OpenACC specification v2.6 (https://www.openacc.org), section 4700 3.2.22. 4701 4702 4703 File: libgomp.info, Node: acc_delete, Next: acc_update_device, Prev: acc_copyout, Up: OpenACC Runtime Library Routines 4704 4705 6.23 'acc_delete' - Free device memory. 4706 ======================================= 4707 4708 _Description_ 4709 This function frees previously allocated device memory specified by 4710 the device address A and the length of LEN bytes. 4711 4712 In Fortran, two (2) forms are supported. In the first form, A 4713 specifies a contiguous array section. The second form A specifies 4714 a variable or array element and LEN specifies the length in bytes. 4715 4716 _C/C++_: 4717 _Prototype_: 'acc_delete(h_void *a, size_t len);' 4718 _Prototype_: 'acc_delete_async(h_void *a, size_t len, int async);' 4719 _Prototype_: 'acc_delete_finalize(h_void *a, size_t len);' 4720 _Prototype_: 'acc_delete_finalize_async(h_void *a, size_t len, int 4721 async);' 4722 4723 _Fortran_: 4724 _Interface_: 'subroutine acc_delete(a)' 4725 'type, dimension(:[,:]...) :: a' 4726 _Interface_: 'subroutine acc_delete(a, len)' 4727 'type, dimension(:[,:]...) :: a' 4728 'integer len' 4729 _Interface_: 'subroutine acc_delete_async(a, async)' 4730 'type, dimension(:[,:]...) :: a' 4731 'integer(acc_handle_kind) :: async' 4732 _Interface_: 'subroutine acc_delete_async(a, len, async)' 4733 'type, dimension(:[,:]...) :: a' 4734 'integer len' 4735 'integer(acc_handle_kind) :: async' 4736 _Interface_: 'subroutine acc_delete_finalize(a)' 4737 'type, dimension(:[,:]...) :: a' 4738 _Interface_: 'subroutine acc_delete_finalize(a, len)' 4739 'type, dimension(:[,:]...) :: a' 4740 'integer len' 4741 _Interface_: 'subroutine acc_delete_async_finalize(a, async)' 4742 'type, dimension(:[,:]...) :: a' 4743 'integer(acc_handle_kind) :: async' 4744 _Interface_: 'subroutine acc_delete_async_finalize(a, len, async)' 4745 'type, dimension(:[,:]...) :: a' 4746 'integer len' 4747 'integer(acc_handle_kind) :: async' 4748 4749 _Reference_: 4750 OpenACC specification v2.6 (https://www.openacc.org), section 4751 3.2.23. 4752 4753 4754 File: libgomp.info, Node: acc_update_device, Next: acc_update_self, Prev: acc_delete, Up: OpenACC Runtime Library Routines 4755 4756 6.24 'acc_update_device' - Update device memory from mapped host memory. 4757 ======================================================================== 4758 4759 _Description_ 4760 This function updates the device copy from the previously mapped 4761 host memory. The host memory is specified with the host address A 4762 and a length of LEN bytes. 4763 4764 In Fortran, two (2) forms are supported. In the first form, A 4765 specifies a contiguous array section. The second form A specifies 4766 a variable or array element and LEN specifies the length in bytes. 4767 4768 _C/C++_: 4769 _Prototype_: 'acc_update_device(h_void *a, size_t len);' 4770 _Prototype_: 'acc_update_device(h_void *a, size_t len, async);' 4771 4772 _Fortran_: 4773 _Interface_: 'subroutine acc_update_device(a)' 4774 'type, dimension(:[,:]...) :: a' 4775 _Interface_: 'subroutine acc_update_device(a, len)' 4776 'type, dimension(:[,:]...) :: a' 4777 'integer len' 4778 _Interface_: 'subroutine acc_update_device_async(a, async)' 4779 'type, dimension(:[,:]...) :: a' 4780 'integer(acc_handle_kind) :: async' 4781 _Interface_: 'subroutine acc_update_device_async(a, len, async)' 4782 'type, dimension(:[,:]...) :: a' 4783 'integer len' 4784 'integer(acc_handle_kind) :: async' 4785 4786 _Reference_: 4787 OpenACC specification v2.6 (https://www.openacc.org), section 4788 3.2.24. 4789 4790 4791 File: libgomp.info, Node: acc_update_self, Next: acc_map_data, Prev: acc_update_device, Up: OpenACC Runtime Library Routines 4792 4793 6.25 'acc_update_self' - Update host memory from mapped device memory. 4794 ====================================================================== 4795 4796 _Description_ 4797 This function updates the host copy from the previously mapped 4798 device memory. The host memory is specified with the host address 4799 A and a length of LEN bytes. 4800 4801 In Fortran, two (2) forms are supported. In the first form, A 4802 specifies a contiguous array section. The second form A specifies 4803 a variable or array element and LEN specifies the length in bytes. 4804 4805 _C/C++_: 4806 _Prototype_: 'acc_update_self(h_void *a, size_t len);' 4807 _Prototype_: 'acc_update_self_async(h_void *a, size_t len, int 4808 async);' 4809 4810 _Fortran_: 4811 _Interface_: 'subroutine acc_update_self(a)' 4812 'type, dimension(:[,:]...) :: a' 4813 _Interface_: 'subroutine acc_update_self(a, len)' 4814 'type, dimension(:[,:]...) :: a' 4815 'integer len' 4816 _Interface_: 'subroutine acc_update_self_async(a, async)' 4817 'type, dimension(:[,:]...) :: a' 4818 'integer(acc_handle_kind) :: async' 4819 _Interface_: 'subroutine acc_update_self_async(a, len, async)' 4820 'type, dimension(:[,:]...) :: a' 4821 'integer len' 4822 'integer(acc_handle_kind) :: async' 4823 4824 _Reference_: 4825 OpenACC specification v2.6 (https://www.openacc.org), section 4826 3.2.25. 4827 4828 4829 File: libgomp.info, Node: acc_map_data, Next: acc_unmap_data, Prev: acc_update_self, Up: OpenACC Runtime Library Routines 4830 4831 6.26 'acc_map_data' - Map previously allocated device memory to host memory. 4832 ============================================================================ 4833 4834 _Description_ 4835 This function maps previously allocated device and host memory. 4836 The device memory is specified with the device address DATA_DEV. 4837 The host memory is specified with the host address DATA_ARG and a 4838 length of BYTES. 4839 4840 _C/C++_: 4841 _Prototype_: 'void acc_map_data(h_void *data_arg, d_void *data_dev, 4842 size_t bytes);' 4843 4844 _Fortran_: 4845 _Interface_: 'subroutine acc_map_data(data_arg, data_dev, bytes)' 4846 'type(*), dimension(*) :: data_arg' 4847 'type(c_ptr), value :: data_dev' 4848 'integer(c_size_t), value :: bytes' 4849 4850 _Reference_: 4851 OpenACC specification v2.6 (https://www.openacc.org), section 4852 3.2.26. OpenACC specification v3.3 (https://www.openacc.org), 4853 section 3.2.21. 4854 4855 4856 File: libgomp.info, Node: acc_unmap_data, Next: acc_deviceptr, Prev: acc_map_data, Up: OpenACC Runtime Library Routines 4857 4858 6.27 'acc_unmap_data' - Unmap device memory from host memory. 4859 ============================================================= 4860 4861 _Description_ 4862 This function unmaps previously mapped device and host memory. The 4863 latter specified by DATA_ARG. 4864 4865 _C/C++_: 4866 _Prototype_: 'void acc_unmap_data(h_void *data_arg);' 4867 4868 _Fortran_: 4869 _Interface_: 'subroutine acc_unmap_data(data_arg)' 4870 'type(*), dimension(*) :: data_arg' 4871 4872 _Reference_: 4873 OpenACC specification v2.6 (https://www.openacc.org), section 4874 3.2.27. OpenACC specification v3.3 (https://www.openacc.org), 4875 section 3.2.22. 4876 4877 4878 File: libgomp.info, Node: acc_deviceptr, Next: acc_hostptr, Prev: acc_unmap_data, Up: OpenACC Runtime Library Routines 4879 4880 6.28 'acc_deviceptr' - Get device pointer associated with specific host address. 4881 ================================================================================ 4882 4883 _Description_ 4884 This function returns the device address that has been mapped to 4885 the host address specified by DATA_ARG. 4886 4887 _C/C++_: 4888 _Prototype_: 'void *acc_deviceptr(h_void *data_arg);' 4889 4890 _Fortran_: 4891 _Interface_: 'type(c_ptr) function acc_deviceptr(data_arg)' 4892 'type(*), dimension(*) :: data_arg' 4893 4894 _Reference_: 4895 OpenACC specification v2.6 (https://www.openacc.org), section 4896 3.2.28. OpenACC specification v3.3 (https://www.openacc.org), 4897 section 3.2.23. 4898 4899 4900 File: libgomp.info, Node: acc_hostptr, Next: acc_is_present, Prev: acc_deviceptr, Up: OpenACC Runtime Library Routines 4901 4902 6.29 'acc_hostptr' - Get host pointer associated with specific device address. 4903 ============================================================================== 4904 4905 _Description_ 4906 This function returns the host address that has been mapped to the 4907 device address specified by DATA_DEV. 4908 4909 _C/C++_: 4910 _Prototype_: 'void *acc_hostptr(d_void *data_dev);' 4911 4912 _Fortran_: 4913 _Interface_: 'type(c_ptr) function acc_hostptr(data_dev)' 4914 'type(c_ptr), value :: data_dev' 4915 4916 _Reference_: 4917 OpenACC specification v2.6 (https://www.openacc.org), section 4918 3.2.29. OpenACC specification v3.3 (https://www.openacc.org), 4919 section 3.2.24. 4920 4921 4922 File: libgomp.info, Node: acc_is_present, Next: acc_memcpy_to_device, Prev: acc_hostptr, Up: OpenACC Runtime Library Routines 4923 4924 6.30 'acc_is_present' - Indicate whether host variable / array is present on device. 4925 ==================================================================================== 4926 4927 _Description_ 4928 This function indicates whether the specified host address in A and 4929 a length of LEN bytes is present on the device. In C/C++, a 4930 non-zero value is returned to indicate the presence of the mapped 4931 memory on the device. A zero is returned to indicate the memory is 4932 not mapped on the device. 4933 4934 In Fortran, two (2) forms are supported. In the first form, A 4935 specifies a contiguous array section. The second form A specifies 4936 a variable or array element and LEN specifies the length in bytes. 4937 If the host memory is mapped to device memory, then a 'true' is 4938 returned. Otherwise, a 'false' is return to indicate the mapped 4939 memory is not present. 4940 4941 _C/C++_: 4942 _Prototype_: 'int acc_is_present(h_void *a, size_t len);' 4943 4944 _Fortran_: 4945 _Interface_: 'function acc_is_present(a)' 4946 'type, dimension(:[,:]...) :: a' 4947 'logical acc_is_present' 4948 _Interface_: 'function acc_is_present(a, len)' 4949 'type, dimension(:[,:]...) :: a' 4950 'integer len' 4951 'logical acc_is_present' 4952 4953 _Reference_: 4954 OpenACC specification v2.6 (https://www.openacc.org), section 4955 3.2.30. 4956 4957 4958 File: libgomp.info, Node: acc_memcpy_to_device, Next: acc_memcpy_from_device, Prev: acc_is_present, Up: OpenACC Runtime Library Routines 4959 4960 6.31 'acc_memcpy_to_device' - Copy host memory to device memory. 4961 ================================================================ 4962 4963 _Description_ 4964 This function copies host memory specified by host address of 4965 DATA_HOST_SRC to device memory specified by the device address 4966 DATA_DEV_DEST for a length of BYTES bytes. 4967 4968 _C/C++_: 4969 _Prototype_: 'void acc_memcpy_to_device(d_void* data_dev_dest,' 4970 'h_void* data_host_src, size_t bytes);' 4971 _Prototype_: 'void acc_memcpy_to_device_async(d_void* data_dev_dest,' 4972 'h_void* data_host_src, size_t bytes, int async_arg);' 4973 4974 _Fortran_: 4975 _Interface_: 'subroutine acc_memcpy_to_device(data_dev_dest, &' 4976 'data_host_src, bytes)' 4977 _Interface_: 'subroutine acc_memcpy_to_device_async(data_dev_dest, &' 4978 'data_host_src, bytes, async_arg)' 4979 'type(c_ptr), value :: data_dev_dest' 4980 'type(*), dimension(*) :: data_host_src' 4981 'integer(c_size_t), value :: bytes' 4982 'integer(acc_handle_kind), value :: async_arg' 4983 4984 _Reference_: 4985 OpenACC specification v2.6 (https://www.openacc.org), section 4986 3.2.31 OpenACC specification v3.3 (https://www.openacc.org), 4987 section 3.2.26. 4988 4989 4990 File: libgomp.info, Node: acc_memcpy_from_device, Next: acc_attach, Prev: acc_memcpy_to_device, Up: OpenACC Runtime Library Routines 4991 4992 6.32 'acc_memcpy_from_device' - Copy device memory to host memory. 4993 ================================================================== 4994 4995 _Description_ 4996 This function copies device memory specified by device address of 4997 DATA_DEV_SRC to host memory specified by the host address 4998 DATA_HOST_DEST for a length of BYTES bytes. 4999 5000 _C/C++_: 5001 _Prototype_: 'void acc_memcpy_from_device(h_void* data_host_dest,' 5002 'd_void* data_dev_src, size_t bytes);' 5003 _Prototype_: 'void acc_memcpy_from_device_async(h_void* 5004 data_host_dest,' 5005 'd_void* data_dev_src, size_t bytes, int async_arg);' 5006 5007 _Fortran_: 5008 _Interface_: 'subroutine acc_memcpy_from_device(data_host_dest, &' 5009 'data_dev_src, bytes)' 5010 _Interface_: 'subroutine acc_memcpy_from_device_async(data_host_dest, 5011 &' 5012 'data_dev_src, bytes, async_arg)' 5013 'type(*), dimension(*) :: data_host_dest' 5014 'type(c_ptr), value :: data_dev_src' 5015 'integer(c_size_t), value :: bytes' 5016 'integer(acc_handle_kind), value :: async_arg' 5017 5018 _Reference_: 5019 OpenACC specification v2.6 (https://www.openacc.org), section 5020 3.2.32. OpenACC specification v3.3 (https://www.openacc.org), 5021 section 3.2.27. 5022 5023 5024 File: libgomp.info, Node: acc_attach, Next: acc_detach, Prev: acc_memcpy_from_device, Up: OpenACC Runtime Library Routines 5025 5026 6.33 'acc_attach' - Let device pointer point to device-pointer target. 5027 ====================================================================== 5028 5029 _Description_ 5030 This function updates a pointer on the device from pointing to a 5031 host-pointer address to pointing to the corresponding device data. 5032 5033 _C/C++_: 5034 _Prototype_: 'void acc_attach(h_void **ptr_addr);' 5035 _Prototype_: 'void acc_attach_async(h_void **ptr_addr, int async);' 5036 5037 _Reference_: 5038 OpenACC specification v2.6 (https://www.openacc.org), section 5039 3.2.34. 5040 5041 5042 File: libgomp.info, Node: acc_detach, Next: acc_get_current_cuda_device, Prev: acc_attach, Up: OpenACC Runtime Library Routines 5043 5044 6.34 'acc_detach' - Let device pointer point to host-pointer target. 5045 ==================================================================== 5046 5047 _Description_ 5048 This function updates a pointer on the device from pointing to a 5049 device-pointer address to pointing to the corresponding host data. 5050 5051 _C/C++_: 5052 _Prototype_: 'void acc_detach(h_void **ptr_addr);' 5053 _Prototype_: 'void acc_detach_async(h_void **ptr_addr, int async);' 5054 _Prototype_: 'void acc_detach_finalize(h_void **ptr_addr);' 5055 _Prototype_: 'void acc_detach_finalize_async(h_void **ptr_addr, int 5056 async);' 5057 5058 _Reference_: 5059 OpenACC specification v2.6 (https://www.openacc.org), section 5060 3.2.35. 5061 5062 5063 File: libgomp.info, Node: acc_get_current_cuda_device, Next: acc_get_current_cuda_context, Prev: acc_detach, Up: OpenACC Runtime Library Routines 5064 5065 6.35 'acc_get_current_cuda_device' - Get CUDA device handle. 5066 ============================================================ 5067 5068 _Description_ 5069 This function returns the CUDA device handle. This handle is the 5070 same as used by the CUDA Runtime or Driver API's. 5071 5072 _C/C++_: 5073 _Prototype_: 'void *acc_get_current_cuda_device(void);' 5074 5075 _Reference_: 5076 OpenACC specification v2.6 (https://www.openacc.org), section 5077 A.2.1.1. 5078 5079 5080 File: libgomp.info, Node: acc_get_current_cuda_context, Next: acc_get_cuda_stream, Prev: acc_get_current_cuda_device, Up: OpenACC Runtime Library Routines 5081 5082 6.36 'acc_get_current_cuda_context' - Get CUDA context handle. 5083 ============================================================== 5084 5085 _Description_ 5086 This function returns the CUDA context handle. This handle is the 5087 same as used by the CUDA Runtime or Driver API's. 5088 5089 _C/C++_: 5090 _Prototype_: 'void *acc_get_current_cuda_context(void);' 5091 5092 _Reference_: 5093 OpenACC specification v2.6 (https://www.openacc.org), section 5094 A.2.1.2. 5095 5096 5097 File: libgomp.info, Node: acc_get_cuda_stream, Next: acc_set_cuda_stream, Prev: acc_get_current_cuda_context, Up: OpenACC Runtime Library Routines 5098 5099 6.37 'acc_get_cuda_stream' - Get CUDA stream handle. 5100 ==================================================== 5101 5102 _Description_ 5103 This function returns the CUDA stream handle for the queue ASYNC. 5104 This handle is the same as used by the CUDA Runtime or Driver 5105 API's. 5106 5107 _C/C++_: 5108 _Prototype_: 'void *acc_get_cuda_stream(int async);' 5109 5110 _Reference_: 5111 OpenACC specification v2.6 (https://www.openacc.org), section 5112 A.2.1.3. 5113 5114 5115 File: libgomp.info, Node: acc_set_cuda_stream, Next: acc_prof_register, Prev: acc_get_cuda_stream, Up: OpenACC Runtime Library Routines 5116 5117 6.38 'acc_set_cuda_stream' - Set CUDA stream handle. 5118 ==================================================== 5119 5120 _Description_ 5121 This function associates the stream handle specified by STREAM with 5122 the queue ASYNC. 5123 5124 This cannot be used to change the stream handle associated with 5125 'acc_async_sync'. 5126 5127 The return value is not specified. 5128 5129 _C/C++_: 5130 _Prototype_: 'int acc_set_cuda_stream(int async, void *stream);' 5131 5132 _Reference_: 5133 OpenACC specification v2.6 (https://www.openacc.org), section 5134 A.2.1.4. 5135 5136 5137 File: libgomp.info, Node: acc_prof_register, Next: acc_prof_unregister, Prev: acc_set_cuda_stream, Up: OpenACC Runtime Library Routines 5138 5139 6.39 'acc_prof_register' - Register callbacks. 5140 ============================================== 5141 5142 _Description_: 5143 This function registers callbacks. 5144 5145 _C/C++_: 5146 _Prototype_: 'void acc_prof_register (acc_event_t, acc_prof_callback, 5147 acc_register_t);' 5148 5149 _See also_: 5150 *note OpenACC Profiling Interface:: 5151 5152 _Reference_: 5153 OpenACC specification v2.6 (https://www.openacc.org), section 5.3. 5154 5155 5156 File: libgomp.info, Node: acc_prof_unregister, Next: acc_prof_lookup, Prev: acc_prof_register, Up: OpenACC Runtime Library Routines 5157 5158 6.40 'acc_prof_unregister' - Unregister callbacks. 5159 ================================================== 5160 5161 _Description_: 5162 This function unregisters callbacks. 5163 5164 _C/C++_: 5165 _Prototype_: 'void acc_prof_unregister (acc_event_t, 5166 acc_prof_callback, acc_register_t);' 5167 5168 _See also_: 5169 *note OpenACC Profiling Interface:: 5170 5171 _Reference_: 5172 OpenACC specification v2.6 (https://www.openacc.org), section 5.3. 5173 5174 5175 File: libgomp.info, Node: acc_prof_lookup, Next: acc_register_library, Prev: acc_prof_unregister, Up: OpenACC Runtime Library Routines 5176 5177 6.41 'acc_prof_lookup' - Obtain inquiry functions. 5178 ================================================== 5179 5180 _Description_: 5181 Function to obtain inquiry functions. 5182 5183 _C/C++_: 5184 _Prototype_: 'acc_query_fn acc_prof_lookup (const char *);' 5185 5186 _See also_: 5187 *note OpenACC Profiling Interface:: 5188 5189 _Reference_: 5190 OpenACC specification v2.6 (https://www.openacc.org), section 5.3. 5191 5192 5193 File: libgomp.info, Node: acc_register_library, Prev: acc_prof_lookup, Up: OpenACC Runtime Library Routines 5194 5195 6.42 'acc_register_library' - Library registration. 5196 =================================================== 5197 5198 _Description_: 5199 Function for library registration. 5200 5201 _C/C++_: 5202 _Prototype_: 'void acc_register_library (acc_prof_reg, acc_prof_reg, 5203 acc_prof_lookup_func);' 5204 5205 _See also_: 5206 *note OpenACC Profiling Interface::, *note ACC_PROFLIB:: 5207 5208 _Reference_: 5209 OpenACC specification v2.6 (https://www.openacc.org), section 5.3. 5210 5211 5212 File: libgomp.info, Node: OpenACC Environment Variables, Next: CUDA Streams Usage, Prev: OpenACC Runtime Library Routines, Up: Top 5213 5214 7 OpenACC Environment Variables 5215 ******************************* 5216 5217 The variables 'ACC_DEVICE_TYPE' and 'ACC_DEVICE_NUM' are defined by 5218 section 4 of the OpenACC specification in version 2.0. The variable 5219 'ACC_PROFLIB' is defined by section 4 of the OpenACC specification in 5220 version 2.6. 5221 5222 * Menu: 5223 5224 * ACC_DEVICE_TYPE:: 5225 * ACC_DEVICE_NUM:: 5226 * ACC_PROFLIB:: 5227 5228 5229 File: libgomp.info, Node: ACC_DEVICE_TYPE, Next: ACC_DEVICE_NUM, Up: OpenACC Environment Variables 5230 5231 7.1 'ACC_DEVICE_TYPE' 5232 ===================== 5233 5234 _Description_: 5235 Control the default device type to use when executing compute 5236 regions. If unset, the code can be run on any device type, 5237 favoring a non-host device type. 5238 5239 Supported values in GCC (if compiled in) are 5240 * 'host' 5241 * 'nvidia' 5242 * 'radeon' 5243 _Reference_: 5244 OpenACC specification v2.6 (https://www.openacc.org), section 4.1. 5245 5246 5247 File: libgomp.info, Node: ACC_DEVICE_NUM, Next: ACC_PROFLIB, Prev: ACC_DEVICE_TYPE, Up: OpenACC Environment Variables 5248 5249 7.2 'ACC_DEVICE_NUM' 5250 ==================== 5251 5252 _Description_: 5253 Control which device, identified by device number, is the default 5254 device. The value must be a nonnegative integer less than the 5255 number of devices. If unset, device number zero is used. 5256 _Reference_: 5257 OpenACC specification v2.6 (https://www.openacc.org), section 4.2. 5258 5259 5260 File: libgomp.info, Node: ACC_PROFLIB, Prev: ACC_DEVICE_NUM, Up: OpenACC Environment Variables 5261 5262 7.3 'ACC_PROFLIB' 5263 ================= 5264 5265 _Description_: 5266 Semicolon-separated list of dynamic libraries that are loaded as 5267 profiling libraries. Each library must provide at least the 5268 'acc_register_library' routine. Each library file is found as 5269 described by the documentation of 'dlopen' of your operating 5270 system. 5271 _See also_: 5272 *note acc_register_library::, *note OpenACC Profiling Interface:: 5273 5274 _Reference_: 5275 OpenACC specification v2.6 (https://www.openacc.org), section 4.3. 5276 5277 5278 File: libgomp.info, Node: CUDA Streams Usage, Next: OpenACC Library Interoperability, Prev: OpenACC Environment Variables, Up: Top 5279 5280 8 CUDA Streams Usage 5281 ******************** 5282 5283 This applies to the 'nvptx' plugin only. 5284 5285 The library provides elements that perform asynchronous movement of 5286 data and asynchronous operation of computing constructs. This 5287 asynchronous functionality is implemented by making use of CUDA 5288 streams(1). 5289 5290 The primary means by that the asynchronous functionality is accessed 5291 is through the use of those OpenACC directives which make use of the 5292 'async' and 'wait' clauses. When the 'async' clause is first used with 5293 a directive, it creates a CUDA stream. If an 'async-argument' is used 5294 with the 'async' clause, then the stream is associated with the 5295 specified 'async-argument'. 5296 5297 Following the creation of an association between a CUDA stream and 5298 the 'async-argument' of an 'async' clause, both the 'wait' clause and 5299 the 'wait' directive can be used. When either the clause or directive 5300 is used after stream creation, it creates a rendezvous point whereby 5301 execution waits until all operations associated with the 5302 'async-argument', that is, stream, have completed. 5303 5304 Normally, the management of the streams that are created as a result 5305 of using the 'async' clause, is done without any intervention by the 5306 caller. This implies the association between the 'async-argument' and 5307 the CUDA stream is maintained for the lifetime of the program. However, 5308 this association can be changed through the use of the library function 5309 'acc_set_cuda_stream'. When the function 'acc_set_cuda_stream' is 5310 called, the CUDA stream that was originally associated with the 'async' 5311 clause is destroyed. Caution should be taken when changing the 5312 association as subsequent references to the 'async-argument' refer to a 5313 different CUDA stream. 5314 5315 ---------- Footnotes ---------- 5316 5317 (1) See "Stream Management" in "CUDA Driver API", TRM-06703-001, 5318 Version 5.5, for additional information 5319 5320 5321 File: libgomp.info, Node: OpenACC Library Interoperability, Next: OpenACC Profiling Interface, Prev: CUDA Streams Usage, Up: Top 5322 5323 9 OpenACC Library Interoperability 5324 ********************************** 5325 5326 9.1 Introduction 5327 ================ 5328 5329 The OpenACC library uses the CUDA Driver API, and may interact with 5330 programs that use the Runtime library directly, or another library based 5331 on the Runtime library, e.g., CUBLAS(1). This chapter describes the use 5332 cases and what changes are required in order to use both the OpenACC 5333 library and the CUBLAS and Runtime libraries within a program. 5334 5335 9.2 First invocation: NVIDIA CUBLAS library API 5336 =============================================== 5337 5338 In this first use case (see below), a function in the CUBLAS library is 5339 called prior to any of the functions in the OpenACC library. More 5340 specifically, the function 'cublasCreate()'. 5341 5342 When invoked, the function initializes the library and allocates the 5343 hardware resources on the host and the device on behalf of the caller. 5344 Once the initialization and allocation has completed, a handle is 5345 returned to the caller. The OpenACC library also requires 5346 initialization and allocation of hardware resources. Since the CUBLAS 5347 library has already allocated the hardware resources for the device, all 5348 that is left to do is to initialize the OpenACC library and acquire the 5349 hardware resources on the host. 5350 5351 Prior to calling the OpenACC function that initializes the library 5352 and allocate the host hardware resources, you need to acquire the device 5353 number that was allocated during the call to 'cublasCreate()'. The 5354 invoking of the runtime library function 'cudaGetDevice()' accomplishes 5355 this. Once acquired, the device number is passed along with the device 5356 type as parameters to the OpenACC library function 5357 'acc_set_device_num()'. 5358 5359 Once the call to 'acc_set_device_num()' has completed, the OpenACC 5360 library uses the context that was created during the call to 5361 'cublasCreate()'. In other words, both libraries share the same 5362 context. 5363 5364 /* Create the handle */ 5365 s = cublasCreate(&h); 5366 if (s != CUBLAS_STATUS_SUCCESS) 5367 { 5368 fprintf(stderr, "cublasCreate failed %d\n", s); 5369 exit(EXIT_FAILURE); 5370 } 5371 5372 /* Get the device number */ 5373 e = cudaGetDevice(&dev); 5374 if (e != cudaSuccess) 5375 { 5376 fprintf(stderr, "cudaGetDevice failed %d\n", e); 5377 exit(EXIT_FAILURE); 5378 } 5379 5380 /* Initialize OpenACC library and use device 'dev' */ 5381 acc_set_device_num(dev, acc_device_nvidia); 5382 5383 Use Case 1 5384 5385 9.3 First invocation: OpenACC library API 5386 ========================================= 5387 5388 In this second use case (see below), a function in the OpenACC library 5389 is called prior to any of the functions in the CUBLAS library. More 5390 specifically, the function 'acc_set_device_num()'. 5391 5392 In the use case presented here, the function 'acc_set_device_num()' 5393 is used to both initialize the OpenACC library and allocate the hardware 5394 resources on the host and the device. In the call to the function, the 5395 call parameters specify which device to use and what device type to use, 5396 i.e., 'acc_device_nvidia'. It should be noted that this is but one 5397 method to initialize the OpenACC library and allocate the appropriate 5398 hardware resources. Other methods are available through the use of 5399 environment variables and these is discussed in the next section. 5400 5401 Once the call to 'acc_set_device_num()' has completed, other OpenACC 5402 functions can be called as seen with multiple calls being made to 5403 'acc_copyin()'. In addition, calls can be made to functions in the 5404 CUBLAS library. In the use case a call to 'cublasCreate()' is made 5405 subsequent to the calls to 'acc_copyin()'. As seen in the previous use 5406 case, a call to 'cublasCreate()' initializes the CUBLAS library and 5407 allocates the hardware resources on the host and the device. However, 5408 since the device has already been allocated, 'cublasCreate()' only 5409 initializes the CUBLAS library and allocates the appropriate hardware 5410 resources on the host. The context that was created as part of the 5411 OpenACC initialization is shared with the CUBLAS library, similarly to 5412 the first use case. 5413 5414 dev = 0; 5415 5416 acc_set_device_num(dev, acc_device_nvidia); 5417 5418 /* Copy the first set to the device */ 5419 d_X = acc_copyin(&h_X[0], N * sizeof (float)); 5420 if (d_X == NULL) 5421 { 5422 fprintf(stderr, "copyin error h_X\n"); 5423 exit(EXIT_FAILURE); 5424 } 5425 5426 /* Copy the second set to the device */ 5427 d_Y = acc_copyin(&h_Y1[0], N * sizeof (float)); 5428 if (d_Y == NULL) 5429 { 5430 fprintf(stderr, "copyin error h_Y1\n"); 5431 exit(EXIT_FAILURE); 5432 } 5433 5434 /* Create the handle */ 5435 s = cublasCreate(&h); 5436 if (s != CUBLAS_STATUS_SUCCESS) 5437 { 5438 fprintf(stderr, "cublasCreate failed %d\n", s); 5439 exit(EXIT_FAILURE); 5440 } 5441 5442 /* Perform saxpy using CUBLAS library function */ 5443 s = cublasSaxpy(h, N, &alpha, d_X, 1, d_Y, 1); 5444 if (s != CUBLAS_STATUS_SUCCESS) 5445 { 5446 fprintf(stderr, "cublasSaxpy failed %d\n", s); 5447 exit(EXIT_FAILURE); 5448 } 5449 5450 /* Copy the results from the device */ 5451 acc_memcpy_from_device(&h_Y1[0], d_Y, N * sizeof (float)); 5452 5453 Use Case 2 5454 5455 9.4 OpenACC library and environment variables 5456 ============================================= 5457 5458 There are two environment variables associated with the OpenACC library 5459 that may be used to control the device type and device number: 5460 'ACC_DEVICE_TYPE' and 'ACC_DEVICE_NUM', respectively. These two 5461 environment variables can be used as an alternative to calling 5462 'acc_set_device_num()'. As seen in the second use case, the device type 5463 and device number were specified using 'acc_set_device_num()'. If 5464 however, the aforementioned environment variables were set, then the 5465 call to 'acc_set_device_num()' would not be required. 5466 5467 The use of the environment variables is only relevant when an OpenACC 5468 function is called prior to a call to 'cudaCreate()'. If 'cudaCreate()' 5469 is called prior to a call to an OpenACC function, then you must call 5470 'acc_set_device_num()'(2) 5471 5472 ---------- Footnotes ---------- 5473 5474 (1) See section 2.26, "Interactions with the CUDA Driver API" in 5475 "CUDA Runtime API", Version 5.5, and section 2.27, "VDPAU 5476 Interoperability", in "CUDA Driver API", TRM-06703-001, Version 5.5, for 5477 additional information on library interoperability. 5478 5479 (2) More complete information about 'ACC_DEVICE_TYPE' and 5480 'ACC_DEVICE_NUM' can be found in sections 4.1 and 4.2 of the OpenACC 5481 (https://www.openacc.org) Application Programming Interface, Version 5482 2.6. 5483 5484 5485 File: libgomp.info, Node: OpenACC Profiling Interface, Next: OpenMP-Implementation Specifics, Prev: OpenACC Library Interoperability, Up: Top 5486 5487 10 OpenACC Profiling Interface 5488 ****************************** 5489 5490 10.1 Implementation Status and Implementation-Defined Behavior 5491 ============================================================== 5492 5493 We're implementing the OpenACC Profiling Interface as defined by the 5494 OpenACC 2.6 specification. We're clarifying some aspects here as 5495 _implementation-defined behavior_, while they're still under discussion 5496 within the OpenACC Technical Committee. 5497 5498 This implementation is tuned to keep the performance impact as low as 5499 possible for the (very common) case that the Profiling Interface is not 5500 enabled. This is relevant, as the Profiling Interface affects all the 5501 _hot_ code paths (in the target code, not in the offloaded code). Users 5502 of the OpenACC Profiling Interface can be expected to understand that 5503 performance is impacted to some degree once the Profiling Interface is 5504 enabled: for example, because of the _runtime_ (libgomp) calling into a 5505 third-party _library_ for every event that has been registered. 5506 5507 We're not yet accounting for the fact that 'OpenACC events may occur 5508 during event processing'. We just handle one case specially, as 5509 required by CUDA 9.0 'nvprof', that 'acc_get_device_type' (*note 5510 acc_get_device_type::)) may be called from 'acc_ev_device_init_start', 5511 'acc_ev_device_init_end' callbacks. 5512 5513 We're not yet implementing initialization via a 5514 'acc_register_library' function that is either statically linked in, or 5515 dynamically via 'LD_PRELOAD'. Initialization via 'acc_register_library' 5516 functions dynamically loaded via the 'ACC_PROFLIB' environment variable 5517 does work, as does directly calling 'acc_prof_register', 5518 'acc_prof_unregister', 'acc_prof_lookup'. 5519 5520 As currently there are no inquiry functions defined, calls to 5521 'acc_prof_lookup' always returns 'NULL'. 5522 5523 There aren't separate _start_, _stop_ events defined for the event 5524 types 'acc_ev_create', 'acc_ev_delete', 'acc_ev_alloc', 'acc_ev_free'. 5525 It's not clear if these should be triggered before or after the actual 5526 device-specific call is made. We trigger them after. 5527 5528 Remarks about data provided to callbacks: 5529 5530 'acc_prof_info.event_type' 5531 It's not clear if for _nested_ event callbacks (for example, 5532 'acc_ev_enqueue_launch_start' as part of a parent compute 5533 construct), this should be set for the nested event 5534 ('acc_ev_enqueue_launch_start'), or if the value of the parent 5535 construct should remain ('acc_ev_compute_construct_start'). In 5536 this implementation, the value generally corresponds to the 5537 innermost nested event type. 5538 5539 'acc_prof_info.device_type' 5540 5541 * For 'acc_ev_compute_construct_start', and in presence of an 5542 'if' clause with _false_ argument, this still refers to the 5543 offloading device type. It's not clear if that's the expected 5544 behavior. 5545 5546 * Complementary to the item before, for 5547 'acc_ev_compute_construct_end', this is set to 5548 'acc_device_host' in presence of an 'if' clause with _false_ 5549 argument. It's not clear if that's the expected behavior. 5550 5551 'acc_prof_info.thread_id' 5552 Always '-1'; not yet implemented. 5553 5554 'acc_prof_info.async' 5555 5556 * Not yet implemented correctly for 5557 'acc_ev_compute_construct_start'. 5558 5559 * In a compute construct, for host-fallback 5560 execution/'acc_device_host' it always is 'acc_async_sync'. It 5561 is unclear if that is the expected behavior. 5562 5563 * For 'acc_ev_device_init_start' and 'acc_ev_device_init_end', 5564 it will always be 'acc_async_sync'. It is unclear if that is 5565 the expected behavior. 5566 5567 'acc_prof_info.async_queue' 5568 There is no 'limited number of asynchronous queues' in libgomp. 5569 This always has the same value as 'acc_prof_info.async'. 5570 5571 'acc_prof_info.src_file' 5572 Always 'NULL'; not yet implemented. 5573 5574 'acc_prof_info.func_name' 5575 Always 'NULL'; not yet implemented. 5576 5577 'acc_prof_info.line_no' 5578 Always '-1'; not yet implemented. 5579 5580 'acc_prof_info.end_line_no' 5581 Always '-1'; not yet implemented. 5582 5583 'acc_prof_info.func_line_no' 5584 Always '-1'; not yet implemented. 5585 5586 'acc_prof_info.func_end_line_no' 5587 Always '-1'; not yet implemented. 5588 5589 'acc_event_info.event_type', 'acc_event_info.*.event_type' 5590 Relating to 'acc_prof_info.event_type' discussed above, in this 5591 implementation, this will always be the same value as 5592 'acc_prof_info.event_type'. 5593 5594 'acc_event_info.*.parent_construct' 5595 5596 * Will be 'acc_construct_parallel' for all OpenACC compute 5597 constructs as well as many OpenACC Runtime API calls; should 5598 be the one matching the actual construct, or 5599 'acc_construct_runtime_api', respectively. 5600 5601 * Will be 'acc_construct_enter_data' or 5602 'acc_construct_exit_data' when processing variable mappings 5603 specified in OpenACC _declare_ directives; should be 5604 'acc_construct_declare'. 5605 5606 * For implicit 'acc_ev_device_init_start', 5607 'acc_ev_device_init_end', and explicit as well as implicit 5608 'acc_ev_alloc', 'acc_ev_free', 'acc_ev_enqueue_upload_start', 5609 'acc_ev_enqueue_upload_end', 'acc_ev_enqueue_download_start', 5610 and 'acc_ev_enqueue_download_end', will be 5611 'acc_construct_parallel'; should reflect the real parent 5612 construct. 5613 5614 'acc_event_info.*.implicit' 5615 For 'acc_ev_alloc', 'acc_ev_free', 'acc_ev_enqueue_upload_start', 5616 'acc_ev_enqueue_upload_end', 'acc_ev_enqueue_download_start', and 5617 'acc_ev_enqueue_download_end', this currently will be '1' also for 5618 explicit usage. 5619 5620 'acc_event_info.data_event.var_name' 5621 Always 'NULL'; not yet implemented. 5622 5623 'acc_event_info.data_event.host_ptr' 5624 For 'acc_ev_alloc', and 'acc_ev_free', this is always 'NULL'. 5625 5626 'typedef union acc_api_info' 5627 ... as printed in '5.2.3. Third Argument: API-Specific 5628 Information'. This should obviously be 'typedef _struct_ 5629 acc_api_info'. 5630 5631 'acc_api_info.device_api' 5632 Possibly not yet implemented correctly for 5633 'acc_ev_compute_construct_start', 'acc_ev_device_init_start', 5634 'acc_ev_device_init_end': will always be 'acc_device_api_none' for 5635 these event types. For 'acc_ev_enter_data_start', it will be 5636 'acc_device_api_none' in some cases. 5637 5638 'acc_api_info.device_type' 5639 Always the same as 'acc_prof_info.device_type'. 5640 5641 'acc_api_info.vendor' 5642 Always '-1'; not yet implemented. 5643 5644 'acc_api_info.device_handle' 5645 Always 'NULL'; not yet implemented. 5646 5647 'acc_api_info.context_handle' 5648 Always 'NULL'; not yet implemented. 5649 5650 'acc_api_info.async_handle' 5651 Always 'NULL'; not yet implemented. 5652 5653 Remarks about certain event types: 5654 5655 'acc_ev_device_init_start', 'acc_ev_device_init_end' 5656 5657 * When a compute construct triggers implicit 5658 'acc_ev_device_init_start' and 'acc_ev_device_init_end' 5659 events, they currently aren't _nested within_ the 5660 corresponding 'acc_ev_compute_construct_start' and 5661 'acc_ev_compute_construct_end', but they're currently observed 5662 _before_ 'acc_ev_compute_construct_start'. It's not clear 5663 what to do: the standard asks us provide a lot of details to 5664 the 'acc_ev_compute_construct_start' callback, without 5665 (implicitly) initializing a device before? 5666 5667 * Callbacks for these event types will not be invoked for calls 5668 to the 'acc_set_device_type' and 'acc_set_device_num' 5669 functions. It's not clear if they should be. 5670 5671 'acc_ev_enter_data_start', 'acc_ev_enter_data_end', 'acc_ev_exit_data_start', 'acc_ev_exit_data_end' 5672 5673 * Callbacks for these event types will also be invoked for 5674 OpenACC _host_data_ constructs. It's not clear if they should 5675 be. 5676 5677 * Callbacks for these event types will also be invoked when 5678 processing variable mappings specified in OpenACC _declare_ 5679 directives. It's not clear if they should be. 5680 5681 Callbacks for the following event types will be invoked, but dispatch 5682 and information provided therein has not yet been thoroughly reviewed: 5683 5684 * 'acc_ev_alloc' 5685 * 'acc_ev_free' 5686 * 'acc_ev_update_start', 'acc_ev_update_end' 5687 * 'acc_ev_enqueue_upload_start', 'acc_ev_enqueue_upload_end' 5688 * 'acc_ev_enqueue_download_start', 'acc_ev_enqueue_download_end' 5689 5690 During device initialization, and finalization, respectively, 5691 callbacks for the following event types will not yet be invoked: 5692 5693 * 'acc_ev_alloc' 5694 * 'acc_ev_free' 5695 5696 Callbacks for the following event types have not yet been 5697 implemented, so currently won't be invoked: 5698 5699 * 'acc_ev_device_shutdown_start', 'acc_ev_device_shutdown_end' 5700 * 'acc_ev_runtime_shutdown' 5701 * 'acc_ev_create', 'acc_ev_delete' 5702 * 'acc_ev_wait_start', 'acc_ev_wait_end' 5703 5704 For the following runtime library functions, not all expected 5705 callbacks will be invoked (mostly concerning implicit device 5706 initialization): 5707 5708 * 'acc_get_num_devices' 5709 * 'acc_set_device_type' 5710 * 'acc_get_device_type' 5711 * 'acc_set_device_num' 5712 * 'acc_get_device_num' 5713 * 'acc_init' 5714 * 'acc_shutdown' 5715 5716 Aside from implicit device initialization, for the following runtime 5717 library functions, no callbacks will be invoked for shared-memory 5718 offloading devices (it's not clear if they should be): 5719 5720 * 'acc_malloc' 5721 * 'acc_free' 5722 * 'acc_copyin', 'acc_present_or_copyin', 'acc_copyin_async' 5723 * 'acc_create', 'acc_present_or_create', 'acc_create_async' 5724 * 'acc_copyout', 'acc_copyout_async', 'acc_copyout_finalize', 5725 'acc_copyout_finalize_async' 5726 * 'acc_delete', 'acc_delete_async', 'acc_delete_finalize', 5727 'acc_delete_finalize_async' 5728 * 'acc_update_device', 'acc_update_device_async' 5729 * 'acc_update_self', 'acc_update_self_async' 5730 * 'acc_map_data', 'acc_unmap_data' 5731 * 'acc_memcpy_to_device', 'acc_memcpy_to_device_async' 5732 * 'acc_memcpy_from_device', 'acc_memcpy_from_device_async' 5733 5734 5735 File: libgomp.info, Node: OpenMP-Implementation Specifics, Next: Offload-Target Specifics, Prev: OpenACC Profiling Interface, Up: Top 5736 5737 11 OpenMP-Implementation Specifics 5738 ********************************** 5739 5740 * Menu: 5741 5742 * Implementation-defined ICV Initialization:: 5743 * OpenMP Context Selectors:: 5744 * Memory allocation:: 5745 5746 5747 File: libgomp.info, Node: Implementation-defined ICV Initialization, Next: OpenMP Context Selectors, Up: OpenMP-Implementation Specifics 5748 5749 11.1 Implementation-defined ICV Initialization 5750 ============================================== 5751 5752 AFFINITY-FORMAT-VAR See *note OMP_AFFINITY_FORMAT::. 5753 DEF-ALLOCATOR-VAR See *note OMP_ALLOCATOR::. 5754 MAX-ACTIVE-LEVELS-VAR See *note OMP_MAX_ACTIVE_LEVELS::. 5755 DYN-VAR See *note OMP_DYNAMIC::. 5756 NTHREADS-VAR See *note OMP_NUM_THREADS::. 5757 NUM-DEVICES-VAR Number of non-host devices found by GCC's 5758 run-time library 5759 NUM-PROCS-VAR The number of CPU cores on the initial device, 5760 except that affinity settings might lead to a 5761 smaller number. On non-host devices, the value 5762 of the NTHREADS-VAR ICV. 5763 PLACE-PARTITION-VAR See *note OMP_PLACES::. 5764 RUN-SCHED-VAR See *note OMP_SCHEDULE::. 5765 STACKSIZE-VAR See *note OMP_STACKSIZE::. 5766 THREAD-LIMIT-VAR See *note OMP_TEAMS_THREAD_LIMIT:: 5767 WAIT-POLICY-VAR See *note OMP_WAIT_POLICY:: and 5768 *note GOMP_SPINCOUNT:: 5769 5770 5771 File: libgomp.info, Node: OpenMP Context Selectors, Next: Memory allocation, Prev: Implementation-defined ICV Initialization, Up: OpenMP-Implementation Specifics 5772 5773 11.2 OpenMP Context Selectors 5774 ============================= 5775 5776 'vendor' is always 'gnu'. References are to the GCC manual. 5777 5778 For the host compiler, 'kind' always matches 'host'; for the 5779 offloading architectures AMD GCN and Nvidia PTX, 'kind' always matches 5780 'gpu'. For the x86 family of computers, AMD GCN and Nvidia PTX the 5781 following traits are supported in addition; while OpenMP is supported on 5782 more architectures, GCC currently does not match any 'arch' or 'isa' 5783 traits for those. 5784 5785 'arch' 'isa' 5786 ----------------------------------------------------------------------- 5787 'x86', 'x86_64', 'i386', 'i486', 'i586', See '-m...' flags in 5788 'i686', 'ia32' "x86 Options" 5789 (without '-m') 5790 'amdgcn', 'gcn' See '-march=' in 5791 "AMD GCN Options"(1) 5792 'nvptx', 'nvptx64' See '-march=' in 5793 "Nvidia PTX Options" 5794 5795 ---------- Footnotes ---------- 5796 5797 (1) Additionally, 'gfx803' is supported as an alias for 'fiji'. 5798 5799 5800 File: libgomp.info, Node: Memory allocation, Prev: OpenMP Context Selectors, Up: OpenMP-Implementation Specifics 5801 5802 11.3 Memory allocation 5803 ====================== 5804 5805 The description below applies to: 5806 5807 * Explicit use of the OpenMP API routines, see *note Memory 5808 Management Routines::. 5809 * The 'allocate' clause, except when the 'allocator' modifier is a 5810 constant expression with value 'omp_default_mem_alloc' and no 5811 'align' modifier has been specified. (In that case, the normal 5812 'malloc' allocation is used.) 5813 * Using the 'allocate' directive for automatic/stack variables, 5814 except when the 'allocator' clause is a constant expression with 5815 value 'omp_default_mem_alloc' and no 'align' clause has been 5816 specified. (In that case, the normal allocation is used: stack 5817 allocation and, sometimes for Fortran, also 'malloc' [depending on 5818 flags such as '-fstack-arrays'].) 5819 * Using the 'allocate' directive for variable in static memory is 5820 currently not supported (compile time error). 5821 * In Fortran, the 'allocators' directive and the executable 5822 'allocate' directive for Fortran pointers and allocatables is 5823 supported, but requires that files containing those directives has 5824 to be compiled with '-fopenmp-allocators'. Additionally, all files 5825 that might explicitly or implicitly deallocate memory allocated 5826 that way must also be compiled with that option. 5827 5828 For the available predefined allocators and, as applicable, their 5829 associated predefined memory spaces and for the available traits and 5830 their default values, see *note OMP_ALLOCATOR::. Predefined allocators 5831 without an associated memory space use the 'omp_default_mem_space' 5832 memory space. 5833 5834 For the memory spaces, the following applies: 5835 * 'omp_default_mem_space' is supported 5836 * 'omp_const_mem_space' maps to 'omp_default_mem_space' 5837 * 'omp_low_lat_mem_space' is only available on supported devices, and 5838 maps to 'omp_default_mem_space' otherwise. 5839 * 'omp_large_cap_mem_space' maps to 'omp_default_mem_space', unless 5840 the memkind library is available 5841 * 'omp_high_bw_mem_space' maps to 'omp_default_mem_space', unless the 5842 memkind library is available 5843 5844 On Linux systems, where the memkind library 5845 (https://github.com/memkind/memkind) ('libmemkind.so.0') is available at 5846 runtime, it is used when creating memory allocators requesting 5847 5848 * the memory space 'omp_high_bw_mem_space' 5849 * the memory space 'omp_large_cap_mem_space' 5850 * the 'partition' trait 'interleaved'; note that for 5851 'omp_large_cap_mem_space' the allocation will not be interleaved 5852 5853 On Linux systems, where the numa library 5854 (https://github.com/numactl/numactl) ('libnuma.so.1') is available at 5855 runtime, it used when creating memory allocators requesting 5856 5857 * the 'partition' trait 'nearest', except when both the libmemkind 5858 library is available and the memory space is either 5859 'omp_large_cap_mem_space' or 'omp_high_bw_mem_space' 5860 5861 Note that the numa library will round up the allocation size to a 5862 multiple of the system page size; therefore, consider using it only with 5863 large data or by sharing allocations via the 'pool_size' trait. 5864 Furthermore, the Linux kernel does not guarantee that an allocation will 5865 always be on the nearest NUMA node nor that after reallocation the same 5866 node will be used. Note additionally that, on Linux, the default 5867 setting of the memory placement policy is to use the current node; 5868 therefore, unless the memory placement policy has been overridden, the 5869 'partition' trait 'environment' (the default) will be effectively a 5870 'nearest' allocation. 5871 5872 Additional notes regarding the traits: 5873 * The 'pinned' trait is supported on Linux hosts, but is subject to 5874 the OS 'ulimit'/'rlimit' locked memory settings. 5875 * The default for the 'pool_size' trait is no pool and for every 5876 (re)allocation the associated library routine is called, which 5877 might internally use a memory pool. 5878 * For the 'partition' trait, the partition part size will be the same 5879 as the requested size (i.e. 'interleaved' or 'blocked' has no 5880 effect), except for 'interleaved' when the memkind library is 5881 available. Furthermore, for 'nearest' and unless the numa library 5882 is available, the memory might not be on the same NUMA node as 5883 thread that allocated the memory; on Linux, this is in particular 5884 the case when the memory placement policy is set to preferred. 5885 * The 'access' trait has no effect such that memory is always 5886 accessible by all threads. 5887 * The 'sync_hint' trait has no effect. 5888 5889 See also: *note Offload-Target Specifics:: 5890 5891 5892 File: libgomp.info, Node: Offload-Target Specifics, Next: The libgomp ABI, Prev: OpenMP-Implementation Specifics, Up: Top 5893 5894 12 Offload-Target Specifics 5895 *************************** 5896 5897 The following sections present notes on the offload-target specifics 5898 5899 * Menu: 5900 5901 * AMD Radeon:: 5902 * nvptx:: 5903 5904 5905 File: libgomp.info, Node: AMD Radeon, Next: nvptx, Up: Offload-Target Specifics 5906 5907 12.1 AMD Radeon (GCN) 5908 ===================== 5909 5910 On the hardware side, there is the hierarchy (fine to coarse): 5911 * work item (thread) 5912 * wavefront 5913 * work group 5914 * compute unit (CU) 5915 5916 All OpenMP and OpenACC levels are used, i.e. 5917 * OpenMP's simd and OpenACC's vector map to work items (thread) 5918 * OpenMP's threads ("parallel") and OpenACC's workers map to 5919 wavefronts 5920 * OpenMP's teams and OpenACC's gang use a threadpool with the size of 5921 the number of teams or gangs, respectively. 5922 5923 The used sizes are 5924 * Number of teams is the specified 'num_teams' (OpenMP) or 5925 'num_gangs' (OpenACC) or otherwise the number of CU. It is limited 5926 by two times the number of CU. 5927 * Number of wavefronts is 4 for gfx900 and 16 otherwise; 5928 'num_threads' (OpenMP) and 'num_workers' (OpenACC) overrides this 5929 if smaller. 5930 * The wavefront has 102 scalars and 64 vectors 5931 * Number of workitems is always 64 5932 * The hardware permits maximally 40 workgroups/CU and 16 5933 wavefronts/workgroup up to a limit of 40 wavefronts in total per 5934 CU. 5935 * 80 scalars registers and 24 vector registers in non-kernel 5936 functions (the chosen procedure-calling API). 5937 * For the kernel itself: as many as register pressure demands (number 5938 of teams and number of threads, scaled down if registers are 5939 exhausted) 5940 5941 The implementation remark: 5942 * I/O within OpenMP target regions and OpenACC parallel/kernels is 5943 supported using the C library 'printf' functions and the Fortran 5944 'print'/'write' statements. 5945 * Reverse offload regions (i.e. 'target' regions with 5946 'device(ancestor:1)') are processed serially per 'target' region 5947 such that the next reverse offload region is only executed after 5948 the previous one returned. 5949 * OpenMP code that has a 'requires' directive with 5950 'unified_shared_memory' will remove any GCN device from the list of 5951 available devices ("host fallback"). 5952 * The available stack size can be changed using the 'GCN_STACK_SIZE' 5953 environment variable; the default is 32 kiB per thread. 5954 * Low-latency memory ('omp_low_lat_mem_space') is supported when the 5955 the 'access' trait is set to 'cgroup'. The default pool size is 5956 automatically scaled to share the 64 kiB LDS memory between the 5957 number of teams configured to run on each compute-unit, but may be 5958 adjusted at runtime by setting environment variable 5959 'GOMP_GCN_LOWLAT_POOL=BYTES'. 5960 * 'omp_low_lat_mem_alloc' cannot be used with true low-latency memory 5961 because the definition implies the 'omp_atv_all' trait; main 5962 graphics memory is used instead. 5963 * 'omp_cgroup_mem_alloc', 'omp_pteam_mem_alloc', and 5964 'omp_thread_mem_alloc', all use low-latency memory as first 5965 preference, and fall back to main graphics memory when the 5966 low-latency pool is exhausted. 5967 5968 5969 File: libgomp.info, Node: nvptx, Prev: AMD Radeon, Up: Offload-Target Specifics 5970 5971 12.2 nvptx 5972 ========== 5973 5974 On the hardware side, there is the hierarchy (fine to coarse): 5975 * thread 5976 * warp 5977 * thread block 5978 * streaming multiprocessor 5979 5980 All OpenMP and OpenACC levels are used, i.e. 5981 * OpenMP's simd and OpenACC's vector map to threads 5982 * OpenMP's threads ("parallel") and OpenACC's workers map to warps 5983 * OpenMP's teams and OpenACC's gang use a threadpool with the size of 5984 the number of teams or gangs, respectively. 5985 5986 The used sizes are 5987 * The 'warp_size' is always 32 5988 * CUDA kernel launched: 'dim={#teams,1,1}, 5989 blocks={#threads,warp_size,1}'. 5990 * The number of teams is limited by the number of blocks the device 5991 can host simultaneously. 5992 5993 Additional information can be obtained by setting the environment 5994 variable to 'GOMP_DEBUG=1' (very verbose; grep for 'kernel.*launch' for 5995 launch parameters). 5996 5997 GCC generates generic PTX ISA code, which is just-in-time compiled by 5998 CUDA, which caches the JIT in the user's directory (see CUDA 5999 documentation; can be tuned by the environment variables 6000 'CUDA_CACHE_{DISABLE,MAXSIZE,PATH}'. 6001 6002 Note: While PTX ISA is generic, the '-mptx=' and '-march=' 6003 commandline options still affect the used PTX ISA code and, thus, the 6004 requirements on CUDA version and hardware. 6005 6006 The implementation remark: 6007 * I/O within OpenMP target regions and OpenACC parallel/kernels is 6008 supported using the C library 'printf' functions. Note that the 6009 Fortran 'print'/'write' statements are not supported, yet. 6010 * Compilation OpenMP code that contains 'requires reverse_offload' 6011 requires at least '-march=sm_35', compiling for '-march=sm_30' is 6012 not supported. 6013 * For code containing reverse offload (i.e. 'target' regions with 6014 'device(ancestor:1)'), there is a slight performance penalty for 6015 _all_ target regions, consisting mostly of shutdown delay Per 6016 device, reverse offload regions are processed serially such that 6017 the next reverse offload region is only executed after the previous 6018 one returned. 6019 * OpenMP code that has a 'requires' directive with 6020 'unified_shared_memory' will remove any nvptx device from the list 6021 of available devices ("host fallback"). 6022 * The default per-warp stack size is 128 kiB; see also '-msoft-stack' 6023 in the GCC manual. 6024 * The OpenMP routines 'omp_target_memcpy_rect' and 6025 'omp_target_memcpy_rect_async' and the 'target update' directive 6026 for non-contiguous list items will use the 2D and 3D memory-copy 6027 functions of the CUDA library. Higher dimensions will call those 6028 functions in a loop and are therefore supported. 6029 * Low-latency memory ('omp_low_lat_mem_space') is supported when the 6030 the 'access' trait is set to 'cgroup', the ISA is at least 'sm_53', 6031 and the PTX version is at least 4.1. The default pool size is 8 6032 kiB per team, but may be adjusted at runtime by setting environment 6033 variable 'GOMP_NVPTX_LOWLAT_POOL=BYTES'. The maximum value is 6034 limited by the available hardware, and care should be taken that 6035 the selected pool size does not unduly limit the number of teams 6036 that can run simultaneously. 6037 * 'omp_low_lat_mem_alloc' cannot be used with true low-latency memory 6038 because the definition implies the 'omp_atv_all' trait; main 6039 graphics memory is used instead. 6040 * 'omp_cgroup_mem_alloc', 'omp_pteam_mem_alloc', and 6041 'omp_thread_mem_alloc', all use low-latency memory as first 6042 preference, and fall back to main graphics memory when the 6043 low-latency pool is exhausted. 6044 6045 6046 File: libgomp.info, Node: The libgomp ABI, Next: Reporting Bugs, Prev: Offload-Target Specifics, Up: Top 6047 6048 13 The libgomp ABI 6049 ****************** 6050 6051 The following sections present notes on the external ABI as presented by 6052 libgomp. Only maintainers should need them. 6053 6054 * Menu: 6055 6056 * Implementing MASTER construct:: 6057 * Implementing CRITICAL construct:: 6058 * Implementing ATOMIC construct:: 6059 * Implementing FLUSH construct:: 6060 * Implementing BARRIER construct:: 6061 * Implementing THREADPRIVATE construct:: 6062 * Implementing PRIVATE clause:: 6063 * Implementing FIRSTPRIVATE LASTPRIVATE COPYIN and COPYPRIVATE clauses:: 6064 * Implementing REDUCTION clause:: 6065 * Implementing PARALLEL construct:: 6066 * Implementing FOR construct:: 6067 * Implementing ORDERED construct:: 6068 * Implementing SECTIONS construct:: 6069 * Implementing SINGLE construct:: 6070 * Implementing OpenACC's PARALLEL construct:: 6071 6072 6073 File: libgomp.info, Node: Implementing MASTER construct, Next: Implementing CRITICAL construct, Up: The libgomp ABI 6074 6075 13.1 Implementing MASTER construct 6076 ================================== 6077 6078 if (omp_get_thread_num () == 0) 6079 block 6080 6081 Alternately, we generate two copies of the parallel subfunction and 6082 only include this in the version run by the primary thread. Surely this 6083 is not worthwhile though... 6084 6085 6086 File: libgomp.info, Node: Implementing CRITICAL construct, Next: Implementing ATOMIC construct, Prev: Implementing MASTER construct, Up: The libgomp ABI 6087 6088 13.2 Implementing CRITICAL construct 6089 ==================================== 6090 6091 Without a specified name, 6092 6093 void GOMP_critical_start (void); 6094 void GOMP_critical_end (void); 6095 6096 so that we don't get COPY relocations from libgomp to the main 6097 application. 6098 6099 With a specified name, use omp_set_lock and omp_unset_lock with name 6100 being transformed into a variable declared like 6101 6102 omp_lock_t gomp_critical_user_<name> __attribute__((common)) 6103 6104 Ideally the ABI would specify that all zero is a valid unlocked 6105 state, and so we wouldn't need to initialize this at startup. 6106 6107 6108 File: libgomp.info, Node: Implementing ATOMIC construct, Next: Implementing FLUSH construct, Prev: Implementing CRITICAL construct, Up: The libgomp ABI 6109 6110 13.3 Implementing ATOMIC construct 6111 ================================== 6112 6113 The target should implement the '__sync' builtins. 6114 6115 Failing that we could add 6116 6117 void GOMP_atomic_enter (void) 6118 void GOMP_atomic_exit (void) 6119 6120 which reuses the regular lock code, but with yet another lock object 6121 private to the library. 6122 6123 6124 File: libgomp.info, Node: Implementing FLUSH construct, Next: Implementing BARRIER construct, Prev: Implementing ATOMIC construct, Up: The libgomp ABI 6125 6126 13.4 Implementing FLUSH construct 6127 ================================= 6128 6129 Expands to the '__sync_synchronize' builtin. 6130 6131 6132 File: libgomp.info, Node: Implementing BARRIER construct, Next: Implementing THREADPRIVATE construct, Prev: Implementing FLUSH construct, Up: The libgomp ABI 6133 6134 13.5 Implementing BARRIER construct 6135 =================================== 6136 6137 void GOMP_barrier (void) 6138 6139 6140 File: libgomp.info, Node: Implementing THREADPRIVATE construct, Next: Implementing PRIVATE clause, Prev: Implementing BARRIER construct, Up: The libgomp ABI 6141 6142 13.6 Implementing THREADPRIVATE construct 6143 ========================================= 6144 6145 In _most_ cases we can map this directly to '__thread'. Except that OMP 6146 allows constructors for C++ objects. We can either refuse to support 6147 this (how often is it used?) or we can implement something akin to 6148 .ctors. 6149 6150 Even more ideally, this ctor feature is handled by extensions to the 6151 main pthreads library. Failing that, we can have a set of entry points 6152 to register ctor functions to be called. 6153 6154 6155 File: libgomp.info, Node: Implementing PRIVATE clause, Next: Implementing FIRSTPRIVATE LASTPRIVATE COPYIN and COPYPRIVATE clauses, Prev: Implementing THREADPRIVATE construct, Up: The libgomp ABI 6156 6157 13.7 Implementing PRIVATE clause 6158 ================================ 6159 6160 In association with a PARALLEL, or within the lexical extent of a 6161 PARALLEL block, the variable becomes a local variable in the parallel 6162 subfunction. 6163 6164 In association with FOR or SECTIONS blocks, create a new automatic 6165 variable within the current function. This preserves the semantic of 6166 new variable creation. 6167 6168 6169 File: libgomp.info, Node: Implementing FIRSTPRIVATE LASTPRIVATE COPYIN and COPYPRIVATE clauses, Next: Implementing REDUCTION clause, Prev: Implementing PRIVATE clause, Up: The libgomp ABI 6170 6171 13.8 Implementing FIRSTPRIVATE LASTPRIVATE COPYIN and COPYPRIVATE clauses 6172 ========================================================================= 6173 6174 This seems simple enough for PARALLEL blocks. Create a private struct 6175 for communicating between the parent and subfunction. In the parent, 6176 copy in values for scalar and "small" structs; copy in addresses for 6177 others TREE_ADDRESSABLE types. In the subfunction, copy the value into 6178 the local variable. 6179 6180 It is not clear what to do with bare FOR or SECTION blocks. The only 6181 thing I can figure is that we do something like: 6182 6183 #pragma omp for firstprivate(x) lastprivate(y) 6184 for (int i = 0; i < n; ++i) 6185 body; 6186 6187 which becomes 6188 6189 { 6190 int x = x, y; 6191 6192 // for stuff 6193 6194 if (i == n) 6195 y = y; 6196 } 6197 6198 where the "x=x" and "y=y" assignments actually have different uids 6199 for the two variables, i.e. not something you could write directly in 6200 C. Presumably this only makes sense if the "outer" x and y are global 6201 variables. 6202 6203 COPYPRIVATE would work the same way, except the structure broadcast 6204 would have to happen via SINGLE machinery instead. 6205 6206 6207 File: libgomp.info, Node: Implementing REDUCTION clause, Next: Implementing PARALLEL construct, Prev: Implementing FIRSTPRIVATE LASTPRIVATE COPYIN and COPYPRIVATE clauses, Up: The libgomp ABI 6208 6209 13.9 Implementing REDUCTION clause 6210 ================================== 6211 6212 The private struct mentioned in the previous section should have a 6213 pointer to an array of the type of the variable, indexed by the thread's 6214 TEAM_ID. The thread stores its final value into the array, and after 6215 the barrier, the primary thread iterates over the array to collect the 6216 values. 6217 6218 6219 File: libgomp.info, Node: Implementing PARALLEL construct, Next: Implementing FOR construct, Prev: Implementing REDUCTION clause, Up: The libgomp ABI 6220 6221 13.10 Implementing PARALLEL construct 6222 ===================================== 6223 6224 #pragma omp parallel 6225 { 6226 body; 6227 } 6228 6229 becomes 6230 6231 void subfunction (void *data) 6232 { 6233 use data; 6234 body; 6235 } 6236 6237 setup data; 6238 GOMP_parallel_start (subfunction, &data, num_threads); 6239 subfunction (&data); 6240 GOMP_parallel_end (); 6241 6242 void GOMP_parallel_start (void (*fn)(void *), void *data, unsigned num_threads) 6243 6244 The FN argument is the subfunction to be run in parallel. 6245 6246 The DATA argument is a pointer to a structure used to communicate 6247 data in and out of the subfunction, as discussed above with respect to 6248 FIRSTPRIVATE et al. 6249 6250 The NUM_THREADS argument is 1 if an IF clause is present and false, 6251 or the value of the NUM_THREADS clause, if present, or 0. 6252 6253 The function needs to create the appropriate number of threads and/or 6254 launch them from the dock. It needs to create the team structure and 6255 assign team ids. 6256 6257 void GOMP_parallel_end (void) 6258 6259 Tears down the team and returns us to the previous 6260 'omp_in_parallel()' state. 6261 6262 6263 File: libgomp.info, Node: Implementing FOR construct, Next: Implementing ORDERED construct, Prev: Implementing PARALLEL construct, Up: The libgomp ABI 6264 6265 13.11 Implementing FOR construct 6266 ================================ 6267 6268 #pragma omp parallel for 6269 for (i = lb; i <= ub; i++) 6270 body; 6271 6272 becomes 6273 6274 void subfunction (void *data) 6275 { 6276 long _s0, _e0; 6277 while (GOMP_loop_static_next (&_s0, &_e0)) 6278 { 6279 long _e1 = _e0, i; 6280 for (i = _s0; i < _e1; i++) 6281 body; 6282 } 6283 GOMP_loop_end_nowait (); 6284 } 6285 6286 GOMP_parallel_loop_static (subfunction, NULL, 0, lb, ub+1, 1, 0); 6287 subfunction (NULL); 6288 GOMP_parallel_end (); 6289 6290 #pragma omp for schedule(runtime) 6291 for (i = 0; i < n; i++) 6292 body; 6293 6294 becomes 6295 6296 { 6297 long i, _s0, _e0; 6298 if (GOMP_loop_runtime_start (0, n, 1, &_s0, &_e0)) 6299 do { 6300 long _e1 = _e0; 6301 for (i = _s0, i < _e0; i++) 6302 body; 6303 } while (GOMP_loop_runtime_next (&_s0, _&e0)); 6304 GOMP_loop_end (); 6305 } 6306 6307 Note that while it looks like there is trickiness to propagating a 6308 non-constant STEP, there isn't really. We're explicitly allowed to 6309 evaluate it as many times as we want, and any variables involved should 6310 automatically be handled as PRIVATE or SHARED like any other variables. 6311 So the expression should remain evaluable in the subfunction. We can 6312 also pull it into a local variable if we like, but since its supposed to 6313 remain unchanged, we can also not if we like. 6314 6315 If we have SCHEDULE(STATIC), and no ORDERED, then we ought to be able 6316 to get away with no work-sharing context at all, since we can simply 6317 perform the arithmetic directly in each thread to divide up the 6318 iterations. Which would mean that we wouldn't need to call any of these 6319 routines. 6320 6321 There are separate routines for handling loops with an ORDERED 6322 clause. Bookkeeping for that is non-trivial... 6323 6324 6325 File: libgomp.info, Node: Implementing ORDERED construct, Next: Implementing SECTIONS construct, Prev: Implementing FOR construct, Up: The libgomp ABI 6326 6327 13.12 Implementing ORDERED construct 6328 ==================================== 6329 6330 void GOMP_ordered_start (void) 6331 void GOMP_ordered_end (void) 6332 6333 6334 File: libgomp.info, Node: Implementing SECTIONS construct, Next: Implementing SINGLE construct, Prev: Implementing ORDERED construct, Up: The libgomp ABI 6335 6336 13.13 Implementing SECTIONS construct 6337 ===================================== 6338 6339 A block as 6340 6341 #pragma omp sections 6342 { 6343 #pragma omp section 6344 stmt1; 6345 #pragma omp section 6346 stmt2; 6347 #pragma omp section 6348 stmt3; 6349 } 6350 6351 becomes 6352 6353 for (i = GOMP_sections_start (3); i != 0; i = GOMP_sections_next ()) 6354 switch (i) 6355 { 6356 case 1: 6357 stmt1; 6358 break; 6359 case 2: 6360 stmt2; 6361 break; 6362 case 3: 6363 stmt3; 6364 break; 6365 } 6366 GOMP_barrier (); 6367 6368 6369 File: libgomp.info, Node: Implementing SINGLE construct, Next: Implementing OpenACC's PARALLEL construct, Prev: Implementing SECTIONS construct, Up: The libgomp ABI 6370 6371 13.14 Implementing SINGLE construct 6372 =================================== 6373 6374 A block like 6375 6376 #pragma omp single 6377 { 6378 body; 6379 } 6380 6381 becomes 6382 6383 if (GOMP_single_start ()) 6384 body; 6385 GOMP_barrier (); 6386 6387 while 6388 6389 #pragma omp single copyprivate(x) 6390 body; 6391 6392 becomes 6393 6394 datap = GOMP_single_copy_start (); 6395 if (datap == NULL) 6396 { 6397 body; 6398 data.x = x; 6399 GOMP_single_copy_end (&data); 6400 } 6401 else 6402 x = datap->x; 6403 GOMP_barrier (); 6404 6405 6406 File: libgomp.info, Node: Implementing OpenACC's PARALLEL construct, Prev: Implementing SINGLE construct, Up: The libgomp ABI 6407 6408 13.15 Implementing OpenACC's PARALLEL construct 6409 =============================================== 6410 6411 void GOACC_parallel () 6412 6413 6414 File: libgomp.info, Node: Reporting Bugs, Next: Copying, Prev: The libgomp ABI, Up: Top 6415 6416 14 Reporting Bugs 6417 ***************** 6418 6419 Bugs in the GNU Offloading and Multi Processing Runtime Library should 6420 be reported via Bugzilla (https://gcc.gnu.org/bugzilla/). Please add 6421 "openacc", or "openmp", or both to the keywords field in the bug report, 6422 as appropriate. 6423 6424 6425 File: libgomp.info, Node: Copying, Next: GNU Free Documentation License, Prev: Reporting Bugs, Up: Top 6426 6427 GNU General Public License 6428 ************************** 6429 6430 Version 3, 29 June 2007 6431 6432 Copyright (C) 2007 Free Software Foundation, Inc. <https://www.fsf.org> 6433 6434 Everyone is permitted to copy and distribute verbatim copies of this 6435 license document, but changing it is not allowed. 6436 6437 Preamble 6438 ======== 6439 6440 The GNU General Public License is a free, copyleft license for software 6441 and other kinds of works. 6442 6443 The licenses for most software and other practical works are designed 6444 to take away your freedom to share and change the works. By contrast, 6445 the GNU General Public License is intended to guarantee your freedom to 6446 share and change all versions of a program-to make sure it remains free 6447 software for all its users. We, the Free Software Foundation, use the 6448 GNU General Public License for most of our software; it applies also to 6449 any other work released this way by its authors. You can apply it to 6450 your programs, too. 6451 6452 When we speak of free software, we are referring to freedom, not 6453 price. Our General Public Licenses are designed to make sure that you 6454 have the freedom to distribute copies of free software (and charge for 6455 them if you wish), that you receive source code or can get it if you 6456 want it, that you can change the software or use pieces of it in new 6457 free programs, and that you know you can do these things. 6458 6459 To protect your rights, we need to prevent others from denying you 6460 these rights or asking you to surrender the rights. Therefore, you have 6461 certain responsibilities if you distribute copies of the software, or if 6462 you modify it: responsibilities to respect the freedom of others. 6463 6464 For example, if you distribute copies of such a program, whether 6465 gratis or for a fee, you must pass on to the recipients the same 6466 freedoms that you received. You must make sure that they, too, receive 6467 or can get the source code. And you must show them these terms so they 6468 know their rights. 6469 6470 Developers that use the GNU GPL protect your rights with two steps: 6471 (1) assert copyright on the software, and (2) offer you this License 6472 giving you legal permission to copy, distribute and/or modify it. 6473 6474 For the developers' and authors' protection, the GPL clearly explains 6475 that there is no warranty for this free software. For both users' and 6476 authors' sake, the GPL requires that modified versions be marked as 6477 changed, so that their problems will not be attributed erroneously to 6478 authors of previous versions. 6479 6480 Some devices are designed to deny users access to install or run 6481 modified versions of the software inside them, although the manufacturer 6482 can do so. This is fundamentally incompatible with the aim of 6483 protecting users' freedom to change the software. The systematic 6484 pattern of such abuse occurs in the area of products for individuals to 6485 use, which is precisely where it is most unacceptable. Therefore, we 6486 have designed this version of the GPL to prohibit the practice for those 6487 products. If such problems arise substantially in other domains, we 6488 stand ready to extend this provision to those domains in future versions 6489 of the GPL, as needed to protect the freedom of users. 6490 6491 Finally, every program is threatened constantly by software patents. 6492 States should not allow patents to restrict development and use of 6493 software on general-purpose computers, but in those that do, we wish to 6494 avoid the special danger that patents applied to a free program could 6495 make it effectively proprietary. To prevent this, the GPL assures that 6496 patents cannot be used to render the program non-free. 6497 6498 The precise terms and conditions for copying, distribution and 6499 modification follow. 6500 6501 TERMS AND CONDITIONS 6502 ==================== 6503 6504 0. Definitions. 6505 6506 "This License" refers to version 3 of the GNU General Public 6507 License. 6508 6509 "Copyright" also means copyright-like laws that apply to other 6510 kinds of works, such as semiconductor masks. 6511 6512 "The Program" refers to any copyrightable work licensed under this 6513 License. Each licensee is addressed as "you". "Licensees" and 6514 "recipients" may be individuals or organizations. 6515 6516 To "modify" a work means to copy from or adapt all or part of the 6517 work in a fashion requiring copyright permission, other than the 6518 making of an exact copy. The resulting work is called a "modified 6519 version" of the earlier work or a work "based on" the earlier work. 6520 6521 A "covered work" means either the unmodified Program or a work 6522 based on the Program. 6523 6524 To "propagate" a work means to do anything with it that, without 6525 permission, would make you directly or secondarily liable for 6526 infringement under applicable copyright law, except executing it on 6527 a computer or modifying a private copy. Propagation includes 6528 copying, distribution (with or without modification), making 6529 available to the public, and in some countries other activities as 6530 well. 6531 6532 To "convey" a work means any kind of propagation that enables other 6533 parties to make or receive copies. Mere interaction with a user 6534 through a computer network, with no transfer of a copy, is not 6535 conveying. 6536 6537 An interactive user interface displays "Appropriate Legal Notices" 6538 to the extent that it includes a convenient and prominently visible 6539 feature that (1) displays an appropriate copyright notice, and (2) 6540 tells the user that there is no warranty for the work (except to 6541 the extent that warranties are provided), that licensees may convey 6542 the work under this License, and how to view a copy of this 6543 License. If the interface presents a list of user commands or 6544 options, such as a menu, a prominent item in the list meets this 6545 criterion. 6546 6547 1. Source Code. 6548 6549 The "source code" for a work means the preferred form of the work 6550 for making modifications to it. "Object code" means any non-source 6551 form of a work. 6552 6553 A "Standard Interface" means an interface that either is an 6554 official standard defined by a recognized standards body, or, in 6555 the case of interfaces specified for a particular programming 6556 language, one that is widely used among developers working in that 6557 language. 6558 6559 The "System Libraries" of an executable work include anything, 6560 other than the work as a whole, that (a) is included in the normal 6561 form of packaging a Major Component, but which is not part of that 6562 Major Component, and (b) serves only to enable use of the work with 6563 that Major Component, or to implement a Standard Interface for 6564 which an implementation is available to the public in source code 6565 form. A "Major Component", in this context, means a major 6566 essential component (kernel, window system, and so on) of the 6567 specific operating system (if any) on which the executable work 6568 runs, or a compiler used to produce the work, or an object code 6569 interpreter used to run it. 6570 6571 The "Corresponding Source" for a work in object code form means all 6572 the source code needed to generate, install, and (for an executable 6573 work) run the object code and to modify the work, including scripts 6574 to control those activities. However, it does not include the 6575 work's System Libraries, or general-purpose tools or generally 6576 available free programs which are used unmodified in performing 6577 those activities but which are not part of the work. For example, 6578 Corresponding Source includes interface definition files associated 6579 with source files for the work, and the source code for shared 6580 libraries and dynamically linked subprograms that the work is 6581 specifically designed to require, such as by intimate data 6582 communication or control flow between those subprograms and other 6583 parts of the work. 6584 6585 The Corresponding Source need not include anything that users can 6586 regenerate automatically from other parts of the Corresponding 6587 Source. 6588 6589 The Corresponding Source for a work in source code form is that 6590 same work. 6591 6592 2. Basic Permissions. 6593 6594 All rights granted under this License are granted for the term of 6595 copyright on the Program, and are irrevocable provided the stated 6596 conditions are met. This License explicitly affirms your unlimited 6597 permission to run the unmodified Program. The output from running 6598 a covered work is covered by this License only if the output, given 6599 its content, constitutes a covered work. This License acknowledges 6600 your rights of fair use or other equivalent, as provided by 6601 copyright law. 6602 6603 You may make, run and propagate covered works that you do not 6604 convey, without conditions so long as your license otherwise 6605 remains in force. You may convey covered works to others for the 6606 sole purpose of having them make modifications exclusively for you, 6607 or provide you with facilities for running those works, provided 6608 that you comply with the terms of this License in conveying all 6609 material for which you do not control copyright. Those thus making 6610 or running the covered works for you must do so exclusively on your 6611 behalf, under your direction and control, on terms that prohibit 6612 them from making any copies of your copyrighted material outside 6613 their relationship with you. 6614 6615 Conveying under any other circumstances is permitted solely under 6616 the conditions stated below. Sublicensing is not allowed; section 6617 10 makes it unnecessary. 6618 6619 3. Protecting Users' Legal Rights From Anti-Circumvention Law. 6620 6621 No covered work shall be deemed part of an effective technological 6622 measure under any applicable law fulfilling obligations under 6623 article 11 of the WIPO copyright treaty adopted on 20 December 6624 1996, or similar laws prohibiting or restricting circumvention of 6625 such measures. 6626 6627 When you convey a covered work, you waive any legal power to forbid 6628 circumvention of technological measures to the extent such 6629 circumvention is effected by exercising rights under this License 6630 with respect to the covered work, and you disclaim any intention to 6631 limit operation or modification of the work as a means of 6632 enforcing, against the work's users, your or third parties' legal 6633 rights to forbid circumvention of technological measures. 6634 6635 4. Conveying Verbatim Copies. 6636 6637 You may convey verbatim copies of the Program's source code as you 6638 receive it, in any medium, provided that you conspicuously and 6639 appropriately publish on each copy an appropriate copyright notice; 6640 keep intact all notices stating that this License and any 6641 non-permissive terms added in accord with section 7 apply to the 6642 code; keep intact all notices of the absence of any warranty; and 6643 give all recipients a copy of this License along with the Program. 6644 6645 You may charge any price or no price for each copy that you convey, 6646 and you may offer support or warranty protection for a fee. 6647 6648 5. Conveying Modified Source Versions. 6649 6650 You may convey a work based on the Program, or the modifications to 6651 produce it from the Program, in the form of source code under the 6652 terms of section 4, provided that you also meet all of these 6653 conditions: 6654 6655 a. The work must carry prominent notices stating that you 6656 modified it, and giving a relevant date. 6657 6658 b. The work must carry prominent notices stating that it is 6659 released under this License and any conditions added under 6660 section 7. This requirement modifies the requirement in 6661 section 4 to "keep intact all notices". 6662 6663 c. You must license the entire work, as a whole, under this 6664 License to anyone who comes into possession of a copy. This 6665 License will therefore apply, along with any applicable 6666 section 7 additional terms, to the whole of the work, and all 6667 its parts, regardless of how they are packaged. This License 6668 gives no permission to license the work in any other way, but 6669 it does not invalidate such permission if you have separately 6670 received it. 6671 6672 d. If the work has interactive user interfaces, each must display 6673 Appropriate Legal Notices; however, if the Program has 6674 interactive interfaces that do not display Appropriate Legal 6675 Notices, your work need not make them do so. 6676 6677 A compilation of a covered work with other separate and independent 6678 works, which are not by their nature extensions of the covered 6679 work, and which are not combined with it such as to form a larger 6680 program, in or on a volume of a storage or distribution medium, is 6681 called an "aggregate" if the compilation and its resulting 6682 copyright are not used to limit the access or legal rights of the 6683 compilation's users beyond what the individual works permit. 6684 Inclusion of a covered work in an aggregate does not cause this 6685 License to apply to the other parts of the aggregate. 6686 6687 6. Conveying Non-Source Forms. 6688 6689 You may convey a covered work in object code form under the terms 6690 of sections 4 and 5, provided that you also convey the 6691 machine-readable Corresponding Source under the terms of this 6692 License, in one of these ways: 6693 6694 a. Convey the object code in, or embodied in, a physical product 6695 (including a physical distribution medium), accompanied by the 6696 Corresponding Source fixed on a durable physical medium 6697 customarily used for software interchange. 6698 6699 b. Convey the object code in, or embodied in, a physical product 6700 (including a physical distribution medium), accompanied by a 6701 written offer, valid for at least three years and valid for as 6702 long as you offer spare parts or customer support for that 6703 product model, to give anyone who possesses the object code 6704 either (1) a copy of the Corresponding Source for all the 6705 software in the product that is covered by this License, on a 6706 durable physical medium customarily used for software 6707 interchange, for a price no more than your reasonable cost of 6708 physically performing this conveying of source, or (2) access 6709 to copy the Corresponding Source from a network server at no 6710 charge. 6711 6712 c. Convey individual copies of the object code with a copy of the 6713 written offer to provide the Corresponding Source. This 6714 alternative is allowed only occasionally and noncommercially, 6715 and only if you received the object code with such an offer, 6716 in accord with subsection 6b. 6717 6718 d. Convey the object code by offering access from a designated 6719 place (gratis or for a charge), and offer equivalent access to 6720 the Corresponding Source in the same way through the same 6721 place at no further charge. You need not require recipients 6722 to copy the Corresponding Source along with the object code. 6723 If the place to copy the object code is a network server, the 6724 Corresponding Source may be on a different server (operated by 6725 you or a third party) that supports equivalent copying 6726 facilities, provided you maintain clear directions next to the 6727 object code saying where to find the Corresponding Source. 6728 Regardless of what server hosts the Corresponding Source, you 6729 remain obligated to ensure that it is available for as long as 6730 needed to satisfy these requirements. 6731 6732 e. Convey the object code using peer-to-peer transmission, 6733 provided you inform other peers where the object code and 6734 Corresponding Source of the work are being offered to the 6735 general public at no charge under subsection 6d. 6736 6737 A separable portion of the object code, whose source code is 6738 excluded from the Corresponding Source as a System Library, need 6739 not be included in conveying the object code work. 6740 6741 A "User Product" is either (1) a "consumer product", which means 6742 any tangible personal property which is normally used for personal, 6743 family, or household purposes, or (2) anything designed or sold for 6744 incorporation into a dwelling. In determining whether a product is 6745 a consumer product, doubtful cases shall be resolved in favor of 6746 coverage. For a particular product received by a particular user, 6747 "normally used" refers to a typical or common use of that class of 6748 product, regardless of the status of the particular user or of the 6749 way in which the particular user actually uses, or expects or is 6750 expected to use, the product. A product is a consumer product 6751 regardless of whether the product has substantial commercial, 6752 industrial or non-consumer uses, unless such uses represent the 6753 only significant mode of use of the product. 6754 6755 "Installation Information" for a User Product means any methods, 6756 procedures, authorization keys, or other information required to 6757 install and execute modified versions of a covered work in that 6758 User Product from a modified version of its Corresponding Source. 6759 The information must suffice to ensure that the continued 6760 functioning of the modified object code is in no case prevented or 6761 interfered with solely because modification has been made. 6762 6763 If you convey an object code work under this section in, or with, 6764 or specifically for use in, a User Product, and the conveying 6765 occurs as part of a transaction in which the right of possession 6766 and use of the User Product is transferred to the recipient in 6767 perpetuity or for a fixed term (regardless of how the transaction 6768 is characterized), the Corresponding Source conveyed under this 6769 section must be accompanied by the Installation Information. But 6770 this requirement does not apply if neither you nor any third party 6771 retains the ability to install modified object code on the User 6772 Product (for example, the work has been installed in ROM). 6773 6774 The requirement to provide Installation Information does not 6775 include a requirement to continue to provide support service, 6776 warranty, or updates for a work that has been modified or installed 6777 by the recipient, or for the User Product in which it has been 6778 modified or installed. Access to a network may be denied when the 6779 modification itself materially and adversely affects the operation 6780 of the network or violates the rules and protocols for 6781 communication across the network. 6782 6783 Corresponding Source conveyed, and Installation Information 6784 provided, in accord with this section must be in a format that is 6785 publicly documented (and with an implementation available to the 6786 public in source code form), and must require no special password 6787 or key for unpacking, reading or copying. 6788 6789 7. Additional Terms. 6790 6791 "Additional permissions" are terms that supplement the terms of 6792 this License by making exceptions from one or more of its 6793 conditions. Additional permissions that are applicable to the 6794 entire Program shall be treated as though they were included in 6795 this License, to the extent that they are valid under applicable 6796 law. If additional permissions apply only to part of the Program, 6797 that part may be used separately under those permissions, but the 6798 entire Program remains governed by this License without regard to 6799 the additional permissions. 6800 6801 When you convey a copy of a covered work, you may at your option 6802 remove any additional permissions from that copy, or from any part 6803 of it. (Additional permissions may be written to require their own 6804 removal in certain cases when you modify the work.) You may place 6805 additional permissions on material, added by you to a covered work, 6806 for which you have or can give appropriate copyright permission. 6807 6808 Notwithstanding any other provision of this License, for material 6809 you add to a covered work, you may (if authorized by the copyright 6810 holders of that material) supplement the terms of this License with 6811 terms: 6812 6813 a. Disclaiming warranty or limiting liability differently from 6814 the terms of sections 15 and 16 of this License; or 6815 6816 b. Requiring preservation of specified reasonable legal notices 6817 or author attributions in that material or in the Appropriate 6818 Legal Notices displayed by works containing it; or 6819 6820 c. Prohibiting misrepresentation of the origin of that material, 6821 or requiring that modified versions of such material be marked 6822 in reasonable ways as different from the original version; or 6823 6824 d. Limiting the use for publicity purposes of names of licensors 6825 or authors of the material; or 6826 6827 e. Declining to grant rights under trademark law for use of some 6828 trade names, trademarks, or service marks; or 6829 6830 f. Requiring indemnification of licensors and authors of that 6831 material by anyone who conveys the material (or modified 6832 versions of it) with contractual assumptions of liability to 6833 the recipient, for any liability that these contractual 6834 assumptions directly impose on those licensors and authors. 6835 6836 All other non-permissive additional terms are considered "further 6837 restrictions" within the meaning of section 10. If the Program as 6838 you received it, or any part of it, contains a notice stating that 6839 it is governed by this License along with a term that is a further 6840 restriction, you may remove that term. If a license document 6841 contains a further restriction but permits relicensing or conveying 6842 under this License, you may add to a covered work material governed 6843 by the terms of that license document, provided that the further 6844 restriction does not survive such relicensing or conveying. 6845 6846 If you add terms to a covered work in accord with this section, you 6847 must place, in the relevant source files, a statement of the 6848 additional terms that apply to those files, or a notice indicating 6849 where to find the applicable terms. 6850 6851 Additional terms, permissive or non-permissive, may be stated in 6852 the form of a separately written license, or stated as exceptions; 6853 the above requirements apply either way. 6854 6855 8. Termination. 6856 6857 You may not propagate or modify a covered work except as expressly 6858 provided under this License. Any attempt otherwise to propagate or 6859 modify it is void, and will automatically terminate your rights 6860 under this License (including any patent licenses granted under the 6861 third paragraph of section 11). 6862 6863 However, if you cease all violation of this License, then your 6864 license from a particular copyright holder is reinstated (a) 6865 provisionally, unless and until the copyright holder explicitly and 6866 finally terminates your license, and (b) permanently, if the 6867 copyright holder fails to notify you of the violation by some 6868 reasonable means prior to 60 days after the cessation. 6869 6870 Moreover, your license from a particular copyright holder is 6871 reinstated permanently if the copyright holder notifies you of the 6872 violation by some reasonable means, this is the first time you have 6873 received notice of violation of this License (for any work) from 6874 that copyright holder, and you cure the violation prior to 30 days 6875 after your receipt of the notice. 6876 6877 Termination of your rights under this section does not terminate 6878 the licenses of parties who have received copies or rights from you 6879 under this License. If your rights have been terminated and not 6880 permanently reinstated, you do not qualify to receive new licenses 6881 for the same material under section 10. 6882 6883 9. Acceptance Not Required for Having Copies. 6884 6885 You are not required to accept this License in order to receive or 6886 run a copy of the Program. Ancillary propagation of a covered work 6887 occurring solely as a consequence of using peer-to-peer 6888 transmission to receive a copy likewise does not require 6889 acceptance. However, nothing other than this License grants you 6890 permission to propagate or modify any covered work. These actions 6891 infringe copyright if you do not accept this License. Therefore, 6892 by modifying or propagating a covered work, you indicate your 6893 acceptance of this License to do so. 6894 6895 10. Automatic Licensing of Downstream Recipients. 6896 6897 Each time you convey a covered work, the recipient automatically 6898 receives a license from the original licensors, to run, modify and 6899 propagate that work, subject to this License. You are not 6900 responsible for enforcing compliance by third parties with this 6901 License. 6902 6903 An "entity transaction" is a transaction transferring control of an 6904 organization, or substantially all assets of one, or subdividing an 6905 organization, or merging organizations. If propagation of a 6906 covered work results from an entity transaction, each party to that 6907 transaction who receives a copy of the work also receives whatever 6908 licenses to the work the party's predecessor in interest had or 6909 could give under the previous paragraph, plus a right to possession 6910 of the Corresponding Source of the work from the predecessor in 6911 interest, if the predecessor has it or can get it with reasonable 6912 efforts. 6913 6914 You may not impose any further restrictions on the exercise of the 6915 rights granted or affirmed under this License. For example, you 6916 may not impose a license fee, royalty, or other charge for exercise 6917 of rights granted under this License, and you may not initiate 6918 litigation (including a cross-claim or counterclaim in a lawsuit) 6919 alleging that any patent claim is infringed by making, using, 6920 selling, offering for sale, or importing the Program or any portion 6921 of it. 6922 6923 11. Patents. 6924 6925 A "contributor" is a copyright holder who authorizes use under this 6926 License of the Program or a work on which the Program is based. 6927 The work thus licensed is called the contributor's "contributor 6928 version". 6929 6930 A contributor's "essential patent claims" are all patent claims 6931 owned or controlled by the contributor, whether already acquired or 6932 hereafter acquired, that would be infringed by some manner, 6933 permitted by this License, of making, using, or selling its 6934 contributor version, but do not include claims that would be 6935 infringed only as a consequence of further modification of the 6936 contributor version. For purposes of this definition, "control" 6937 includes the right to grant patent sublicenses in a manner 6938 consistent with the requirements of this License. 6939 6940 Each contributor grants you a non-exclusive, worldwide, 6941 royalty-free patent license under the contributor's essential 6942 patent claims, to make, use, sell, offer for sale, import and 6943 otherwise run, modify and propagate the contents of its contributor 6944 version. 6945 6946 In the following three paragraphs, a "patent license" is any 6947 express agreement or commitment, however denominated, not to 6948 enforce a patent (such as an express permission to practice a 6949 patent or covenant not to sue for patent infringement). To "grant" 6950 such a patent license to a party means to make such an agreement or 6951 commitment not to enforce a patent against the party. 6952 6953 If you convey a covered work, knowingly relying on a patent 6954 license, and the Corresponding Source of the work is not available 6955 for anyone to copy, free of charge and under the terms of this 6956 License, through a publicly available network server or other 6957 readily accessible means, then you must either (1) cause the 6958 Corresponding Source to be so available, or (2) arrange to deprive 6959 yourself of the benefit of the patent license for this particular 6960 work, or (3) arrange, in a manner consistent with the requirements 6961 of this License, to extend the patent license to downstream 6962 recipients. "Knowingly relying" means you have actual knowledge 6963 that, but for the patent license, your conveying the covered work 6964 in a country, or your recipient's use of the covered work in a 6965 country, would infringe one or more identifiable patents in that 6966 country that you have reason to believe are valid. 6967 6968 If, pursuant to or in connection with a single transaction or 6969 arrangement, you convey, or propagate by procuring conveyance of, a 6970 covered work, and grant a patent license to some of the parties 6971 receiving the covered work authorizing them to use, propagate, 6972 modify or convey a specific copy of the covered work, then the 6973 patent license you grant is automatically extended to all 6974 recipients of the covered work and works based on it. 6975 6976 A patent license is "discriminatory" if it does not include within 6977 the scope of its coverage, prohibits the exercise of, or is 6978 conditioned on the non-exercise of one or more of the rights that 6979 are specifically granted under this License. You may not convey a 6980 covered work if you are a party to an arrangement with a third 6981 party that is in the business of distributing software, under which 6982 you make payment to the third party based on the extent of your 6983 activity of conveying the work, and under which the third party 6984 grants, to any of the parties who would receive the covered work 6985 from you, a discriminatory patent license (a) in connection with 6986 copies of the covered work conveyed by you (or copies made from 6987 those copies), or (b) primarily for and in connection with specific 6988 products or compilations that contain the covered work, unless you 6989 entered into that arrangement, or that patent license was granted, 6990 prior to 28 March 2007. 6991 6992 Nothing in this License shall be construed as excluding or limiting 6993 any implied license or other defenses to infringement that may 6994 otherwise be available to you under applicable patent law. 6995 6996 12. No Surrender of Others' Freedom. 6997 6998 If conditions are imposed on you (whether by court order, agreement 6999 or otherwise) that contradict the conditions of this License, they 7000 do not excuse you from the conditions of this License. If you 7001 cannot convey a covered work so as to satisfy simultaneously your 7002 obligations under this License and any other pertinent obligations, 7003 then as a consequence you may not convey it at all. For example, 7004 if you agree to terms that obligate you to collect a royalty for 7005 further conveying from those to whom you convey the Program, the 7006 only way you could satisfy both those terms and this License would 7007 be to refrain entirely from conveying the Program. 7008 7009 13. Use with the GNU Affero General Public License. 7010 7011 Notwithstanding any other provision of this License, you have 7012 permission to link or combine any covered work with a work licensed 7013 under version 3 of the GNU Affero General Public License into a 7014 single combined work, and to convey the resulting work. The terms 7015 of this License will continue to apply to the part which is the 7016 covered work, but the special requirements of the GNU Affero 7017 General Public License, section 13, concerning interaction through 7018 a network will apply to the combination as such. 7019 7020 14. Revised Versions of this License. 7021 7022 The Free Software Foundation may publish revised and/or new 7023 versions of the GNU General Public License from time to time. Such 7024 new versions will be similar in spirit to the present version, but 7025 may differ in detail to address new problems or concerns. 7026 7027 Each version is given a distinguishing version number. If the 7028 Program specifies that a certain numbered version of the GNU 7029 General Public License "or any later version" applies to it, you 7030 have the option of following the terms and conditions either of 7031 that numbered version or of any later version published by the Free 7032 Software Foundation. If the Program does not specify a version 7033 number of the GNU General Public License, you may choose any 7034 version ever published by the Free Software Foundation. 7035 7036 If the Program specifies that a proxy can decide which future 7037 versions of the GNU General Public License can be used, that 7038 proxy's public statement of acceptance of a version permanently 7039 authorizes you to choose that version for the Program. 7040 7041 Later license versions may give you additional or different 7042 permissions. However, no additional obligations are imposed on any 7043 author or copyright holder as a result of your choosing to follow a 7044 later version. 7045 7046 15. Disclaimer of Warranty. 7047 7048 THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY 7049 APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE 7050 COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" 7051 WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, 7052 INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 7053 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE 7054 RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. 7055 SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL 7056 NECESSARY SERVICING, REPAIR OR CORRECTION. 7057 7058 16. Limitation of Liability. 7059 7060 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN 7061 WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES 7062 AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR 7063 DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR 7064 CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE 7065 THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA 7066 BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD 7067 PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER 7068 PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF 7069 THE POSSIBILITY OF SUCH DAMAGES. 7070 7071 17. Interpretation of Sections 15 and 16. 7072 7073 If the disclaimer of warranty and limitation of liability provided 7074 above cannot be given local legal effect according to their terms, 7075 reviewing courts shall apply local law that most closely 7076 approximates an absolute waiver of all civil liability in 7077 connection with the Program, unless a warranty or assumption of 7078 liability accompanies a copy of the Program in return for a fee. 7079 7080 END OF TERMS AND CONDITIONS 7081 =========================== 7082 7083 How to Apply These Terms to Your New Programs 7084 ============================================= 7085 7086 If you develop a new program, and you want it to be of the greatest 7087 possible use to the public, the best way to achieve this is to make it 7088 free software which everyone can redistribute and change under these 7089 terms. 7090 7091 To do so, attach the following notices to the program. It is safest 7092 to attach them to the start of each source file to most effectively 7093 state the exclusion of warranty; and each file should have at least the 7094 "copyright" line and a pointer to where the full notice is found. 7095 7096 ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES. 7097 Copyright (C) YEAR NAME OF AUTHOR 7098 7099 This program is free software: you can redistribute it and/or modify 7100 it under the terms of the GNU General Public License as published by 7101 the Free Software Foundation, either version 3 of the License, or (at 7102 your option) any later version. 7103 7104 This program is distributed in the hope that it will be useful, but 7105 WITHOUT ANY WARRANTY; without even the implied warranty of 7106 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 7107 General Public License for more details. 7108 7109 You should have received a copy of the GNU General Public License 7110 along with this program. If not, see <https://www.gnu.org/licenses/>. 7111 7112 Also add information on how to contact you by electronic and paper 7113 mail. 7114 7115 If the program does terminal interaction, make it output a short 7116 notice like this when it starts in an interactive mode: 7117 7118 PROGRAM Copyright (C) YEAR NAME OF AUTHOR 7119 This program comes with ABSOLUTELY NO WARRANTY; for details type 'show w'. 7120 This is free software, and you are welcome to redistribute it 7121 under certain conditions; type 'show c' for details. 7122 7123 The hypothetical commands 'show w' and 'show c' should show the 7124 appropriate parts of the General Public License. Of course, your 7125 program's commands might be different; for a GUI interface, you would 7126 use an "about box". 7127 7128 You should also get your employer (if you work as a programmer) or 7129 school, if any, to sign a "copyright disclaimer" for the program, if 7130 necessary. For more information on this, and how to apply and follow 7131 the GNU GPL, see <https://www.gnu.org/licenses/>. 7132 7133 The GNU General Public License does not permit incorporating your 7134 program into proprietary programs. If your program is a subroutine 7135 library, you may consider it more useful to permit linking proprietary 7136 applications with the library. If this is what you want to do, use the 7137 GNU Lesser General Public License instead of this License. But first, 7138 please read <https://www.gnu.org/licenses/why-not-lgpl.html>. 7139 7140 7141 File: libgomp.info, Node: GNU Free Documentation License, Next: Funding, Prev: Copying, Up: Top 7142 7143 GNU Free Documentation License 7144 ****************************** 7145 7146 Version 1.3, 3 November 2008 7147 7148 Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. 7149 <https://www.fsf.org> 7150 7151 Everyone is permitted to copy and distribute verbatim copies 7152 of this license document, but changing it is not allowed. 7153 7154 0. PREAMBLE 7155 7156 The purpose of this License is to make a manual, textbook, or other 7157 functional and useful document "free" in the sense of freedom: to 7158 assure everyone the effective freedom to copy and redistribute it, 7159 with or without modifying it, either commercially or 7160 noncommercially. Secondarily, this License preserves for the 7161 author and publisher a way to get credit for their work, while not 7162 being considered responsible for modifications made by others. 7163 7164 This License is a kind of "copyleft", which means that derivative 7165 works of the document must themselves be free in the same sense. 7166 It complements the GNU General Public License, which is a copyleft 7167 license designed for free software. 7168 7169 We have designed this License in order to use it for manuals for 7170 free software, because free software needs free documentation: a 7171 free program should come with manuals providing the same freedoms 7172 that the software does. But this License is not limited to 7173 software manuals; it can be used for any textual work, regardless 7174 of subject matter or whether it is published as a printed book. We 7175 recommend this License principally for works whose purpose is 7176 instruction or reference. 7177 7178 1. APPLICABILITY AND DEFINITIONS 7179 7180 This License applies to any manual or other work, in any medium, 7181 that contains a notice placed by the copyright holder saying it can 7182 be distributed under the terms of this License. Such a notice 7183 grants a world-wide, royalty-free license, unlimited in duration, 7184 to use that work under the conditions stated herein. The 7185 "Document", below, refers to any such manual or work. Any member 7186 of the public is a licensee, and is addressed as "you". You accept 7187 the license if you copy, modify or distribute the work in a way 7188 requiring permission under copyright law. 7189 7190 A "Modified Version" of the Document means any work containing the 7191 Document or a portion of it, either copied verbatim, or with 7192 modifications and/or translated into another language. 7193 7194 A "Secondary Section" is a named appendix or a front-matter section 7195 of the Document that deals exclusively with the relationship of the 7196 publishers or authors of the Document to the Document's overall 7197 subject (or to related matters) and contains nothing that could 7198 fall directly within that overall subject. (Thus, if the Document 7199 is in part a textbook of mathematics, a Secondary Section may not 7200 explain any mathematics.) The relationship could be a matter of 7201 historical connection with the subject or with related matters, or 7202 of legal, commercial, philosophical, ethical or political position 7203 regarding them. 7204 7205 The "Invariant Sections" are certain Secondary Sections whose 7206 titles are designated, as being those of Invariant Sections, in the 7207 notice that says that the Document is released under this License. 7208 If a section does not fit the above definition of Secondary then it 7209 is not allowed to be designated as Invariant. The Document may 7210 contain zero Invariant Sections. If the Document does not identify 7211 any Invariant Sections then there are none. 7212 7213 The "Cover Texts" are certain short passages of text that are 7214 listed, as Front-Cover Texts or Back-Cover Texts, in the notice 7215 that says that the Document is released under this License. A 7216 Front-Cover Text may be at most 5 words, and a Back-Cover Text may 7217 be at most 25 words. 7218 7219 A "Transparent" copy of the Document means a machine-readable copy, 7220 represented in a format whose specification is available to the 7221 general public, that is suitable for revising the document 7222 straightforwardly with generic text editors or (for images composed 7223 of pixels) generic paint programs or (for drawings) some widely 7224 available drawing editor, and that is suitable for input to text 7225 formatters or for automatic translation to a variety of formats 7226 suitable for input to text formatters. A copy made in an otherwise 7227 Transparent file format whose markup, or absence of markup, has 7228 been arranged to thwart or discourage subsequent modification by 7229 readers is not Transparent. An image format is not Transparent if 7230 used for any substantial amount of text. A copy that is not 7231 "Transparent" is called "Opaque". 7232 7233 Examples of suitable formats for Transparent copies include plain 7234 ASCII without markup, Texinfo input format, LaTeX input format, 7235 SGML or XML using a publicly available DTD, and standard-conforming 7236 simple HTML, PostScript or PDF designed for human modification. 7237 Examples of transparent image formats include PNG, XCF and JPG. 7238 Opaque formats include proprietary formats that can be read and 7239 edited only by proprietary word processors, SGML or XML for which 7240 the DTD and/or processing tools are not generally available, and 7241 the machine-generated HTML, PostScript or PDF produced by some word 7242 processors for output purposes only. 7243 7244 The "Title Page" means, for a printed book, the title page itself, 7245 plus such following pages as are needed to hold, legibly, the 7246 material this License requires to appear in the title page. For 7247 works in formats which do not have any title page as such, "Title 7248 Page" means the text near the most prominent appearance of the 7249 work's title, preceding the beginning of the body of the text. 7250 7251 The "publisher" means any person or entity that distributes copies 7252 of the Document to the public. 7253 7254 A section "Entitled XYZ" means a named subunit of the Document 7255 whose title either is precisely XYZ or contains XYZ in parentheses 7256 following text that translates XYZ in another language. (Here XYZ 7257 stands for a specific section name mentioned below, such as 7258 "Acknowledgements", "Dedications", "Endorsements", or "History".) 7259 To "Preserve the Title" of such a section when you modify the 7260 Document means that it remains a section "Entitled XYZ" according 7261 to this definition. 7262 7263 The Document may include Warranty Disclaimers next to the notice 7264 which states that this License applies to the Document. These 7265 Warranty Disclaimers are considered to be included by reference in 7266 this License, but only as regards disclaiming warranties: any other 7267 implication that these Warranty Disclaimers may have is void and 7268 has no effect on the meaning of this License. 7269 7270 2. VERBATIM COPYING 7271 7272 You may copy and distribute the Document in any medium, either 7273 commercially or noncommercially, provided that this License, the 7274 copyright notices, and the license notice saying this License 7275 applies to the Document are reproduced in all copies, and that you 7276 add no other conditions whatsoever to those of this License. You 7277 may not use technical measures to obstruct or control the reading 7278 or further copying of the copies you make or distribute. However, 7279 you may accept compensation in exchange for copies. If you 7280 distribute a large enough number of copies you must also follow the 7281 conditions in section 3. 7282 7283 You may also lend copies, under the same conditions stated above, 7284 and you may publicly display copies. 7285 7286 3. COPYING IN QUANTITY 7287 7288 If you publish printed copies (or copies in media that commonly 7289 have printed covers) of the Document, numbering more than 100, and 7290 the Document's license notice requires Cover Texts, you must 7291 enclose the copies in covers that carry, clearly and legibly, all 7292 these Cover Texts: Front-Cover Texts on the front cover, and 7293 Back-Cover Texts on the back cover. Both covers must also clearly 7294 and legibly identify you as the publisher of these copies. The 7295 front cover must present the full title with all words of the title 7296 equally prominent and visible. You may add other material on the 7297 covers in addition. Copying with changes limited to the covers, as 7298 long as they preserve the title of the Document and satisfy these 7299 conditions, can be treated as verbatim copying in other respects. 7300 7301 If the required texts for either cover are too voluminous to fit 7302 legibly, you should put the first ones listed (as many as fit 7303 reasonably) on the actual cover, and continue the rest onto 7304 adjacent pages. 7305 7306 If you publish or distribute Opaque copies of the Document 7307 numbering more than 100, you must either include a machine-readable 7308 Transparent copy along with each Opaque copy, or state in or with 7309 each Opaque copy a computer-network location from which the general 7310 network-using public has access to download using public-standard 7311 network protocols a complete Transparent copy of the Document, free 7312 of added material. If you use the latter option, you must take 7313 reasonably prudent steps, when you begin distribution of Opaque 7314 copies in quantity, to ensure that this Transparent copy will 7315 remain thus accessible at the stated location until at least one 7316 year after the last time you distribute an Opaque copy (directly or 7317 through your agents or retailers) of that edition to the public. 7318 7319 It is requested, but not required, that you contact the authors of 7320 the Document well before redistributing any large number of copies, 7321 to give them a chance to provide you with an updated version of the 7322 Document. 7323 7324 4. MODIFICATIONS 7325 7326 You may copy and distribute a Modified Version of the Document 7327 under the conditions of sections 2 and 3 above, provided that you 7328 release the Modified Version under precisely this License, with the 7329 Modified Version filling the role of the Document, thus licensing 7330 distribution and modification of the Modified Version to whoever 7331 possesses a copy of it. In addition, you must do these things in 7332 the Modified Version: 7333 7334 A. Use in the Title Page (and on the covers, if any) a title 7335 distinct from that of the Document, and from those of previous 7336 versions (which should, if there were any, be listed in the 7337 History section of the Document). You may use the same title 7338 as a previous version if the original publisher of that 7339 version gives permission. 7340 7341 B. List on the Title Page, as authors, one or more persons or 7342 entities responsible for authorship of the modifications in 7343 the Modified Version, together with at least five of the 7344 principal authors of the Document (all of its principal 7345 authors, if it has fewer than five), unless they release you 7346 from this requirement. 7347 7348 C. State on the Title page the name of the publisher of the 7349 Modified Version, as the publisher. 7350 7351 D. Preserve all the copyright notices of the Document. 7352 7353 E. Add an appropriate copyright notice for your modifications 7354 adjacent to the other copyright notices. 7355 7356 F. Include, immediately after the copyright notices, a license 7357 notice giving the public permission to use the Modified 7358 Version under the terms of this License, in the form shown in 7359 the Addendum below. 7360 7361 G. Preserve in that license notice the full lists of Invariant 7362 Sections and required Cover Texts given in the Document's 7363 license notice. 7364 7365 H. Include an unaltered copy of this License. 7366 7367 I. Preserve the section Entitled "History", Preserve its Title, 7368 and add to it an item stating at least the title, year, new 7369 authors, and publisher of the Modified Version as given on the 7370 Title Page. If there is no section Entitled "History" in the 7371 Document, create one stating the title, year, authors, and 7372 publisher of the Document as given on its Title Page, then add 7373 an item describing the Modified Version as stated in the 7374 previous sentence. 7375 7376 J. Preserve the network location, if any, given in the Document 7377 for public access to a Transparent copy of the Document, and 7378 likewise the network locations given in the Document for 7379 previous versions it was based on. These may be placed in the 7380 "History" section. You may omit a network location for a work 7381 that was published at least four years before the Document 7382 itself, or if the original publisher of the version it refers 7383 to gives permission. 7384 7385 K. For any section Entitled "Acknowledgements" or "Dedications", 7386 Preserve the Title of the section, and preserve in the section 7387 all the substance and tone of each of the contributor 7388 acknowledgements and/or dedications given therein. 7389 7390 L. Preserve all the Invariant Sections of the Document, unaltered 7391 in their text and in their titles. Section numbers or the 7392 equivalent are not considered part of the section titles. 7393 7394 M. Delete any section Entitled "Endorsements". Such a section 7395 may not be included in the Modified Version. 7396 7397 N. Do not retitle any existing section to be Entitled 7398 "Endorsements" or to conflict in title with any Invariant 7399 Section. 7400 7401 O. Preserve any Warranty Disclaimers. 7402 7403 If the Modified Version includes new front-matter sections or 7404 appendices that qualify as Secondary Sections and contain no 7405 material copied from the Document, you may at your option designate 7406 some or all of these sections as invariant. To do this, add their 7407 titles to the list of Invariant Sections in the Modified Version's 7408 license notice. These titles must be distinct from any other 7409 section titles. 7410 7411 You may add a section Entitled "Endorsements", provided it contains 7412 nothing but endorsements of your Modified Version by various 7413 parties--for example, statements of peer review or that the text 7414 has been approved by an organization as the authoritative 7415 definition of a standard. 7416 7417 You may add a passage of up to five words as a Front-Cover Text, 7418 and a passage of up to 25 words as a Back-Cover Text, to the end of 7419 the list of Cover Texts in the Modified Version. Only one passage 7420 of Front-Cover Text and one of Back-Cover Text may be added by (or 7421 through arrangements made by) any one entity. If the Document 7422 already includes a cover text for the same cover, previously added 7423 by you or by arrangement made by the same entity you are acting on 7424 behalf of, you may not add another; but you may replace the old 7425 one, on explicit permission from the previous publisher that added 7426 the old one. 7427 7428 The author(s) and publisher(s) of the Document do not by this 7429 License give permission to use their names for publicity for or to 7430 assert or imply endorsement of any Modified Version. 7431 7432 5. COMBINING DOCUMENTS 7433 7434 You may combine the Document with other documents released under 7435 this License, under the terms defined in section 4 above for 7436 modified versions, provided that you include in the combination all 7437 of the Invariant Sections of all of the original documents, 7438 unmodified, and list them all as Invariant Sections of your 7439 combined work in its license notice, and that you preserve all 7440 their Warranty Disclaimers. 7441 7442 The combined work need only contain one copy of this License, and 7443 multiple identical Invariant Sections may be replaced with a single 7444 copy. If there are multiple Invariant Sections with the same name 7445 but different contents, make the title of each such section unique 7446 by adding at the end of it, in parentheses, the name of the 7447 original author or publisher of that section if known, or else a 7448 unique number. Make the same adjustment to the section titles in 7449 the list of Invariant Sections in the license notice of the 7450 combined work. 7451 7452 In the combination, you must combine any sections Entitled 7453 "History" in the various original documents, forming one section 7454 Entitled "History"; likewise combine any sections Entitled 7455 "Acknowledgements", and any sections Entitled "Dedications". You 7456 must delete all sections Entitled "Endorsements." 7457 7458 6. COLLECTIONS OF DOCUMENTS 7459 7460 You may make a collection consisting of the Document and other 7461 documents released under this License, and replace the individual 7462 copies of this License in the various documents with a single copy 7463 that is included in the collection, provided that you follow the 7464 rules of this License for verbatim copying of each of the documents 7465 in all other respects. 7466 7467 You may extract a single document from such a collection, and 7468 distribute it individually under this License, provided you insert 7469 a copy of this License into the extracted document, and follow this 7470 License in all other respects regarding verbatim copying of that 7471 document. 7472 7473 7. AGGREGATION WITH INDEPENDENT WORKS 7474 7475 A compilation of the Document or its derivatives with other 7476 separate and independent documents or works, in or on a volume of a 7477 storage or distribution medium, is called an "aggregate" if the 7478 copyright resulting from the compilation is not used to limit the 7479 legal rights of the compilation's users beyond what the individual 7480 works permit. When the Document is included in an aggregate, this 7481 License does not apply to the other works in the aggregate which 7482 are not themselves derivative works of the Document. 7483 7484 If the Cover Text requirement of section 3 is applicable to these 7485 copies of the Document, then if the Document is less than one half 7486 of the entire aggregate, the Document's Cover Texts may be placed 7487 on covers that bracket the Document within the aggregate, or the 7488 electronic equivalent of covers if the Document is in electronic 7489 form. Otherwise they must appear on printed covers that bracket 7490 the whole aggregate. 7491 7492 8. TRANSLATION 7493 7494 Translation is considered a kind of modification, so you may 7495 distribute translations of the Document under the terms of section 7496 4. Replacing Invariant Sections with translations requires special 7497 permission from their copyright holders, but you may include 7498 translations of some or all Invariant Sections in addition to the 7499 original versions of these Invariant Sections. You may include a 7500 translation of this License, and all the license notices in the 7501 Document, and any Warranty Disclaimers, provided that you also 7502 include the original English version of this License and the 7503 original versions of those notices and disclaimers. In case of a 7504 disagreement between the translation and the original version of 7505 this License or a notice or disclaimer, the original version will 7506 prevail. 7507 7508 If a section in the Document is Entitled "Acknowledgements", 7509 "Dedications", or "History", the requirement (section 4) to 7510 Preserve its Title (section 1) will typically require changing the 7511 actual title. 7512 7513 9. TERMINATION 7514 7515 You may not copy, modify, sublicense, or distribute the Document 7516 except as expressly provided under this License. Any attempt 7517 otherwise to copy, modify, sublicense, or distribute it is void, 7518 and will automatically terminate your rights under this License. 7519 7520 However, if you cease all violation of this License, then your 7521 license from a particular copyright holder is reinstated (a) 7522 provisionally, unless and until the copyright holder explicitly and 7523 finally terminates your license, and (b) permanently, if the 7524 copyright holder fails to notify you of the violation by some 7525 reasonable means prior to 60 days after the cessation. 7526 7527 Moreover, your license from a particular copyright holder is 7528 reinstated permanently if the copyright holder notifies you of the 7529 violation by some reasonable means, this is the first time you have 7530 received notice of violation of this License (for any work) from 7531 that copyright holder, and you cure the violation prior to 30 days 7532 after your receipt of the notice. 7533 7534 Termination of your rights under this section does not terminate 7535 the licenses of parties who have received copies or rights from you 7536 under this License. If your rights have been terminated and not 7537 permanently reinstated, receipt of a copy of some or all of the 7538 same material does not give you any rights to use it. 7539 7540 10. FUTURE REVISIONS OF THIS LICENSE 7541 7542 The Free Software Foundation may publish new, revised versions of 7543 the GNU Free Documentation License from time to time. Such new 7544 versions will be similar in spirit to the present version, but may 7545 differ in detail to address new problems or concerns. See 7546 <https://www.gnu.org/copyleft/>. 7547 7548 Each version of the License is given a distinguishing version 7549 number. If the Document specifies that a particular numbered 7550 version of this License "or any later version" applies to it, you 7551 have the option of following the terms and conditions either of 7552 that specified version or of any later version that has been 7553 published (not as a draft) by the Free Software Foundation. If the 7554 Document does not specify a version number of this License, you may 7555 choose any version ever published (not as a draft) by the Free 7556 Software Foundation. If the Document specifies that a proxy can 7557 decide which future versions of this License can be used, that 7558 proxy's public statement of acceptance of a version permanently 7559 authorizes you to choose that version for the Document. 7560 7561 11. RELICENSING 7562 7563 "Massive Multiauthor Collaboration Site" (or "MMC Site") means any 7564 World Wide Web server that publishes copyrightable works and also 7565 provides prominent facilities for anybody to edit those works. A 7566 public wiki that anybody can edit is an example of such a server. 7567 A "Massive Multiauthor Collaboration" (or "MMC") contained in the 7568 site means any set of copyrightable works thus published on the MMC 7569 site. 7570 7571 "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 7572 license published by Creative Commons Corporation, a not-for-profit 7573 corporation with a principal place of business in San Francisco, 7574 California, as well as future copyleft versions of that license 7575 published by that same organization. 7576 7577 "Incorporate" means to publish or republish a Document, in whole or 7578 in part, as part of another Document. 7579 7580 An MMC is "eligible for relicensing" if it is licensed under this 7581 License, and if all works that were first published under this 7582 License somewhere other than this MMC, and subsequently 7583 incorporated in whole or in part into the MMC, (1) had no cover 7584 texts or invariant sections, and (2) were thus incorporated prior 7585 to November 1, 2008. 7586 7587 The operator of an MMC Site may republish an MMC contained in the 7588 site under CC-BY-SA on the same site at any time before August 1, 7589 2009, provided the MMC is eligible for relicensing. 7590 7591 ADDENDUM: How to use this License for your documents 7592 ==================================================== 7593 7594 To use this License in a document you have written, include a copy of 7595 the License in the document and put the following copyright and license 7596 notices just after the title page: 7597 7598 Copyright (C) YEAR YOUR NAME. 7599 Permission is granted to copy, distribute and/or modify this document 7600 under the terms of the GNU Free Documentation License, Version 1.3 7601 or any later version published by the Free Software Foundation; 7602 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover 7603 Texts. A copy of the license is included in the section entitled ``GNU 7604 Free Documentation License''. 7605 7606 If you have Invariant Sections, Front-Cover Texts and Back-Cover 7607 Texts, replace the "with...Texts." line with this: 7608 7609 with the Invariant Sections being LIST THEIR TITLES, with 7610 the Front-Cover Texts being LIST, and with the Back-Cover Texts 7611 being LIST. 7612 7613 If you have Invariant Sections without Cover Texts, or some other 7614 combination of the three, merge those two alternatives to suit the 7615 situation. 7616 7617 If your document contains nontrivial examples of program code, we 7618 recommend releasing these examples in parallel under your choice of free 7619 software license, such as the GNU General Public License, to permit 7620 their use in free software. 7621 7622 7623 File: libgomp.info, Node: Funding, Next: Library Index, Prev: GNU Free Documentation License, Up: Top 7624 7625 Funding Free Software 7626 ********************* 7627 7628 If you want to have more free software a few years from now, it makes 7629 sense for you to help encourage people to contribute funds for its 7630 development. The most effective approach known is to encourage 7631 commercial redistributors to donate. 7632 7633 Users of free software systems can boost the pace of development by 7634 encouraging for-a-fee distributors to donate part of their selling price 7635 to free software developers--the Free Software Foundation, and others. 7636 7637 The way to convince distributors to do this is to demand it and 7638 expect it from them. So when you compare distributors, judge them 7639 partly by how much they give to free software development. Show 7640 distributors they must compete to be the one who gives the most. 7641 7642 To make this approach work, you must insist on numbers that you can 7643 compare, such as, "We will donate ten dollars to the Frobnitz project 7644 for each disk sold." Don't be satisfied with a vague promise, such as 7645 "A portion of the profits are donated," since it doesn't give a basis 7646 for comparison. 7647 7648 Even a precise fraction "of the profits from this disk" is not very 7649 meaningful, since creative accounting and unrelated business decisions 7650 can greatly alter what fraction of the sales price counts as profit. If 7651 the price you pay is $50, ten percent of the profit is probably less 7652 than a dollar; it might be a few cents, or nothing at all. 7653 7654 Some redistributors do development work themselves. This is useful 7655 too; but to keep everyone honest, you need to inquire how much they do, 7656 and what kind. Some kinds of development make much more long-term 7657 difference than others. For example, maintaining a separate version of 7658 a program contributes very little; maintaining the standard version of a 7659 program for the whole community contributes much. Easy new ports 7660 contribute little, since someone else would surely do them; difficult 7661 ports such as adding a new CPU to the GNU Compiler Collection contribute 7662 more; major new features or packages contribute the most. 7663 7664 By establishing the idea that supporting further development is "the 7665 proper thing to do" when distributing free software for a fee, we can 7666 assure a steady flow of resources into making more free software. 7667 7668 Copyright (C) 1994 Free Software Foundation, Inc. 7669 Verbatim copying and redistribution of this section is permitted 7670 without royalty; alteration is not permitted. 7671 7672 7673 File: libgomp.info, Node: Library Index, Prev: Funding, Up: Top 7674 7675 Library Index 7676 ************* 7677 7678 [index] 7679 * Menu: 7680 7681 * acc_get_property: acc_get_property. (line 6) 7682 * acc_get_property_string: acc_get_property. (line 6) 7683 * Environment Variable: OMP_ALLOCATOR. (line 6) 7684 * Environment Variable <1>: OMP_AFFINITY_FORMAT. (line 6) 7685 * Environment Variable <2>: OMP_CANCELLATION. (line 6) 7686 * Environment Variable <3>: OMP_DISPLAY_AFFINITY. (line 6) 7687 * Environment Variable <4>: OMP_DISPLAY_ENV. (line 6) 7688 * Environment Variable <5>: OMP_DEFAULT_DEVICE. (line 6) 7689 * Environment Variable <6>: OMP_DYNAMIC. (line 6) 7690 * Environment Variable <7>: OMP_MAX_ACTIVE_LEVELS. (line 6) 7691 * Environment Variable <8>: OMP_MAX_TASK_PRIORITY. (line 6) 7692 * Environment Variable <9>: OMP_NESTED. (line 6) 7693 * Environment Variable <10>: OMP_NUM_TEAMS. (line 6) 7694 * Environment Variable <11>: OMP_NUM_THREADS. (line 6) 7695 * Environment Variable <12>: OMP_PROC_BIND. (line 6) 7696 * Environment Variable <13>: OMP_PLACES. (line 6) 7697 * Environment Variable <14>: OMP_STACKSIZE. (line 6) 7698 * Environment Variable <15>: OMP_SCHEDULE. (line 6) 7699 * Environment Variable <16>: OMP_TARGET_OFFLOAD. (line 6) 7700 * Environment Variable <17>: OMP_TEAMS_THREAD_LIMIT. 7701 (line 6) 7702 * Environment Variable <18>: OMP_THREAD_LIMIT. (line 6) 7703 * Environment Variable <19>: OMP_WAIT_POLICY. (line 6) 7704 * Environment Variable <20>: GOMP_CPU_AFFINITY. (line 6) 7705 * Environment Variable <21>: GOMP_DEBUG. (line 6) 7706 * Environment Variable <22>: GOMP_STACKSIZE. (line 6) 7707 * Environment Variable <23>: GOMP_SPINCOUNT. (line 6) 7708 * Environment Variable <24>: GOMP_RTEMS_THREAD_POOLS. 7709 (line 6) 7710 * FDL, GNU Free Documentation License: GNU Free Documentation License. 7711 (line 6) 7712 * Implementation specific setting: OMP_NESTED. (line 6) 7713 * Implementation specific setting <1>: OMP_NUM_THREADS. (line 6) 7714 * Implementation specific setting <2>: OMP_SCHEDULE. (line 6) 7715 * Implementation specific setting <3>: OMP_TARGET_OFFLOAD. (line 6) 7716 * Implementation specific setting <4>: GOMP_STACKSIZE. (line 6) 7717 * Implementation specific setting <5>: GOMP_SPINCOUNT. (line 6) 7718 * Implementation specific setting <6>: GOMP_RTEMS_THREAD_POOLS. 7719 (line 6) 7720 * Implementation specific setting <7>: Implementation-defined ICV Initialization. 7721 (line 6) 7722 * Introduction: Top. (line 6) 7723 7724 7725 7726 Tag Table: 7727 Node: Top2083 7728 Node: Enabling OpenMP4900 7729 Node: OpenMP Implementation Status6081 7730 Node: OpenMP 4.56777 7731 Node: OpenMP 5.06953 7732 Node: OpenMP 5.112374 7733 Node: OpenMP 5.216686 7734 Ref: OpenMP 5.2-Footnote-119831 7735 Node: OpenMP Technical Report 1220232 7736 Node: Runtime Library Routines24759 7737 Node: Thread Team Routines25392 7738 Node: omp_set_num_threads26979 7739 Node: omp_get_num_threads27825 7740 Node: omp_get_max_threads28916 7741 Node: omp_get_thread_num29671 7742 Node: omp_in_parallel30540 7743 Node: omp_set_dynamic31190 7744 Node: omp_get_dynamic32057 7745 Node: omp_get_cancellation32932 7746 Node: omp_set_nested33726 7747 Node: omp_get_nested35045 7748 Node: omp_set_schedule36787 7749 Node: omp_get_schedule37866 7750 Node: omp_get_teams_thread_limit38814 7751 Node: omp_get_supported_active_levels39582 7752 Node: omp_set_max_active_levels40387 7753 Node: omp_get_max_active_levels41336 7754 Node: omp_get_level42059 7755 Node: omp_get_ancestor_thread_num42693 7756 Node: omp_get_team_size43615 7757 Node: omp_get_active_level44586 7758 Node: Thread Affinity Routines45278 7759 Node: omp_get_proc_bind45678 7760 Node: Teams Region Routines46650 7761 Node: omp_get_num_teams47358 7762 Node: omp_get_team_num47844 7763 Node: omp_set_num_teams48343 7764 Node: omp_get_max_teams49215 7765 Node: omp_set_teams_thread_limit49907 7766 Node: omp_get_thread_limit50912 7767 Node: Tasking Routines51512 7768 Node: omp_get_max_task_priority52023 7769 Node: omp_in_explicit_task52606 7770 Node: omp_in_final53496 7771 Node: Resource Relinquishing Routines54139 7772 Node: omp_pause_resource54611 7773 Node: omp_pause_resource_all55704 7774 Node: Device Information Routines56691 7775 Node: omp_get_num_procs57509 7776 Node: omp_set_default_device58030 7777 Node: omp_get_default_device58829 7778 Node: omp_get_num_devices59518 7779 Node: omp_get_device_num60053 7780 Node: omp_is_initial_device60868 7781 Node: omp_get_initial_device61572 7782 Node: Device Memory Routines62307 7783 Node: omp_target_alloc63347 7784 Node: omp_target_free64922 7785 Node: omp_target_is_present66110 7786 Node: omp_target_is_accessible67782 7787 Node: omp_target_memcpy69596 7788 Node: omp_target_memcpy_async71410 7789 Node: omp_target_memcpy_rect73789 7790 Node: omp_target_memcpy_rect_async76993 7791 Node: omp_target_associate_ptr80765 7792 Node: omp_target_disassociate_ptr83730 7793 Node: omp_get_mapped_ptr85483 7794 Node: Lock Routines87026 7795 Node: omp_init_lock87874 7796 Node: omp_init_nest_lock88499 7797 Node: omp_destroy_lock89221 7798 Node: omp_destroy_nest_lock89896 7799 Node: omp_set_lock90634 7800 Node: omp_set_nest_lock91492 7801 Node: omp_unset_lock92388 7802 Node: omp_unset_nest_lock93317 7803 Node: omp_test_lock94311 7804 Node: omp_test_nest_lock95289 7805 Node: Timing Routines96277 7806 Node: omp_get_wtick96654 7807 Node: omp_get_wtime97209 7808 Node: Event Routine97978 7809 Node: omp_fulfill_event98311 7810 Node: Memory Management Routines99303 7811 Node: omp_init_allocator100219 7812 Node: omp_destroy_allocator101848 7813 Node: omp_set_default_allocator102832 7814 Node: omp_get_default_allocator103866 7815 Node: omp_alloc104807 7816 Node: omp_aligned_alloc106910 7817 Node: omp_free109440 7818 Node: omp_calloc111095 7819 Node: omp_aligned_calloc113314 7820 Node: omp_realloc115866 7821 Node: Environment Display Routine119252 7822 Node: omp_display_env119628 7823 Node: Environment Variables122462 7824 Node: OMP_ALLOCATOR125243 7825 Node: OMP_AFFINITY_FORMAT129053 7826 Node: OMP_CANCELLATION131661 7827 Node: OMP_DISPLAY_AFFINITY132261 7828 Node: OMP_DISPLAY_ENV132956 7829 Node: OMP_DEFAULT_DEVICE133806 7830 Node: OMP_DYNAMIC134814 7831 Node: OMP_MAX_ACTIVE_LEVELS135441 7832 Node: OMP_MAX_TASK_PRIORITY136466 7833 Node: OMP_NESTED137169 7834 Node: OMP_NUM_TEAMS138418 7835 Node: OMP_NUM_THREADS139127 7836 Node: OMP_PROC_BIND140143 7837 Node: OMP_PLACES141664 7838 Node: OMP_STACKSIZE144400 7839 Node: OMP_SCHEDULE145302 7840 Node: OMP_TARGET_OFFLOAD146049 7841 Node: OMP_TEAMS_THREAD_LIMIT147536 7842 Node: OMP_THREAD_LIMIT148389 7843 Node: OMP_WAIT_POLICY149049 7844 Node: GOMP_CPU_AFFINITY149741 7845 Node: GOMP_DEBUG151459 7846 Node: GOMP_STACKSIZE151961 7847 Node: GOMP_SPINCOUNT152792 7848 Node: GOMP_RTEMS_THREAD_POOLS153996 7849 Node: Enabling OpenACC156171 7850 Node: OpenACC Runtime Library Routines156993 7851 Node: acc_get_num_devices161274 7852 Node: acc_set_device_type162000 7853 Node: acc_get_device_type162764 7854 Node: acc_set_device_num163777 7855 Node: acc_get_device_num164594 7856 Node: acc_get_property165393 7857 Node: acc_async_test167605 7858 Node: acc_async_test_all168576 7859 Node: acc_wait169459 7860 Node: acc_wait_all170322 7861 Node: acc_wait_all_async171083 7862 Node: acc_wait_async171835 7863 Node: acc_init172543 7864 Node: acc_shutdown173188 7865 Node: acc_on_device173855 7866 Node: acc_malloc174844 7867 Node: acc_free175552 7868 Node: acc_copyin176196 7869 Node: acc_present_or_copyin177783 7870 Node: acc_create179551 7871 Node: acc_present_or_create181183 7872 Node: acc_copyout182959 7873 Node: acc_delete185263 7874 Node: acc_update_device187510 7875 Node: acc_update_self189084 7876 Node: acc_map_data190674 7877 Node: acc_unmap_data191746 7878 Node: acc_deviceptr192488 7879 Node: acc_hostptr193283 7880 Node: acc_is_present194067 7881 Node: acc_memcpy_to_device195594 7882 Node: acc_memcpy_from_device197029 7883 Node: acc_attach198514 7884 Node: acc_detach199181 7885 Node: acc_get_current_cuda_device200020 7886 Node: acc_get_current_cuda_context200605 7887 Node: acc_get_cuda_stream201205 7888 Node: acc_set_cuda_stream201796 7889 Node: acc_prof_register202467 7890 Node: acc_prof_unregister203026 7891 Node: acc_prof_lookup203593 7892 Node: acc_register_library204114 7893 Node: OpenACC Environment Variables204680 7894 Node: ACC_DEVICE_TYPE205169 7895 Node: ACC_DEVICE_NUM205696 7896 Node: ACC_PROFLIB206167 7897 Node: CUDA Streams Usage206773 7898 Ref: CUDA Streams Usage-Footnote-1208665 7899 Node: OpenACC Library Interoperability208774 7900 Ref: OpenACC Library Interoperability-Footnote-1215123 7901 Ref: OpenACC Library Interoperability-Footnote-2215375 7902 Node: OpenACC Profiling Interface215583 7903 Node: OpenMP-Implementation Specifics225581 7904 Node: Implementation-defined ICV Initialization225900 7905 Node: OpenMP Context Selectors227071 7906 Ref: OpenMP Context Selectors-Footnote-1228352 7907 Node: Memory allocation228420 7908 Node: Offload-Target Specifics233065 7909 Node: AMD Radeon233356 7910 Node: nvptx236294 7911 Node: The libgomp ABI239921 7912 Node: Implementing MASTER construct240771 7913 Node: Implementing CRITICAL construct241188 7914 Node: Implementing ATOMIC construct241929 7915 Node: Implementing FLUSH construct242412 7916 Node: Implementing BARRIER construct242685 7917 Node: Implementing THREADPRIVATE construct242956 7918 Node: Implementing PRIVATE clause243611 7919 Node: Implementing FIRSTPRIVATE LASTPRIVATE COPYIN and COPYPRIVATE clauses244194 7920 Node: Implementing REDUCTION clause245520 7921 Node: Implementing PARALLEL construct246080 7922 Node: Implementing FOR construct247339 7923 Node: Implementing ORDERED construct249339 7924 Node: Implementing SECTIONS construct249647 7925 Node: Implementing SINGLE construct250415 7926 Node: Implementing OpenACC's PARALLEL construct251129 7927 Node: Reporting Bugs251389 7928 Node: Copying251752 7929 Node: GNU Free Documentation License289304 7930 Node: Funding314432 7931 Node: Library Index316958 7932 7933 End Tag Table 7934
Indexes created Wed Mar 18 00:23:26 UTC 2026