JuliaSIMD / JuliaSIMD/Polyester.jl

Unclear/misleading README.md

Open
#124 5 comments 0 reactions 0 assignees View on GitHub
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.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.