@@ -16,16 +16,13 @@ In addition, some concurrency and parallelism primitives are provided:
1616- ` Moonpool.Chan ` provides simple cooperative and thread-safe channels
1717 to use within pool-bound tasks. They're essentially re-usable futures.
1818
19- On OCaml 5 (meaning there's actual domains and effects, not just threads),
20- a ` Fut.await ` primitive is provided. It's simpler and more powerful
19+ Moonpool now requires OCaml 5 (meaning there's actual domains and effects, not just threads),
20+ so the ` Fut.await ` primitive is always provided. It's simpler and more powerful
2121 than the monadic combinators.
2222- ` Moonpool_forkjoin ` , in the library ` moonpool.forkjoin `
2323 provides the fork-join parallelism primitives
2424 to use within tasks running in the pool.
2525
26- On OCaml 4.xx, there is only one domain; all threads run on it, but the
27- pool abstraction is still useful to provide preemptive concurrency.
28-
2926## Usage
3027
3128The user can create several thread pools (implementing the interface ` Runner.t ` ).
@@ -182,7 +179,7 @@ scope).
182179
183180### Fork-join
184181
185- On OCaml 5, again using effect handlers, the sublibrary ` moonpool.forkjoin `
182+ The sub-library ` moonpool.forkjoin `
186183provides a module ` Moonpool_forkjoin `
187184implements the [ fork-join model] ( https://en.wikipedia.org/wiki/Fork%E2%80%93join_model ) .
188185It must run on a pool (using ` Runner.run_async ` or inside a future via ` Fut.spawn ` ).
@@ -296,21 +293,18 @@ You are assuming that, if pool P1 has 5000 tasks, and pool P2 has 10 other tasks
296293
297294## OCaml versions
298295
299- This works for OCaml >= 4.08.
300- - On OCaml 4.xx, there are no domains, so this is just a library for regular thread pools
301- with not actual parallelism (except for threads that call C code that releases the runtime lock, that is).
302- C calls that do release the runtime lock (e.g. to call [ Z3] ( https://github.com/Z3Prover/z3 ) , hash a file, etc.)
303- will still run in parallel.
304- - on OCaml 5.xx, there is a fixed pool of domains (using the recommended domain count).
305- These domains do not do much by themselves, but we schedule new threads on them, and form pools
306- of threads that contain threads from each domain.
307- Each domain might thus have multiple threads that belong to distinct pools (and several threads from
308- the same pool, too — this is useful for threads blocking on IO); Each pool will have threads
309- running on distinct domains, which enables parallelism.
310-
311- A useful analogy is that each domain is a bit like a CPU core, and ` Thread.t ` is a logical thread running on a core.
312- Multiple threads have to share a single core and do not run in parallel on it[ ^ 2 ] .
313- We can therefore build pools that spread their worker threads on multiple cores to enable parallelism within each pool.
296+ This works for OCaml >= 5.00.
297+
298+ Internally, there is a fixed pool of domains (using the recommended domain count).
299+ These domains do not do much by themselves, but we schedule new threads on them, and form pools
300+ of threads that contain threads from each domain.
301+ Each domain might thus have multiple threads that belong to distinct pools (and several threads from
302+ the same pool, too — this is useful for threads blocking on IO); Each pool will have threads
303+ running on distinct domains, which enables parallelism.
304+
305+ A useful analogy is that each domain is a bit like a CPU core, and ` Thread.t ` is a logical thread running on a core.
306+ Multiple threads have to share a single core and do not run in parallel on it[ ^ 2 ] .
307+ We can therefore build pools that spread their worker threads on multiple cores to enable parallelism within each pool.
314308
315309TODO: actually use https://github.com/haesbaert/ocaml-processor to pin domains to cores,
316310possibly optionally using ` select ` in dune.
@@ -326,3 +320,4 @@ $ opam install moonpool
326320```
327321
328322[ ^ 2 ] : ignoring hyperthreading for the sake of the analogy.
323+
0 commit comments