Use jl_effective_threads for container-aware CPU detection (#59916)

👨 It seems to me we should use the effective thread number basically
everywhere when defaulting to running some threaded workload. Running
with the raw cpu threads will explode quickly when running in a
constrained environment.

-----

🤖 

Julia was not respecting container CPU limits (Docker --cpus, Kubernetes
CPU limits, cgroups) in several places, leading to oversubscription when
determining parallelism.

Changes:
- src/aotcompile.cpp:2013: Use jl_effective_threads() for LLVM
compilation threads
- src/threading.c:760: Use jl_effective_threads() for GC thread
capping/warnings
- src/threading.c:842: Use jl_effective_threads() for JULIA_EXCLUSIVE
mode validation
- base/sysinfo.jl: Add Sys.EFFECTIVE_CPU_THREADS constant for user
access
- test/runtests.jl:119: Use Sys.EFFECTIVE_CPU_THREADS for test worker
processes
- base/precompilation.jl:529: Use Sys.EFFECTIVE_CPU_THREADS for
precompilation tasks
- base/util.jl:697: Use Sys.EFFECTIVE_CPU_THREADS for Base.runtests()
default

The existing jl_effective_threads() function returns
min(jl_cpu_threads(),
uv_available_parallelism()), where uv_available_parallelism() respects
cgroup limits.

--------

Author: KristofferC

base/precompilation.jl

@@ -526,7 +526,7 @@ function _precompilepkgs(pkgs::Union{Vector{String}, Vector{PkgId}},
 
     # Windows sometimes hits a ReadOnlyMemoryError, so we halve the default number of tasks. Issue #2323
     # TODO: Investigate why this happens in windows and restore the full task limit
-    default_num_tasks = Sys.iswindows() ? div(Sys.CPU_THREADS::Int, 2) + 1 : Sys.CPU_THREADS::Int + 1
+    default_num_tasks = Sys.iswindows() ? div(Sys.EFFECTIVE_CPU_THREADS::Int, 2) + 1 : Sys.EFFECTIVE_CPU_THREADS::Int + 1
     default_num_tasks = min(default_num_tasks, 16) # limit for better stability on shared resource systems
 
     num_tasks = max(1, something(tryparse(Int, get(ENV, "JULIA_NUM_PRECOMPILE_TASKS", string(default_num_tasks))), 1))

base/sysinfo.jl

@@ -8,6 +8,7 @@ Provide methods for retrieving information about hardware and the operating syst
 export BINDIR,
        STDLIB,
        CPU_THREADS,
+       EFFECTIVE_CPU_THREADS,
        CPU_NAME,
        WORD_SIZE,
        ARCH,
@@ -73,9 +74,28 @@ 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
 
@@ -167,6 +187,7 @@ function __init__()
     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}, ())

base/util.jl

@@ -680,7 +680,7 @@ end
 # testing
 
 """
-    Base.runtests(tests=["all"]; ncores=ceil(Int, Sys.CPU_THREADS / 2),
+    Base.runtests(tests=["all"]; ncores=ceil(Int, Sys.EFFECTIVE_CPU_THREADS / 2),
                   exit_on_error=false, revise=false, propagate_project=true, [seed], [julia_args::Cmd])
 
 Run the Julia unit tests listed in `tests`, which can be either a string or an array of
@@ -694,7 +694,7 @@ If a seed is provided via the keyword argument, it is used to seed the
 global RNG in the context where the tests are run; otherwise the seed is chosen randomly.
 The argument `julia_args` can be used to pass custom `julia` command line flags to the test process.
 """
-function runtests(tests = ["all"]; ncores::Int = ceil(Int, Sys.CPU_THREADS / 2),
+function runtests(tests = ["all"]; ncores::Int = ceil(Int, Sys.EFFECTIVE_CPU_THREADS / 2),
                   exit_on_error::Bool=false,
                   revise::Bool=false,
                   propagate_project::Bool=false,

doc/src/base/constants.md

@@ -10,6 +10,7 @@ Base.DEPOT_PATH
 Base.LOAD_PATH
 Base.Sys.BINDIR
 Base.Sys.CPU_THREADS
+Base.Sys.EFFECTIVE_CPU_THREADS
 Base.Sys.WORD_SIZE
 Base.Sys.KERNEL
 Base.Sys.ARCH

src/aotcompile.cpp

@@ -2010,7 +2010,7 @@ static unsigned compute_image_thread_count(const ModuleInfo &info) {
         return 1;
     }
 
-    unsigned threads = std::max(jl_cpu_threads() / 2, 1);
+    unsigned threads = std::max(jl_effective_threads() / 2, 1);
 
     auto max_threads = info.globals / 100;
     if (max_threads < threads) {

src/threading.c

@@ -757,7 +757,7 @@ void jl_init_threading(void)
         }
     }
 
-    int cpu = jl_cpu_threads();
+    int cpu = jl_effective_threads();
     jl_n_markthreads = jl_options.nmarkthreads - 1;
     jl_n_sweepthreads = jl_options.nsweepthreads;
     if (jl_n_markthreads == -1) { // --gcthreads not specified
@@ -839,7 +839,7 @@ void jl_start_threads(void)
     // default pool according to a 'compact' policy
     // non-exclusive: no affinity settings; let the kernel move threads about
     if (exclusive) {
-        if (ndefault_threads > jl_cpu_threads()) {
+        if (ndefault_threads > jl_effective_threads()) {
             jl_printf(JL_STDERR, "ERROR: Too many threads requested for %s option.\n", MACHINE_EXCLUSIVE_NAME);
             exit(1);
         }

test/runtests.jl

@@ -116,7 +116,7 @@ cd(@__DIR__) do
     # multiple worker processes regardless of the value of `net_on`.
     # Otherwise, we use multiple worker processes if and only if `net_on` is true.
     if net_on || JULIA_TEST_USE_MULTIPLE_WORKERS
-        n = min(Sys.CPU_THREADS, length(tests))
+        n = min(Sys.EFFECTIVE_CPU_THREADS, length(tests))
         n > 1 && addprocs_with_testenv(n)
         LinearAlgebra.BLAS.set_num_threads(1)
     end