👋🏽 Welcome

Welcome to the Vision² website!

Leads: @nikomatsakis and Shane Miller

What is this?

The Vision² is a "vision doc for vision docs". Vision docs are an experimental way to help build and establish consensus for open source projects -- though really they could work for any distributed project.

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

🔮 The vision

What is this

This section lays out a general vision and set of goals for Async I/O in Rust. This document is being written in January of 2021. The core pieces of async-await are stable, but there remains a lot of work for it to feel like a "first class" feature of Rust.

This section describes three things:

• The design tenets, or principles, that we are using to drive our work on Async I/O in Rust;
• Descriptions of how writing Async I/O code in Rust feels today;
• Descriptions of how we think writing Async I/O code in Rust should feel eventually.

Status and schedule

This document is currently being formed. We expect to publish the first version on March 31. Once that version is published, we intend to revisit the document once per quarter to keep it up to date.

Think big -- too big, if you have to

You'll notice that the ideas in this document are maximalist and ambitious. They stake out an opinionated position on how the ergonomics of Async I/O should feel. This position may not, in truth, be attainable, and for sure there will be changes along the way. Sometimes the realities of how computers actually work may prevent us from doing all that we'd like to. That's ok. This is a dream and a goal.

The vision drives the work

The vision is not just idle speculation. It is the central document that we use to organize ourselves. When we think about our roadmap for any given year, it is always with the aim of moving us closer to the vision we lay out here.

This is a group effort

As the leads of the Async Foundation group, Niko and Tyler are driving and organizing this document. But writing it and shaping it is a group effort. If you think there is a part of the async experience that is not reflected here, we want to hear from you! Check out the How to vision doc for more details on how to contribute.

✏️ Design tenets for vision docs

1. Describe the problems you see honestly.
2. Establish the long-term vision first.
3. Customed focused.

🙋‍♀️ Cast of characters

Alan: the startup guy trying to stand-up a web stack quickly

Alan is a "full stack" JavaScript developer. He's bounced around from startup to startup building things both in node.js and doing front-end work. Alan was recently hired at fido.io, a pioneering dog-food delivery business that uses a combination of deep learning and IoT to select the optimum dog food for your pet's health. Fido has chosen to build their networking stack in Rust. They were already using Rust for their deep learning code and they wanted to keep to a single language. For the time being, their needs are relatively simple. They want to stand up a server that serves up pages and connects to various back-end and cloud services.

Grace: the principal engineer hacking on T4, a new storage service

Grace works on T4, a cloud storage service that is used in a lot of the world's largest web properties. She is a principal engineer who has been building high-performance networking systems in C for a number of years. T4 recently switched to Rust for the new component they are building. They are hoping it will help them avoid security vulnerabilities without compromising on performance. Huma has been using Rust for a while now and she's starting to feel fairly comfortable with it. The new T4 component is getting ready to go into production soon; she's hoping they'll be able to meet their performance goals.

Niklaus: the developer building generic Rust libraries and frameworks

Niklaus is an open source developer building various generic libraries and frameworks. He is hoping to create successful open source projects that are widely used in all sorts of applications and which have a lively community around them. Niklaus is currently working on the following projects:

• SLOW, a Rust implementation of a fancy new communications protocol that is gaining in popularity.
• Hyperactive, a Rust web framework meant to make it easy to standup a web server and start serving requests. Probably exactly what Alan wants!

Barbara: embedded developer doing networking

Barbara is building a sensor grid system using Rust. The sensors communicate wirelessly to relay their results, and Barbara is responsible for the networking component. These sensors are relatively simple devices with limited resources, so she is coding in a #[no_std] environment and is very careful about things like allocation.

😱 Status quo stories

What is this

The "status quo" stores are here to state our "theory of the case". That is, they present (and prove) our hypotheses as to what the various challenges are for users of Async I/O in Rust. These hypotheses are presented in narrative form, by telling the story of a specific character as they try (and typically fail in dramatic fashion) to achieve their goals.

Based on a true story

These stories are not made up. They are always based on real-life experiences of actual people. Each story contains a "Frequently Asked Questions" section, and that will include notes the sources used to create the story. In some cases, it may link to notes or summaries in the conversations section, though that is not required. The "Frequently Asked Questions" section also contains a summary of what the "morals" of the story are (i.e., what are the key takeaways), along with answers to questions that people have raised along the way.

The stories provide data we use to prioritize, not a prioritization itself

Just because a user story is represented here doesn't mean we're going to be able to fix it right now. Some of these user stories will indicate more severe problems than others. As we consider the stories, we'll select some subset to try and address; that choice is reflected in the roadmap.

