Openmp 3.1 API C/C++ Syntax Quick Reference Card

OpenMP API 3.1 C/C++ Page 1 OpenMP 3.1 API C/C++ Syntax Quick Reference Card OpenMP Application Program Interface(API) is a portable, scalable OpenMP supports multi-platform shared-memory parallel model that gives shared-memory parallel programmers a simple programming in C/C++ and Fortran on all architectures, including ® and flexible interface for developing parallel applications for Unix platforms and Windows NT platforms. platforms ranging from the desktop to the supercomputer. A separate OpenMP reference card for Fortran is also available. C/C++ [n.n.n] refers to sections in the OpenMP API Specification available at www.openmp.org.

Directives An OpenMP executable directive applies to the Single [2.5.3] Taskyield [2.7.2] succeeding structured block or an OpenMP Construct. The single construct specifies that the associated The taskyield construct specifies that the current task can A structured-block is a single statement or a compound structured block is executed by only one of the threads be suspended in favor of execution of a different task. statement with a single entry at the top and a single exit in the team (not necessarily the master thread), in the #pragma omp taskyield at the bottom. context of its implicit task. Master [2.8.1] Parallel [2.4] #pragma omp single [clause[ [, ]clause] ...] structured-block The master construct specifies a structured block that The parallel construct forms a team of threads and starts is executed by the master thread of the team. There is parallel execution. clause: no implied barrier either on entry to, or exit from, the private(list) #pragma omp parallel [clause[ [, ]clause] ...] master construct. structured-block firstprivate(list) #pragma omp master clause: copyprivate(list) structured-block if(scalar-expression) nowait Critical [2.8.2] num_threads(integer-expression) Parallel Loop [2.6.1] The critical construct restricts execution of the associated default(shared | none) The parallel loop construct is a shortcut for specifying structured block to a single thread at a time. private(list) a parallel construct containing one or more associated #pragma omp critical[ (name)] firstprivate(list) loops and no other statements. structured-block shared(list) #pragma omp parallel for [clause[ [, ]clause] ...] copyin(list) for-loop Barrier [2.8.3] reduction(operator: list) clause: The barrier construct specifies an explicit barrier at the Any accepted by the parallel or for directives, except point at which the construct appears. Loop [2.5.1] the nowait clause, with identical meanings and #pragma omp barrier The loop construct specifies that the iterations of restrictions. loops will be distributed among and executed by the Taskwait [2.8.4] encountering team of threads. The taskwait construct specifies a wait on the completion #pragma omp for [clause[ [, ]clause] ...] Simple Parallel Loop Example of child tasks of the current task. for-loops The following example demonstrates how to #pragma omp taskwait clause: parallelize a simple loop using the parallel loop private(list) construct. Atomic [2.8.5] firstprivate(list) The atomic construct ensures that a specific storage Most common form location is updated atomically, rather than exposing it to lastprivate(list) void simple(int n, float *a, float *b) of the for loop: the possibility of multiple, simultaneous writing threads. reduction(operator: list) { schedule(kind[, chunk_size]) for(var = lb; int i; #pragma omp atomic [read | write | update | capture] expression-stmt collapse(n) var relational-op b; #pragma omp parallel for ordered var += incr) for (i=1; icompiler and/or runtime system. {v = x; x--;} {v = x; --x;} {--x; v = x;} {x--; v = x;} } • runtime: The schedule and chunk size are taken from Flush [2.8.6] the run-sched-var ICV. clause: Any of the clauses accepted by the parallel or sections The flush construct executes the OpenMP flush operation, which makes a thread’s temporary view of Sections [2.5.2] directives, except the nowait clause, with identical memory consistent with memory, and enforces an order The sections construct contains a set of structured blocks meanings and restrictions. on the memory operations of the variables. that are to be distributed among and executed by the encountering team of threads. Task [2.7.1] #pragma omp flush[ (list)] #pragma omp sections[clause[[ ,] clause] ...] The task construct defines an explicit task. The data Ordered [2.8.7] { environment of the task is created according to the The ordered construct specifies a structured block in a [#pragma omp section] data-sharing attribute clauses on the task construct loop region that will be executed in the order of the loop structured-block and any defaults that apply. iterations. This sequentializes and orders the code within [#pragma omp section #pragma omp task [clause[ [, ]clause] ...] an ordered region while allowing code outside the region structured-block] structured-block to run in parallel. ... clause: #pragma omp ordered } if(scalar-expression) structured-block final(scalar-expression) clause: Threadprivate [2.9.2] untied The threadprivate directive specifies that variables are private(list) default(shared | none) replicated, with each thread having its own copy. firstprivate(list) mergeable lastprivate(list) #pragma omp threadprivate(list) private(list) list: reduction(operator: list) firstprivate(list) nowait A comma-separated list of file-scope, namespace- shared(list) scope, or static block-scope variables that do not have incomplete types.

