Module concurrency 

Available on crate feature concurrency only.

Async concurrency primitives.

Three patterns, each generic over the consumer’s domain type, each the canonical way to do the corresponding shape of async work in HyperI Rust libraries. See hyperi-ai/standards/languages/RUST.md §“Three async primitives every HyperI library uses” for design philosophy and a decision matrix.

Decision matrix

Shape	Use
Consumer pushes; background batches + writes to a backend	BackgroundSink + SinkDrain
Timer-driven loop, no inbound queue	PeriodicWorker + PeriodicTask
Mutable state, command queue, optional oneshot replies	ActorHandle + Actor

The hard rule

An async fn in HyperI libraries MUST yield to the runtime. No hidden synchronous I/O. If you need sync I/O from async:

• Use tokio::fs / tokio::io::AsyncWrite for occasional async I/O.
• Use BackgroundSink for high-throughput durable writes.
• Use tokio::task::spawn_blocking for one-off unavoidable sync work.
• Don’t – push the sync work to startup, before the runtime is hot.

The grep-based tests/sync_in_async.rs lint enforces this mechanically: any async fn body containing std::fs::*, std::io::Write::write_*, std::thread::sleep, reqwest::blocking::*, or parking_lot::*::lock() held across .await fails CI.

Considered alternatives

• tokio-actors (v0.6) – covers ActorHandle + PeriodicWorker cleanly but doesn’t provide batched-drain-with-flush-barrier, which is the load-bearing case for BackgroundSink. Wrapping it would equal the size of this module’s impl. Rejected.
• tokio-prometheus-metered-channel (v0.2) – bounded channel with Prometheus metrics, no actor / batch / flush. Too narrow.
• xtra, actix, bastion – heavy actor frameworks. Don’t fit the sink shape. Rejected.
• tracing-appender::non_blocking – used elsewhere for the logger subscriber; orthogonal to this module’s tokio-runtime concerns.

Rationale per Alice Ryhl’s “Actors with Tokio” and the 2026-05-08 audit.

Structs

ActorConfig

Configuration for an ActorHandle.

ActorHandle

Cloneable handle for sending commands.

ActorJoinHandle

Single-owner handle for awaiting actor shutdown.

BackgroundSink

Cloneable handle for pushing messages. Hot-path consumers clone freely and push from many tasks concurrently.

BackgroundSinkConfig

Configuration for a BackgroundSink.

BackgroundSinkHandle

Single-owner handle for awaiting actor shutdown.

PeriodicWorker

Handle for the worker task.

Enums

ActorError

Errors returned by super::ActorHandle send operations.

DrainError

Errors returned by super::SinkDrain implementations.

Overflow

Overflow policy for BackgroundSink::try_push.

SinkError

Errors returned by super::BackgroundSink push / flush operations.

TickError

Errors returned by super::PeriodicTask tick implementations.

Traits

Actor

An actor owns mutable state and processes commands sequentially.

PeriodicTask

A task that runs on a fixed interval.

SinkDrain

A drain consumes batches of messages and writes them to the backend.