compat: add a compat runtime

[hawkw]

Motivation

The futures crate's compat module 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:

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:

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

[hawkw]

AFAICT the FreeBSD CI failures are spurious and appear to be occuring on master as well (https://github.com/tokio-rs/tokio/runs/260482009)

[LucioFranco]

This looks great, nothing blocking on my end. I'd really like to ship this ASAP and get some sort of blog post up about how to use it. Thoughts @carllerche?

[hawkw]

@LucioFranco

I'd really like to ship this ASAP and get some sort of blog post up about how to use it.

I'm definitely planning on doing a blog post! There are a couple things missing from the compat crate (CurrentThread compat runtime, AsyncRead/AsyncWrite adapters...) that I'd like to get in before we release it, though.

[LucioFranco]

@hawkw those sound like a good plan to me

[hawkw]

I don't think it's possible for tokio 0.1's blocking to work on the compat runtime. This is because (unlike the timer, executor, and reactor), there's no way to override the global blocking functionality. I think the best solution is for tokio-compat to provide its own blocking for 0.1 futures.

Unless there are any objections, I think we might want to do that in a subsequent PR. (cc @carllerche)

[carllerche]

@hawkw ah, I see. That would mean stuff like tokio-fs doesn't work...

I have another thought... hear me out, and feel free to shoot it down. Have we considered updating tokio 0.1 to include a tokio-next-compat feature flag? If it were enabled, it would swap the impl details w/ 0.2's impl. I don't know if this would make things easier or harder...

[carllerche]

We can also add the necessary hooks to 0.1 to support blocking compat.

[hawkw]

Yeah, I think in order to get the ideal compat story for blocking, we'll need to make changes to the 0.1 runtime as well. I'm open to doing that, but I think it would be better to roll forward with these changes, if possible, and then move on to getting 0.1 blocking to work.

[carllerche]

👍 I'll leave the decisions to you & @LucioFranco. I'm just throwing out ideas.

[LucioFranco]

Things left are to fix block_on futures not getting a timer.

I think @taiki-e is right we need to add tokio back to the workspace.

Otherwise, I am happy with this change, the blocking stuff is somewhat not as important imo. Most users probably don't use that as much? For my use case I can easily swap out our blocking code.

[hawkw]

Things left are to fix block_on futures not getting a timer.

Yup, looks like the tokio 0.1 timer was not being set in calls to Runtime::block_on (with the thread pool runtime), thanks for catching that! I've added tests for this in 8505ee0 and cd2d646, and fixed it in 477a417!

I think @taiki-e is right we need to add tokio back to the workspace.

Fixed that one too, my bad!

Otherwise, I am happy with this change, the blocking stuff is somewhat not as important imo. Most users probably don't use that as much? For my use case I can easily swap out our blocking code.

I've added a note documenting that the compat runtime doesn't currently support legacy blocking. I think adding support for blocking is best done in a follow-up.

[LucioFranco]

Lets get this merged, I will contiue to look for issues in trying to convert my codebase over.