Add deprecation for Sys.CPU_CORES => Sys.CPU_THREADS

NEWS.md

@@ -524,6 +524,11 @@ This section lists changes that do not have deprecation warnings.
   * `dot(u, v)` now acts recursively. Instead of `sum(u[i]' * v[i] for i in ...)`, it computes
     `sum(dot(u[i], v[i]) for i in ...)`, similarly to `vecdot` before ([#27401]).
 
+  * `Sys.CPU_CORES` has been renamed to `Sys.CPU_THREADS`; it still gives the number
+    of "logical cores" (including hyperthreading) rather than the number of physical
+    cores present on the CPU. Similarly, the environment variable `JULIA_CPU_CORES` is
+    deprecated in favor of `JULIA_CPU_THREADS` ([#27856]).
+
 Library improvements
 --------------------
 

base/deprecated.jl

@@ -1575,6 +1575,10 @@ end
     Base.@deprecate log Base.log
 end
 
+# PR 27856
+@eval Base.Sys Base.@deprecate_binding CPU_CORES CPU_THREADS true :nothing false
+# TODO: delete deprecation code in sysimg.jl and sysinfo.jl
+
 # PR 26071
 @deprecate(matchall(r::Regex, s::AbstractString; overlap::Bool = false),
            collect(m.match for m in eachmatch(r, s, overlap = overlap)))

base/sysimg.jl

@@ -462,6 +462,9 @@ function __init__()
             ENV["OPENBLAS_NUM_THREADS"] = "8"
         elseif haskey(ENV, "JULIA_CPU_THREADS") # or exactly as specified
             ENV["OPENBLAS_NUM_THREADS"] = cpu_cores
+        elseif haskey(ENV, "JULIA_CPU_CORES") # TODO: delete in 1.0 (deprecation)
+            Core.print("JULIA_CPU_CORES is deprecated, use JULIA_CPU_THREADS instead.\n")
+            ENV["OPENBLAS_NUM_THREADS"] = cpu_cores
         end # otherwise, trust that openblas will pick CPU_THREADS anyways, without any intervention
     end
     # for the few uses of Libc.rand in Base:

base/sysinfo.jl

@@ -47,15 +47,17 @@ STDLIB = "$BINDIR/../share/julia/stdlib/v$(VERSION.major).$(VERSION.minor)" # fo
 
 # helper to avoid triggering precompile warnings
 
-global CPU_THREADS
 """
     Sys.CPU_THREADS
 
-The number of logical CPU cores available in the system.
+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.
 """
-:CPU_THREADS
+CPU_THREADS = 1 # for bootstrap, changed on startup
 
 """
     Sys.ARCH
@@ -87,17 +89,24 @@ Standard word size on the current machine, in bits.
 const WORD_SIZE = Core.sizeof(Int) * 8
 
 function __init__()
-    env_cores = get(ENV, "JULIA_CPU_THREADS", "")
-    global CPU_THREADS = if !isempty(env_cores)
+    env_cores = nothing
+    if haskey(ENV, "JULIA_CPU_THREADS")
+        env_cores = ENV["JULIA_CPU_THREADS"]
+    elseif haskey(ENV, "JULIA_CPU_CORES") # TODO: delete in 1.0 (deprecation)
+        Core.print("JULIA_CPU_CORES is deprecated, use JULIA_CPU_THREADS instead.\n")
+        env_cores = ENV["JULIA_CPU_CORES"]
+    end
+    global CPU_THREADS = if env_cores !== nothing
         env_cores = tryparse(Int, env_cores)
         if !(env_cores isa Int && env_cores > 0)
-            Core.print(Core.stderr, "WARNING: couldn't parse `JULIA_CPU_THREADS` environment variable. Defaulting Sys.CPU_THREADS to 1.\n")
-            env_cores = 1
+            env_cores = Int(ccall(:jl_cpu_cores, Int32, ()))
+            Core.print(Core.stderr, "WARNING: couldn't parse `JULIA_CPU_THREADS` environment variable. Defaulting Sys.CPU_THREADS to $env_cores.\n")
         end
         env_cores
     else
         Int(ccall(:jl_cpu_cores, Int32, ()))
     end
+    global CPU_CORES = CPU_THREADS # TODO: delete in 1.0 (deprecation)
     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}, ())