Codebase documentation

[ghost]

copy-pasting some suggestions from @benmkw:

We still found it pretty challenging to dig though it. We found our way to the ThreadLokalExecutor and the ioEvent and the WorkStealingExecutor but the Reactor really puzzled us. We also did not really found how the waker is used. Like there are these three ways https://boats.gitlab.io/blog/post/wakers-i/ a waker can be implemented and the flag kind of seemed like it was the first of the three (which supposedly gets set by the OS), but then sending [1] onto the socket did not really make sense to us, like why is the executor writing to my own socket? Or no this has to be a signal that the OS sends to signal the executor that the future is ready? But why is it a socket then? Why is the writer a normal socket but the reader an Async<Socket>? These were questions that we took into our minds to resolve in the future (after polling some more on them I guess ;) (Like when I’m talking about the OS im thinking of epoll/kqueue)

I think what would maybe help me is a kind of walk thought of execution from submitting a future to how its suspended, how the waker gets registered in the OS/ how the OS calls back into the executor to signal the future is ready to be polled again….

[z64]

To offer my own two cents, in understanding async systems (or any system with sufficient moving parts), having a visual aid component is immensely helpful. Walls of text and documentation can be intimidating.

I think such a reference graph of the runtime and future lifecycle would be a great way to both document the concepts smol presents, and to further lower the barrier to those new to async primitives. To cite another resource, diagrams such as the ones listed https://cheats.rs/#basic-types have been a fantastic reference.

I would love to help with this, but I'm still new to this space myself in Rust. I leave the suggestion here, maybe someone else will like the idea :)

[hwchen]

I highly agree that a visual component is very important. As I was learning the basics for Rust async, I had to draw out diagrams in order to make sense of the life cycle.

[llebout]

Better yet a real time visualization of the runtime's behavior given smol runtime can write somewhere detailed diagnostic information when asked, that would also be a powerful performance optimization and debugging tool.