Execution Environment Routines [3.2] int omp_in_parallel(void); int omp_get_thread_limit(void); Lock Routines [3.3] Execution environment routines affect Returns true if the call to the routine is Returns the value of the thread-limit-var Lock routines support synchronization with and monitor threads, processors, and the enclosed by an active parallel region; ICV, which is the maximum number of OpenMP locks. parallel environment. otherwise, it returns false. OpenMP threads available to the program. void omp_init_lock(omp_lock_t *lock); void omp_set_num_threads( void omp_set_dynamic( void omp_set_max_active_levels( void omp_init_nest_lock( int num_threads); int dynamic_threads); int max_levels); omp_nest_lock_t *lock); Affects the number of threads used for Enables or disables dynamic adjustment of Limits the number of nested active parallel These routines initialize an OpenMP lock. subsequent parallel regions that do not the number of threads available by setting regions, by setting max-active-levels-var specify a num_threads clause. the value of the dyn-var ICV. ICV. void omp_destroy_lock(omp_lock_t *lock); int omp_get_num_threads(void); void omp_destroy_nest_lock( int omp_get_dynamic(void); int omp_get_max_active_levels(void); omp_nest_lock_t *lock); Returns the number of threads in the Returns the value of the dyn-var ICV, Returns the value of max-active-levels-var current team. These routines ensure that the OpenMP determining whether dynamic adjustment ICV, which determines the maximum lock is uninitialized. of the number of threads is enabled or int omp_get_max_threads(void); number of nested active parallel regions. disabled. void omp_set_lock(omp_lock_t *lock); Returns maximum number of threads that int omp_get_level(void); could be used to form a new team using a void omp_set_nested(int nested); void omp_set_nest_lock( Returns the number of nested parallel omp_nest_lock_t *lock); parallel construct without a num_threads Enables or disables nested parallelism, by regions enclosing the task that contains clause. setting the nest-var ICV. These routines provide a means of setting the call. an OpenMP lock. int omp_get_thread_num(void); int omp_get_nested(void); int omp_get_ancestor_thread_num( void omp_unset_lock(omp_lock_t *lock); Returns the ID of the encountering thread Returns the value of the nest-var ICV, which int level); void omp_unset_nest_lock( where ID ranges from zero to the size of determines if nested parallelism is enabled Returns, for a given nested level of the the team minus 1. or disabled. omp_nest_lock_t *lock); current thread, the thread number of the These routines provide a means of void omp_set_schedule(omp_sched_t kind, ancestor or the current thread. unsetting an OpenMP lock. int omp_get_num_procs(void); int modifier); level int omp_get_team_size(int ); int omp_test_lock(omp_lock_t *lock); Returns the number of processors available Affects the schedule that is applied when Returns, for a given nested level of the to the program. runtime is used as schedule kind, by setting int omp_test_nest_lock( current thread, the size of the thread team lock the value of the run-sched-var ICV. to which the ancestor or the current thread omp_nest_lock_t * ); kind belongs. These routines attempt to set an OpenMP is one of static, dynamic, guided, lock but do not suspend execution of the auto, or an implementation-defined task executing the routine. schedule. See loop construct [2.5.1] for int omp_get_active_level(void); descriptions. Returns the number of nested, active Data Types For Runtime parallel regions enclosing the task that Timing Routines [3.4] void omp_get_schedule( contains the call. Timing routines support a portable wall Library Routines omp_sched_t *kind, int *modifier); int omp_in_final(void); clock timer. omp_lock_t: Represents a simple lock. Returns the value of run-sched-var ICV, which is the schedule applied when Returns true if the routine is executed in a double omp_get_wtime(void); omp_nest_lock_t: Represents a runtime schedule is used. final or included task region; otherwise, it Returns elapsed wall clock time in seconds. nestable lock. returns false. See kind above. double omp_get_wtick(void); omp_sched_t: Represents a schedule. Returns the precision of the timer used by omp_get_wtime.

