API

pinthread(threadid::Integer, cpuid::Integer; kwargs...)

Pin the given Julia thread (threadid) to the CPU with ID cpuid.

pinthread(cpuid::Integer; warn::Bool = true)

Pin the calling Julia thread to the CPU with id cpuid.

pinthreads(cpuids[; nthreads=Threads.nthreads(), force=true, warn=true])

Pin the first min(length(cpuids), nthreads) Julia threads to an explicit or implicit list of CPU IDs. The latter can be specified in three ways:

1. explicitly (e.g. 0:3 or [0,12,4]),
2. by passing one of several predefined symbols (e.g. :cores or :sockets),
3. by providing a logical specification via helper functions (e.g. node and socket).

See below for more information.

If force=false the pinthreads call will only pin threads if this is the first attempt to pin threads with ThreadPinning.jl. Otherwise it will be a no-op. This may be particularly useful for packages that merely want to specify a "default pinning".

The option warn toggles general warnings, such as unwanted interference with BLAS thread settings.

1) Explicit

Simply provide an AbstractVector{<:Integer} of CPU IDs. The latter are expected to be the "physical" ids, i.e. as provided by lscpu, and thus start at zero!

2) Predefined Symbols

• :cputhreads or :compact: successively pin to all available CPU-threads.
• :cores: spread threads across all available cores, only use hyperthreads if necessary.
• :sockets: spread threads across sockets (round-robin), only use hyperthreads if necessary. Set compact=true to get compact pinning within each socket.
• :numa: spread threads across NUMA/memory domains (round-robin), only use hyperthreads if necessary. Set compact=true to get compact pinning within each NUMA/memory domain.
• :random: pin threads randomly to CPU-threads
• :current: pin threads to the CPU-threads they are currently running on
• :firstn: pin threads to CPU-threads in "physical" order (as specified by lscpu).

3) Logical Specification

The functions node, socket, numa, and core can be used to to specify CPU IDs of/within a certain domain. Moreover, the functions sockets and numas can be used to express a round-robin scatter policy between sockets or NUMA domains, respectively.

Examples (domains):

• pinthreads(socket(1, 1:3)) # pin to the first 3 cores in the first socket
• pinthreads(socket(1, 1:3; compact=true)) # pin to the first 3 CPU-threads in the first socket
• pinthreads(numa(2, [2,4,6])) # pin to the second, the fourth, and the sixth cores in the second NUMA/memory domain
• pinthreads(node(ncores():-1:1)) # pin threads to cores in reversing order (starting at the end of the node)
• pinthreads(sockets()) # scatter threads between sockets, cores before hyperthreads

Different domains can be concatenated by providing them in a vector or as separate arguments to pinthreads.

Examples (concatenation):

• pinthreads([socket(1, 1:3), numa(2, 4:6)])
• pinthreads(socket(1, 1:3), numa(2, 4:6))

Unpins the Julia thread with the given threadid by setting the affinity mask to all unity. Afterwards, the OS is free to move the Julia thread from one CPU thread to another.

Unpins all Julia threads by setting the affinity mask of all threads to all unity. Afterwards, the OS is free to move any Julia thread from one CPU thread to another.

Represents the CPU ID domain of core i (logical index, starts at 1). Uses compact ordering by default. Set shuffle=true to randomize.

Optional second argument: Logical indices to select a subset of the domain.

To be used as input argument for pinthreads. What it actually returns is an implementation detail!

Returns a Vector{Int} which lists all valid CPUIDs. There is no guarantee about the order except that it is the same as in lscpu.

Returns a Vector{Vector{Int}} which indicates the CPUIDs associated with the available physical cores

Returns a Vector{Int} which indicates the CPUIDs associated with the available node. Physical cores come first. Set compact=true to get compact ordering.

Returns a Vector{Vector{Int}} which indicates the CPUIDs associated with the available NUMA domains. Within each memory domain, physical cores come first. Set compact=true to get compact ordering instead.

Returns a Vector{Vector{Int}} which indicates the CPUIDs associated with the available CPU sockets. Within each socket, physical cores come first. Set compact=true to get compact ordering instead.

Returns the ID of the CPU thread on which the given Julia thread (threadid) is currently running.

Returns the ID of the CPU thread on which the calling thread is currently running.

See sched_getcpu for more information.

Returns the IDs of the CPU-threads on which the Julia threads are currently running.

See getcpuid for more information.

Check whether hyperthreading is enabled.

Check whether the given CPU-thread is a hyperthread (i.e. the second CPU-thread associated with a CPU-core).

Number of cores (i.e. excluding hyperthreads)

Number of CPU-cores per NUMA domain

Number of CPU-cores per socket

Number of CPU-threads

Number of CPU-threads per core

Number of CPU-threads per NUMA domain

Number of CPU-threads per socket

Number of NUMA nodes

Represents the CPU ID domain of the entire node/system. By default, cores will be used first and hyperthreads will only be used if necessary. Provide compact=true to get compact ordering instead. Set shuffle=true to randomize. Set shuffle=true to randomize.

Optional first argument: Logical indices to select a subset of the domain.

To be used as input argument for pinthreads. What it actually returns is an implementation detail!

Number of CPU sockets

Represents the CPU ID domain of NUMA/memory domain i (logical index, starts at 1). By default, cores will be used first and hyperthreads will only be used if necessary. Provide compact=true to get compact ordering instead. Set shuffle=true to randomize.

Optional second argument: Logical indices to select a subset of the domain.

To be used as input argument for pinthreads. What it actually returns is an implementation detail!

Represents the CPU IDs of the system as obtained by a round-robin scattering between NUMA/memory domain. By default, within each memory domain, cores will be used first and hyperthreads will only be used if necessary. Provide compact=true to get compact ordering within each memory domain. Set shuffle=true to randomize.

Optional first argument: Logical indices to select a subset of the domain.

To be used as input argument for pinthreads. What it actually returns is an implementation detail!

Print the affinity masks of all Julia threads.

Represents the CPU ID domain of socket i (logical index, starts at 1). By default, cores will be used first and hyperthreads will only be used if necessary. Provide compact=true to get compact ordering instead. Set shuffle=true to randomize.

Optional second argument: Logical indices to select a subset of the domain.

To be used as input argument for pinthreads. What it actually returns is an implementation detail!

Represents the CPU IDs of the system as obtained by a round-robin scattering between sockets. By default, within each socket, cores will be used first and hyperthreads will only be used if necessary. Provide compact=true to get compact ordering within each socket. Set shuffle=true to randomize.

Optional first argument: Logical indices to select a subset of the domain.

To be used as input argument for pinthreads. What it actually returns is an implementation detail!

Print information about Julia threads, e.g. on which CPU-threads (i.e. cores if hyperthreading is disabled) they are running.

Keyword arguments:

• color (default: true): Toggle between colored and black-and-white output.
• blocksize (default: 32): Wrap to a new line after blocksize many CPU-threads.
• hyperthreading (default: true): If true, we (try to) highlight CPU-threads associated with hyperthreading in the color=true output.
• blas (default: false): Show information about BLAS threads as well.
• hints (default: false): Give some hints about how to improve the threading related settings.
• groupby (default: :sockets): Options are :sockets, :numa, :cores, or :none.
• masks (default: false): Show the affinity masks of all Julia threads.
• threadpool (default: :all): Only consider Julia threads in the given thread pool. Supported values are :all, :default, and :interactive. Only works for Julia >= 1.9.