Struct DispatcherConfig 

pub struct DispatcherConfig {

    pub source_port: usize,
    pub result_port: usize,
    pub queue_size: usize,
    pub message_size: usize,
    pub max_in_flight: usize,
    pub report_refresh_interval_seconds: u64,
    pub max_result_bytes: usize,
    pub sink_writers: usize,
    pub finalize_batch_size: usize,
    pub finalize_flush_ms: u64,
    pub lease_timeout_seconds: i64,
    pub reap_interval_seconds: i64,
    pub tcp_keepalive_idle_seconds: i32,
    pub input_prefetchers: usize,
    pub prefetch_max_entry_mb: usize,
    pub prefetch_budget_mb: usize,
}

ZeroMQ dispatcher settings.

Fields

source_port: usize

Port the ventilator listens on for worker task requests.

result_port: usize

Port the sink listens on for worker results.

queue_size: usize

Batch size for task-store queue requests (also the in-memory dispatch queue size).

Must never exceed PostgreSQL’s max_locks_per_transaction setting.

message_size: usize

Size of an individual ZeroMQ message chunk, in bytes.

max_in_flight: usize

Backpressure threshold: the maximum number of in-flight (dispatched-but-unfinished) tasks the ventilator tolerates before it stops leasing new work and mock-replies to requesting workers (which back off and retry). This bounds the in-flight set so it drains via the sink as results return, instead of growing toward the hard panic bound crate::dispatcher::server::PROGRESS_QUEUE_HARD_LIMIT — graceful degradation under overload rather than a crash (KNOWN_ISSUES D-6). Keep it well below that hard bound to leave recovery headroom. In steady state the in-flight set is ~the worker count (~200), so the default leaves a wide margin.

report_refresh_interval_seconds: u64

How often (seconds) the finalize thread refreshes the report_summary rollup regardless of drain, bounding report staleness while a long run is in flight (a conversion run can take weeks, so drain-only refresh is not enough). This is the automatic freshness guarantee; with REFRESH ... CONCURRENTLY the rebuild no longer blocks readers, so it is cheap to run often. The cost is one rebuild’s DB load per interval (a few minutes at production scale). Default 1h.

max_result_bytes: usize

Hard cap on the byte size of a single worker result the sink will write to /data. A reply that exceeds it is rejected (the partial file is removed, the rest of the multipart message is drained frame-by-frame to keep the socket in sync, and the task is marked Invalid) rather than allowed to fill the disk — protecting the shared filesystem from a runaway worker. We accept genuinely large jobs but draw the line here. Default 2 GiB.

sink_writers: usize

Sink archive-writer pool size. Number of background threads the sink fans the blocking /data result-archive writes out to (dispatcher rationalization phase 3, closes D-7). The sink’s single ZMQ-PULL receive loop reads each result’s frames and hands them — task, then streamed chunks, then a commit — to one of these writers, so receiving the next result is no longer hostage to the current one’s slow QLC-RAID6 write + cortex.log parse. Per-task ordering is preserved (a task’s frames go contiguously to one writer); fan-out is across different tasks. Memory stays O(chunk) per writer (chunks are streamed and dropped, never the whole archive resident) bounded by a small per-writer channel. Default 4 — a modest decoupling that suits a box co-resident with ~200 workers; raise toward host cores if the disk can absorb more concurrent writes. (1 is the floor; a single writer ≈ the legacy inline behavior but still off the receive loop.)

finalize_batch_size: usize

Finalize batch coalescing — size threshold (N). The finalize thread accumulates returned task reports and persists them to Postgres in one transaction per batch (crate::backend::Backend::mark_done), flushing when the batch reaches this many reports — or finalize_flush_ms elapses, whichever fires first. Larger N amortizes the DB round-trip harder under load (fewer, bigger writes) at the cost of more rows per transaction. It is a ceiling that mainly bites under burst/saturation; at steady-state load the time window usually flushes first. Unlike queue_size, N is not bound by max_locks_per_transaction (that limits object locks; mark_done takes only row locks), so it can be large. Default 1024 — the empirical throughput knee from examples/dispatcher_bench.rs (tasks/s rises to ~1024 then plateaus, and regresses by ~4096 where a single transaction holds row locks long enough to stall the pipeline; see docs/DISPATCHER_BENCH.md). 1024 also bounds worst-case crash re-work to ~1024 tasks. (Dispatcher rationalization phase 2, docs/archive/DISPATCHER_RATIONALIZATION.md.)

finalize_flush_ms: u64

Finalize batch coalescing — time threshold (T), milliseconds. The maximum time a report waits in an accumulating batch before it is flushed, bounding both report staleness and worst-case crash re-work. An unflushed in-memory batch is never lost — its tasks stay Queued and are recovered on restart — so T trades a little latency for far fewer DB writes, not safety. At steady-state load this is usually the threshold that fires. Default 300 ms (at ~200 tasks/s it coalesces ~60 tasks per write instead of one write per task, for a few hundred ms of staleness).

