medi_rs/adapters/
queue.rs

1//! Event/job queue abstraction for generated mediators.
2//!
3//! Each runtime adapter provides an implementation of [`EventQueue`] so that
4//! the [`mediator!`](crate::mediator!) macro can enqueue and
5//! dequeue typed events without coupling to a specific channel backend.
6
7use crate::{Result, TryPublishError};
8use core::future::Future;
9
10/// Async queue used by generated mediators to enqueue events and dequeue
11/// them in a background processing loop.
12///
13/// # Type parameters
14///
15/// * `T` — The job/enum type that the generated mediator uses to represent
16///   all possible events across its subscribed modules.
17pub trait EventQueue<T>: Send + Sync + 'static {
18    /// Create a new queue.
19    ///
20    /// `Some(capacity)` requests a bounded queue; `None` requests an
21    /// unbounded queue. Adapters may ignore the hint if the underlying
22    /// channel does not support bounding.
23    fn new(capacity: Option<usize>) -> Self;
24
25    /// Enqueue an item.
26    ///
27    /// Returns [`Error::EventPublishingError`](crate::Error::EventPublishingError)
28    /// if the channel is closed or full.
29    fn publish(&self, item: T) -> impl Future<Output = Result<()>> + Send;
30
31    /// Attempt to enqueue an item without waiting for queue capacity.
32    ///
33    /// Returns the original item in [`TryPublishError`] when the queue is
34    /// full or no longer accepts events.
35    fn try_publish(&self, item: T) -> core::result::Result<(), TryPublishError<T>>;
36
37    /// Stop accepting new items.
38    ///
39    /// Items for which [`Self::publish`] has already returned `Ok(())` remain
40    /// available to receivers. Generated shutdown then enqueues internal
41    /// worker-control items behind that accepted work.
42    fn close(&self) -> impl Future<Output = ()> + Send;
43
44    /// Enqueue an internal worker-control item after closure.
45    #[doc(hidden)]
46    fn publish_internal(&self, item: T) -> impl Future<Output = Result<()>> + Send;
47
48    /// Dequeue the next item.
49    ///
50    /// Returns [`Error::EventProcessingError`](crate::Error::EventProcessingError)
51    /// if the channel is closed.
52    fn recv(&self) -> impl Future<Output = Result<T>> + Send;
53}
medi_rs/adapters/queue.rs

medi_rs/adapters/
queue.rs
