Eliza Weisman
9c5cad037f
## Motivation
In order to implement "out of band" `Subscriber` APIs in third-party
subscriber implementations (see [this comment]) users may want to
downcast the current `Dispatch` to a concrete subscriber type.
For example, in a library for integrating `tokio-trace` with a fancy new
(hypothetical) distributed tracing technology "ElizaTracing", which uses
256-bit span IDs, we might expect to see a function like this:
```rust
pub fn correlate(tt: tokio_trace::span::Id, et: elizatracing::SpanId) {
tokio_trace::dispatcher::with(|c| {
if let Some(s) = c.downcast_ref::<elizatracing::Subscriber>() {
s.do_elizatracing_correlation_magic(tt, et);
}
});
}
```
This allows users to correlate `tokio-trace` IDs with IDs in the
distributed tracing system without having to pass a special handle to
the subscriber through application code (as one is already present in
thread-local storage, but with its type erased).
## Solution
This branch makes the following changes:
* Add an object-safe `downcast_raw` method to the `Subscriber` trait,
taking a `TypeId` and returning an `*const ()` if the type ID
matches the subscriber's type ID, or `None` if it does not, and
* Add `is<T>` and `downcast_ref<T>` functions to `Subscriber`
and `Dispatch`, using `downcast_raw`.
Unlike the approach implemented in #950, the `downcast_raw` method is
object-safe, since it takes a `TypeId` rather than a type _parameter_
and returns a void pointer rather than an `&T`. This means that
`Subscriber` implementations can override this method if necessary. For
example, a `Subscriber` that fans out to multiple component subscribers
can downcast to their component parts, and "chained" or "middleware"
subscribers, which wrap an inner `Subscriber` and modify its behaviour
somehow, can downcast to the inner type if they choose to.
[this comment]: https://github.com/tokio-rs/tokio/issues/932#issuecomment-469473501
[`std::error::Error`'s]: https://doc.rust-lang.org/1.33.0/src/std/error.rs.html#204
Refs: #950, #953, https://github.com/tokio-rs/tokio/issues/948#issuecomment-469444293
Signed-off-by: Eliza Weisman <[email protected]>
tokio-trace-core
Core primitives for tokio-trace.
Overview
tokio-trace is a framework for instrumenting Rust programs to collect
structured, event-based diagnostic information. This crate defines the core
primitives of tokio-trace.
The crate provides:
-
Spanidentifies a span within the execution of a program. -
Eventrepresents a single event within a trace. -
Subscriber, the trait implemented to collect trace data. -
Field,FieldSet,Value, andValueSetrepresent the structured data attached to aSpan. -
Dispatchallows span events to be dispatched toSubscribers.
In addition, it defines the global callsite registry and per-thread current dispatcher which other components of the tracing system rely on.
Application authors will typically not use this crate directly. Instead, they
will use the tokio-trace crate, which provides a much more fully-featured
API. However, this crate's API will change very infrequently, so it may be used
when dependencies must be very stable.
License
This project is licensed under the MIT license.
Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Tokio by you, shall be licensed as MIT, without any additional terms or conditions.