lease_timeout_seconds: i64

Lease / visibility timeout (seconds). Base deadline for a dispatched (in-flight) task to return a result before the reaper re-leases it. The effective per-task deadline backs off with retries — (retries + 1) × lease_timeout_seconds from dispatch — so a task that keeps timing out waits progressively longer rather than re-leasing ever-faster (crate::helpers::TaskProgress::expected_at). This is the correctness net for a silently dead / half-open worker (no ZMTP heartbeat needed): its task is recovered once the lease lapses. Default 240 — just above the worker’s hard per-document timeout (the CorTeX latexml fleet caps each conversion at 180 s and hard-kills the process on overrun), with a 60 s margin, which bounds any single conversion’s runtime. With that cap, a lease expiry reliably means the worker died (timeout / OOM kill) on an unprocessable paper, so prompt re-lease — and, after MAX_DISPATCH_RETRIES, dead-letter to Fatal — recovers the task within the run instead of stranding it for an hour (orphaned-lease tail observed at scale). Raise it only for a service whose workers have unbounded runtime (no per-task timeout). Paired with reap_interval_seconds (how often the sweep runs).

reap_interval_seconds: i64

Reaper sweep interval (seconds). How often the ventilator scans the in-flight set for tasks past their lease_timeout_seconds deadline and re-leases / dead-letters them. Decoupled from the request path so the in-flight set drains even under sustained backpressure (KNOWN_ISSUES D-6). Kept well below the lease timeout so an expired task is recovered promptly without scanning the set on every request. Default 60 s. (Lowering both this and lease_timeout_seconds is what lets a fast chaos test exercise reaper-based recovery in seconds instead of the hour-scale production timing.)

tcp_keepalive_idle_seconds: i32

TCP keepalive idle (seconds) on the worker-facing ZMQ sockets (ventilator + sink). After this many idle seconds the OS begins probing the peer; this both keeps idle worker connections alive across NAT/firewall idle-timeouts — essential when the ~200 remote workers reach the dispatcher over an overlay/VPN or any NAT’d path, where an idle mapping is otherwise silently dropped and the worker falls out of the fleet until it reconnects — and lets the OS reap a genuinely dead peer so the ROUTER doesn’t accumulate stale routes. Task-recovery correctness does not depend on this (the lease reaper is that net, see lease_timeout_seconds); it keeps the fleet connected. <= 0 leaves the OS keepalive default (effectively off). Default 120, well under the common 5-minute NAT idle window. (Probe interval/count are fixed sane values in crate::dispatcher::server::apply_tcp_keepalive.)

input_prefetchers: usize

Input-archive prefetcher pool size (D-20). Number of background threads that warm the next batch of task input archives into the OS page cache ahead of dispatch, so the ventilator’s inline /data read is served from RAM (~0.02 ms) instead of the cold QLC-RAID6 platter (~10 ms median — the single-thread dispatch ceiling at full-arXiv scale where the working set ≫ RAM). The warmers open + read → discard; the warmed bytes are reclaimable page cache, not dispatcher RSS, so this cannot OOM (the kernel drops the cache before the workers’ anon memory). Graceful: a warm that lags or fails just leaves a cold read, exactly as before. Default 8 (the warmers outpace dispatch ~8×, keeping the window warm); 0 disables (the ventilator reads inline, the pre-D-20 behavior).

prefetch_max_entry_mb: usize

Per-entry prefetch cap (MiB). Input archives larger than this are not prefetched — they fall through to the ventilator’s existing chunk-streaming read (O(chunk) resident, never the whole file), so the rare 50–100 MB monster streams cold instead of doubling its bytes in cache. Default 50.

prefetch_budget_mb: usize

Total prefetch warm budget per batch (MiB). The warmers stop warming a fetch batch once their cumulative warmed bytes reach this, so a batch that clusters large entries can’t dump tens of GiB into page cache and churn out Postgres’s working set; the batch’s tail streams cold. The typical batch (~queue_size × mean-entry ≈ a few hundred MiB) warms fully well under this. Default 8192 (8 GiB).

Trait Implementations

impl Clone for DispatcherConfig

fn clone(&self) -> DispatcherConfig

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for DispatcherConfig

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for DispatcherConfig

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for DispatcherConfig

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl JsonSchema for DispatcherConfig

fn schema_name() -> String

The name of the generated JSON Schema.

fn schema_id() -> Cow<'static, str>

Returns a string that uniquely identifies the schema produced by this type.

fn json_schema(generator: &mut SchemaGenerator) -> Schema

Generates a JSON Schema for this type.

fn is_referenceable() -> bool

Whether JSON Schemas generated for this type should be re-used where possible using the $ref keyword.

impl Serialize for DispatcherConfig

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.