Module kernel::serial_trace::dispatcher

Dispatches trace events to Subscribers.

The dispatcher is the component of the tracing system which is responsible for forwarding trace data from the instrumentation points that generate it to the subscriber that collects it.

Using the Trace Dispatcher

Every thread in a program using tracing has a default subscriber. When events occur, or spans are created, they are dispatched to the thread’s current subscriber.

Setting the Default Subscriber

By default, the current subscriber is an empty implementation that does nothing. To use a subscriber implementation, it must be set as the default. There are two methods for doing so: with_default and set_global_default. with_default sets the default subscriber for the duration of a scope, while set_global_default sets a default subscriber for the entire process.

To use either of these functions, we must first wrap our subscriber in a Dispatch, a cloneable, type-erased reference to a subscriber. For example:

use dispatcher::Dispatch;

let my_subscriber = FooSubscriber::new();
let my_dispatch = Dispatch::new(my_subscriber);

Then, we can use with_default to set our Dispatch as the default for the duration of a block:

// no default subscriber

dispatcher::with_default(&my_dispatch, || {
    // my_subscriber is the default
});

// no default subscriber again

It’s important to note that with_default will not propagate the current thread’s default subscriber to any threads spawned within the with_default block. To propagate the default subscriber to new threads, either use with_default from the new thread, or use set_global_default.

As an alternative to with_default, we can use set_global_default to set a Dispatch as the default for all threads, for the lifetime of the program. For example:

// no default subscriber

dispatcher::set_global_default(my_dispatch)
    // `set_global_default` will return an error if the global default
    // subscriber has already been set.
    .expect("global default was already set!");

// `my_subscriber` is now the default

Note: The thread-local scoped dispatcher (with_default)
requires the Rust standard library. no_std users should
use set_global_default
instead.

Accessing the Default Subscriber

A thread’s current default subscriber can be accessed using the get_default function, which executes a closure with a reference to the currently default Dispatch. This is used primarily by tracing instrumentation.

Structs

• DefaultGuard
  A guard that resets the current default dispatcher to the prior default dispatcher when dropped.
• Dispatch
  Dispatch trace data to a Subscriber.
• SetGlobalDefaultError
  Returned if setting the global dispatcher fails.
• WeakDispatch
  WeakDispatch is a version of Dispatch that holds a non-owning reference to a Subscriber.

Functions

• get_default
  Executes a closure with a reference to this thread’s current dispatcher.
• set_default
  Sets the dispatch as the default dispatch for the duration of the lifetime of the returned DefaultGuard
• set_global_default
  Sets this dispatch as the global default for the duration of the entire program. Will be used as a fallback if no thread-local dispatch has been set in a thread (using with_default.)
• with_default
  Sets this dispatch as the default for the duration of a closure.