Comments (14)
Re: Async / await, I strongly feel that the documentation should be built off stable Rust by default. Examples can have both stable & async / await versions and docs can reference / explain async / await & link to external resources on it, but the flow should not be based on it until it hits stable.
from tokio.
Thanks @0freeman00! I'm working actively on a small book for async programming in Rust, and have already taken into account many of the suggestions you present. Talking specifically about the C10K problem (or similar), though, in an interesting twist; I'll give it some thought.
from tokio.
Here is my current (rough) outline for docs:
-
"Hello world" tutorial
- Echo server using tokio-io helpers
-
Foundational knowledge
- Execution model / non-blocking / event-driven
- Reactor
- Tasks (basics)
- Async type
- Using a socket
-
AsyncRead / AsyncWrite (using a socket)
- Reading / writing in more depth
bytes
crate for buffers- Echo server reading / writing to the socket
- Composing / decorating
- TLS
- Shutdown (drop can't block).
- Reading / writing in more depth
-
Futures
- What is a future
- Combinators
- Functional / passing state
- How futures work on top of tasks
- Callbacks do not fire immediately!!! unlike other libs
- Architecting w/ futures
- Returning futures
- Timeouts
- Cancellation
-
Transports (Sink + Stream)
- Framing concepts
- Implement transport manually
- Using transport
- Split, forward
- tokio-io codec module
-
More transports
- Handshake
- Ping / pong
- Timeouts
- Reconnect
-
Organizing an application
- Tasks to manage resources / message passing (mpsc)
- Chat server
- File operations / blocking ops / CPU bound
-
Advanced topics
- Back pressure
- Routing / broadcast
-
Cookbook / FAQ?
- Shutting down the reactor
- ???
from tokio.
It should also be plausible to work on the docs incrementally vs. a long lived branch.
from tokio.
Take this with a grain of salt since I haven't had an opportunity to use tokio (or any other Rust code) for any serious projects, but I did experience some confusion back when I read the tokio docs "cover to cover". I believe that was primarily because of the counterintuitiveness of the poll method/the Future trait, but also partially because a large portion of it simply wasn't useful information for writing high-level applications. Some concrete suggestions:
-
If the actual Future trait/poll() signature is not something the average tokio user should need to understand (which is the impression I'm getting here), we should make it very obvious when they get to that part of the documentation that this is optional low-level stuff that is not required. The impression the current docs gave me is that understanding poll() is technically not required, but in practice you're gonna have to know it to be productive with any non-toy code, much the same way many niggling C++ details are technically not need-to-know but still get thorough coverage in Effective C++.
-
When we do get to the part that explains poll(), do not start with the signature, or with "low-level" code that talks to futures directly. Such code feels a lot like the definition of a monad to me, i.e. it's so abstract and generic that it's likely to appear totally meaningless unless you're already familiar with it (I feel obligated to link http://thecodelesscode.com/case/143 at this point). Instead, start with a conceptual execution trace of some simple but high-level async I/O program. Like, these methods return a main future that's the combination of futures A, B, C which gets compiled into a state machine like enum { A(...), }, then calling core.run() calls .poll() on the main future, which calls poll() on A, then A says it's ready so we actually call the callback for it, then the core calls .poll() again and this time since A already finished it calls poll() on B which says it's not ready and registers the core to wake up on some OS event rather than busy waiting...and so on. At least, that's how I think a typical tokio program operates at runtime based on the current docs, but I'd really like to know for sure if I've gotten that right or not. Then we reveal the Future trait/poll() method after we've mentioned all the key things that may or may not actually happen at runtime via that trait/method.
-
There should probably be very brief but dedicated sections somewhere that specifically address the handful of other major languages with strong async I/O conventions. Otherwise newcomers will have to waste a lot of cognitive energy on questions like "Is this conceptually the same as X from my language or is it a totally separate thing I need to pay close attention to?" For example, Javascript developers should get told that "reactor::Core is a single-threaded event loop, so when you're using futures (or
#[async]
/await!()
) driven by reactor::Core the semantics are very similar to Javascript with A+ promises (or ES7 async/await keywords)" (that is correct, right?) while C# developers and Python developers and so on get told something else.
Everything else I can think of (e.g., more examples!) is already in the OP post.
from tokio.
I know you have already noted this above, but yes, could you please strive towards more real world examples?
Such as:
- An http server that also makes http requests (using a single core reactor).
- How do I add a periodic timer task to the example above?
from tokio.
Some notes from a chat earlier today:
We'll probably want an FAQ or otherwise style page about maintaining state with futures. Right now most futures are 'static
but idiomatic methods in Rust already are &self
, and this causes quite the tension when you say, want to use &self
inside of an and_then
closure.
Today you need to restort to using self
and threading ownership or to use Rc
or some other reference-counted sharing solution likely. We should document this explicitly and explore the various tradeoffs as well.
from tokio.
something I just stumbled upon, it would be nice to have an example where you pass down a &msg
down to a spawn_fn
- pretty desirable when you're parsing binary data from things like kafka
from tokio.
I struggled a lot while learning futures/tokio
, I will note down reasons, this might help you guys to give some perspective from a normal newcomer.
-
Hello, world
. But, simple, describe how to get data fromstream
clearly, and how to send data throughsink
clearly, instead of usingCopy
or some abstract method. -
How to work with
raw byte streams
instead of using abstractframed
on socket and then useencoder
,decoder
. Why this? because, if I am coming from another language, I will be familiar with byte streams, so it will be a little bit confusing for me to understand encoder and decoder at first, no doubt they are really cool features. -
Is single thread enough for
C10K
problem? This is I get allot in my mind, will single threaded loop will be able to handle such a big connection pool, (Why? because I don't know that many lower level details and it has always been taught to me that multithreaded applications are always good and all, so, just clarifying on that will relax new users on how Tokio is really cool for building applications.) -
Simple Example on how to scale Tokio in terms of big applications, like how to
architect
code and all the modules. What should be a standard way of handling functions and returning values.- Should I return `boxed futures'?
- Should I return `one of the combinators'?
- Should I return direct values and then encapsulate them into combinator chain?
-
If possible, small example on how to create multiple reactors on different threads and then provide work to those threads from other threads.
-
Simple
standard
to buildclient
applications. -
Simple
standard
to buildserver
applications.
point 6, 7 are not in terms of giving traits
and implement them, just with example if you guys can demonstrate that, if you were to build Tokio servers, this is how you would build. This may boost a lot of confidence in newcomers.
It's not much, but I hope my input help grow Tokio
.
from tokio.
@aturon waiting for the book to come out then. :)
from tokio.
Just saw a great source of inspiration for "advanced user"/"reference" documentation passing by in TWIR: https://cafbit.com/post/tokio_internals/ .
from tokio.
@aturon do you have any updates on the book?
from tokio.
There has been miscommunication and @aturon has not been planning on writing this book as documentation, so this is still an open issue.
from tokio.
An extremely early version is up here, but it's based on a bunch of changes to the relevant crates that have since seen further iteration. I've been holding off further work on it until the dust settles a bit on the design.
from tokio.
Related Issues (20)
- Proposed list of Metrics to Stabilize HOT 5
- Ability to split a JoinSet into spawn and join halves HOT 1
- runtime metrics blocking threads miscount
- Add File::create_new convenience c'tor HOT 1
- Tonic server uses encapsulation HOT 2
- Missing methods `join_set::Builder::spawn_blocking()` and `join_set::Builder::spawn_blocking_on()` HOT 2
- Add a `CancellationToken` method for running a future until completion or cancellation HOT 1
- CI failure on windows HOT 3
- Vectored IO for `write_all_buf` HOT 1
- Doc bug in `Command::stdin`? HOT 1
- Include relevant values in ReadBuf.put_slice() panic message HOT 1
- File IO hangs after timeout / cancellation HOT 2
- Use `[lints.rust.unexpected_cfgs.check-cfg]` instead of hacky check-cfg workaround HOT 2
- Helper struct/wrapper for a stream of named pipe connections HOT 7
- tokio::sync::mpsc::bounded::Receiver<T>::is_empty() returns false when recv().await blocks HOT 3
- Feature tokio::sync::mpsc::Receiver::wait_close(&self) HOT 11
- Panic at linked_list.rs - reborn HOT 5
- Every 32 messages `is_empty()` on `Receiver` and `UnboundedReceiver` returns `false` even though len == 0 HOT 1
- LengthDelimitedCodec misses that last N bytes of the frame with num_skip(0) HOT 1
- Segment fault at `poll_future` HOT 8
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from tokio.