API - Querying

threadinfo

ThreadPinning.threadinfoFunction
threadinfo(;
    groupby = :sockets,
    threadpool = :default,
    blas = false,
    slurm = false,
    hints = false,
    compact = true,
    hyperthreads = SysInfo.hyperthreading_is_enabled(),
    efficiency = SysInfo.ncorekinds() > 1,
    masks = false,
    coregaps = SysInfo.hyperthreading_is_enabled(),
    logical = false,
    color = true,
    blocksize = choose_blocksize()
)

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

Keyword arguments

  • groupby: Options are :sockets, :numa, :cores, or :none.
  • threadpool: Only consider Julia threads in the given thread pool. Supported values are :default, :interactive, and :all.
  • blas: Visualize BLAS threads instead of Julia threads.
  • slurm: Only show the part of the system that is covered by the active SLURM allocation.
  • hints: Try to give some hints about how to improve the threading related settings.
  • compact: Toggle between compact and "cores before hyperthreads" ordering.
  • hyperthreads: If true, we (try to) highlight CPU-threads that aren't the first threads within a CPU-core.
  • efficiency: If true, we highlight (underline) CPU-threads that belong to efficiency cores.
  • masks: Show the affinity masks of all Julia threads.
  • coregaps: Put an extra space ("gap") between different CPU-cores, when printing.
  • logical: Toggle between logical and "physical" CPU-thread indices.
  • color: Toggle between colored and black-and-white output.
  • blocksize: Wrap to a new line after blocksize many CPU-threads. May also be set to :numa in which case the line break will occur after each numa domain.
source

Querying

ThreadPinning.getcpuidsFunction
getcpuids(; threadpool = :default)

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

The keyword argument threadpool (default: :default) may be used to specify a specific thread pool.

source
ThreadPinning.getcpuidFunction
getcpuid(; threadid = nothing)

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

If threadid=nothing (default), we query the id directly from the calling thread.

source
ThreadPinning.ispinnedFunction
ispinned(; threadid = Threads.threadid())

Returns true if the thread is pinned, that is, if it has an affinity mask that highlights a single CPU-thread.

source
ThreadPinning.getispinnedFunction
getispinned(; threadpool = :default)

Returns the results of ispinned for all Julia threads.

The keyword argument threadpool (default: :default) may be used to specify a specific thread pool.

source
ThreadPinning.getaffinityFunction
getaffinity(; threadid = Threads.threadid(), cutoff = cpuidlimit())

Get the thread affinity of a Julia thread. Returns the affinity mask as a vector of zeros and ones. By default, the mask is cut off at Sys.CPU_THREADS. This can be tuned via the cutoff keyword argument (nothing means no cutoff).

source
ThreadPinning.printaffinityFunction
printaffinity(; threadid::Integer = Threads.threadid())

Print the affinity mask of the Julia thread.

The keyword argument groupby may be used to change how CPU-threads are grouped visually. It defaults to groupby=:socket. Other valid values are :numa and :core.

source
ThreadPinning.getnumanodeFunction
getnumanode(; threadid = nothing)

Returns the ID (starting at zero) of the NUMA node corresponding to the CPU thread on which the calling thread is currently running. A threadid may be provided to consider a Julia thread that is different from the calling one.

source
ThreadPinning.getnumanodesFunction
getnumanodes(; threadpool = :default)

Returns the IDs (starting at zero) of the NUMA nodes corresponding to the CPU threads on which the Julia threads are currently running.

The keyword argument threadpool (default: :default) may be used to consider only those Julia threads that belong to a specific thread pool.

source

Querying - Logical

ThreadPinning.coreFunction

Returns the CPU IDs that belong to core i (logical index, starts at 1). Set shuffle=true to randomize.

Optional second argument: Logical indices to select a subset of the CPU-threads.

source
ThreadPinning.numaFunction

Returns the CPU IDs that belong to the ith NUMA domain (logical index, starts at 1). By default, an "cores before hyperthreads" ordering is used. Set compact=true if you want compact ordering. Set shuffle=true to randomize.

Optional second argument: Logical indices to select a subset of the CPU-threads.

source
ThreadPinning.socketFunction

Returns the CPU IDs that belong to the ith CPU/socket (logical index, starts at 1). By default, an "cores before hyperthreads" ordering is used. Set compact=true if you want compact ordering. Set shuffle=true to randomize.

