Executor_pool docs

[SGrondin]

Changes to the README:

• Replaced a few "5.0" with "5.1" since Eio now requires OCaml 5.1
• Moved the Domainslib and kcas sections to their own files in doc/
• Rewrote the Multicore Support section to include, in order:
  • an overview of the tools available
  • a comparison between Executor_pool and Domain_manager.run. Assumption: expert users will know when they need to directly create threads, no need to explain the rationale to them.
  • docs and example for Executor_pool
  • docs and example for Domain_manager.run
  • a basic "Multicore Performance Guide" based on our conversation with @samoht
• I've moved the following sections to be after Synchronization tools:
  • Multicore Support (the user shoul learn about Promise, Mutexes, Streams, etc. first)
  • Running processes (same, and I expect this feature to see less frequent use than most modules that were placed ahead of it in the docs)
  • Tracing (this is a somewhat advanced feature, mostly geared towards debugging. I find it easier to not constantly mix "features" with "testing+debugging" in the docs)
  • Testing with Mocks (same as Tracing)
• Moved the Mock Clocks section from Time to Testing with Mocks
• Removed the Worker Pool example from the Streams section
  • I kept as much information as possible. Feel free to re-add anything here.

Please let me know if any of the above causes issues. Feel free to make changes directly on this branch.

[Sudha247]

Thanks @SGrondin! This is great. I've left some comments below.

[SGrondin]

Thank you @Sudha247 and @balat for the comments! I've pushed a new commit with a few small changes based on your feedback.

[Sudha247]

LGTM. I'll wait until @talex5 has had a chance to review before merging.

[talex5]

It's hard to see what changes with sections being moved and edited at the same time. It seems like this is combining three things:

1. Some obvious fixes, e.g. requiring OCaml 5.1
2. Moving things around
3. Documenting the executor pool

It would be helpful to separate these, as 2 needs more thinking about. For example, the section introducing traceln is moved later, but all of the examples use traceln. The part about mocks could perhaps go a bit later, but the reason for having it at the front is to show an immediate benefit of passing the environment to main, as people might wonder why we're doing that.

The tracing section comes right after the fibers section so you can see visually what it looks like to run fibers concurrently. Ideally, we'd also illustrate the other examples, and readers can run the tracing tool to understand any code they write. As the tools aren't ready yet, it currently just shows how to dump the logs, which I agree isn't useful here, but this is just a place-holder while that's being written.

[SGrondin]

Thank you for the details, I really appreciate it because I know how annoying it can be when someone starts changing stuff without understanding why it is the way it is.

I just reverted 2. Moving things around. I'll give it another try in a separate PR that takes everything you just described into account.

Now this PR is only about the Executor_pool and any obvious little fixes I ran into. Please give it another read and let me know what you think! Thank you

[talex5]

Most of this was merged in #650, so closing.