Help wanted!

This is not a static document! There are lots of ways you can help to expand it! Take a look at the How to Vision Doc for more details.

Alan has trouble getting started

Outline:

• At first, Alan can't find docs about how to do async stuff
• Alan finds learning Rust challenging enough, learning async at the same time is even harder (cite)
• Alan has trouble picking a runtime, it's kind of overwhelming -- what if he picks the wrong one?
• Alan is confused because adding async/await doesn't seem to be getting him concurrency
• Alan tries to connect to a database but the docs aren't very comprehensive
• Alan doesn't like the web framework he's using, but the one he likes requires a different runtime, and switching between them is a real pain
• Alan quits and becomes a Bob Ross groupy

Alan finds the experience of writing async code is a lot more painful than sync code

Outline:

• Alan gets inscrutable backtraces
• Alan tries to write a recursive function and gets a weird error
• Alan gets confusing diagnostics because of incompatible versions of the futures crate
• Alan gets a confusing compiler error about a variable being live across an await point that doesn’t seem to be live
• Bobs gets an error message that exceeds the memory limits in his terminal program, crashes his computer, and forces him to reboot

Grace tries to write a stream and pin breaks her mind

Outline:

• We need to make this better -- pick some specific problem Grace was trying to solve
• She winds up implementing a stream and has to use pin and it's hard
• we don’t currently provide any language support for doing this
• so you have to work with pin
• it is very confusing and nobody really understands it
• she doesn’t get parallel like she wanted
• she switches to a stream of futures
• it kind of works but it’s a pain to maintain and she doesn’t like fixing bugs in that code
  • she transfers to another team and somebody else deletes the file, starts over, and repeats her experience

Grace deploys her service and hits obstacles

Outline:

• She gets stack traces from her production users and they are 10s of KB and she can’t make heads or tails of them
  • Back in the olden days of C# they were able to fix bugs more often than not based just on the stack trace, but now they can’t even figure out what code it is talking about
• Tasks are stuck
• Performance is good but one customer has 10x latency —- why?
• She wants to use tracing but it’s not stable

Grace wants to use io-uring

Outline:

• there are existing crates, which to use?
  • ringbahn
  • glommio
  • rio -- "but users should beware that use-after-free bugs are still possible without unsafe when using rio."
  • tokio-rs/io-uring
  • quininer/ritsu
  • ...and probably more
• the AsyncRead trait is not a perfect fit

Niklaus goes to write SLOW but it’s annoying

Outline:

• async fns in traits maybe come into this story?
• to make it work across many runtimes he has to juggle a lot of feature gates
• the AsyncRead trait is in the futures crate, but he can’t tell how stable that crate is — can he rely on it in his public interface? Can he call that 1.0?
  • futures crate makes a breaking change, is he screwed?
• he has to copy and paste a bunch of random utilities that everyone seems to use but which aren’t defined in a shared crate that has a stable version
  • xxx some of them are in futures??
• maybe he wants to target WASM?

Niklaus builds his web framework

Outline:

• He is frustrated by lack of async trait support
• He uses the async-trait procedural macro but it feels weird to have that in a public, stable API.
• As with the SLOW library, he would to make it independent of a specific runtime, but that's very difficult

Barbara tries to use the embedded runtime

Outline:

• She doesn’t want to use allocation and dyn Trait but async fns in traits are not available on stable rust
• She is not wanting to use nightly

✨ Shiny future: Where we want to get to

The "shiny future" is here to tell you what we are trying to build over the next 2-3 years. That is, it presents our "best guess" as to what will look like a few years from now. When describing specific features, it also embeds links to design notes that describe the constraints and general plans around that feature.

Predicting the future is a tricky business! Many of the things described in the "shiny future" doc have a lot of uncertainty. We fully expect that the designs and narratives described in this document will change as we work towards realizing them. When there are areas of particular uncertainty, we use the Frequently Asked Questions and the design docs to call them out.

Help wanted. This is not a static document! There are lots of ways you can help to expand it! Take a look at the How to Vision Doc for more details.

Alan has a blast standing up a web server

Outline:

...

Grace deploys her service and is able to fix problems

Outline:

• Grace launches service
• Hits a stalled task, debugs the problem
• Customers complain about poor performance, she tracks it down

Grace discovers the joy of generators

Outline:

• Grace uses generators and the code writes itself. It's ALMOST TOO EASY.

📅 The roadmap: what we're doing in 2021

