Module concurrency 

Bounded parallelism budget (--max-concurrency, Semaphore, Rayon, join_bounded). Bounded parallelism and concurrency for the one-shot CLI.

Workload classification (rules_rust_paralelismo)

Class	Paths	Tool
I/O-bound	HTTP scrape/crawl/batch, CDP fan-out, robots	Tokio + Arc<Semaphore> / JoinSet / [join_bounded]
CPU-bound	Structural scan (sg), multi-file text match	Rayon par_iter
Mista	Browser session (CDP I/O + light DOM parse)	Multi-thread Tokio; no Rayon on async workers
Subprocess	Chrome residual	Existing residual kill path (no unbounded fork)

Formula (permits)

auto = min(
  available_parallelism(),
  max(1, (free_ram_mb * 50%) / ram_per_task_mb),
  HARD_CAP
)
effective = override_if_set_else(auto)

• ram_per_task_mb: 64 for HTTP I/O tasks (conservative floor). Measure with /usr/bin/time -v → “Maximum resident set size” via scripts/rss-baseline.sh (doctor offline / single scrape). Revalidate when reqwest/scraper/chromiumoxide jump materially.
• 50% safety margin on free RAM so concurrent tasks cannot OOM the host.
• HARD_CAP prevents FD / Chrome overwhelm on large hosts.
• Override: global CLI --max-concurrency=N (0 = auto).
• One-shot: auto budget is cached once (OnceLock); long daemon rebalance is N/A (BORN→EXECUTE→FINALIZE→DIE). Crawl/batch respect cancel token mid-run.

Product law

One-shot CLI (BORN→EXECUTE→FINALIZE→DIE). No daemon fleets, no remote metrics of available_permits, no systemd-run default (ops N/A). Every fan-out must use [effective_limit] or an explicit local clamp derived from it. Gate of record: Arc<Semaphore> + acquire_owned.

Enums

WorkloadClass

Workload class for documentation and call-site comments.

Constants

CPU_MAP_THRESHOLD

Below this length, map_cpu stays sequential (rule: never parallelize when cost ≪ coordination overhead). Measured trade-off for one-shot CLI filters.

HARD_CAP

Hard ceiling for any fan-out (FD budget + Chrome CDP politeness).

MIN_CONCURRENCY

Floor when auto-detection fails.

RAM_PER_IO_TASK_MB

Conservative RSS budget per concurrent HTTP/CDP task (MiB).

Functions

browser_max_blocking_threads

Cap for Tokio max_blocking_threads on the browser runtime.

browser_worker_threads

Browser Tokio worker threads: enough for CDP event fan-out, capped.

budget_report

Snapshot of budget for doctor / --json diagnostics.

command_workload_matrix

Per-command parallelism posture (agent discovery / doctor).

compute_auto_budget

Auto budget: min(cpus, ram_budget, HARD_CAP).

cpu_count

CPU count used in the formula (available_parallelism, min 1).

create_dir_all_blocking

create_dir_all on the blocking pool.

effective_limit

Effective concurrency for I/O fan-out (and Rayon thread hint).

effective_limit_capped

Same as effective_limit but capped for a specific subsystem.

filter_cpu

Parallel filter with the same threshold rule as map_cpu (PAR-84).

free_ram_mb

Free / available RAM in MiB when the platform exposes it.

install_limit

Install CLI override. Call once after clap parse.

install_rayon_pool_once

Run a CPU-bound closure on a Rayon pool sized to the process budget.

io_semaphore

Arc<Semaphore> gate with effective_limit permits.

join_bounded

Run a list of futures with bounded concurrency via Arc<Semaphore>.

join_bounded_ordered

Like join_bounded but preserves input order via indexed futures.

map_cpu

CPU map over a slice: sequential when items.len() < CPU_MAP_THRESHOLD, else Rayon under install_rayon_pool_once (pool sized to budget).

map_cpu_owned

Like map_cpu but for owned items that are consumed (into_par_iter).

rayon_threads

Suggested Rayon thread count (respects RAYON_NUM_THREADS via Rayon itself when using the global pool; this value is for explicit ThreadPoolBuilder).

read_bytes_blocking

Read a file fully on the blocking pool.

read_to_string_blocking

Read a UTF-8 file on the blocking pool (PAR-77: never fs::read_to_string on async worker).

rename_blocking

rename on the blocking pool (PAR-80: state rotation must not pin async workers).

resolve_permits

Resolve permits for a fan-out: 0 → process budget; else clamp to hard cap.

semaphore_with

Semaphore with an explicit permit count (already clamped by caller).

sort_by_cpu

In-place sort with comparator; Rayon when large (PAR-94).

sort_by_key_cpu

In-place sort by key with the same threshold as sort_cpu (PAR-94).

sort_cpu

In-place sort with Rayon when items.len() >= CPU_MAP_THRESHOLD (PAR-94).

walk_threads

Walk / Rayon thread hint: budget capped by CPUs (respects --max-concurrency).

write_bytes_blocking

Write bytes on the Tokio blocking pool (docsrs: never pin async workers with std::fs for non-trivial payloads).

write_bytes_sync

Sync write helper for outer CLI dispatch (no active Tokio worker). Prefer write_bytes_blocking when inside async fn / block_on_*.