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