This page describes the current plans for 2021. It is updated on a monthly basis.

Key

Roadmap items

❓ How to vision doc

This page describes the process for contributing to the vision doc.

Who owns this document?

This document is owned and maintained by the leads of the Async Foundations Working Group. They decide what content to accept or reject. This decision is made in consultation with the Rust teams that will be making the ultimate decisions. For example, if a design doc or part of the shiny future is describing a new language feature, the leads ought to discuss that with the language design team, since that team will ultimately have to approve the RFCs for its design.

How can I finish or add a section to the document?

If you'd like to volunteer to finish a section in the document, ping nikomatsakis and tmandry on Zulip, either in privmsg or the #wg-async-foundations stream.

If you think you have a new section you'd like to add, write up a short description or general outline and float it on #wg-async-foundations. Again, please ping nikomatsakis and tmandry.

Assuming you get positive feedback, you can open a PR. The PR should add one or more of the following things:

• A new section in the status quo document, or edits to an existing section
  • This may be accompanied by new evidence, though it doesn't have to be.
• A new section in the shiny future document, or edits to an existing section
  • This may be accompanied by new design docs, or edits to existing ones.
  • It doesn't have to be, but the PR discussion process may lead to requests to write design docs to help people imagine how this future could come about.
• New entries in the roadmap, for work you propose to do.
  • This may be accompanied by new design docs, or edits to existing ones.

Editing the narratives

The narratives in the vision doc are there to establish the state of how things are (the "status quo"), and the ultimate goals we are working towards (the "shiny future"). The goals in the shiny future are not necessarily meant to be achievable in a short time frame. Think about how you would like things to look 3-4 years down the road -- that is the "shiny future" we are describing.

Each section have very different characteristics. Here is a summary:

• Status quo narrative
  • establishes: problem framing
  • identifies: root problems
  • provides: supporting evidence for your theses
  • links to: evidence, if you want to provide it
• Shiny future narrative
  • establishes: north star
  • identifies: key elements of the solution
  • provides: a detailed description of how things should work for Rust's users down the road
  • links to: design notes

The "Frequently Asked Questions" section

The FAQ section is there to elaborate on the narrative and to answer common questions that people have when reading it. Assembling the FAQ always begins with a few required questions. After that, you can add whatever questions come to mind -- but usually the FAQ is populated by literally recording your answers to the questions that people ask you.

Required and suggested FAQs

The required FAQs vary by depending on what kind of section it is.

• Status quo
  • What are the morals of the story?
  • Are you just making this stuff up?
  • In addition to the above, add FAQs
• Shiny future
  • What is NAME most excited about and why?
  • What is NAME most disappointed with?
  • What key things did the Rust org do to make this happen?
  • What things did the other groups do to make this happen?
• Characters
  • Which of the async tenets would NAME put first and which would they put last? Why?
• Design docs
  • What assumptions are you using as the basis for this design?
  • Why not do ALTERNATIVE-X? (For each compelling alternative)
  • What design decisions cannot easily be reversed?

The roadmap

The roadmap describes the work we plan to do over the next year.

🔬 Design documents

The design documents (or "design docs", more commonly) describe potential designs. These docs vary greatly in terms of their readiness to be implemented:

• Early on, they describe a vague idea for a future. Often this takes the shape of capturing constraints on the solution, rather than the solution itself.
• When a feature is getting ready to ship, they can evolve into a full blown RFC, with links to tracking issues or other notes.

Early stage design docs

In the early stages, design docs are meant to capture interesting bits of "async design space". They are often updated to capture the results of a fruitful conversation or thread which uncovered contraints or challenges in solving a particular problem. They will capture a combination of the following:

• use cases;
• interesting aspects to the design;
• alternatives;
• interactions with other features.

Late stage design docs

As a design progresses, the doc should get more and more complete, until it becomes something akin to an RFC. (Often, at that point, we will expand the design document into a directory, adding an actual RFC draft and other contents; those things can live in this repo or elsewhere, depending.) Once we decide to put a design doc onto the roadmap, it will also contain links to tracking issues or other places to track the status.

💬 Conversations

This section contains notes and summaries from conversations that we have had with people are using Rust and async and describing their experiences. These conversations and links are used as "evidence" when building the "status quo" section.

Not exhaustive nor mandatory

This section is not meant to be an "exhaustive list" of all sources. That would be impossible. Many conversations are short, not recorded, and hard to summaize. Others are subject to NDA. We certainly don't require that all claims in the status quo section are backed by evidence found here. Still, it's useful to have a place to dump notes and things for future reference.