Enum OverflowPolicy 

pub enum OverflowPolicy {
    Fail,
    Drop,
    Block,
}

Controls what happens when a subscriber’s channel is full.

Events flow through two stages: producers send to the broker (stage 1), and the broker dispatches to subscriber channels (stage 2). Overflow policy governs stage 2 - what the broker does when a specific subscriber can’t keep up.

The policy is defined on Topic, not on actors, because flow semantics are properties of the data: a critical command topic needs different handling than expendable telemetry, regardless of which actor consumes it.

Policies

Policy	On full channel	Use case
Drop	Discard the event, continue	Telemetry, metrics, status updates
Block	Wait for space	Commands, data that must arrive
Fail	Close the subscriber’s channel	Real-time topics where stale data is worse than no actor

Default

The default policy is Fail, which ensures overflow is never silent. If a subscriber can’t keep up, the system surfaces the problem immediately rather than hiding it behind dropped events. Override Topic::overflow_policy() to choose per-topic behavior.

Single-broker limitation

With a single broker (current architecture), Block on one topic delays dispatch to all other topics while the broker waits for space. For most systems (tens to hundreds of actors, moderate event rates) this delay is acceptable. Multi-broker support (planned) eliminates this by giving each topic group its own broker.

Example

impl Topic<MyEvent> for MyTopic {
    fn from_event(event: &MyEvent) -> Self {
        match event {
            MyEvent::Control => MyTopic::Control,
            MyEvent::Telemetry => MyTopic::Telemetry,
        }
    }

    fn overflow_policy(&self) -> OverflowPolicy {
        match self {
            MyTopic::Control => OverflowPolicy::Block,
            MyTopic::Telemetry => OverflowPolicy::Drop,
        }
    }
}

Variants

Fail

Close the subscriber’s channel, terminating the actor.

The broker removes the subscriber immediately. The actor’s receive channel closes, causing it to exit its event loop and run on_shutdown(). Use this for topics where falling behind is unacceptable and the actor should be stopped rather than allowed to process stale data.

Drop

Discard the event when the subscriber’s channel is full.

The broker logs the drop and continues dispatching to other subscribers. The slow consumer never sees the event. Use this for data that is acceptable to lose under load (telemetry, periodic status updates, metrics).

Block

Wait for space in the subscriber’s channel.

The broker blocks (via .await) until the subscriber has capacity. Multiple blocked subscribers are awaited concurrently. Use this for events that must be delivered (commands, data integrity).

With a single broker, this delays dispatch of all other topics during the wait.

Implementations

impl OverflowPolicy

pub fn is_fail(&self) -> bool

Returns true if this is the Fail policy.

pub fn is_drop(&self) -> bool

Returns true if this is the Drop policy.

pub fn is_block(&self) -> bool

Returns true if this is the Block policy.

Trait Implementations

impl Clone for OverflowPolicy

fn clone(&self) -> OverflowPolicy

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for OverflowPolicy

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

Formats the value using the given formatter.

impl Default for OverflowPolicy

fn default() -> OverflowPolicy

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for OverflowPolicy

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for OverflowPolicy

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

Formats the value using the given formatter.

impl Hash for OverflowPolicy

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for OverflowPolicy

fn cmp(&self, other: &OverflowPolicy) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for OverflowPolicy

fn eq(&self, other: &OverflowPolicy) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for OverflowPolicy

fn partial_cmp(&self, other: &OverflowPolicy) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Serialize for OverflowPolicy

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

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Copy for OverflowPolicy

impl Eq for OverflowPolicy

impl StructuralPartialEq for OverflowPolicy