Simpler future lifecycle

[alecandido]

I've just finished reading the book, and while not actively maintained, and still containing many TODOs, I believe to be still a valuable reference.
Moreover, the idea of the book is something that is required to back the effort of async Rust, since there exists an "async Rust" regardless of the individual runtimes.

As reported in #101 there are actually many levels in the book, ranging from basic usage, to more advanced usage (like streams and patterns to face current limitations), and eventually to a sketch of internals.
Even though, I agree on the idea of a user guide, I really appreciated the part (chapter 2) explaining the ideas behind futures, but it is hard to have an actual grasp without reading over and over, trying to figure out the overall workflow from the many pieces and different concepts.

It would be helpful to have something like a global diagram of a future lifecycle. I drew a very sketchy one for myself, with no clear encoding for different entities and so on, but is just to have an idea (and maybe I have a wrong one...).

It doesn't even need to be something graphical, but just to outline the whole thing with few words, just to give a reference frame for everything else.
Maybe it is a personal limitation, but it is very helpful to explore concepts hierarchically. And if I have to build the hierarchy myself, from the individual pieces, this makes everything more complicated.

[alecandido]

I'd be even happy to volunteer to do something myself. But I've just finished reading the book, so this tells something about my current expertise...

[eholk]

@alecandido - I'd say go for it if you want to. I find often people who have just learned something are in a really good position to explain that to newcomers because they can still remember what they found confusing as a newcomer :)

I like your diagram as a starting point. I'd love to see it with some text explaining what's happening at each step. One thing I like about it is that it shows the difference between the executor and the reactor. I feel like I only just recently understood what a reactor is (for a while I thought it was basically synonymous with the executor), so a diagram like that with some explanation would have helped me learn this sooner.