base/sysinfo.jl - master - githubmirror/julia

base/sysinfo.jl
556 строк18 KB
Rui JingAn
Sys: Fix CPU summary aggregation across models and speeds (#62609)
03 авг 2026, 22:32
03 авг 2026, 22:325a3fa28
# This file is a part of Julia. License is MIT: https://julialang.org/license

# NB: This file is `Core.eval`-uated into the (pre-existing) module Sys

@doc """
Provide methods for retrieving information about hardware and the operating system.
""" Sys

export BINDIR,
       STDLIB,
       CPU_THREADS,
       EFFECTIVE_CPU_THREADS,
       CPU_NAME,
       WORD_SIZE,
       ARCH,
       MACHINE,
       JIT,
       PAGESIZE,
       cpu_info,
       cpu_summary,
       sysimage_target,
       uptime,
       loadavg,
       free_memory,
       total_memory,
       free_physical_memory,
       total_physical_memory,
       isexecutable,
       isreadable,
       iswritable,
       username,
       which

import ..Base: DATAROOTDIR, show

"""
    Sys.BINDIR::String

A string containing the full path to the directory containing the `julia` executable.
"""
global BINDIR::String = ccall(:jl_get_julia_bindir, Any, ())::String

"""
    Sys.STDLIB::String

A string containing the full path to the directory containing the `stdlib` packages.
"""
global STDLIB::String = "$BINDIR/$DATAROOTDIR/julia/stdlib/v$(VERSION.major).$(VERSION.minor)" # for bootstrap
# In case STDLIB change after julia is built, the variable below can be used
# to update cached method locations to updated ones.
const BUILD_STDLIB_PATH = STDLIB

# helper to avoid triggering precompile warnings

"""
    Sys.CPU_THREADS::Int

The number of logical CPU cores available in the system, i.e. the number of threads
that the CPU can run concurrently. Note that this is not necessarily the number of
CPU cores, for example, in the presence of
[hyper-threading](https://en.wikipedia.org/wiki/Hyper-threading).

See Hwloc.jl or CpuId.jl for extended information, including number of physical cores.

See also: [`Sys.EFFECTIVE_CPU_THREADS`](@ref) for a container-aware CPU count that respects
cgroup limits.
"""
global CPU_THREADS::Int = 1 # for bootstrap, changed on startup

"""
    Sys.EFFECTIVE_CPU_THREADS::Int

The effective number of logical CPU cores available to the Julia process, taking into
account container limits (e.g., Docker `--cpus`, Kubernetes CPU limits, cgroup quotas).
This is the minimum of the hardware CPU thread count and any imposed CPU limits.

In non-containerized environments, this typically equals `Sys.CPU_THREADS`. In containerized
environments, it respects cgroup CPU limits and provides a more accurate measure of
available parallelism.

Use this constant when determining default thread pool sizes or parallelism levels to
ensure proper behavior in containerized deployments.
"""
global EFFECTIVE_CPU_THREADS::Int = 1 # for bootstrap, changed on startup

"""
    Sys.ARCH::Symbol

A symbol representing the architecture of the build configuration.
"""
const ARCH = ccall(:jl_get_ARCH, Any, ())::Symbol


"""
    Sys.MACHINE::String

A string containing the build triple.
"""
const MACHINE = Base.MACHINE::String

"""
    Sys.WORD_SIZE::Int

Standard word size on the current machine, in bits.
"""
const WORD_SIZE = Core.sizeof(Int) * 8

"""
    Sys.SC_CLK_TCK::Clong

The number of system "clock ticks" per second, corresponding to `sysconf(_SC_CLK_TCK)` on
POSIX systems, or `0` if it is unknown.
"""
global SC_CLK_TCK::Clong

"""
    Sys.CPU_NAME::String

A string representing the name of the host CPU.

# Examples
For example, `Sys.CPU_NAME` might equal `"tigerlake"` on an
[Intel Core "Tiger Lake" CPU](https://en.wikipedia.org/wiki/Tiger_Lake),
or `"apple-m1"` on an [Apple M1 CPU](https://en.wikipedia.org/wiki/Apple_M1).

Note: Included in the output of `versioninfo()`.
"""
global CPU_NAME::String

"""
    Sys.JIT::String

A string representing the specific Just-In-Time (JIT) compiler being utilized in the current runtime.

# Examples
Currently, this equals `"ORCJIT"` for the LLVM "ORC" ("On-Request Compilation") JIT library:
```jldoctest
julia> Sys.JIT
"ORCJIT"
```

Note: Included in the output of `versioninfo()`.
"""
global JIT::String

"""
    Sys.PAGESIZE::Clong

A number providing the pagesize of the given OS.  Common values being 4kb or 64kb on Linux.
On Windows, this stores the allocation granularity, not the page size.
"""
global PAGESIZE::Clong

function __init__()
    env_threads = nothing
    if haskey(ENV, "JULIA_CPU_THREADS")
        env_threads = ENV["JULIA_CPU_THREADS"]
    end
    global CPU_THREADS = if env_threads !== nothing
        env_threads = tryparse(Int, env_threads)
        if env_threads === nothing || env_threads <= 0
            env_threads = Int(ccall(:jl_cpu_threads, Int32, ()))
            Core.print(Core.stderr, "WARNING: couldn't parse `JULIA_CPU_THREADS` environment variable. Defaulting Sys.CPU_THREADS to $env_threads.\n")
        end
        env_threads
    else
        Int(ccall(:jl_cpu_threads, Int32, ()))
    end
    global EFFECTIVE_CPU_THREADS = min(CPU_THREADS, Int(ccall(:jl_effective_threads, Int32, ())))
    global SC_CLK_TCK = ccall(:jl_SC_CLK_TCK, Clong, ())
    global CPU_NAME = ccall(:jl_get_cpu_name, Ref{String}, ())
    global JIT = ccall(:jl_get_JIT, Ref{String}, ())
    global PAGESIZE = Int(Sys.isunix() ? ccall(:jl_getpagesize, Clong, ()) : ccall(:jl_getallocationgranularity, Clong, ()))
    __init_build()
    nothing
end
# Populate the paths needed by sysimg compilation, e.g. `generate_precompile.jl`,
# without pulling in anything unnecessary like `CPU_NAME`
function __init_build()
    global BINDIR = ccall(:jl_get_julia_bindir, Any, ())::String
    vers = "v$(string(VERSION.major)).$(string(VERSION.minor))"
    global STDLIB = abspath(BINDIR, DATAROOTDIR, "julia", "stdlib", vers)
    nothing
end

mutable struct UV_cpu_info_t
    model::Ptr{UInt8}
    speed::Int32
    cpu_times!user::UInt64
    cpu_times!nice::UInt64
    cpu_times!sys::UInt64
    cpu_times!idle::UInt64
    cpu_times!irq::UInt64
end

"""
    Sys.CPUinfo

The `CPUinfo` type is a mutable struct with the following fields:
- `model::String`: CPU model information.
- `speed::Int32`: CPU speed (in MHz).
- `cpu_times!user::UInt64`: Time spent in user mode. CPU state shows CPU time used by user space processes.
- `cpu_times!nice::UInt64`: Time spent in nice mode. CPU state is a subset of the "user" state and shows the CPU time used by processes that have a positive niceness, meaning a lower priority than other tasks.
- `cpu_times!sys::UInt64`: Time spent in system mode. CPU state shows the amount of CPU time used by the kernel.
- `cpu_times!idle::UInt64`: Time spent in idle mode. CPU state shows the CPU time that's not actively being used.
- `cpu_times!irq::UInt64`: Time spent handling interrupts. CPU state shows the amount of time the CPU has been servicing hardware interrupts.

The times are in units of milliseconds.

Note: Included in the detailed system information via `versioninfo(verbose=true)`.
"""
mutable struct CPUinfo
    model::String
    speed::Int32
    cpu_times!user::UInt64
    cpu_times!nice::UInt64
    cpu_times!sys::UInt64
    cpu_times!idle::UInt64
    cpu_times!irq::UInt64
    CPUinfo(model,speed,u,n,s,id,ir)=new(model,speed,u,n,s,id,ir)
end
CPUinfo(info::UV_cpu_info_t) = CPUinfo(unsafe_string(info.model), info.speed,
    info.cpu_times!user, info.cpu_times!nice, info.cpu_times!sys,
    info.cpu_times!idle, info.cpu_times!irq)

public CPUinfo

function _show_cpuinfo(io::IO, info::Sys.CPUinfo, header::Bool=true, prefix::AbstractString="    ")
    if header
        println(io, info.model, ": ")
        print(io, " "^length(prefix))
        println(io, "    ", lpad("speed", 5), "    ", lpad("user", 9), "    ", lpad("nice", 9), "    ",
                lpad("sys", 9), "    ", lpad("idle", 9), "    ", lpad("irq", 9))
    end
    print(io, prefix)
    ms_per_s = 1000
    unit = " s  "
    d(i, unit=unit) = lpad(string(round(Int64,i)), 9) * unit
    print(io,
          lpad(string(info.speed), 5), " MHz  ",
          d(info.cpu_times!user / ms_per_s), d(info.cpu_times!nice / ms_per_s), d(info.cpu_times!sys / ms_per_s),
          d(info.cpu_times!idle / ms_per_s), d(info.cpu_times!irq / ms_per_s))
end

show(io::IO, ::MIME"text/plain", info::CPUinfo) = _show_cpuinfo(io, info, true, "    ")

function _cpu_summary(io::IO, cpu::AbstractVector{CPUinfo}, i, j)
    if j-i < 9
        header = true
        for x = i:j
            header || println(io)
            _show_cpuinfo(io, cpu[x], header, "#$(x-i+1) ")
            header = false
        end
    else
        summary = CPUinfo(cpu[i].model,0,0,0,0,0,0)
        count = j - i + 1
        for x = i:j
            summary.speed += cpu[x].speed
            summary.cpu_times!user += cpu[x].cpu_times!user
            summary.cpu_times!nice += cpu[x].cpu_times!nice
            summary.cpu_times!sys += cpu[x].cpu_times!sys
            summary.cpu_times!idle += cpu[x].cpu_times!idle
            summary.cpu_times!irq += cpu[x].cpu_times!irq
        end
        summary.speed = div(summary.speed,count)
        _show_cpuinfo(io, summary, true, "#1-$(count) ")
    end
    println(io)
end

"""
    Sys.cpu_summary(io::IO=stdout, cpu::AbstractVector{CPUinfo}=cpu_info())

Print a summary of CPU information to the `io` stream (defaulting to [`stdout`](@ref)), organizing and displaying aggregated data for CPUs with the same model, for a given array of `CPUinfo` data structures
describing a set of CPUs (which defaults to the return value of the [`Sys.cpu_info`](@ref) function).

The summary includes aggregated information for each distinct CPU model,
providing details such as average CPU speed and total time spent in different modes (user, nice, sys, idle, irq) across all cores with the same model.

Note: Included in the detailed system information via `versioninfo(verbose=true)`.
"""
function cpu_summary(io::IO=stdout, cpu::AbstractVector{CPUinfo} = cpu_info())
    model = cpu[1].model
    first = 1
    for i = 2:length(cpu)
        if model != cpu[i].model
            _cpu_summary(io, cpu, first, i-1)
            first = i
            model = cpu[i].model
        end
    end
    _cpu_summary(io, cpu, first, length(cpu))
end

"""
    Sys.cpu_info()

Return a vector of `CPUinfo` objects, where each object represents information about a CPU core.

This is pretty-printed in a tabular format by `Sys.cpu_summary`, which is included in the output
of `versioninfo(verbose=true)`, so most users will not need to access the `CPUinfo`
data structures directly.

The function provides information about each CPU, including model, speed, and usage statistics such as user time, nice time, system time, idle time, and interrupt time.

"""
function cpu_info()
    UVcpus = Ref{Ptr{UV_cpu_info_t}}()
    count = Ref{Int32}()
    err = ccall(:uv_cpu_info, Int32, (Ptr{Ptr{UV_cpu_info_t}}, Ptr{Int32}), UVcpus, count)
    Base.uv_error("uv_cpu_info", err)
    cpus = Vector{CPUinfo}(undef, count[])
    for i = 1:length(cpus)
        cpus[i] = CPUinfo(unsafe_load(UVcpus[], i))
    end
    ccall(:uv_free_cpu_info, Cvoid, (Ptr{UV_cpu_info_t}, Int32), UVcpus[], count[])
    return cpus
end

"""
    Sys.sysimage_target()

Return the CPU target string that was used to build the current system image.

This function returns the original CPU target specification that was passed to Julia
when the system image was compiled. This can be useful for reproducing the same
system image or for understanding what CPU features were enabled during compilation.

If the system image was built with the default settings this will return `"native"`.

See also [`JULIA_CPU_TARGET`](@ref).
"""
function sysimage_target()
    return ccall(:jl_get_sysimage_cpu_target, Ref{String}, ())
end

"""
    Sys.uptime()

Get the current system uptime in seconds.
"""
function uptime()
    uptime_ = Ref{Float64}()
    err = ccall(:uv_uptime, Int32, (Ptr{Float64},), uptime_)
    Base.uv_error("uv_uptime", err)
    return uptime_[]
end

"""
    Sys.loadavg()

Get the load average. See: https://en.wikipedia.org/wiki/Load_(computing).
"""
function loadavg()
    loadavg_ = Vector{Float64}(undef, 3)
    ccall(:uv_loadavg, Cvoid, (Ptr{Float64},), loadavg_)
    return loadavg_
end

"""
    Sys.free_physical_memory()

Get the free memory of the system in bytes. The entire amount may not be available to the
current process; use `Sys.free_memory()` for the actually available amount.
"""
free_physical_memory() = ccall(:uv_get_free_memory, UInt64, ())

"""
    Sys.total_physical_memory()

Get the total memory in RAM (including that which is currently used) in bytes. The entire
amount may not be available to the current process; see `Sys.total_memory()`.
"""
total_physical_memory() = ccall(:uv_get_total_memory, UInt64, ())

"""
    Sys.free_memory()

Get the total free memory in RAM in bytes.
"""
free_memory() = ccall(:uv_get_available_memory, UInt64, ())

"""
    Sys.total_memory()

Get the total memory in RAM (including that which is currently used) in bytes.
This amount may be constrained, e.g., by Linux control groups. For the unconstrained
amount, see `Sys.total_physical_memory()`.
"""
function total_memory()
    constrained = ccall(:uv_get_constrained_memory, UInt64, ())
    physical = total_physical_memory()
    if 0 < constrained <= physical
        return constrained
    else
        return physical
    end
end

"""
    Sys.get_process_title()

Get the process title. On some systems, will always return an empty string.
"""
function get_process_title()
    buf = Vector{UInt8}(undef, 512)
    err = ccall(:uv_get_process_title, Cint, (Ptr{UInt8}, Cint), buf, 512)
    Base.uv_error("get_process_title", err)
    return unsafe_string(pointer(buf))
end

"""
    Sys.set_process_title(title::AbstractString)

Set the process title. No-op on some operating systems.
"""
function set_process_title(title::AbstractString)
    err = ccall(:uv_set_process_title, Cint, (Cstring,), title)
    Base.uv_error("set_process_title", err)
end

"""
    Sys.maxrss()

Get the maximum resident set size utilized in bytes.
See also:
    - man page of `getrusage`(2) on Linux and BSD.
    - Windows API `GetProcessMemoryInfo`.
"""
maxrss() = ccall(:jl_maxrss, Csize_t, ())

if iswindows()
    function windows_version()
        verinfo = ccall(:GetVersion, UInt32, ())
        VersionNumber(verinfo & 0xFF, (verinfo >> 8) & 0xFF, verinfo >> 16)
    end
else
    windows_version() = v"0.0"
end

"""
    Sys.windows_version()

Return the version number for the Windows NT Kernel as a `VersionNumber`,
i.e. `v"major.minor.build"`, or `v"0.0.0"` if this is not running on Windows.
"""
windows_version

const WINDOWS_VISTA_VER = v"6.0"

const isexecutable = Base.isexecutable
const isreadable   = Base.isreadable
const iswritable   = Base.iswritable

"""
    Sys.which(program_name::String)

Given a program name, search the current `PATH` to find the first binary with
the proper executable permissions that can be run and return an absolute path
to it, or return `nothing` if no such program is available. If a path with
a directory in it is passed in for `program_name`, tests that exact path
for executable permissions only (with `.exe` and `.com` extensions added on
Windows platforms); no searching of `PATH` is performed.
"""
function which(program_name::String)
    if isempty(program_name)
       return nothing
    end
    # Build a list of program names that we're going to try
    program_names = String[]
    base_pname = basename(program_name)
    if iswindows()
        # If the file already has an extension, try that name first
        if !isempty(splitext(base_pname)[2])
            push!(program_names, base_pname)
        end

        # But also try appending .exe and .com
        for pe in (".exe", ".com")
            push!(program_names, string(base_pname, pe))
        end
    else
        # On non-windows, we just always search for what we've been given
        push!(program_names, base_pname)
    end

    path_dirs = String[]
    program_dirname = dirname(program_name)
    # If we've been given a path that has a directory name in it, then we
    # check to see if that path exists.  Otherwise, we search the PATH.
    if isempty(program_dirname)
        # If we have been given just a program name (not a relative or absolute
        # path) then we should search `PATH` for it here:
        pathsep = iswindows() ? ';' : ':'
        path_dirs = map(abspath, eachsplit(get(ENV, "PATH", ""), pathsep))

        # On windows we always check the current directory as well
        if iswindows()
            pushfirst!(path_dirs, pwd())
        end
    else
        push!(path_dirs, abspath(program_dirname))
    end

    # Here we combine our directories with our program names, searching for the
    # first match among all combinations.
    for path_dir in path_dirs
        for pname in program_names
            program_path = joinpath(path_dir, pname)
            try
                # If we find something that matches our name and we can execute
                if isfile(program_path) && isexecutable(program_path)
                    return program_path
                end
            catch e
                # If we encounter a permission error, we skip this directory
                # and continue to the next directory in the PATH variable.
                if isa(e, Base.IOError) && e.code == Base.UV_EACCES
                    # Permission denied, continue searching
                    continue
                else
                    # Rethrow the exception if it's not a permission error
                    rethrow(e)
                end
            end
        end
    end

    # If we couldn't find anything, don't return anything
    nothing
end
which(program_name::AbstractString) = which(String(program_name)::String)

"""
    Sys.username()::String

Return the username for the current user. If the username cannot be determined
or is empty, this function throws an error.

To retrieve a username that is overridable via an environment variable,
e.g., `USER`, consider using
```julia
user = get(Sys.username, ENV, "USER")
```

!!! compat "Julia 1.11"
    This function requires at least Julia 1.11.

See also [`homedir`](@ref).
"""
function username()
    pw = Libc.getpw()
    isempty(pw.username) && Base.uv_error("username", Base.UV_ENOENT)
    return pw.username
end