2.2 OpenMP Environment Variables

OMP_SCHEDULE

Sets schedule type for DO, PARALLEL DO, for, parallel for, directives/pragmas with schedule type RUNTIME specified.

If not set, a default value of STATIC is used. value is “type[,chunk]”

Example: setenv OMP_SCHEDULE 'GUIDED,4'

OMP_NUM_THREADS

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

OMP_DYNAMIC

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

OMP_NESTED

Enables or disables nested parallelism.

value is either TRUE or FALSE.

The default is FALSE.

Example: setenv OMP_NESTED FALSE

OMP_STACKSIZE

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

OMP_WAIT_POLICY

Set desired policy regarding waiting threads. The value is either ACTIVE or PASSIVE.

ACTIVE threads consume processor time while waiting. PASSIVE threads do not and may yield the processor or go to sleep.

OMP_MAX_ACTIVE_LEVELS

Sets the maximum number of levels of nested active parallel regions. Value is a non-negative integer. 

OMP_THREAD_LIMIT

Sets the number of threads to use in the whole OpenMP program. Value is a positive integer. 

PARALLEL

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.

SUNW_MP_WARN

Controls warning messages issued by the OpenMP runtime library. If set to TRUE the runtime library issues warning messages to stderr; FALSE disables warning messages. The default is FALSE.

The OpenMP runtime library has the ability to check for many common OpenMP violations, such as incorrect nesting and deadlocks. However, runtime checking does add overhead to the execution of the program.  

The runtime library issues warning messages to stderr if SUNW_MP_WARN is set to 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.

Example: 

setenv SUNW_MP_WARN TRUE

SUNW_MP_THR_IDLE

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). SLEEP, SLEEP(0), SLEEP(0s), SLEEP(0ms), and SLEEP(0mc) are all equivalent.

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.  

Note that if both SUNW_MP_THR_IDLE and OMP_WAIT_POLICY are set, they must have consistent values.

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)

SUNW_MP_PROCBIND

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.

SUNW_MP_MAX_POOL_THREADS

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.

SUNW_MP_MAX_NESTED_LEVELS

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.

STACKSIZE

Sets the stack size for each thread. The value is in kilobytes. The default stack size for a helper thread is 4 Megabytes for 32-bit applications, and 8 Megabytes for 64-bit applications.

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.

SUNW_MP_GUIDED_WEIGHT

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.