Skip to main content

TraceSink

cove_runtime::trace

Trait TraceSink 

Source 
pub trait TraceSink: Send + Sync {
    // Required method
    fn record(&self, event: TraceEvent);

    // Provided method
    fn is_recording(&self) -> bool { ... }
}
Expand description

Where trace events go.

A sink records through a shared reference and is Send + Sync because every task thread traces into the same one: ADR 0008 runs each spawned task on its own thread, and a trace that each thread wrote to separately would not be one trace. A sink that needs mutable state of its own synchronizes it, which is also what keeps two threads from interleaving halves of a line.

§Two installation points, not one

One Arc<dyn TraceSink> does not see every event: a run has two of them. HostRegistry::set_trace is where TraceEvent::HostCall alone goes. Every other event — TraceEvent::TaskSpawned, TraceEvent::TaskCompleted, TraceEvent::TaskCancelled, TraceEvent::HeapCollected, TraceEvent::HeapSummary, TraceEvent::EntryEnter, TraceEvent::EntryExit and TraceEvent::RunEnded — goes through Runtime::with_trace. Each defaults to its own NullSink, independently, so installing one says nothing about whether the other was, and an embedding that installs only one gets a trace that is silently missing the other’s events rather than an error.

§Correlating an event to something of the host’s own

TraceEvent’s task-lifecycle and per-call variants carry a bare task id — crate::runtime::ENTRY_TASK for the entry, and whatever Runtime::next_task_id handed out for a spawned one — and nothing else. That is deliberate rather than an omission: the id a host wants to hang an event on (a creature, a request, a session) belongs to the host, not to the runtime, and a sink is exactly the place a host bridges the two. A sink built per invocation, closing over the host’s own identifier, is how that bridge is made; the runtime does not carry the identifier itself because it has no way to know what shape it should be.

Required Methods§

Source

fn record(&self, event: TraceEvent)

Records one event. Must not panic: a broken trace sink should degrade the trace, not the program being traced.

Provided Methods§

Source

fn is_recording(&self) -> bool

Whether anything will read what is recorded.

Describing a host call’s values costs a copy of each of them, and a value no boundary may carry costs printing it. A run that is not being traced should not pay for a trace nobody keeps, so a sink that discards everything says so and crate::host::HostRegistry::call skips the description. The default is true: a sink that does something with an event needs the event to be complete.

Dyn Compatibility§

This trait is dyn compatible.

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

Implementors§