JuliaSIMD / JuliaSIMD/Polyester.jl
Unclear/misleading README.md
- Dominant language
- Julia
- Stars
- 285
- Forks
- 20
- PR merge metrics
- No merged PRs in 30d
Description
Hi @chriselrod,
I think that the current README.md doesn't do a particularly good job at explaining how Polyester.jl works with respect to three (crucial) points:
1. How many "Polyester threads" are there in total (and does it vary dynamically)?
2. Are "Polyester threads" pinned to CPU-cores/CPU-threads?
3. How do "Polyester threads" relate to / cooperate with / interfere with Julia's task-based multithreading?
I think that sentences like the following are insufficient and potentially misleading:
> Note that `@batch` defaults to using up to one thread per physical core, instead of 1 thread per CPU thread.
It suggests that Polyester potentially changes the number of threads (1) and also pins them to CPU-cores/threads (2). Of course, neither is the case. To be fair, that Polyester doesn't do (2) is mentioned in the README.md but only in a comment in a code example, which can easily be overlooked. The fact that Polyester just uses the already existing Julia threads (1) is also mentioned in the README (at a more prominent place) but is potentially misleading in the context of everything else that follows.
As for point (3) above, the README only compares to `@threads` which (as of now) defaults to `:dynamic` scheduling. This seems somewhat strange/misleading because (IIUC) `@batch` creates sticky tasks and and schedules the workload statically. Hence, it should really be compared to `@threads :static`. Of course, one can also compare to `@threads :dynamic` but the conceptual differences should be highlighted then IMHO.
Overall, IIUC, Polyester really just creates, manages, and re-uses a bunch of sticky **tasks** and just runs them on existing Julia threads (similar to `@threads :static`). However, IMHO, this isn't clear from the README.md which doesn't contain the words "sticky", "task(s)" or, most importantly, "static" at all.
If you're open to it, I might make a suggestion for an improved README.md in a PR later this week. Let me know what you think!
(BTW, apart from the `stride` option, Polyester.jl doesn't implement any form of load-balancing, right?)
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.