Add deprecation for Sys.CPU_CORES => Sys.CPU_THREADS

This also introduces minor functional changes to the behavior of
JULIA_CPU_THREADS: when the environment variable is set but empty
that is now considered to be a parse error and the default value
will be used for `Sys.CPU_THREADS`; the default value when there
is a parse error for JULIA_CPU_THREADS is now `jl_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_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["OPENBLAS_NUM_THREADS"] = cpu_threads
         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_threads = get(ENV, "JULIA_CPU_THREADS", "")
-    global CPU_THREADS = if !isempty(env_threads)
+    env_threads = nothing
+    if haskey(ENV, "JULIA_CPU_THREADS")
+        env_threads = 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_threads = ENV["JULIA_CPU_CORES"]
+    end
+    global CPU_THREADS = if env_threads !== nothing
         env_threads = tryparse(Int, env_threads)
         if !(env_threads isa Int && env_threads > 0)
-            Core.print(Core.stderr, "WARNING: couldn't parse `JULIA_CPU_THREADS` environment variable. Defaulting Sys.CPU_THREADS to 1.\n")
-            env_threads = 1
+            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 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}, ())

test/cmdlineargs.jl

@@ -50,17 +50,17 @@ let exename = `$(Base.julia_cmd()) --sysimage-native-code=yes --startup-file=no`
         @test isempty(v[2])
         @test startswith(v[3], "┌ Warning: Failed to insert InteractiveUtils into module Main\n")
     end
-    for nc in ("0", "-2", "x", "2x", " ")
+    real_threads = string(ccall(:jl_cpu_threads, Int32, ()))
+    for nc in ("0", "-2", "x", "2x", " ", "")
         v = readchomperrors(setenv(`$exename -i -E 'Sys.CPU_THREADS'`, "JULIA_CPU_THREADS" => nc))
         @test v[1]
-        @test v[2] == "1"
-        @test v[3] == "WARNING: couldn't parse `JULIA_CPU_THREADS` environment variable. Defaulting Sys.CPU_THREADS to 1."
+        @test v[2] == real_threads
+        @test v[3] == "WARNING: couldn't parse `JULIA_CPU_THREADS` environment variable. Defaulting Sys.CPU_THREADS to $real_threads."
     end
-    real_threads = string(ccall(:jl_cpu_threads, Int32, ()))
-    for nc in ("1", " 1 ", " +1 ", " 0x1 ", "")
+    for nc in ("1", " 1 ", " +1 ", " 0x1 ")
         v = readchomperrors(setenv(`$exename -i -E 'Sys.CPU_THREADS'`, "JULIA_CPU_THREADS" => nc))
         @test v[1]
-        @test v[2] == (isempty(nc) ? real_threads : "1")
+        @test v[2] == "1"
         @test isempty(v[3])
     end
 end