API naming, StructuredTaskScope

[Ron Pressler]

> On 8 Nov 2024, at 13:26, Eirik Bjørsnøs <eirbjo at gmail.com> wrote:
> 
> 
> scope.fork(() -> ..)
> Since we're forking a scope, you may think this returns another.. scope? Ok, it doesn't. Then perhaps..  a Task? No. A SubTask! Well, then what's a Task? There is no such thing! Well, ok..
> 
> scope.join(): 
> What does it actually mean to "join a scope"?  Is "join" used in a transitive or intransitive sense? Is something in the scope being joined (tasks?), or are we (the caller) "joining" the scope, like Thread::join?
> Maybe the API docs give us a clue: "Waits for all subtasks started in this scope to complete". Aha, so we are "completing" the scope/tasks/subtasks. Then perhaps "join" is here just to provide symmetry with "fork" and "complete" would be a more honest name?

I agree there are some novel challenges to naming StructuredTaskScope and SubTask, but as to fork and join I will say that both are terms of art in the concurrency and parallelism world, where “fork" means splitting the instruction stream into multiple parallel ones (typically ones that retain some child-parent relationship to the forking stream), while "join" means joining multiple instruction streams into one, which, in practice, means waiting for them to complete.

“Join" is used in this same sense in the JDK in Thread.join, CompetableFuture.join, and ForkJoinTask.join. “Fork" is used in this sense in ForkJoinTask.fork.

I don’t think `complete` is a better name than `join`. While `join` may be cryptic, `complete` is misleading as the call completes nothing. `awaitCompletion` would be a more evocative name but, as always, when picking names there’s a tension between choosing a name that could be easy for the uninitiated to grasp and a name that would make the developer familiar with a standard term of art in the relevant domain.

There are other similar cases in Java. For example, why is it that we “throw” and “catch” an “exception” rather than “signal” and “handle” an “error”? Or why is the key-value data structure known elsewhere as a “dictionary” or a “table” or an “associative array” called a “map” in Java?

I’m not saying what the right answer is — if there is one — only that perceived obviousness is not the only consideration.


— Ron