The OpenMP specification defines several environment variables that control the execution of OpenMP programs. For details, refer to the OpenMP 4.0 specification at http://openmp.org. Also see OpenMP Implementation-Defined Behaviors for information about the implementation of OpenMP environment variables in Oracle Developer Studio.
Oracle Developer Studio supports additional environment variables which are not part of the OpenMP specification, are summarized in Oracle Developer Studio Environment Variables.
The following table describes the behaviors of the OpenMP environment variables supported by Oracle Developer Studio and their default values. Note that the values specified for the environment variables are case insensitive and can be in uppercase or lowercase.
|
The following additional environment variables affect the execution of OpenMP programs but are not part of the OpenMP specifications. Note that the values specified for the following environment variables are case insensitive and can be in uppercase or lowercase.
For compatibility with legacy programs, setting the PARALLEL environment variable has the same effect as setting OMP_NUM_THREADS.
If both PARALLEL and OMP_NUM_THREADS are set, they must be set to the same value.
The OpenMP runtime library has the ability to issue warnings about many common OpenMP violations, such as incorrect nesting of regions, incorrect placement of explicit barriers, deadlocks, invalid settings of environment variables, and the like.
The environment variable SUNW_MP_WARN controls warning messages issued by the OpenMP runtime library. If SUNW_MP_WARN is set to TRUE, the runtime library issues warning messages to stderr. If the environment variable is set to FALSE, the runtime library does not issue any warning messages. The default is FALSE.
Example:
% setenv SUNW_MP_WARN TRUE
The runtime library will also issue warning messages if the program registers a callback function to accept warning messages. A program can register a callback function by calling the following function:
int sunw_mp_register_warn (void (*func)(void *));
The address of the callback function is passed as an argument to sunw_mp_register_warn(). sunw_mp_register_warn() returns 0 upon successfully registering the callback function, or 1 upon failure.
If the program has registered a callback function, the runtime library will call the registered function and pass a pointer to the localized string containing the warning message. The memory pointed to is no longer valid upon return from the callback function.
Controls the behavior of threads in an OpenMP program that are waiting for work (idle) or waiting at a barrier. You can set the value to be one of the following: SPIN, SLEEP, SLEEP(time s), SLEEP(time ms), SLEEP(time mc), where time is an integer that specifies an amount of time, and s, ms, and mc are optional suffixes that specify the time unit (seconds, milliseconds, and microseconds, respectively). If the time unit is not specified, then a time unit of seconds is assumed.
SPIN specifies that a thread should spin while waiting for work (idle) or waiting at a barrier. SLEEP without a time parameter specifies that a waiting thread should sleep immediately. SLEEP with a time parameter specifies the amount of time a thread should spin-wait before going to sleep.
The default behavior is to sleep after possibly spin-waiting for some amount of time. SLEEP, SLEEP(0), SLEEP(0s), SLEEP(0ms), and SLEEP(0mc) are all equivalent.
If both SUNW_MP_THR_IDLE and OMP_WAIT_POLICY are set, then OMP_WAIT_POLICY will be ignored.
Examples:
% setenv SUNW_MP_THR_IDLE SPIN % setenv SUNW_MP_THR_IDLE SLEEP
The following are all equivalent:
% setenv SUNW_MP_THR_IDLE SLEEP(5) % setenv SUNW_MP_THR_IDLE SLEEP(5s) % setenv SUNW_MP_THR_IDLE SLEEP(5000ms) % setenv SUNW_MP_THR_IDLE SLEEP(5000000mc)
The SUNW_MP_PROCBIND environment variable can be used to bind OpenMP threads to hardware threads on the running system. Performance can be enhanced with processor binding, but performance degradation will occur if multiple threads are bound to the same hardware thread. You cannot set both SUNW_MP_PROCBIND and OMP_PROC_BIND. If SUNW_MP_PROCBIND is not set, the default is FALSE. See Processor Binding (Thread Affinity) for more information.
Specifies the maximum size of the OpenMP helper thread pool. OpenMP helper threads are those threads that the OpenMP runtime library creates to work on parallel regions. The helper thread pool does not include the initial (or main) thread or any threads created explicitly by the user’s program. If this environment variable is set to zero, the OpenMP helper thread pool will be empty and all parallel regions will be executed by the initial (or main) thread. If not set, the default is 1023. See Control of Nested Parallelism for more information.
Note that SUNW_MP_MAX_POOL_THREADS specifies the maximum number of non-user OpenMP threads to use for the program, while OMP_THREAD_LIMIT specifies the maximum number of user and non-user OpenMP threads to use for the program. If both SUNW_MP_MAX_POOL_THREADS and OMP_THREAD_LIMIT are set, they must be set to consistent values. The value of OMP_THREAD_LIMIT must be 1 more than the value of SUNW_MP_MAX_POOL_THREADS.
Sets the maximum number of nested active parallel regions. A parallel region is active if it is executed by a team consisting of more than one thread. If SUNW_MP_MAX_NESTED_LEVELS is not set, the default is 4. See Control of Nested Parallelism for more information.
Sets the stack size for each OpenMP helper thread. The environment variable accepts numeric values with an optional suffix of B, K, M, or G for Bytes, Kilobytes, Megabytes, or Gigabytes, respectively. If no suffix is specified, the default is Kilobytes.
If not set, the default OpenMP helper thread stack size is 4 Megabytes for 32-bit applications, and 8 Megabytes for 64-bit applications.
Examples:
% setenv STACKSIZE 8192 <- sets the OpenMP helper thread stack size to 8 Megabytes % setenv STACKSIZE 16M <- sets the OpenMP helper thread stack size to 16 Megabytes
Note that if both STACKSIZE and OMP_STACKSIZE are set, they must be set to the same value.
Sets the weighting factor used to determine the size of chunks in loops with the guided schedule. The value should be a positive floating-point number, and will apply to all loops with the guided schedule in the program. If not set, the default weighting factor is 2.0.
When the schedule(guided, chunk_size) clause is specified with the for/do directive, the loop iterations are assigned to threads in chunks as the threads request them, with the chunk sizes decreasing to chunk_size, except that the last chunk may have a smaller size. The thread executes a chunk of iterations and then requests another chunk until no chunks remain to be assigned. For a chunk_size of 1, the size of each chunk is proportional to the number of unassigned iterations divided by the number of threads, decreasing to 1. For a chunk_size of k (where k is greater than 1), the size of each chunk is determined in the same way with the restriction that the chunks do not contain fewer than k iterations except possibly for the last chunk. When no chunk_size is specified, the value defaults to 1.
The OpenMP runtime library, libmtsk.so, uses the following formula to compute the chunk sizes for a loop with the guided schedule:
chunk_size = num-unassigned-iters / (guided-weight * num-threads)
num-unassigned-iters is the number of iterations in the loop that have not yet been assigned to any thread.
guided-weight is the weighting factor specified by the SUNW_MP_THR_GUIDED_WEIGHT environment variable (or 2.0 if the environment variable is not set).
num-threads is the number of threads used to execute the loop.
To illustrate, suppose a 100-iteration loop with the guided schedule. If num-threads = 4 and the weighting factor = 1.0, then the chunk sizes will be:
25, 18, 14, 10, 8, 6, 4, 3, 3, 2, 1,...
On the other hand, if num-threads= 4 and the weighting factor = 2.0, then the chunk sizes will be:
12, 11, 9, 8, 7, 6, 5, 5, 4, 4, 3,...
Allows fine-grained control of the behavior of OpenMP threads in the program that are waiting for work (idle), waiting at a barrier, or waiting for tasks to complete. The behavior for each of these types of wait has three possibilities: spin for a while, yield the processor for a while, or sleep until awakened.
The syntax (shown using csh) is as follows:
% setenv SUNW_MP_WAIT_POLICY "IDLE=val:BARRIER=val:TASKWAIT=val"
IDLE, BARRIER, and TASKWAIT are optional keywords that specify the type of wait being controlled. IDLE refers to the wait for work. BARRIER refers to the wait at an explicit or implicit barrier. TASKWAIT refers to the wait at a taskwait region. Each of these keywords is followed by a val setting that describes the wait behavior using the keywords SPIN, YIELD, or SLEEP.
SPIN(time) specifies how long a waiting thread should spin before yielding the processor. time can be in seconds, milliseconds, or microseconds (denoted by s, ms, or mc, respectively). If no time unit is specified, then seconds is assumed. SPIN with no time parameter means that the thread should continuously spin while waiting.
YIELD(number) specifies the number of times a thread should yield the processor before sleeping. After each yield of the processor, a thread will run again when the operating system schedules it to run. YIELD with no number parameter means the thread should continuously yield while waiting.
SLEEP specifies that a waiting thread should immediately go to sleep.
Note that the SPIN, SLEEP, and YIELD settings for a particular type of wait can be specified in any order. The settings must be separated by comma. "SPIN(0),YIELD(0)" is the same as "YIELD(0),SPIN(0)", which is equivalent to SLEEP or sleep immediately. When processing the settings for IDLE, BARRIER, and TASKWAIT, the “left-most wins” rule is used. The "left-most wins" rule means that if different values are specified for the same type of wait, then the left-most value is the one that will apply. In the following example, two values are specified for IDLE. The first is SPIN, and the second is SLEEP. Because SPIN appears first (it is the left-most in the string), this is the value that will be applied by the OpenMP runtime library.
% setenv SUNW_MP_WAIT_POLICY "IDLE=SPIN:IDLE=SLEEP"
If both SUNW_MP_WAIT_POLICY and OMP_WAIT_POLICY are set, OMP_WAIT_POLICY will be ignored.
Example 1:
% setenv SUNW_MP_WAIT_POLICY “BARRIER=SPIN”
A thread waiting at a barrier spins until all threads in the team have reached the barrier.
Example 2:
% setenv SUNW_MP_WAIT_POLICY “IDLE=SPIN(10ms),YIELD(5)”
A thread waiting for work (idle) spins for 10 milliseconds, then yields the processor 5 times before going to sleep.
Example 3:
% setenv SUNW_MP_WAIT_POLICY “IDLE=SPIN(2s),YIELD(2):BARRIER=SLEEP:TASKWAIT=YIELD(10)”
A thread waiting for work (idle) spins for 2 seconds, then yields the processor 2 times before going to sleep; a thread waiting at a barrier goes to sleep immediately; a thread waiting at a taskwait yields the processor 10 times before going to sleep.