Trait Subscribe 

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

    // Provided methods
    fn execution(&self) -> SubscriberExecution { ... }
    fn name(&self) -> &str { ... }
    fn queue_capacity(&self) -> NonZeroUsize { ... }
}

Synchronous observer for best-effort Event values.

Each subscriber has one serial lane. By default, all lanes use one fixed shared worker. SubscriberExecution::Dedicated gives one lane its own worker. Events delivered to on_event keep FIFO order for that subscriber. Shutdown or a failed callback lane can still discard queued events. Dedicated lanes may run concurrently with the shared worker and with each other. These callbacks do not use Tokio async workers or its blocking pool.

Keep shared callbacks short. Dedicated execution isolates a callback that may block, but that lane can still fill its own queue and outlive the shutdown deadline. Copy the needed fields into an application-owned channel when handling requires async I/O. The borrowed event is valid only for the callback.

A full queue drops the incoming event only for that subscriber. Taskvisor counts dropped ordinary events and delivers one direct SubscriberOverflow summary after the lane catches up. Dropping an internal diagnostic, or panicking while handling one, does not generate another diagnostic.

Taskvisor catches an unwinding panic from an ordinary event callback and tries to publish a SubscriberPanicked event. A panic = "abort" build exits instead.

During shutdown, all subscriber lanes share one drain timeout. Queued events are dropped at the deadline. A callback already running cannot be aborted and may continue on its worker thread after shutdown returns. Taskvisor does not join callback workers or wait for their thread-local destructors.

Examples

use std::num::NonZeroUsize;
use std::sync::Arc;
use taskvisor::{Event, EventKind, Subscribe, Supervisor, SupervisorConfig};

struct Metrics;

impl Subscribe for Metrics {
    fn on_event(&self, event: &Event) {
        if event.kind == EventKind::AttemptFailed {
            // Update an in-memory counter.
        }
    }

    fn name(&self) -> &str {
        "metrics"
    }

    fn queue_capacity(&self) -> NonZeroUsize {
        NonZeroUsize::new(2048).unwrap()
    }
}

let subscribers: Vec<Arc<dyn Subscribe>> = vec![Arc::new(Metrics)];
let supervisor = Supervisor::builder(SupervisorConfig::default())
    .with_subscribers(subscribers)
    .build();
// Start it with `Supervisor::run`, `run_until`, or `serve`.

Required Methods

fn on_event(&self, event: &Event)

Serial callback for one delivered event.

Taskvisor calls this method on the subscriber’s selected callback worker. Calls never run in the event publisher or on a Tokio worker.

Provided Methods

fn execution(&self) -> SubscriberExecution

Callback-worker choice for this subscriber’s serial lane.

Supervisor construction reads and stores this value once. The default is SubscriberExecution::Shared.

fn name(&self) -> &str

Stable name for subscriber diagnostics.

Supervisor construction reads and stores this value once. Choose a stable, recognizable name for logs and alerts. The default is the fully qualified type_name.

fn queue_capacity(&self) -> NonZeroUsize

Maximum queued events for this subscriber.

Supervisor construction reads this value once. Values above Taskvisor’s structural async-capacity limit make SupervisorBuilder::try_build return BuildError::CapacityTooLarge. A full queue drops the new event for this subscriber. Increase capacity for short bursts. A larger queue does not make a slow callback faster.

The default capacity is 1024.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl Subscribe for LogWriter

Available on crate feature logging only.

impl Subscribe for TracingBridge

Available on crate feature tracing only.

impl Subscribe for TracingBridgeWithReasons

Available on crate feature tracing only.