server.workers

Page actions AI-ready formats and sharing
Open LLM text
Share with AI
Ask Claude Ask ChatGPT Ask Gemini Ask Copilot
module

Quota-aware production worker resolution.

AppConfig.workers=0means auto-detect. Pounce resolves that via os.cpu_count(), which reports the host CPU count inside containers and can spawn dozens of workers on a one-vCPU Railway service.…

Quota-aware production worker resolution.

AppConfig.workers=0means auto-detect. Pounce resolves that via os.cpu_count(), which reports the host CPU count inside containers and can spawn dozens of workers on a one-vCPU Railway service.

Chirp owns resolution on the production launch path: whenworkers=0, we resolve to a concrete count using portable cgroup/cpuset signals (and optional WEB_CONCURRENCY) before constructing Pounce ServerConfig. Explicit workers=Nremains authoritative and is passed through unchanged.

server.workers

Name Type Default Description
type —
qualified_name —
element_type —
description —
source_file —
line_number —
is_autodoc —
autodoc_element —
_autodoc_template —
_autodoc_url_path —
_autodoc_page_type —
title —
doc_content_hash —

Symbols on this page

class WorkerResolution

Inputs and outcome for production worker auto-detect.

Jump to symbol function parse_cpu_set

Count CPUs listed in a Linux cpuset range string (e.g.0-3,8).

ReturnsNonefor empty/malformed input.

Jump to symbol function _cpus_from_quota_ratio

Convert cgroup quota/period into a whole CPU count.

Uses ceiling division so a fractional allocation (e.g. 0.5 CPU) still yields at least one worker.…

Jump to symbol function read_cgroup_cpu_quota

Return effective CPU quota as a whole-CPU count, orNoneif unknown.

Jump to symbol function read_cpuset_cpus

Return cpuset size from the first readable cgroup cpuset file.

Jump to symbol function _platform_concurrency

HonorWEB_CONCURRENCYwhen it is a positive integer.

Jump to symbol function detect_available_cpus

Return(available, quota_cpus, cpuset_cpus)for auto-detect.

available is min(host, quota?, cpuset?)with a floor of 1. Whencgroup_rootis provided (tests), quota/cpuset are read…

Jump to symbol function resolve_production_workers

Resolve the worker count Chirp should pass to Pounce.

Rules (measured portable contract for #750):

  1. requested > 0— explicit; never clamped by quota.…
Jump to symbol function emit_worker_resolution

Write the worker resolution diagnostic to stderr (startup visibility).

Jump to symbol
WorkerResolution
class

Inputs and outcome for production worker auto-detect.

parse_cpu_set
function 
def parse_cpu_set(spec: str) -> int | None

Count CPUs listed in a Linux cpuset range string (e.g.0-3,8).

ReturnsNonefor empty/malformed input.

Parameters

Name Type Default Description
spec str —
_cpus_from_quota_ratio
function 
def _cpus_from_quota_ratio(quota: int, period: int) -> int | None

Convert cgroup quota/period into a whole CPU count.

Uses ceiling division so a fractional allocation (e.g. 0.5 CPU) still yields at least one worker. Unlimited quotas (quota < 0) return None.

Parameters

Name Type Default Description
quota int —
period int —
read_cgroup_cpu_quota
function 
def read_cgroup_cpu_quota(*, v2_max: Path | None = None, v1_quota: Path | None = None, v1_period: Path | None = None) -> int | None

Return effective CPU quota as a whole-CPU count, orNoneif unknown.

Parameters

Name Type Default Description
v2_max Path | None None
v1_quota Path | None None
v1_period Path | None None
read_cpuset_cpus
function 
def read_cpuset_cpus(*, paths: tuple[Path, ...] | None = None) -> int | None

Return cpuset size from the first readable cgroup cpuset file.

Parameters

Name Type Default Description
paths tuple[Path, ...] | None None
_platform_concurrency
function 
def _platform_concurrency(environ: Mapping[str, str]) -> int | None

HonorWEB_CONCURRENCYwhen it is a positive integer.

Parameters

Name Type Default Description
environ Mapping[str, str] —
detect_available_cpus
function 
def detect_available_cpus(*, host_cpus: int | None = None, quota_cpus: int | None = None, cpuset_cpus: int | None = None, cgroup_root: Path | None = None) -> tuple[int, int | None, int | None]

Return(available, quota_cpus, cpuset_cpus)for auto-detect.

available is min(host, quota?, cpuset?)with a floor of 1. Whencgroup_rootis provided (tests), quota/cpuset are read from that tree instead of the live/sys/fs/cgrouppaths.

Parameters

Name Type Default Description
host_cpus int | None None
quota_cpus int | None None
cpuset_cpus int | None None
cgroup_root Path | None None
resolve_production_workers
function 
def resolve_production_workers(requested: int, *, environ: Mapping[str, str] | None = None, host_cpus: int | None = None, cgroup_root: Path | None = None) -> WorkerResolution

Resolve the worker count Chirp should pass to Pounce.

Rules (measured portable contract for #750):

  1. requested > 0— explicit; never clamped by quota.
  2. requested == 0 and valid WEB_CONCURRENCY— platform concurrency.
  3. requested == 0 otherwise — min(host_cpus, cgroup_quota?, cpuset?), floor 1. Missing/malformed cgroup files fall back to the host count.
  4. requested < 0— treated as auto (same as 0) after clamping intent; callers should not pass negatives (Pounce rejects them).

Parameters

Name Type Default Description
requested int —
environ Mapping[str, str] | None None
host_cpus int | None None
cgroup_root Path | None None
emit_worker_resolution
function 
def emit_worker_resolution(resolution: WorkerResolution, *, stream: TextIO | None = None) -> None

Write the worker resolution diagnostic to stderr (startup visibility).

Parameters

Name Type Default Description
resolution WorkerResolution —
stream TextIO | None None

View source · /home/runner/work/chirp/chirp/site/../src/chirp/server/workers.py:1