Thread Affinity Interface (Linux* and Windows*)
The Intel® runtime library has the ability to bind OpenMP* threads to physical processing units. The interface is controlled using the
environment variable. Depending on the system (machine) topology, application, and operating system, thread affinity can have a dramatic effect on the application speed.
Thread affinityrestricts execution of certain threads (virtual execution units) to a subset of the physical processing units in a multiprocessor computer. Depending upon the topology of the machine, thread affinity can have a dramatic effect on the execution speed of a program.
Thread affinity is supported on Windows* systems and versions of Linux* systems that have kernel support for thread affinity
, but is not supported by.
The Intel OpenMP runtime library has the ability to bind OpenMP* threads to physical processing units. There are three types of interfaces you can use to specify this binding, which are collectively referred to as the Intel OpenMP Thread Affinity Interface:
- The high-level affinity interface uses an environment variable to determine the machine topology and assigns OpenMP* threads to the processors based upon their physical location in the machine. This interface is controlled entirely by theKMP_AFFINITYenvironment variable.
- The mid-level affinity interface uses an environment variable to explicitly specifies which processors (labeled with integer IDs) are bound to OpenMP* threads. This interface provides compatibility with the gcc*environment variable, but you can also invoke it by using theGOMP_AFFINITYenvironment variable. TheKMP_AFFINITYenvironment variable is supported on Linux* systems only, but users on Windows* or Linux* systems can use the similar functionality provided by theGOMP_AFFINITYenvironment variable.KMP_AFFINITY
- The low-level affinity interface uses APIs to enable OpenMP* threads to make calls into the OpenMP* runtime library to explicitly specify the set of processors on which they are to be run. This interface is similar in nature tosched_setaffinityand related functions on Linux* systems or toSetThreadAffinityMaskand related functions on Windows* systems. In addition, you can specify certain options of theenvironment variable to affect the behavior of the low-level API interface. For example, you can set the affinity typeKMP_AFFINITYto disabled, which disables the low-level affinity interface, or you could use theKMP_AFFINITYorKMP_AFFINITYenvironment variables to set the initial affinity mask, and then retrieve the mask with the low-level API interface.GOMP_AFFINITY
The following terms are used in this section:
- The total number of processing elements on the machine is referred to as the number ofOS thread contexts.
- Each processing element is referred to as an Operating System processor, orOS proc.
- Each OS processor has a unique integer identifier associated with it, called anOS proc ID.
- The termpackagerefers to a single or multi-core processor chip.
- The termOpenMP* Global Thread ID(GTID) refers to an integer which uniquely identifies all threads known to the Intel OpenMP runtime library. The thread that first initializes the library is given GTID 0. In the normal case where all other threads are created by the library and when there is no nested parallelism, thenn-threads-var- 1 new threads are created with GTIDs ranging from 1 tontheads-var- 1, and each thread's GTID is equal to the OpenMP* thread number returned by functionomp_get_thread_num(). The high-level and mid-level interfaces rely heavily on this concept. Hence, their usefulness is limited in programs containing nested parallelism. The low-level interface does not make use of the concept of a GTID, and can be used by programs containing arbitrarily many levels of parallelism.
Some environment variables are available for both Intel® microprocessors and non-Intel microprocessors, but may perform additional optimizations for Intel® microprocessors than for non-Intel microprocessors.
KMP_AFFINITY Environment Variable
You must set the
KMP_AFFINITYenvironment variable before the first parallel region, or certain API calls including
omp_get_num_procs()and any affinity API calls, as described in Low Level Affinity API, below.
KMP_AFFINITYenvironment variable uses the following general syntax:
For example, to list a machine topology map, specify
KMP_AFFINITY=verbose,noneto use a
The following table describes the supported specific arguments.
Optional. String consisting of keyword and specifier.
The syntax for
<is explained in mid-level affinity interface.
On Windows* with multiple processor groups, the norespect affinity modifier is assumed when the process affinity mask equals a single processor group (which is default on Windows*). Otherwise, the respect affinity modifier is used.
Required string. Indicates the thread affinity to use.
physicaltypes are deprecated but supported for backward compatibility.
Optional. Positive integer value. Not valid with type values of