Skip to content
EngineeringEmad Khair14 min read

Five Eligible CPUs, a Four-CPU Quota: What Runtimes Report and What It Costs

In one Linux container, Python and Go selected five-way parallelism while Node.js and Java reported four. We traced the difference to CPU affinity, cgroup quotas, and runtime defaults, then measured what an extra worker did to throttling.

Five Eligible CPUs, a Four-CPU Quota: What Runtimes Report and What It Costs

A Linux container had enough CPU affinity to run on five logical processors. Its CPU quota, however, allowed the equivalent of four processors' worth of execution time.

That sounded like a straightforward environment in which to choose the number of workers for a CPU-bound service. We asked four runtimes how much parallelism they thought was available and got two answers.

Runtime API or setting Result
Python 3.13.5 os.process_cpu_count() 5
Go 1.23.2 default runtime.GOMAXPROCS(0) 5
Node.js 22.16.0 os.availableParallelism() 4
OpenJDK 21.0.12.1 Runtime.availableProcessors() 4

All four programs ran in the same container. We did not change its CPU quota or affinity between them.

The difference matters because these values influence application decisions. Python's ProcessPoolExecutor, for example, uses os.process_cpu_count() to set its default worker limit. The Go runtime uses GOMAXPROCS to determine how many goroutines can execute Go code simultaneously. Java's processor count feeds several of its runtime sizing decisions. Node.js exposes availableParallelism() to help programs choose a suitable level of concurrency.

The APIs do not all promise exactly the same thing, and the numbers are not necessarily bugs. To understand the disagreement, we followed the two limits that Linux was enforcing, then tested what happened when we ran four workers instead of five.

Octri on a Gulf waterfront compares Python and Go reporting five with Node.js and OpenJDK reporting four in the same container.

Four runtimes, one container, and two different answers about how much CPU is available.

What Linux actually gave the container

We started by reading the container's cgroup v2 CPU configuration:

text
$ cat /sys/fs/cgroup/cpuset.cpus.effective
0-4

$ cat /sys/fs/cgroup/cpu.max
400000 100000

The first line tells us which logical CPUs the container's cpuset permits. Here, CPUs 0 through 4 give us five eligible processors. The process's affinity mask also contained those five CPUs.

The second line is a bandwidth limit. Linux's cpu.max file contains a quota and a period, both in microseconds. In this case, the cgroup can consume up to 400,000 microseconds of CPU time in a 100,000-microsecond wall-clock period.

text
CPU quota / scheduling period
= 400,000 µs / 100,000 µs
= 4 CPU-equivalents

That quota is shared across the work running in the cgroup. It does not tell Linux to pick four of the five CPUs and keep the fifth idle.

For example, four continuously busy threads could each run for nearly the whole 100 ms period. Five continuously busy threads could collectively consume the same 400 ms of CPU time in roughly 80 ms of wall time. If they exhaust the quota early, the CPU controller throttles the cgroup until its bandwidth is replenished.

The distinction is between where work may run and how much CPU time it may use. Affinity answers the first question. The quota answers the second.

Linux documents these interfaces in its cgroup v2 CPU controller reference. The same interface exposes cpu.stat, which can tell us how often a cgroup was throttled.

A Gulf causeway has five open CPU lanes but a shared time budget equal to four full-time CPUs during each scheduling period.

CPU affinity determines where a process may run. CPU quota limits how much processing time it can consume.

How the four runtimes interpreted it

The first two results came from Python:

python
import os
from concurrent.futures import ProcessPoolExecutor, ThreadPoolExecutor

print(os.cpu_count())          # 5 in this container
print(os.process_cpu_count())  # 5 in this container

with ProcessPoolExecutor() as processes:
    print(processes._max_workers)  # 5

with ThreadPoolExecutor() as threads:
    print(threads._max_workers)    # 9

The executor attributes above are internal and shown only to inspect the defaults; application code should configure its worker counts through the public max_workers argument.

Python 3.13 introduced os.process_cpu_count() to report logical processors usable by the calling thread. On Linux, it takes CPU affinity into account. Our five-CPU affinity mask therefore produced a count of five, despite the lower cgroup bandwidth quota.

The process pool inherited that number. The thread pool's default was nine because Python 3.13 uses min(32, (os.process_cpu_count() or 1) + 4) as its default upper bound. That extra room is intentional: thread pools often overlap I/O. Nine threads is not a claim that nine CPU-bound Python functions would run efficiently in parallel, and it is not a count of threads started immediately.

This difference is already a recognized question in CPython. A May 2026 issue proposes accounting for cgroup CPU quotas in os.process_cpu_count(); its reproducer shows a container limited to two CPU-equivalents reporting 20 eligible CPUs. We saw a smaller instance of the same distinction.

Go 1.23.2 made a related decision, although through a different mechanism:

go
package main

import (
    "fmt"
    "runtime"
)

func main() {
    fmt.Println(runtime.NumCPU())       // 5
    fmt.Println(runtime.GOMAXPROCS(0))  // 5
}

