Skip to main content

Subscribe

taskvisor

Trait Subscribe 

Source 
pub trait Subscribe:
    Send
    + Sync
    + 'static {
    // Required method
    fn on_event(&self, event: &Event);

    // Provided methods
    fn name(&self) -> &'static str { ... }
    fn queue_capacity(&self) -> usize { ... }
}
Expand description

Event subscriber for runtime observability.

Each subscriber runs in isolation:

  • Panic isolation: panics are caught and published as SubscriberPanicked.
  • Bounded queue buffers events (capacity via Self::queue_capacity).
  • Dedicated worker task processes events sequentially (FIFO).

§Implementation requirements

  • Keep on_event fast: it runs on a dedicated worker task but blocks that worker’s event loop. For async I/O, send to a channel and process elsewhere.
  • Slow processing affects only this subscriber’s queue.
  • Handle errors internally; do not panic.

§Synchronous design

on_event is intentionally synchronous:

  • The SubscriberSet infrastructure already provides async fan-out via per-subscriber mpsc channels and dedicated worker tasks.
  • If a subscriber needs async I/O, send events to a channel inside on_event and process them in a separate task.
  • Adding async to on_event would force a Box::pin allocation per event per subscriber with no benefit; All real subscribers are synchronous.

§Also

  • See Event and EventKind for the event structure.
  • For a built-in reference implementation see LogWriter (feature = logging).

Required Methods§

Source

fn on_event(&self, event: &Event)

Processes a single event synchronously.

Called from a dedicated worker task, not in the publisher context. Events are delivered in FIFO order per subscriber.

Panics are caught; the runtime publishes EventKind::SubscriberPanicked.

Provided Methods§

Source

fn name(&self) -> &'static str

Returns the subscriber name used in logs/metrics and overflow/panic events.

Prefer short, descriptive names (e.g., “metrics”, “audit”, “slack”). The default uses type_name::<Self>(), which can be verbose - override it when possible.

Source

fn queue_capacity(&self) -> usize

Returns the preferred queue capacity for this subscriber.

Overflow behavior:

  1. The new event is dropped for this subscriber only,
  2. an EventKind::SubscriberOverflow is published,
  3. other subscribers are unaffected.

The runtime clamps capacity to a minimum of 1.

Default: 1024.

Implementors§