Closed SGrondin closed 2 months ago
Thank you @Sudha247 and @balat for the comments! I've pushed a new commit with a few small changes based on your feedback.
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:
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.
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
Most of this was merged in #650, so closing.
Changes to the README:
"5.0"
with"5.1"
since Eio now requires OCaml 5.1Domainslib
andkcas
sections to their own files indoc/
Multicore Support
section to include, in order:Executor_pool
andDomain_manager.run
. Assumption: expert users will know when they need to directly create threads, no need to explain the rationale to them.Executor_pool
Domain_manager.run
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)~Mock Clocks
section fromTime
toTesting with Mocks
~Worker Pool
example from theStreams
sectionPlease let me know if any of the above causes issues. Feel free to make changes directly on this branch.