mirror of
https://github.com/tokio-rs/tokio.git
synced 2026-08-23 00:00:10 +02:00
Eliza Weisman
7e7a5147a3
## Motivation The `tracing` crate implements scoped, structured, context-aware diagnostics, which can add significant debugging value over unstructured log messages. `tracing` is part of the Tokio project. As part of the `tokio` 0.2 changes, I thought it would be good to move over from `log` to `tracing` in the tokio runtime. Updating the executor crate is an obvious starting point. ## Solution This branch replaces the use of `log` in `tokio-executor` with `tracing`. I've tried to leave all the instrumentation points more or less the same, but modified to use structured fields instead of string interpolation. I've also added a few `tracing` spans, primarily in places where a variable is added to all the log messages in a scope. ## Notes For users who are using the legacy `log` output, there is a feature flag to enable `log` support in `tracing`. I thought about making this on by default, but that would also enable the `tracing` dependency by default, and it is only pulled in when the `threadpool` feature flag is enabled. The `tokio` crate could enable the log feature in its default features instead, since the threadpool feature is on by default in `tokio`. If this isn't the right approach, I can change how `log` back-compatibility is enabled. We might want to consider adding more `tracing` spans in the threadpool later. This could be useful for profiling, and for helping users debug the way their applications interact with the executor. This branch is just intended as a starting point so that we can begin emitting `tracing` data from the executor; we should revisit what instrumentation should be exposed, as well. Signed-off-by: Eliza Weisman <[email protected]>
81 lines
3.0 KiB
Rust
81 lines
3.0 KiB
Rust
#![doc(html_root_url = "https://docs.rs/tokio-executor/0.2.0-alpha.2")]
|
|
#![warn(
|
|
missing_debug_implementations,
|
|
missing_docs,
|
|
rust_2018_idioms,
|
|
unreachable_pub
|
|
)]
|
|
#![doc(test(no_crate_inject, attr(deny(rust_2018_idioms))))]
|
|
|
|
//! Task execution related traits and utilities.
|
|
//!
|
|
//! In the Tokio execution model, futures are lazy. When a future is created, no
|
|
//! work is performed. In order for the work defined by the future to happen,
|
|
//! the future must be submitted to an executor. A future that is submitted to
|
|
//! an executor is called a "task".
|
|
//!
|
|
//! The executor is responsible for ensuring that [`Future::poll`] is called
|
|
//! whenever the task is notified. Notification happens when the internal
|
|
//! state of a task transitions from *not ready* to *ready*. For example, a
|
|
//! socket might have received data and a call to `read` will now be able to
|
|
//! succeed.
|
|
//!
|
|
//! This crate provides traits and utilities that are necessary for building an
|
|
//! executor, including:
|
|
//!
|
|
//! * The [`Executor`] trait spawns future object onto an executor.
|
|
//!
|
|
//! * The [`TypedExecutor`] trait spawns futures of a specific type onto an
|
|
//! executor. This is used to be generic over executors that spawn futures
|
|
//! that are either `Send` or `!Send` or implement executors that apply to
|
|
//! specific futures.
|
|
//!
|
|
//! * [`enter`] marks that the current thread is entering an execution
|
|
//! context. This prevents a second executor from accidentally starting from
|
|
//! within the context of one that is already running.
|
|
//!
|
|
//! * [`DefaultExecutor`] spawns tasks onto the default executor for the current
|
|
//! context.
|
|
//!
|
|
//! * [`Park`] abstracts over blocking and unblocking the current thread.
|
|
//!
|
|
//! # Implementing an executor
|
|
//!
|
|
//! Executors should always implement `TypedExecutor`. This usually is the bound
|
|
//! that applications and libraries will use when generic over an executor. See
|
|
//! the [trait documentation][`TypedExecutor`] for more details.
|
|
//!
|
|
//! If the executor is able to spawn all futures that are `Send`, then the
|
|
//! executor should also implement the `Executor` trait. This trait is rarely
|
|
//! used directly by applications and libraries. Instead, `tokio::spawn` is
|
|
//! configured to dispatch to type that implements `Executor`.
|
|
//!
|
|
//! [`Executor`]: trait.Executor.html
|
|
//! [`TypedExecutor`]: trait.TypedExecutor.html
|
|
//! [`enter`]: fn.enter.html
|
|
//! [`DefaultExecutor`]: struct.DefaultExecutor.html
|
|
//! [`Park`]: park/index.html
|
|
//! [`Future::poll`]: https://doc.rust-lang.org/std/future/trait.Future.html#tymethod.poll
|
|
#[cfg(any(feature = "current-thread", feature = "threadpool"))]
|
|
#[macro_use]
|
|
mod tracing;
|
|
|
|
mod enter;
|
|
mod error;
|
|
mod executor;
|
|
mod global;
|
|
pub mod park;
|
|
mod typed;
|
|
|
|
#[cfg(feature = "current-thread")]
|
|
pub mod current_thread;
|
|
|
|
#[cfg(feature = "threadpool")]
|
|
pub mod threadpool;
|
|
|
|
pub use crate::enter::{enter, exit, Enter, EnterError};
|
|
pub use crate::error::SpawnError;
|
|
pub use crate::executor::Executor;
|
|
pub use crate::global::{spawn, with_default, DefaultExecutor};
|
|
pub use crate::typed::TypedExecutor;
|