Module concurrency 

Bounded multi-host / tunnel fan-out (Semaphore + JoinSet). Bounded concurrency for multi-host SSH fan-out (Rules Rust — paralelismo).

Workload classification

I/O-bound (SSH/TCP, SCP streams, tunnel accepts/forwards). Network RTT dominates; CPU is secondary (crypto inside russh is already async on Tokio). Not CPU-bound ML/batch — do not pull Rayon into product paths. Heavy-memory singletons stay on OnceLock / atomics elsewhere. Subprocess / systemd-run MemoryMax: N/A (no child fan-out of heavy workers; this binary is the one-shot process).

Where parallelism lives

Surface	Gate	Saturates
`health-check	exec	scp –all/–hosts`
scp multi-file single-host	1 session, serial files (G-PAR-47)	one TCP + auth
scp multi-host × multi-file	map_bounded per host + serial files	sessions (not files)
Tunnel local accepts → channel forwards	JoinSet + Semaphore	FDs, SSH channels
Tokio runtime workers	capped from concurrency budget	scheduler threads

Host lists are built only via crate::vps::resolve_host_jobs (G-PAR-31). Sequential paths (local TOML CRUD, locale, completions, secrets key ops) are intentionally serial: work is tiny vs coordination overhead — see module docs on each command handler (G-PAR-28).

Fan-out units get tracing span fan_out_unit (G-PAR-52) + available_permits debug on admit (G-PAR-40).

Permit formula

permits = clamp(
  min(
    available_parallelism() * IO_OVERSUBSCRIBE,
    (MemAvailable * SAFETY_NUM / SAFETY_DEN) / RAM_PER_TASK_BYTES
  ),
  MIN_CONCURRENCY ..= HARD_CAP
)

• IO_OVERSUBSCRIBE = 4 — async I/O may exceed cores without CPU thrash.
• SAFETY_NUM/DEN = 1/2 — 50% of free RAM reserved for OS / peer tools.
• RAM_PER_TASK_BYTES = 16 MiB — ballpark for one authenticated russh session + capture buffers (revalidate with /usr/bin/time -v after major dependency bumps; Maximum resident set size of a single health-check).
• Non-Linux / no MemAvailable: CPU budget capped at 8 so cpus×4 cannot alone open too many sessions on low-RAM macOS/Windows (G-PAR-25).
• Override: CLI --max-concurrency=N > auto formula (no env-as-store; G-UNSAFE-14) > auto formula. N=0 is rejected at clap parse.

Cancel / panic

Permits are held as OwnedSemaphorePermit and dropped on task end (RAII), including panic unwind of the task future. Callers must still handle tokio::task::JoinError::is_panic.

Re-exports

pub use crate::constants::MIN_CONCURRENCY;

pub use crate::constants::HARD_CAP;

pub use crate::constants::IO_OVERSUBSCRIBE;

pub use crate::constants::NON_LINUX_CPU_CAP;

pub use crate::constants::RAM_PER_TASK_BYTES;

Structs

IndexedResult

Result of one fan-out unit (preserves input order index).

Functions

acquire_owned

Acquire one owned permit (for spawned tasks).

auto_limit

Auto formula: CPUs × oversubscribe vs free-RAM budget, clamped.

effective_limit

Effective concurrency for this process.

fail_fast_enabled

Whether multi-host fan-out should stop admission after the first unit failure.

free_ram_bytes

Reads free RAM (Linux MemAvailable; other OS → None → CPU-only formula).

install_fail_fast

Install global fail-fast policy (G-O1). Default: false (partial success).

install_process_limit

Install the process concurrency limit once (CLI --max-concurrency or auto).

install_scp_file_concurrency

Install max concurrent SCP files per host session (G-O4). 1 = serial (default).

map_bounded

Bounded map over independent I/O units.

map_bounded_ok

Convenience: map and unwrap join panics via resume_unwind.

map_bounded_with

Bounded fan-out with optional per-result fail-fast (G-O1).

max_blocking_threads

Blocking-pool size for rare spawn_blocking (crypto edge / sync FS).

peak_in_flight

Peak in-flight observed since process start (test helper).

reset_peak_counters

Reset peak counters (tests only).

resolve_limit

Resolve a limit from optional CLI override without installing it.

scp_file_concurrency

Effective SCP per-session file concurrency (default 1).

semaphore

Shared admission gate for a fan-out scope.

worker_threads

Tokio worker thread count for main (before clap).