runtime.NumCPU() reports the logical processors available to the process. In Go 1.23, the default GOMAXPROCS followed that count. GOMAXPROCS is not a worker-pool size: it caps how many goroutines may execute Go code simultaneously. In our environment, the old default allowed five-way parallel execution against a four-CPU-equivalent budget.

Node.js 22.16.0 returned four through its dedicated parallelism API:

javascript
const os = require("node:os");

console.log(os.cpus().length);       // 5
console.log(os.availableParallelism()); // 4

That distinction is reflected in Node.js's own documentation. os.cpus() enumerates CPU information, while os.availableParallelism() is the API intended to estimate an appropriate amount of parallelism. It delegates to libuv, which can take Linux cgroup bandwidth limits into account. This is an estimate for application sizing, not an automatic resizing of every Node.js worker pool.

Finally, OpenJDK 21 reported four:

java
class CpuProbe {
    public static void main(String[] args) {
        System.out.println(
            Runtime.getRuntime().availableProcessors()
        ); // 4
    }
}

The JVM's container support considers CPU limits when determining the processors available to the VM. That value influences runtime ergonomics, including some thread pool sizing decisions. Java's container support documentation also describes -XX:ActiveProcessorCount as an explicit override.

These calls were all behaving according to the policies of their particular versions and APIs. Some were answering an affinity question; others were estimating a suitable execution budget. The next question was whether the distinction changed the work we observed.

Four waterfront dispatch kiosks display Python five, Go five, Node.js four, and Java four against the same harbor resource limit.

The reported CPU count depends on which system constraints a runtime considers.

The extra worker did not improve throughput

A CPU count is only useful if it helps make the right scheduling decision. To test that, we ran a small CPU-bound workload in Python with either four or five worker processes.

Each run executed 80 jobs. Every job performed a busy loop until it had accumulated approximately 50 milliseconds of CPU time, measured inside its own worker process with time.process_time(). We recorded the elapsed time of each job from inside the worker, the total batch duration, and the change in cgroup throttling counters over the run. We warmed the process pool before starting the measurements.

One pair of runs produced:

CPU-bound worker processes Batch time, 80 jobs 95th-percentile job execution time Throttled cgroup periods
4 1.014 s 50.4 ms 0 of 10
5 1.000 s 70.9 ms 9 of 10

Adding the fifth process made almost no difference to total throughput. It did increase the measured 95th-percentile duration of an individual job by about 41%. The cgroup's nr_throttled counter increased during nine of the ten periods in that five-worker run.

We repeated the four-versus-five comparison. The second pair gave 50.3 ms versus 70.6 ms at the 95th percentile, with one throttled period for four workers and nine for five. A further run showed some background throttling even at four workers, but the per-job duration remained close to 50 ms; five workers again approached 71 ms.

These figures describe a small controlled workload, not a general claim that five workers are 41% slower in all containerized services. We measured time spent executing a job inside a worker, not end-to-end request latency including time waiting in the process pool's queue. The cpu.stat counters belong to the cgroup as a whole, so other processes in the cgroup can affect them. Run-to-run scheduling noise also matters.

Still, the mechanism behind the result was visible. With four busy processes, the workload could use roughly the available CPU budget throughout each scheduling period. With five, the processes could exhaust that budget earlier and wait for the next period. The same total amount of CPU work finished in about the same wall time, but individual jobs experienced more uneven progress.

This is why CPU bandwidth throttling is especially relevant to latency-sensitive services. A pool can create more simultaneous work without making the container capable of executing more total work.

Four workboats flow through a Gulf marina while five boats experience congestion under the same quota, reflecting measured job execution times.

An additional worker can increase contention without delivering a corresponding improvement in throughput.

Ten Gulf harbor signals show zero throttled periods with four workers, and nine throttled periods with five workers.

In the measured run, the container was throttled in nine of ten periods with five workers, versus none with four.

Why newer Go versions behave differently

Our Go measurement used version 1.23.2. The version is important.

Go 1.25, released in August 2025, changed the default behavior of GOMAXPROCS on Linux. When no explicit override is active, the runtime can consider cgroup CPU bandwidth limits as well as the available logical processors. It can also periodically update the default when the limits change.

In the environment used for our experiment, a Go program using the new container-aware default would ordinarily select four instead of five. runtime.NumCPU() would still describe the processor availability; it is GOMAXPROCS that changes its default policy.

The Go team's release notes and its explanation of container-aware GOMAXPROCS are explicit about the motivation: a cgroup quota limits aggregate CPU time, while GOMAXPROCS limits simultaneous Go execution. Bringing those values closer reduces the chances of a runtime exhausting its quota early and experiencing abrupt throttling.

There is a compatibility detail worth checking when upgrading. The new behavior depends on the Go version declared by the main module, as well as GODEBUG settings and whether GOMAXPROCS has been explicitly set. A newer toolchain does not automatically guarantee that every older module uses the new default. The runtime documentation describes those conditions and the special handling of small or fractional quotas.

Python's position is different. Its affinity-aware CPU count is useful in many situations, but it does not by itself tell a CPU-bound process pool how much CPU bandwidth a container has been allocated. Python 3.13 provides PYTHON_CPU_COUNT and -X cpu_count so deployments can override the reported value, or applications can supply max_workers explicitly.

