HOME
| OPENMP API Specification: Version 5.0 November 2018

6.5  OMP_PLACES

A list of places can be specified in the OMP_PLACES environment variable. The place-partition-var ICV obtains its initial value from the OMP_PLACES value, and makes the list available to the execution environment. The value of OMP_PLACES can be one of two types of values: either an abstract name that describes a set of places or an explicit list of places described by non-negative numbers.

The OMP_PLACES environment variable can be defined using an explicit ordered list of comma-separated places. A place is defined by an unordered set of comma-separated non-negative numbers enclosed by braces. The meaning of the numbers and how the numbering is done are implementation defined. Generally, the numbers represent the smallest unit of execution exposed by the execution environment, typically a hardware thread.

Intervals may also be used to define places. Intervals can be specified using the <lower-bound> : <length> : <stride> notation to represent the following list of numbers: “<lower-bound>, <lower-bound> + <stride>, ..., <lower-bound> + (<length> - 1)*<stride>.” When <stride> is omitted, a unit stride is assumed. Intervals can specify numbers within a place as well as sequences of places.

An exclusion operator “!” can also be used to exclude the number or place immediately following the operator.

Alternatively, the abstract names listed in Table 6.1 should be understood by the execution and runtime environment. The precise definitions of the abstract names are implementation defined. An implementation may also add abstract names as appropriate for the target platform.


Table 6.1: Defined Abstract Names for OMP_PLACES


Abstract Name Meaning


threads Each place corresponds to a single hardware thread on the target machine.
cores Each place corresponds to a single core (having one or more hardware threads) on the target machine.
sockets Each place corresponds to a single socket (consisting of one or more cores) on the target machine.


The abstract name may be appended by a positive number in parentheses to denote the length of the place list to be created, that is abstract_name(num-places). When requesting fewer places than available on the system, the determination of which resources of type abstract_name are to be included in the place list is implementation defined. When requesting more resources than available, the length of the place list is implementation defined.

The behavior of the program is implementation defined when the execution environment cannot map a numerical value (either explicitly defined or implicitly derived from an interval) within the OMP_PLACES list to a processor on the target platform, or if it maps to an unavailable processor. The behavior is also implementation defined when the OMP_PLACES environment variable is defined using an abstract name.

The following grammar describes the values accepted for the OMP_PLACES environment variable.

       ⟨list⟩ |=  ⟨p- list⟩ | ⟨aname ⟩
     ⟨p- list⟩ |=  ⟨p- interval⟩ | ⟨p-list⟩,⟨p-interval⟩

  ⟨p-interval⟩ |=  ⟨place⟩:⟨len⟩:⟨stride⟩ | ⟨place⟩:⟨len⟩ | ⟨place⟩ | !⟨place⟩
     ⟨place⟩ |=  {⟨res- list⟩}
    ⟨res- list⟩ |=  ⟨res- interval⟩ | ⟨res- list⟩,⟨res- interval⟩
⟨res-interval⟩ |=  ⟨res⟩:⟨num-places⟩:⟨stride⟩ | ⟨res⟩:⟨num -places⟩ | ⟨res⟩ | !⟨res⟩

    ⟨aname ⟩ |=  ⟨word⟩(⟨num-places⟩) | ⟨word⟩
     ⟨word⟩ |=  sockets | cores | threads | <implementation- definedabstractname>
       ⟨res⟩ |=  non- negativeinteger
⟨num-places⟩ |=  positiveinteger

     ⟨stride⟩ |=  integer
       ⟨len⟩ |=  positiveinteger

Examples:  

 
setenv OMP_PLACES threads 
setenv OMP_PLACES "threads(4)" 
setenv OMP_PLACES "{0,1,2,3},{4,5,6,7},{8,9,10,11},{12,13,14,15}" 
setenv OMP_PLACES "{0:4},{4:4},{8:4},{12:4}" 
setenv OMP_PLACES "{0:4}:4:4"  

where each of the last three definitions corresponds to the same 4 places including the smallest units of execution exposed by the execution environment numbered, in turn, 0 to 3, 4 to 7, 8 to 11, and 12 to 15.

Cross References