mirror of
https://github.com/tokio-rs/tokio.git
synced 2026-09-06 00:00:10 +02:00
Eliza Weisman
e699d46534
## Motivation The `futures` crate's [`compat` module][futures-compat] provides interoperability between `futures` 0.1 and `std::future` _future types_ (e.g. implementing `std::future::Future` for a type that implements the `futures` 0.1 `Future` trait). However, this on its own is insufficient to run code written against `tokio` 0.1 on a `tokio` 0.2 runtime, if that code also relies on `tokio`'s runtime services. If legacy tasks are executed that rely on `tokio::timer`, perform IO using `tokio`'s reactor, or call `tokio::spawn`, those API calls will fail unless there is also a runtime compatibility layer. ## Solution As proposed in #1549, this branch introduces a new `tokio-compat` crate, with implementations of the thread pool and current-thread runtimes that are capable of running both tokio 0.1 and tokio 0.2 tasks. The compat runtime creates a background thread that runs a `tokio` 0.1 timer and reactor, and sets itself as the `tokio` 0.1 executor as well as the default 0.2 executor. This allows 0.1 futures that use 0.1 timer, reactor, and executor APIs may run alongside `std::future` tasks on the 0.2 runtime. ### Examples Spawning both `tokio` 0.1 and `tokio` 0.2 futures: ```rust use futures_01::future::lazy; tokio_compat::run(lazy(|| { // spawn a `futures` 0.1 future using the `spawn` function from the // `tokio` 0.1 crate: tokio_01::spawn(lazy(|| { println!("hello from tokio 0.1!"); Ok(()) })); // spawn an `async` block future on the same runtime using `tokio` // 0.2's `spawn`: tokio_02::spawn(async { println!("hello from tokio 0.2!"); }); Ok(()) })) ``` Futures on the compat runtime can use `timer` APIs from both 0.1 and 0.2 versions of `tokio`: ```rust use std::time::{Duration, Instant}; use futures_01::future::lazy; use tokio_compat::prelude::*; tokio_compat::run_03(async { // Wait for a `tokio` 0.1 `Delay`... let when = Instant::now() + Duration::from_millis(10); tokio_01::timer::Delay::new(when) // convert the delay future into a `std::future` that we can `await`. .compat() .await .expect("tokio 0.1 timer should work!"); println!("10 ms have elapsed"); // Wait for a `tokio` 0.2 `Delay`... let when = Instant::now() + Duration::from_millis(20); tokio_02::timer::delay(when).await; println!("20 ms have elapsed"); }); ``` ## Future Work This is just an initial implementation of a `tokio-compat` crate; there are more compatibility layers we'll want to provide before that crate is complete. For example, we should also provide compatibility between `tokio` 0.2's `AsyncRead` and `AsyncWrite` traits and the `futures` 0.1 and `futures` 0.3 versions of those traits. In #1549, @carllerche also suggests that the `compat` crate provide reimplementations of APIs that were removed from `tokio` 0.2 proper, such as the `tcp::Incoming` future. Additionally, there is likely extra work required to get the `tokio-threadpool` 0.1 `blocking` APIs to work on the compat runtime. This will be addressed in a follow-up PR. Fixes: #1605 Fixes: #1552 Refs: #1549 [futures-compat]: https://rust-lang-nursery.github.io/futures-api-docs/0.3.0-alpha.19/futures/compat/index.html
61 lines
1.8 KiB
TOML
61 lines
1.8 KiB
TOML
[package]
|
|
name = "tokio-compat"
|
|
# When releasing to crates.io:
|
|
# - Remove path dependencies
|
|
# - Update html_root_url.
|
|
# - Update doc url
|
|
# - Cargo.toml
|
|
# - README.md
|
|
# - Update CHANGELOG.md.
|
|
# - Create "v0.1.x" git tag.
|
|
version = "0.1.0-alpha.1"
|
|
edition = "2018"
|
|
authors = ["Tokio Contributors <[email protected]>"]
|
|
license = "MIT"
|
|
readme = "README.md"
|
|
documentation = "https://docs.rs/tokio-compat/0.1.0-alpha.1/tokio-compat/"
|
|
repository = "https://github.com/tokio-rs/tokio"
|
|
homepage = "https://tokio.rs"
|
|
description = """
|
|
Compatibility between `tokio` 0.2 and legacy versions.
|
|
"""
|
|
categories = ["asynchronous", "network-programming"]
|
|
keywords = ["io", "async", "non-blocking", "futures"]
|
|
|
|
|
|
[features]
|
|
default = ["rt-full", "sink"]
|
|
# enables the compat runtimes.
|
|
rt-current-thread = [
|
|
"tokio-timer-02",
|
|
"tokio-reactor-01",
|
|
"tokio-executor-01",
|
|
"tokio-02/rt-current-thread",
|
|
"tokio-02/timer",
|
|
"tokio-02/sync",
|
|
"tokio-02/net-driver",
|
|
]
|
|
rt-full = [
|
|
"tracing-core",
|
|
"num_cpus",
|
|
"tokio-02/rt-full",
|
|
"rt-current-thread",
|
|
]
|
|
sink = ["futures-util/sink"]
|
|
|
|
[dependencies]
|
|
futures-01 = { package = "futures", version = "0.1" }
|
|
futures-03-core = { package = "futures-core-preview", version = "0.3.0-alpha.19" }
|
|
futures-util = { package = "futures-util-preview", version = "0.3.0-alpha.19", default-features = false, features = ["compat"] }
|
|
tokio-02 = { package = "tokio", path = "../tokio", default_features = false }
|
|
|
|
# runtime-only
|
|
tokio-timer-02 = { package = "tokio-timer", version = "0.2", optional = true}
|
|
tokio-reactor-01 = { package = "tokio-reactor", version = "0.1", optional = true }
|
|
tokio-executor-01 = { package = "tokio-executor", version = "0.1", optional = true }
|
|
num_cpus = { version = "1", optional = true }
|
|
tracing-core = { version = "0.1", optional = true }
|
|
|
|
[dev-dependencies]
|
|
tokio-01 = { package = "tokio", version = "0.1" }
|