Optional second argument: Logical indices to select a subset of the CPU-threads.

source
ThreadPinning.nodeFunction

Returns all CPU IDs of the system/compute node (logical index, starts at 1). By default, an "cores before hyperthreads" ordering is used. Set compact=true if you want compact ordering. Set shuffle=true to randomize.

Optional second argument: Logical indices to select a subset of the CPU-threads.

source
ThreadPinning.coresFunction

Returns the CPU IDs of the system as obtained by a round-robin scattering between CPU cores. This is the same as nodes(; compact=false). Set shuffle=true to randomize.

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

source
ThreadPinning.numasFunction

Returns the CPU IDs of the system as obtained by a round-robin scattering between NUMA domains. Within each NUMA domain, a round-robin ordering among CPU cores is used ("cores before hyperthreads"). Provide compact=true to get compact ordering within each NUMA domain. Set shuffle=true to randomize.

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

source
ThreadPinning.socketsFunction

Returns the CPU IDs of the system as obtained by a round-robin scattering between sockets. By default, within each socket, a round-robin ordering among CPU cores is used ("cores before hyperthreads"). 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 sockets.

source
ThreadPinning.idFunction

Returns the logical index (starts at 1) that corresponds to the given CPU ID ("physical" OS index).

source
ThreadPinning.cpuidFunction

Returns the CPU ID ("physical" OS index) that corresponds to the given logical index (starts at 1).

source

Querying - System

ThreadPinning.nsmtFunction

The number of SMT-threads in a core. If this number varies between different cores, the maximum is returned.

source
ThreadPinning.isefficiencycoreFunction

Returns true if the given CPU-thread lies inside of a CPU-core that has the highest power efficiency of all the CPU-cores (i.e. an efficiency value of 1). If there is only a single CPU-core kind, the return value is false for all CPU IDs.

source
ThreadPinning.ishyperthreadFunction

Check whether the given CPU-thread is a SMT-thread / "hyperthread" (i.e. it is not the first CPU-thread in the CPU-core).

source

Querying - OpenBLAS

ThreadPinning.openblas_getaffinityFunction
openblas_getaffinity(; threadid, convert = true)

Query the affinity of the OpenBLAS thread with the given threadid (typically 1:BLAS.get_num_threads()). By default, returns a vector respresenting the mask. If convert=false a Ccpu_set_t is returned instead.

source
ThreadPinning.openblas_getcpuidFunction
openblas_getcpuid(; threadid)

Get the id of the CPU thread on which the OpenBLAS thread with the given threadid is running on according to its affinity.

Note: If the OpenBLAS thread has not been pinned before, this function will error because the affinity mask highlights more than a single CPU thread by default.

source

Querying - MPI

ThreadPinning.mpi_getcpuidsFunction

On rank 0, this function returns a Dict{Int, Vector{Int}} where the keys are the MPI rank ids and the values are the CPU IDs of the CPU-threads that are currently running the Julia threads of the MPI rank. Returns nothing on all other ranks.

source
ThreadPinning.mpi_gethostnamesFunction

On rank 0, this function returns a Dict{Int, String} where the keys are the MPI rank ids and the values are the hostnames of the nodes that are currently hosting the respective MPI ranks. Returns nothing on all other ranks.

source
ThreadPinning.mpi_getlocalrankFunction

Returns a node-local rank id (starts at zero). Nodes are identified based on their hostnames (gethostname). On each node, ranks are ordered based on their global rank id.

source

Querying - Distributed.jl

ThreadPinning.distributed_getcpuidsFunction

Returns a Dict{Int, Vector{Int}} where the keys are the pids of the Julia workers and the values are the CPU IDs of the CPU-threads that are currently running the Julia threads of the worker.

If include_master=true, the master process (Distributed.myid() == 1) will be included.

source
ThreadPinning.distributed_gethostnamesFunction

Returns a Dict{Int, String} where the keys are the pids of the Julia workers and the values are the hostnames of the nodes that are currently hosting the respective workers.

If include_master=true, the master process (Distributed.myid() == 1) will be included.

source
ThreadPinning.distributed_getispinnedFunction

Returns a Dict{Int, Vector{Bool}} where the keys are the pids of the Julia workers and the values are the results of ThreadPinning.ispinned evaluated for all Julia threads of a worker.

If include_master=true, the master process (Distributed.myid() == 1) will be included.

source