Module cpu 

Module for thread pool-based parallelization of CPU-heavy blocking workloads.

Zombie Task Prevention

The Rayon thread pool is sized to CPU cores for crypto operations. Callers wrap tasks with timeouts (e.g., 150ms for packet decoding). When a timeout fires, the async receiver is dropped, but Rayon has no native cancellation—the closure continues as a “zombie” task whose result is discarded.

Under sustained load, zombie accumulation can starve the pool: timed-out tasks continue occupying threads, causing subsequent tasks to also time out. To break this cycle, each spawned closure checks tx.is_canceled() before executing. If the receiver was dropped while queued, the closure returns immediately.

Queue Depth Limiting

To prevent unbounded queue growth, the module tracks outstanding tasks (queued + running). Use [spawn_blocking] or [spawn_fifo_blocking] which return [SpawnError::QueueFull] when the configured limit is reached.

Set HOPR_CPU_TASK_QUEUE_LIMIT environment variable to enable limiting.

Observability

Prometheus metrics (behind the prometheus feature) track:

• submitted: total tasks entering the queue
• completed: tasks that delivered results to a live receiver
• cancelled: tasks skipped via cooperative cancellation
• orphaned: tasks that ran but whose receiver was dropped during execution
• rejected: tasks rejected due to queue being full
• queue_wait: histogram of queue wait time
• execution_time: histogram of task execution duration
• outstanding_tasks: current queued + running tasks
• queue_limit: configured maximum (for comparison)

Re-exports

pub use rayon;

Enums

SpawnError

Error type for spawn operations.

Functions

init_thread_pool

Initialize the Rayon thread pool with the given number of threads.

outstanding_tasks

Returns the current outstanding task count (queued + running).

queue_limit

Returns the configured queue limit, or None if unlimited.

spawn_blocking

Spawn a blocking function on the Rayon thread pool (LIFO scheduling).

spawn_fifo_blocking

Spawn a blocking function on the Rayon thread pool (FIFO scheduling).