API - Querying

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.

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.

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.

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.

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.

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).

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.

printaffinities(; threadpool = :default, kwargs...)

Print the affinity masks of all Julia threads. See printaffinity for options.

Visualize the affinity mask of a Julia thread. Many of the keyword options of threadinfo work here as well.

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.

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.

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.

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.

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.

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.

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.

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.

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.

All valid CPU IDs of the system (sorted).

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

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

Number of CPU-threads

Number of cores (i.e. excluding hyperthreads)

Number of NUMA nodes

Number of CPU-sockets / CPUs

Number of different kinds of cores (e.g. efficiency and performance cores).

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

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.

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

Check whether simultaneous multithreading (SMT) / "hyperthreading" is enabled.

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.

openblas_getcpuids()

Get the ids of the CPU threads on which the OpenBLAS threads are running on according to their affinity. See openblas_getcpuid for more information."

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.

openblas_ispinned(; threadid)

Check if the OpenBLAS thread is pinned to a single CPU thread.

Print the affinities of all OpenBLAS threads.

openblas_printaffinity(; threadid)

Print the affinity of an OpenBLAS thread.

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.

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.

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.

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.

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.

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.