OpenMP::Environment - Perl extension managing OpenMP variables in %ENV within a script.
%ENV
Example 1; ensure an OpenMP environment is set up properly already (externally)
use OpenMP::Environment; my $env = OpenMP::Environment->new; $env->assert_omp_environment;
Example 2; Managing a range of thread scales (useful for benchmarking, testing, etc)
use OpenMP::Environment; my $env = OpenMP::Environment->new; foreach my $i (1 2 4 8 16 32 64 128 256) { $env->set_omp_num_threads($i); # Note: validated my $exit_code = system(qw{/path/to/my_prog_r --opt1 x --opt2 y}); if ($exit_code == 0) { # ... do some post processing } else { # ... handle failed execution } }
Example 3; Extended benchmarking, affecting OMP_SCHEDULE in addition to OMP_NUM_THREADS.
OMP_SCHEDULE
OMP_NUM_THREADS
use OpenMP::Environment; my $env = OpenMP::Environment->new; foreach my $i (1 2 4 8 16 32 64 128 256) { $env->set_omp_num_threads($i); # Note: validated foreach my $sched (qw/static dynamic auto/) { # compute chunk size my $chunk = get_baby_ruth($i); # set schedule using prescribed format $env->set_omp_schedule(qq{$sched;$chunk}); # Note: Not validated my $exit_code = system(qw{/path/to/my_prog_r --opt1 x --opt2 y}); if ($exit_code == 0) { # ... do some post processing } else { # ... handle failed execution } } }
There are setters, getters, and unsetters for all published OpenMP (and GOMP) environmental variables, in additional to some utility methods.
Provides accessors for affecting the OpenMP/GOMP environmental variables described at at the time of this writing, as:
The environment variables which beginning with OMP_ are defined by section 4 of the OpenMP specification in version 4.5, while those beginning with GOMP_ are GNU extensions.
Most provided methods are meant to manipulate a particular OpenMP environmental variable. Each has a setter, getter, and unsetter (i.e., deletes the variable from %ENV directly.
Each method is documented, and it is noted if the setter will validate the provided value. Validation occurs whenever the set of values is a simple numerical value or is a limited set of specific strings. It is clearly noted below when a setter does not validate. This is extended to assert_omp_environment, which will validate the variables it is able if they are already set in %ENV.
assert_omp_environment
https://gcc.gnu.org/onlinedocs/libgomp/Environment-Variables.html
There is a growing set of example scripts in the distribution's, examples/ directory.
examples/
The number and breadth of testing is also growing, so for more examples on using it and this module's flexibility; please see those.
Lastly, the Section "SUPPORTED OpenMP ENVIRONMENTAL VARIABLES" provides the full description of each environmental variable available in the OpenMP and GOMP documentation. It also describes the range of values that are deemed valid for each variable.
OpenMP
valid
new
Constructor
Validates OpenMP related environmental variables that might happen to be set in %ENV directly. Useful as a guard in launcher scripts to ensure the variables that are validated in this module are valid.
As is the case for all variables, an Environment completely devoid of any related variables being set is considered valid. In other words, only variables that are already set in the Environment are validated.
vars
Returns a list of all supported OMP_* and GOMP_* environmental variables.
OMP_*
GOMP_*
vars_unset
Returns a list of all unset supported variables.
vars_set
Returns a list of hash references of all set variables, of the form,
( VARIABLE1 => value1, VARIABLE2 => value2, ... )
print_omp_summary_unset
Prints summary of all unset variable.
Uses internal method, _omp_summary_unset to get string to print.
_omp_summary_unset
print_omp_summary_set
Prints summary of all set variables, including values.
Uses internal method, _omp_summary_set to get string to print.
_omp_summary_set
print_omp_summary
Prints summary of all set and unset variables; including values where applicable.
Uses internal method, _omp_summary to get string to print.
_omp_summary
omp_cancellation
Setter/getter for OMP_CANCELLATION.
OMP_CANCELLATION
Validated.
unset_omp_cancellation
Unsets OMP_CANCELLATION, deletes it from localized %ENV.
omp_display_env
Setter/getter for OMP_DISPLAY_ENV.
OMP_DISPLAY_ENV
unset_omp_display_env
Unsets OMP_DISPLAY_ENV, deletes it from localized %ENV.
omp_default_device
Setter/getter for OMP_DEFAULT_DEVICE.
OMP_DEFAULT_DEVICE
unset_omp_default_device
Unsets OMP_DEFAULT_DEVICE, deletes it from localized %ENV.
omp_dynamic
Setter/getter for OMP_DYNAMIC.
OMP_DYNAMIC
unset_omp_dynamic
Unsets OMP_DYNAMIC, deletes it from localized %ENV.
omp_max_active_levels
Setter/getter for OMP_MAX_ACTIVE_LEVELS.
OMP_MAX_ACTIVE_LEVELS
unset_omp_max_active_levels
Unsets OMP_MAX_ACTIVE_LEVELS, deletes it from localized %ENV.
omp_max_task_priority
Setter/getter for OMP_MAX_TASK_PRIORITY.
OMP_MAX_TASK_PRIORITY
unset_omp_max_task_priority
Unsets OMP_MAX_TASK_PRIORITY, deletes it from localized %ENV.
omp_nested
Setter/getter for OMP_NESTED.
OMP_NESTED
unset_omp_nested
Unsets OMP_NESTED, deletes it from localized %ENV.
omp_num_threads
Setter/getter for OMP_NUM_THREADS.
unset_omp_num_threads
Unsets OMP_NUM_THREADS, deletes it from localized %ENV.
omp_proc_bind
Setter/getter for OMP_PROC_BIND.
OMP_PROC_BIND
Not validated.
unset_omp_proc_bind
Unsets OMP_PROC_BIND, deletes it from localized %ENV.
omp_places
Setter/getter for OMP_PLACES.
OMP_PLACES
unset_omp_places
Unsets OMP_PLACES, deletes it from localized %ENV.
omp_stacksize
Setter/getter for OMP_STACKSIZE.
OMP_STACKSIZE
unset_omp_stacksize
Unsets OMP_STACKSIZE, deletes it from localized %ENV.
omp_schedule
Setter/getter for OMP_SCHEDULE.
unset_omp_schedule
Unsets OMP_SCHEDULE, deletes it from localized %ENV.
omp_target_offload
Setter/getter for OMP_TARGET_OFFLOADS.
OMP_TARGET_OFFLOADS
unset_omp_target_offload
Unsets OMP_TARGET_OFFLOADS, deletes it from localized %ENV.
omp_thread_limit
Setter/getter for OMP_THREAD_LIMIT.
OMP_THREAD_LIMIT
unset_omp_thread_limit
Unsets OMP_THREAD_LIMIT, deletes it from localized %ENV.
omp_wait_policy
Setter/getter for OMP_WAIT_POLICY.
OMP_WAIT_POLICY
unset_omp_wait_policy
Unsets OMP_WAIT_POLICY, deletes it from localized %ENV.
gomp_cpu_affinity
Setter/getter for GOMP_CPU_AFFINITY.
GOMP_CPU_AFFINITY
unset_gomp_cpu_affinity
Unsets GOMP_CPU_AFFINITY, deletes it from localized %ENV.
gomp_debug
Setter/getter for GOMP_DEBUG.
GOMP_DEBUG
unset_gomp_debug
Unsets GOMP_DEBUG, deletes it from localized %ENV.
gomp_stacksize
Setter/getter for GOMP_STACKSIZE.
GOMP_STACKSIZE
unset_gomp_stacksize
Unsets GOMP_STACKSIZE, deletes it from localized %ENV.
gomp_spincount
Setter/getter for GOMP_SPINCOUNT.
GOMP_SPINCOUNT
unset_gomp_spincount
Unsets GOMP_SPINCOUNT, deletes it from localized %ENV.
gomp_rtems_thread_pools
Setter/getter for GOMP_RTEMS_THREAD_POOLS.
GOMP_RTEMS_THREAD_POOLS
unset_gomp_rtems_thread_pools
Unsets GOMP_RTEMS_THREAD_POOLS, deletes it from localized %ENV.
Essentially direct copy from the URL in DESCRIPTION.
If set to TRUE, the cancellation is activated. If set to FALSE or if unset, cancellation is disabled and the cancel construct is ignored.
This variable is validated via setter.
If set to TRUE, the OpenMP version number and the values associated with the OpenMP environment variables are printed to stderr. If set to VERBOSE, it additionally shows the value of the environment variables which are GNU extensions. If undefined or set to FALSE, this information will not be shown.
Set to choose the device which is used in a target region, unless the value is overridden by omp_get_set_assert_default_device or by a device clause. The value shall be the nonnegative device number. If no device with the given device number exists, the code is executed on the host. If unset, device number 0 will be used.
Enable or disable the dynamic adjustment of the number of threads within a team. The value of this environment variable shall be TRUE or FALSE. If undefined, dynamic adjustment is disabled by default.
Specifies the initial value for the maximum number of nested parallel regions. The value of this variable shall be a positive integer. If undefined, then if OMP_NESTED is defined and set to true, or if OMP_NUM_THREADS or OMP_PROC_BIND are defined and set to a list with more than one item, the maximum number of nested parallel regions will be initialized to the largest number supported, otherwise it will be set to one.
Specifies the initial value for the maximum priority value that can be set for a task. The value of this variable shall be a non-negative integer, and zero is allowed. If undefined, the default priority is 0.
Enable or disable nested parallel regions, i.e., whether team members are allowed to create new teams. The value of this environment variable shall be TRUE or FALSE. If set to TRUE, the number of maximum active nested regions supported will by default be set to the maximum supported, otherwise it will be set to one. If OMP_MAX_ACTIVE_LEVELS is defined, its setting will override this setting. If both are undefined, nested parallel regions are enabled if OMP_NUM_THREADS or OMP_PROC_BINDS are defined to a list with more than one item, otherwise they are disabled by default.
Specifies the default number of threads to use in parallel regions. The value of this variable shall be a comma-separated list of positive integers; the value specifies the number of threads to use for the corresponding nested level. Specifying more than one item in the list will automatically enable nesting by default. If undefined one thread per CPU is used.
Specifies whether threads may be moved between processors. If set to TRUE, OpenMP theads should not be moved; if set to FALSE they may be moved. Alternatively, a comma separated list with the values MASTER, CLOSE and SPREAD can be used to specify the thread affinity policy for the corresponding nesting level. With MASTER the worker threads are in the same place partition as the master thread. With CLOSE those are kept close to the master thread in contiguous place partitions. And with SPREAD a sparse distribution across the place partitions is used. Specifying more than one item in the list will automatically enable nesting by default.
When undefined, OMP_PROC_BIND defaults to TRUE when OMP_PLACES or GOMP_CPU_AFFINITY is set and FALSE otherwise.
This module provides access to, but does NOT validate this variable.
The thread placement can be either specified using an abstract name or by an explicit list of the places. The abstract names threads, cores and sockets can be optionally followed by a positive number in parentheses, which denotes the how many places shall be created. With threads each place corresponds to a single hardware thread; cores to a single core with the corresponding number of hardware threads; and with sockets the place corresponds to a single socket. The resulting placement can be shown by setting the OMP_DISPLAY_ENV environment variable.
Alternatively, the placement can be specified explicitly as comma separated list of places. A place is specified by set of nonnegative numbers in curly braces, denoting the denoting the hardware threads. The hardware threads belonging to a place can either be specified as comma separated list of nonnegative thread numbers or using an interval. Multiple places can also be either specified by a comma separated list of places or by an interval. To specify an interval, a colon followed by the count is placed after after the hardware thread number or the place. Optionally, the length can be followed by a colon and the stride number - otherwise a unit stride is assumed. For instance, the following specifies the same places list: "{0,1,2}, {3,4,6}, {7,8,9}, {10,11,12}"; "{0:3}, {3:3}, {7:3}, {10:3}"; and "{0:2}:4:3".
If OMP_PLACES and GOMP_CPU_AFFINITY are unset and OMP_PROC_BIND is either unset or false, threads may be moved between CPUs following no placement policy.
Set the default thread stack size in kilobytes, unless the number is suffixed by B, K, M or G, in which case the size is, respectively, in bytes, kilobytes, megabytes or gigabytes. This is different from pthread_attr_get_set_assertstacksize which gets the number of bytes as an argument. If the stack size cannot be set due to system constraints, an error is reported and the initial stack size is left unchanged. If undefined, the stack size is system dependent.
Allows to specify schedule type and chunk size. The value of the variable shall have the form: type[,chunk] where type is one of static, dynamic, guided or auto The optional chunk size shall be a positive integer. If undefined, dynamic scheduling and a chunk size of 1 is used.
OMP_TARGET_OFFLOAD
Specifies the behaviour with regard to offloading code to a device. This variable can be set to one of three values - MANDATORY, DISABLED or DEFAULT.
If set to MANDATORY, the program will terminate with an error if the offload device is not present or is not supported. If set to DISABLED, then offloading is disabled and all code will run on the host. If set to DEFAULT, the program will try offloading to the device first, then fall back to running code on the host if it cannot.
If undefined, then the program will behave as if DEFAULT was set.
Specifies the number of threads to use for the whole program. The value of this variable shall be a positive integer. If undefined, the number of threads is not limited.
Specifies whether waiting threads should be active or passive. If the value is PASSIVE, waiting threads should not consume CPU power while waiting; while the value is ACTIVE specifies that they should. If undefined, threads wait actively for a short time before waiting passively.
Binds threads to specific CPUs. The variable should contain a space-separated or comma-separated list of CPUs. This list may contain different kinds of entries: either single CPU numbers in any order, a range of CPUs (M-N) or a range with some stride (M-N:S). CPU numbers are zero based. For example, GOMP_CPU_AFFINITY="0 3 1-2 4-15:2" will bind the initial thread to CPU 0, the second to CPU 3, the third to CPU 1, the fourth to CPU 2, the fifth to CPU 4, the sixth through tenth to CPUs 6, 8, 10, 12, and 14 respectively and then start assigning back from the beginning of the list. GOMP_CPU_AFFINITY=0 binds all threads to CPU 0.
There is no libgomp library routine to determine whether a CPU affinity specification is in effect. As a workaround, language-specific library functions, e.g., getenv in C or GET_ENVIRONMENT_VARIABLE in Fortran, may be used to query the setting of the GOMP_CPU_AFFINITY environment variable. A defined CPU affinity on startup cannot be changed or disabled during the runtime of the application.
If both GOMP_CPU_AFFINITY and OMP_PROC_BIND are set, OMP_PROC_BIND has a higher precedence. If neither has been set and OMP_PROC_BIND is unset, or when OMP_PROC_BIND is set to FALSE, the host system will handle the assignment of threads to CPUs.
Enable debugging output. The variable should be set to 0 (disabled, also the default if not set), or 1 (enabled).
If enabled, some debugging output will be printed during execution. This is currently not specified in more detail, and subject to change.
Determines how long a threads waits actively with consuming CPU power before waiting passively without consuming CPU power. The value may be either INFINITE, INFINITY to always wait actively or an integer which gives the number of spins of the busy-wait loop. The integer may optionally be followed by the following suffixes acting as multiplication factors: k (kilo, thousand), M (mega, million), G (giga, billion), or T (tera, trillion). If undefined, 0 is used when OMP_WAIT_POLICY is PASSIVE, 300,000 is used when OMP_WAIT_POLICY is undefined and 30 billion is used when OMP_WAIT_POLICY is ACTIVE. If there are more OpenMP threads than available CPUs, 1000 and 100 spins are used for OMP_WAIT_POLICY being ACTIVE or undefined, respectively; unless the GOMP_SPINCOUNT is lower or OMP_WAIT_POLICY is PASSIVE.
Set the default thread stack size in kilobytes. This is different from pthread_attr_get_set_assertstacksize which gets the number of bytes as an argument. If the stack size cannot be set due to system constraints, an error is reported and the initial stack size is left unchanged. If undefined, the stack size is system dependent.
This environment variable is only used on the RTEMS real-time operating system. It determines the scheduler instance specific thread pools. The format for GOMP_RTEMS_THREAD_POOLS is a list of optional <thread-pool-count>[$<priority>]@<scheduler-name> configurations separated by : where:
1. thread-pool-count is the thread pool count for this scheduler instance.
thread-pool-count
2. $<priority> is an optional priority for the worker threads of a thread pool according to pthread_get_set_assertschedparam. In case a priority value is omitted, then a worker thread will inherit the priority of the OpenMP master thread that created it. The priority of the worker thread is not changed after creation, even if a new OpenMP master thread using the worker has a different priority.
3. @<scheduler-name> is the scheduler instance name according to the RTEMS application configuration.
In case no thread pool configuration is specified for a scheduler instance, then each OpenMP master thread of this scheduler instance will use its own dynamically allocated thread pool. To limit the worker thread count of the thread pools, each OpenMP master thread must call set_num_threads.
This module heavily favors the GOMP implementation of the OpenMP specification within gcc.
GOMP
https://gcc.gnu.org/onlinedocs/libgomp/index.html
oodler577
Copyright (C) 2021 by oodler577
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.30.0 or, at your option, any later version of Perl 5 you may have available.
To install OpenMP::Environment, copy and paste the appropriate command in to your terminal.
cpanm
cpanm OpenMP::Environment
CPAN shell
perl -MCPAN -e shell install OpenMP::Environment
For more information on module installation, please visit the detailed CPAN module installation guide.