Clauses Environment Variables

The set of clauses that is valid on a reduction(operator:list) particular directive is described with the Declares accumulation into the list items Environment variables are described OMP_NESTED nested directive. Most clauses accept a comma- using the indicated associative operator. in section [4] of the API specification. Sets the nest-var ICV to enable or to separated list of list items. All list items Accumulation occurs into a private copy for Environment variable names are upper disable nested parallelism. Valid values appearing in a clause must be visible. each list item which is then combined with case, and the values assigned to them for nested are true or false. the original item. are case insensitive and may have leading Data Sharing Attribute Clauses [2.9.3] and trailing white space. OMP_STACKSIZE size[B | K | M | G] Operators for reduction (initialization values) Sets the stacksize-var ICV that specifies Data-sharing attribute clauses apply only OMP_SCHEDULE type[,chunk] to variables whose names are visible in the + (0) | (0) the size of the stack for threads created construct on which the clause appears. * (1) ^ (0) Sets the run-sched-var ICV for the by the OpenMP implementation. size is a - (0) && (1) runtime schedule type and chunk size. positive integer that specifies stack size. default(shared | none) Valid OpenMP schedule types are static, If unit is not specified, size is measured in & (~0) || (0) Controls the default data-sharing attributes dynamic, guided, or auto. chunk is a kilobytes (K). of variables that are referenced in a parallel max (Least number in reduction list item type) positive integer that specifies chunk size. or task construct. min (Largest number in reduction list item type) OMP_WAIT_POLICY policy OMP_NUM_THREADS list Sets the wait-policy-var ICV that controls shared(list) Sets the nthreads-var ICV for the number the desired behavior of waiting threads. Declares one or more list items to be shared Data Copying Clauses [2.9.4] of threads to use for parallel regions. Valid values for policy are ACTIVE by tasks generated by a parallel or task These clauses support the copying of (waiting threads consume processor construct. data values from private or threadprivate OMP_DYNAMIC dynamic cycles while waiting) and PASSIVE. variables on one implicit task or thread Sets the dyn-var ICV for the dynamic private(list) to the corresponding variables on other adjustment of threads to use for parallel OMP_MAX_ACTIVE_LEVELS levels Declares one or more list items to be private implicit tasks or threads in the team. regions. Valid values for dynamic are true Sets the max-active-levels-var ICV that to a task. or false. controls the maximum number of nested copyin(list) active parallel regions. firstprivate(list) Copies the value of the master thread’s OMP_PROC_BIND bind Declares one or more list items to be private threadprivate variable to the threadprivate Sets the value of the global bind-var ICV. OMP_THREAD_LIMIT limit to a task, and initializes each of them with variable of each other member of the team The value of this environment variable Sets the thread-limit-var ICV that controls the value that the corresponding original executing the parallel region. must be true or false. the maximum number of threads item has when the construct is encountered. participating in the OpenMP program. copyprivate(list) lastprivate(list) Broadcasts a value from the data Declares one or more list items to be environment of one implicit task to the data private to an implicit task, and causes the Copyright © 2011 OpenMP Architecture Review Board. Permission to copy without fee all or part environments of the other implicit tasks of this material is granted, provided the OpenMP Architecture Review Board copyright notice and corresponding original item to be updated belonging to the parallel region. the title of this document appear. Notice is given that copying is by permission of the OpenMP after the end of the region. Architecture Review Board. Products or publications based on one or more of the OpenMP specifications must acknowledge the copyright by displaying the following statement: “OpenMP is a trademark of the OpenMP Architecture Review Board. Portions of this product/publication may have been derived from the OpenMP Language Application Program Interface Specification.”