Node.js's os.availableParallelism() and Java's container-aware availableProcessors() happen to align with the quota in our test. That does not mean every pool in those runtimes automatically follows those values, nor that the estimates will always be right. The process may sit under multiple cgroups with different limits, have an I/O-bound workload, or be constrained by resources other than CPU time.

These details make it risky to carry a single hard-coded rule across languages. The number worth using depends both on the environment and on what the runtime does with it.

Choosing a worker count in a container

For a CPU-bound pool, an effective parallelism estimate based on the smaller of eligible CPUs and the available CPU bandwidth is a reasonable starting point. It is not a universal optimum. Fractional quotas require a rounding policy, memory limits can dominate, and operations that frequently wait for I/O may benefit from much higher concurrency.

In this environment, an explicit Python process pool limit avoids the five-process default:

python
from concurrent.futures import ProcessPoolExecutor

with ProcessPoolExecutor(max_workers=4) as pool:
    # Submit CPU-bound jobs here.
    ...

At deployment time, Python 3.13+ also supports:

bash
PYTHON_CPU_COUNT=4 python3 app.py

For older Go runtimes, or deployments that require a fixed scheduler limit, the corresponding control is:

bash
GOMAXPROCS=4 ./service

For Go 1.25+ applications that use the new container-aware default, it is preferable to understand that default before pinning it, since an explicit GOMAXPROCS value prevents the runtime from updating it automatically.

In Node.js, use os.availableParallelism() as a starting point when sizing a CPU-bound pool of Worker threads; do not use os.cpus().length merely because it returns an array of CPU descriptions. In Java, inspect Runtime.availableProcessors() and, when needed, use the JVM's -XX:ActiveProcessorCount option to control processor-based runtime sizing decisions.

There is also a difference between choosing a starting value and verifying it. For workloads where latency matters, compare worker counts under the actual production CPU limits. Record throughput, queue wait time, job duration, and throttling. Changing the number of workers can improve one metric while worsening another.

The cgroup counters are a useful place to begin:

bash
cat /sys/fs/cgroup/cpu.stat

In particular, nr_periods records quota periods, nr_throttled records periods in which execution was throttled, and throttled_usec records throttling time. These are cgroup-level measurements, so interpret them alongside application metrics and other activity in the same cgroup.

For more complicated deployments, do not assume that reading a single leaf cpu.max file is a complete portable sizing algorithm. Linux cgroup controllers are hierarchical, older systems may use cgroup v1, and affinity and CPU quotas can be imposed at different levels. A mature runtime or scheduler library may handle those cases more reliably than a custom one-off parser.

Octri reviews CPU affinity, quota, job times, and throttling from a Gulf harbor operations dashboard before choosing a worker count.

Worker counts should be chosen using the limits and performance characteristics of the environment in which the application actually runs.

What the container was telling us

The container did not give the runtimes conflicting resource limits. It allowed execution on five logical CPUs while enforcing a quota equivalent to four CPUs of average throughput. Both facts were true at the same time.

Python 3.13 and Go 1.23 used the five-CPU view for the defaults we inspected. Node.js 22 and OpenJDK 21 selected four through their parallelism-related APIs. Newer Go versions also account for container quotas when choosing the default GOMAXPROCS.

The practical effect was visible in our small CPU-bound test. Four workers completed the batch in about a second with individual jobs taking roughly their expected 50 ms of CPU time. A fifth worker did not materially improve throughput, but it made individual jobs take longer in wall time and repeatedly pushed the cgroup into throttling.

That is a useful reminder when debugging performance inside containers. A service may be allowed to run on more processors than it can afford to keep busy. Worker counts based only on the first number can create more contention without creating more capacity.

The fastest way to resolve the confusion is to inspect both limits, check what the runtime actually reports, and measure the work under the quota the kernel enforces.


Methodology and reproduction

  • Environment: Linux x86-64 sandbox with cgroup v2, cpuset.cpus.effective = 0-4, process affinity for five logical processors, and cpu.max = 400000 100000. This is four CPU-equivalents of bandwidth across five eligible logical CPUs.
  • Runtime probes: Python 3.13.5; Go 1.23.2; Node.js 22.16.0; OpenJDK 21.0.12.1. We recorded the specified APIs, not a single standardized CPU-count API shared by every language.
  • Worker benchmark: Python 3.13.5, ProcessPoolExecutor, four or five processes, warm-up before measurement, 80 jobs per run, approximately 50 ms of process CPU time per job. Batch duration and per-job wall-clock execution time measured using time.perf_counter(); CPU consumption measured with time.process_time().
  • Throttling: Read nr_periods and nr_throttled from /sys/fs/cgroup/cpu.stat before and after each run. These counters apply to the whole cgroup. The benchmark was repeated; the main table presents one paired run and describes subsequent observations separately.
  • Limits: Small synthetic CPU-bound tasks are useful for exposing quota replenishment, but these measurements do not predict application throughput or HTTP tail latency. The test did not measure queue wait time as part of per-job duration, and the cgroup may contain unrelated activity.

Primary references