Trait Source 

pub trait Source: Any + Send {
    // Required methods
    fn flush(&mut self, ctx: &FlushContext<'_>);
    fn name(&self) -> &'static str;

    // Provided methods
    fn on_thread_start(&mut self) -> Result<(), Error> { ... }
    fn on_thread_stop(&mut self) { ... }
    fn segment_metadata(&mut self, out: &mut Vec<(String, String)>) { ... }
    fn segment_processor(&mut self) -> Option<Box<dyn SegmentProcessor>> { ... }
}

Available on crate feature dial9 only.

A data source drained by the flush thread each cycle.

Implement this trait to feed custom events into the dial9 trace. Register the source with RecorderBuilder::source before starting the flush thread; the flush thread calls flush once per cycle.

Panic safety

The flush thread catches panics from flush and segment_metadata so one source’s panic can’t poison the flush thread or skip sibling sources’ turns. The same instance is reused next cycle, so implementations must remain valid after a panic. segment_metadata fully discards this cycle’s metadata on panic; flush does not. Events already recorded before the panic point still reach the trace.

Each panic is also marked in the trace’s segment metadata, as dial9.source.<name>.flush_panicked or dial9.source.<name>.segment_metadata_panicked set to "true", where <name> is name.

Required Methods

fn flush(&mut self, ctx: &FlushContext<'_>)

Drain pending data into the trace. Called once per flush cycle.

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

Diagnostic name for this source (e.g. "cpu_profile", "sched").

Provided Methods

fn on_thread_start(&mut self) -> Result<(), Error>

Called when a thread joins the recorder: a Tokio worker’s first poll, or an explicit Dial9Handle::track_current_thread.

Per-thread sources (e.g. SchedProfiler) use this to begin tracking the current thread. Returns an error if setup fails.

fn on_thread_stop(&mut self)

Called when a thread stops. Per-thread sources use this to stop tracking the current thread.

fn segment_metadata(&mut self, out: &mut Vec<(String, String)>)

Append this source’s segment-metadata entries to out iff they have changed since the last call.

The flush loop merges only when out is non-empty, so appending nothing on an unchanged cycle keeps steady-state cycles allocation-free. The default reports a source with no metadata.

fn segment_processor(&mut self) -> Option<Box<dyn SegmentProcessor>>

Available on crate feature pipeline only.

A segment-processing stage this source’s data needs, folded into the recorder’s default pipeline at build. Called once, at build.

A custom pipeline replaces the default outright and does not pick these up; you must chain the stage yourself in those cases.

Dyn Compatibility

This trait is dyn compatible.

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

Implementors

impl Source for CustomEventsSource