Tokio: meta: Roadmap to 1.0

Created on 29 Jul 2020 · 13Comments · Source: tokio-rs/tokio

We will be aiming to release Tokio 1.0 by the end of 2020. This issue is a high-level proposal of how to get there.

Impacted crates

The 1.0 release applies to the tokio and tokio-macros crates. The remaining crates, tokio-util and tokio-test will remain at 0.x versions.

Changes

At a high level, Tokio 1.0 will be fairly close to Tokio 0.2. Major differences are:

[x] Updated I/O traits (#2716, #2428).
[x] Remove mio from the public API (#2728).
[x] Update to mio 0.7 (#1190).
[x] Update to bytes 1.0 (#3058).
[x] Move remaining async fns to an intrusive waker style (#2779, #2927, #3028).
[x] Runtime and #[tokio::main] refinements (#2720).
[x] Tweak (or temporarily remove) DelayQueue (issue TBD).
[x] Misc API tweaks (#2928).

Open questions

There are still some questions that need to be finalized.

[x] Coordinating with the addition of Stream in std (#2870).
[x] Consider making JoinHandle cancel on drop (#1830).

Pause on adding new APIs

Focus should be put on work that impacts existing APIs, either by altering them or removing them. Once Tokio 1.0 is released, there will be limited flexibility for altering imperfect APIs. However, it is always possible to add new APIs. There may be cases in which a new API is high value and very straight forward or a reason that adding the API after 1.0 is difficult. In this case, we can explore adding the API before 1.0.

In other words, now is the time to voice complaints about any existing API.

Target release date

Previously, Q3 2020 was mentioned as the target release date. However, productivity this year has been lower than expected due to unforeseen global events. We are now going to target the end of 2020 as a release date.

Intermediate 0.x releases

There will be a Tokio 0.3 release. This release will contain at the very least:

New I/O traits.
Runtime tweaks.

There also will be an "0.x" release made as a 1.0 candidate. So, there will be a minimum of two more 0.x releases before 1.0.

1.0 LTS guarantees

Tokio 1.0 will come with LTS guarantees. The proposal is:

A minimum of 5 years of maintenance.
A minimum of 3 years before a hypothetical 2.0 release.

The goal of these guarantees is to provide stability to the ecosystem.

MSRV

Tokio 1.0 will need a well-defined "minimum supported Rust version" policy. My proposal is:

All 1.x Tokio releases will support at least a 6-month old Rust release.
The MSRV will only be increased on 1.x releases.

Versioning policy

Because Tokio is pre-1.0, features have been released in 0.2.x releases. This will no longer be the case after 1.0.

1._.x releases should only contain bug fixes. Besides this, these releases should not substantially change runtime behavior.
1.x releases may contain new functionality and larger internal implementation changes.

A-tokio C-proposal

Source

carllerche

🎉35 👍8

Most helpful comment

Tokio has been released: https://tokio.rs/blog/2020-12-tokio-1-0 🎉

Well done everyone ❤️

carllerche on 23 Dec 2020

🎉11

All 13 comments

I assume at 1.0, we shouldn't publicly expose any non-1.0 dependencies. Or, more generally, any exposed dependencies cannot be upgraded to breaking-changes versions without that upgrade being a breaking change in Tokio.

So, since bytes is publicly exposed (the Buf and BufMut) trait, we'd either need to:

Promote bytes to 1.0.
Extract Buf and BufMut to some other crate that can be released at 1.0.

seanmonstar on 30 Jul 2020

👍6

Extract Buf and BufMut to some other crate that _can_ be released at 1.0.

This seems like potentially the better option, since it allows us to continue versioning bytes more aggressively? It might also encourage more experimentation with other implementations of Buf/BufMut, which seems beneficial to the ecosystem.

hawkw on 30 Jul 2020

👍1

@seanmonstar @hawkw a third option is to "hide" Buf and BufMut from the Tokio public API for the initial 1.0 release. I added that to the original issue and will write up my thoughts on it.

carllerche on 30 Jul 2020

It's probably also worth being sure that tokio-compat makes it real easy to try out each of these releases. The amount of refactoring needed from now on should be very low, but if it's possible to make it a cinch to try out 0.3 and 0.4, we can get more testing before solidifying our unseen mistakes forever.

seanmonstar on 30 Jul 2020

👍2

Remove mio from the public API (issue TBD).

Do we have any idea of how far mio is from 1.0?

Another question, what is our general game plan for io_uring? Do we want to go the route of a separate crate so that we can 1.0 and deal with it later? Or will it be some internal refactor of the driver?

Runtime tweaks.

What does this entail?

Otherwise, this is +1, lets for sure break this up and spread the load.

LucioFranco on 30 Jul 2020

@LucioFranco Removing Mio from the public API isn't really based on Mio not being 1.0 but more that it exposes too much implentation detail IMO.

"Runtime tweaks" has a linked issue w/ details.

carllerche on 30 Jul 2020

👍2

re:

Tweak (or temporarily remove) DelayQueue (issue TBD).

Should we just put DelayQueue in util? IIRC, it doesn't depend on anything private that it _needs_ to be in tokio for (though I'd have to double check).

hawkw on 30 Jul 2020

DelayQueue is definitely not a top priority, so if we need to cut something, we definitely can move it to tokio-util initially.

carllerche on 31 Jul 2020

👍3

I believe that https://github.com/tokio-rs/tokio/issues/2777 should be handled in some way before release of tokio 1.0, even if that way is to remove tokio::time::{pause, resume, advance} entirely (it could be restored later). In the current state I consider this API harmful as it makes a programmer think it works when it doesn't really.

Consider the following example:

use tokio::task::JoinError;
use tokio::time::{self, Duration, Instant};

#[tokio::main]
async fn main() -> Result<(), JoinError> {
    time::pause();
    println!("{:?}", Instant::now());
    tokio::spawn(time::sleep(Duration::from_secs(10)));
    tokio::spawn(async { }).await?;
    println!("{:?}", Instant::now());
    Ok(())
}

This will advance the time by 10 seconds because of automatic time advancement, which I believe makes tokio::time::pause a broken API that cannot be used correctly with tasks. This actually did work correctly before merging in #2059, which is a breaking change that went unnoticed due to nobody using tokio::time::pause.

I think that when a time is paused sleeping should deadlock until the time is manually advanced.