Deterministic Worker Pool in Rust

A deterministic, multi-threaded worker pool implemented in pure Rust (std), designed to process jobs concurrently while producing fully deterministic output, with cooperative per-job timeouts and robust error handling.

This project focuses on correct concurrency design, explicit lifecycle management, and predictable execution — without async runtimes or external concurrency frameworks.

Why This Program

This small program was built to:

• Study and self-demonstrate correct concurrent programming in Rust
• Demonstrate understanding of deadlocks, channel lifecycle, and cooperative cancellation
• Favor explicitness and correctness over abstractions

---

Key Features

• Deterministic execution
  • Jobs are processed concurrently but results are sorted and aggregated deterministically.
• Thread-based worker pool
  • Fixed-size pool using std::thread and std::sync::mpsc.
• Per-job cooperative timeout
  • Each job defines its own execution budget (timeout_ms).
  • Timeouts are enforced inside the worker logic without killing threads.
• Robust error model
  • Typed errors (InvalidJob, ProcessingError, Timeout) propagated cleanly.
• Graceful termination
  • Correct channel lifecycle management ensures no deadlocks or hanging receivers.
• No async / no runtime
  • Designed using only the Rust standard library to demonstrate low-level concurrency understanding.

---

Design Overview

The system is composed of separated layers:

1. Orchestration (processor)

• Distributes jobs to a worker pool via a shared channel.
• Collects job outcomes through a result channel.
• Aggregates successful results and errors into a final batch report.
• Ensures deterministic output ordering.

2. Execution (worker)

• Implements the actual job logic.
• Enforces cooperative per-job timeouts using Instant and Duration.
• Stops execution immediately when a timeout is exceeded without affecting other workers.

---

Timeout Model

Timeouts are:

• Per-job, not global
• Cooperative, not preemptive
• Enforced inside the job execution loop

This avoids unsafe thread termination and guarantees system stability even under time-constrained workloads.

---

Key Features

• Deterministic execution
  • Jobs are processed concurrently but results are sorted and aggregated deterministically.
• Thread-based worker pool
  • Fixed-size pool using std::thread and std::sync::mpsc.
• Per-job cooperative timeout
  • Each job defines its own execution budget (timeout_ms).
  • Timeouts are enforced inside the worker logic without killing threads.
• Robust error model
  • Typed errors (InvalidJob, ProcessingError, Timeout) propagated cleanly.
• Graceful termination
  • Correct channel lifecycle management ensures no deadlocks or hanging receivers.
• No async / no runtime
  • Designed using only the Rust standard library to demonstrate low-level concurrency understanding.

---

Design Overview

The system is composed of three clearly separated layers:

1. Orchestration (processor)

• Distributes jobs to a worker pool via a shared channel.
• Collects job outcomes through a result channel.
• Aggregates successful results and errors into a final batch report.
• Ensures deterministic output ordering.

2. Execution (worker)

• Implements the actual job logic.
• Enforces cooperative per-job timeouts using Instant and Duration.
• Stops execution immediately when a timeout is exceeded without affecting other workers.

---

Timeout Model

Timeouts are:

• Per-job, not global
• Cooperative, not preemptive
• Enforced inside the job execution loop

This avoids unsafe thread termination and guarantees system stability even under time-constrained workloads.