| Skip Navigation Links | |
| Exit Print View | |
|
Oracle Solaris Studio 12.2: OpenMP API User's Guide |
2. Compiling and Running OpenMP Programs
2.3.3 Interpreting the Value Specified for SUNW_MP_PROCBIND
2.3.4 Interaction with OS Processor Sets
2.5 Checking and Analyzing OpenMP Programs
3. Implementation-Defined Behaviors
6. Automatic Scoping of Variables
The OpenMP specification defines several environment variables that control the execution of OpenMP programs. These are summarized in 2.2.1 Common OpenMP Environment Variables. For details, refer to the OpenMP API Version 3.0 specification at openmp.org. Additional environment variables that are not part of the OpenMP specification are defined by this release of the Solaris Studio compilers, and are summarized in 2.2.2 Solaris Studio Specific Environment Variables.
Sets schedule type for DO, PARALLEL DO, for, parallel for, directives/pragmas with schedule type RUNTIME specified.
If not defined, a default value of STATIC is used. value is “type[,chunk]”
Example: setenv OMP_SCHEDULE 'GUIDED,4'
Sets the number of threads to use during execution of a parallel region.
You can override this value by a num_threads clause, or a call to omp_set_num_threads().
If not set, a default of 1 is used. value is a positive integer.
Example: setenv OMP_NUM_THREADS 16
Enables or disables dynamic adjustment of the number of threads available for execution of parallel regions.
If not set, a default value of TRUE is used. value is either TRUE or FALSE.
Example: setenv OMP_DYNAMIC FALSE
Enables or disables nested parallelism.
value is either TRUE or FALSE.
The default is FALSE.
Example: setenv OMP_NESTED FALSE
Sets the size of the stack for threads created by OpenMP.
Size may be specified as a positive integer in Kilobytes, or with a suffix B, K, M, or G, for Bytes, Kilobytes, Megabytes, or Gigabytes.
Example: setenv OMP_STACKSIZE 10M
See also the Solaris Studio environment variable STACKSIZE described in the next section.
Sets desired policy regarding waiting threads, ACTIVE or PASSIVE.
ACTIVE threads consume processor time while waiting. PASSIVE threads do not and may yield the processor or go to sleep.
Sets the maximum number of levels of nested active parallel regions to a non-negative integer value.
Sets the number of threads to use in the whole OpenMP program to a positive integer.
Additional multiprocessing environment variables affect execution of OpenMP programs and are not part of the OpenMP specifications.
For compatibility with legacy programs, setting the PARALLEL environment variable has the same effect as setting OMP_NUM_THREADS. However, if both PARALLEL and OMP_NUM_THREADS are set, they must be set to the same value.
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. In addition, the runtime library outputs the settings of all environment variables for informational purposes. If the environment variable is set to FALSE, the runtime library does not issue any warning messages or output any settings.The default is FALSE.
The OpenMP runtime library has the ability to check for many common OpenMP violations, such as incorrect nesting and deadlocks. Runtime checking does add overhead to the execution of the program. See Chapter 3, Implementation-Defined Behaviors. The runtime library issues warning messages to stderr if SUNW_MP_WARN is set to TRUE.
Example:
setenv SUNW_MP_WARN TRUE
The runtime library will also issue warning messages if the program registers a call-back function to accept warning messages. A program can register a user call-back function by calling the following function:
int sunw_mp_register_warn (void (*func)(void *));
The address of the call-back function is passed as argument to sunw_mp_register_warn(). This function returns 0 upon successfully registering the call-back function, 1 upon failure.
If the program has registered a call-back function, libmtsk will call the registered function passing a pointer to the localized string containing the error message. The memory pointed to is no longer valid upon return from the call-back function.
Note - Set SUNW_MP_WARN to TRUE while testing or debugging a program. This will enable you to see any warning messages from the OpenMP runtime library.
Controls the status of idle threads in an OpenMP program that are waiting at a barrier or waiting for new parallel regions to work on. You can set the value to be one of the following: SPIN, SLEEP, SLEEP( times), SLEEP(timems), SLEEP( timemc), where time is an integer that specifies an amount of time, and s, ms, and mc specify the time unit (seconds, milli-seconds, and micro-seconds, respectively).
SPIN specifies that an idle thread should spin while waiting at barrier or waiting for new parallel regions to work on. SLEEP without a time argument specifies that an idle thread should sleep immediately. SLEEP with a time argument specifies the amount of time a thread should spin-wait before going to sleep.
The default idle thread status 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.
Examples:
setenv SUNW_MP_THR_IDLE SPIN setenv SUNW_MP_THR_IDLE SLEEP setenv SUNW_MP_THR_IDLE SLEEP(2s) setenv SUNW_MP_THR_IDLE SLEEP(20ms) setenv SUNW_MP_THR_IDLE SLEEP(150mc)
This environment variable works on both Solaris and Linux systems. The SUNW_MP_PROCBIND environment variable can be used to bind threads of an OpenMP program to virtual processors on the running system. Performance can be enhanced with processor binding, but performance degradation will occur if multiple threads are bound to the same virtual processor. See 2.3 Processor Binding for details.
Specifies the maximum size of the thread pool. The thread pool contains only non-user threads that the OpenMP runtime library creates. It does not contain the master thread or any threads created explicitly by the user’s program. If this environment variable is set to zero, the thread pool will be empty and all parallel regions will be executed by one thread. The default, if not specified, is 1023. See 4.2 Control of Nested Parallelism for details.
Note that SUNW_MP_MAX_POOL_THREADS specifies the maximum number of non-user OpenMP threads to use for the whole program, while OMP_THREAD_LIMIT specifies the maximum number of user and non-user OpenMP threads for the whole program. If both SUNW_MP_MAX_POOL_THREADS and OMP_THREAD_LIMIT are set they must have consistent values such that OMP_THREAD_LIMIT is set to one more than the value of SUNW_MP_MAX_POOL_THREADS.
Specifies the maximum depth of active nested parallel regions. Any parallel region that has an active nested depth greater than the value of this environment variable will be executed by only one thread. A parallel region is considered not active if it is an OpenMP parallel region that has a false if clause. The default, if not specified, is 4. See 4.2 Control of Nested Parallelism for details.
Note that if both SUNW_MP_MAX_NESTED_LEVELS and OMP_MAX_ACTIVE_LEVELS are set, they must be set to the same value.
Sets the stack size for each thread. The value is in kilobytes. The default thread stack sizes are 4 Mb on 32-bit SPARC V8 and x86 platforms, and 8 Mb on 64-bit SPARC V9 and x86 platforms.
Example:
setenv STACKSIZE 8192 sets the thread stack size to 8 MB
The STACKSIZE environment variable also accepts numerical values with a suffix of either B, K, M, or G for bytes, kilobytes, megabytes, or gigabytes respectively. The default is kilobytes.
Note that if both STACKSIZE and OMP_STACKSIZE are set, they must be set to the same value. If they are not the same, a run time error occurs.
Sets the weighting factor used to determine the size of chunks assigned to threads in loops with GUIDED scheduling. The value should be a positive floating-point number, and will apply to all loops with GUIDED scheduling in the program. If not set, the default value assumed is 2.0.
Controls the behavior of threads in the program that are waiting for work (idle), waiting at a barrier, or waiting for a task. The behavior for each of the above types of wait has three possibilities: spin for awhile, yield the CPU for awhile, and sleep until awakened.
The syntax is (shown using csh):
setenv SUNW_MP_WAIT_POLICY IDLE=val:BARRIER=val:TASKWAIT=val
IDLE=val, BARRIER=val, and TASKWAIT=val are optional keywords that specify the type of wait being controlled.
For each of these keywords, there is a val setting that describes the wait behavior, SPIN, YIELD, or SLEEP.
SPIN(time) specifies how long a thread should spin before yielding the CPU. time can be in seconds, milliseconds, or microseconds (denoted by s, ms, and 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 CPU before sleeping. After each yield of the CPU, 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 thread should immediately go to sleep.
Note that SPIN, SLEEP, and YIELD settings for a particular type of wait can be specified in any order. The settings are separated by comma. "SPIN(0),YIELD(0)", is the same as SLEEP or sleep immediately. When processing the settings for IDLE, BARRIER, and TASKWAIT, the “left-most wins” rule is used.
Examples:
% setenv SUNW_MP_WAIT_POLICY “BARRIER=SPIN”
A thread waiting at a barrier spins until all threads in the team have reached the barrier.
% setenv SUNW_MP_WAIT_POLICY “IDLE=SPIN(10ms),YIELD(5)”
A thread waiting for work (idle) spins for 10 milliseconds, then yields the CPU 5 times before going to sleep.
% setenv SUNW_MP_WAIT_POLICY “IDLE=SPIN(10ms),YIELD(2):BARRIER=SLEEP:TASKWAIT=YIELD(10)”
A thread waiting for work (idle) spins for 10 milliseconds, then yields the CPU 2 times before going to sleep; a thread waiting at a barrier goes to sleep immediately; a thread waiting at a taskwait yields the CPU 10 times before going to sleep.
|