Skip to main content

Module concurrency

Module concurrency 

Source
Expand description

Bounded concurrency budget for the multi-thread one-shot runtime.

§Workload classification (Rules Rust — parallelism)

  • Class: mixed — I/O-bound HTTPS on the Tokio multi-thread runtime plus CPU-bound HTML/JSON parse on the spawn_blocking pool.
  • Stages: (1) network/cache GET on async workers → (2) body decode + scrape/markdown on blocking workers gated by this budget → (3) emit.
  • Bound: every fan-out of CPU work acquires a permit from ConcurrencyBudget’s Arc<Semaphore>. Drop of the permit (RAII) returns capacity. HTTP remains one in-flight request per command today; the same budget is ready for multi-GET fan-out if a batch command is added.
  • Formula (auto): min(cpus, floor((free_ram_mib / 2) / RAM_PER_TASK_MIB)) clamped to [1, MAX_AUTO_CONCURRENCY]. Free RAM uses MemAvailable on Linux (/proc/meminfo); other platforms fall back to CPU count only.
  • RSS ground truth: RAM_PER_TASK_MIB rounds up a single HTML parse of a body near HARD_MAX_BODY_BYTES (10 MiB body + DOM + markdown ≈ 2–3× peak). Re-measure with /usr/bin/time -v docsrs-cli search-in-crate … when the body cap or scraper stack changes materially.
  • Override: CLI --max-concurrency=N or max_concurrency in XDG config.toml only (not product DOCSRS_CLI_* env). 0 / omit = auto.

Structs§

ConcurrencyBudget
Shared admission gate for CPU-bound (and future multi-GET) work.

Constants§

MAX_AUTO_CONCURRENCY
Hard ceiling for auto-computed concurrency (CLI, not a server farm).
MAX_EXPLICIT_CONCURRENCY
Hard ceiling for explicit --max-concurrency / config override.
RAM_PER_TASK_MIB
Estimated peak RSS (MiB) for one CPU-bound parse task.

Functions§

auto_max_concurrency
Auto permits from CPUs and free RAM (50% free-RAM safety margin).
max_blocking_threads
Cap for Tokio’s spawn_blocking pool (Rules Rust — rede / paralelismo).
resolve_max_concurrency
Resolve permit count from config override (0 = auto).
runtime_worker_threads
Worker thread count for the multi-thread Tokio runtime (I/O + signal tasks).