| Skip Navigation Links | |
| Exit Print View | |
|
Oracle Solaris Studio 12.3: OpenMP API User's Guide Oracle Solaris Studio 12.3 Information Library |
| Skip Navigation Links | |
| Exit Print View | |
|
|
Oracle Solaris Studio 12.3: OpenMP API User's Guide Oracle Solaris Studio 12.3 Information Library |
2. Compiling and Running OpenMP Programs
2.2 OpenMP Environment Variables
2.2.1 OpenMP Environment Variables Defaults
2.2.2 Oracle Solaris Studio Environment Variables
2.2.2.5 SUNW_MP_MAX_POOL_THREADS
2.3.1 Virtual and Logical Processor IDs
2.3.2 Interpreting the Value Specified for SUNW_MP_PROCBIND
2.3.3 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. For details, refer to the OpenMP API Version 3.1 specification at http://openmp.org. See also 3.8 Environment Variables for specific information on the implementation of OpenMP environment variables by the Oracle Solaris Studio compilers.
Additional environment variables defined by the Oracle Solaris Studio compilers that are not part of the OpenMP specification are summarized in 2.2.2 Oracle Solaris Studio Environment Variables.
This section describes the defaults for the OpenMP environment variables.
If not set, a default value of STATIC is used.
Example: setenv OMP_SCHEDULE 'GUIDED,4'
If not set, a default of 2 is used.
Example: setenv OMP_NUM_THREADS 16
If not set, a default value of TRUE is used. .
Example: setenv OMP_DYNAMIC FALSE
If not set, the default is FALSE.
Example: setenv OMP_NESTED FALSE
The default is 4 Megabytes for 32-bit applications, and 8 Megabytes for 64-bit applications.
The following additional environment variables affect the execution of OpenMP programs and 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. 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.
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 user callback function by calling the following function:
int sunw_mp_register_warn (void (*func)(void *));
The address of the callback function is passed as argument to sunw_mp_register_warn(). This function returns 0 upon successfully registering the call-back 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 error message. The memory pointed to is no longer valid upon return from the callback function.
Note - The OpenMP runtime library has the ability to check for many common OpenMP violations, such as incorrect nesting and deadlocks. Runtime checking, however, adds overhead to the execution of the program. Set SUNW_MP_WARN to TRUE while testing or debugging a program to enable warning messages from the OpenMP runtime library to be displayed.
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, milliseconds, and microseconds, 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.
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 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 Oracle 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. If both SUNW_MP_PROCBIND and OMP_PROC_BIND are set, they must be set to the same value. 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 to work on parallel regions. The pool does not contain the initial (main) 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. If not specified, the default 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.
Sets the 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 specified, the default 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 Megabytes on 32-bit SPARC V8 and x86 platforms and 8 Megabytes on 64-bit SPARC V9 and x86 platforms.
The STACKSIZE environment variable accepts numerical values with a suffix of either B, K, M, or G for Bytes, Kilobytes, Megabytes, or Gigabytes respectively. If no suffix is specified, the default is Kilobytes.
Examples:
setenv STACKSIZE 8192 // sets the thread stack size to 8 Megabytes setenv STACKSIZE 16M // sets the thread stack size to 16 Megabytes
Note that if both STACKSIZE and OMP_STACKSIZE are set, they must be set to the same value. If the values are not the same, a runtime 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.
Allows fine-grain control of the behavior of 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 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.
Each of these keywords has 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.
If both SUNW_MP_WAIT_POLICY and OMP_WAIT_POLICY are set, OMP_WAIT_POLICY will be ignored.
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.
|