[ruby-core:101677] [Ruby master Bug#17389] New docs for non-blocking Fibers and scheduler

Issue #17389 has been updated by hakusaro (Lucas Nicodemus).


I reckon that Samuel is just wrapped up in some other things. Async is the gem carrying the "example torch," and he's been putting in [work on native scheduler use](https://github.com/socketry/async/commit/e403cc244482baf7adf17414a15b95aa8a99036f). He's also done more than a few conference talks at Ruby Kaigi and published several reports on Ruby concurrency. I'd say that while the Ruby text documentaton isn't quite on par with the rest of the material, the Fiber changes are far from undocumented.

See:
* [Fibers are the right solution (talk)](https://rubykaigi.org/2019/presentations/ioquatix.html) and [text version](https://www.codeotaku.com/journal/2018-11/fibers-are-the-right-solution/index).
* [Progress report 1](https://www.codeotaku.com/journal/2019-12/ruby-concurrency-progress-report/index) and [progress report 2](https://www.codeotaku.com/journal/2020-01/ruby-concurrency-progress-report/index) on the concurrency project for the 2019 Ruby Association Grant.
* [Asynchronous ruby](https://www.codeotaku.com/journal/2018-06/asynchronous-ruby/index)

In general, this is really hard CS stuff for the uninitiated (at least, it is/was to me). I completely sympathize with you, but I feel like there's just a lot of dense material about this required to understand it.

I think it'd be worth explaining components of your PR and where they line up with the latest changes (particularly, why/what the end goal is). Some kind of comprehensive scheduling/concurrency Ruby documentation, between Fibers + Ractors, is probably necessary in the long run. But the people who are going to be working with these tools right out the gate are also like to be people who are already experienced in this field(?).

Given all this, it may not be super urgent -- but I tend to agree that anything that helps understanding is beneficial.

----------------------------------------
Bug #17389: New docs for non-blocking Fibers and scheduler 
https://bugs.ruby-lang.org/issues/17389#change-89499

* Author: zverok (Victor Shepelev)
* Status: Open
* Priority: Normal
* Backport: 2.5: UNKNOWN, 2.6: UNKNOWN, 2.7: UNKNOWN
----------------------------------------
**GitHub PR: https://github.com/ruby/ruby/pull/3891**

Copying from its description:

I propose new documentation approach for new features in Ruby 3.0: non-blocking Fiber and the scheduler.

Right now, the documentation is in a confusing state. First, the `doc/scheduler.md` is even not rendered correclty: https://docs.ruby-lang.org/en/master/doc/scheduler_md.html (relatively easy to fix: wrong markdown markup for the code-blocks), and Fiber class itself has no mention for new concepts, and no docs for new methods: https://docs.ruby-lang.org/en/master/Fiber.html#method-c-schedule.

But on the bigger level, the documentation is quite hard to follow unless you are already fully in context of asynchronous loops and schedulers.

I am trying to fix it by:

* adding to the `Fiber` class necessary docs, both high-level overview and particular method details
* redocumenting the expected scheduler interface via "imaginary" `Fiber::SchedulerInterface` class: it is present only in docs to leverage RDoc's method-by-method documentation, be able to link to them separately and so on

Test rendering of the docs on my personal site:

* [Fiber](https://zverok.github.io/ruby-rdoc/Fiber.html)
* [Fiber::SchedulerInterface](https://zverok.github.io/ruby-rdoc/Fiber/SchedulerInterface.html)

I have not yet in this PR removed doc/scheduler.md, but I suggest to, as it is completely superseded by new docs.

I'd be really grateful if @ioquatix will find some time to review this initiative in the upcoming days.



-- 
https://bugs.ruby-lang.org/

Unsubscribe: <mailto:[e-mail]?subject=unsubscribe>
<http://lists.ruby-lang.org/cgi-bin/mailman/options/ruby-core>