JuliaLang/julia

[docs] Better describe difference role of @spawn in multithreading

Open

#37,011 opened on Aug 12, 2020

View on GitHub
 (0 comments) (3 reactions) (0 assignees)Julia (48,709 stars) (5,773 forks)batch import
docshelp wantedmultithreading

Description

https://docs.julialang.org/en/v1/base/multi-threading/#Base.Threads.@spawn says See the manual chapter on threading for important caveats. but in https://docs.julialang.org/en/v1/manual/multi-threading/ the @spawn macro is not used in any bigger example, not elaborated in more detail. Difference and similarity of @async and @spawn should be elaborated more, ideally with demonstration of both @async and @spawn being used with @sync. In https://docs.julialang.org/en/v1/base/parallel/#Base.@sync I see it can be used for @spawn too, but I think actually having example in manual would help much. Some related discussion here: https://julialang.slack.com/archives/C6SMTHQ3T/p1597182853179500

Contributor guide

Tech stack
None
Domain
documentation
Issue type
documentation
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
2
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-3 hours
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
stale
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
Basic Julia programmingUnderstanding of @async and @spawn
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
75
Research direction
The issue requests better documentation for @spawn in the Julia manual. The relevant files are the @spawn documentation at base/multi threading and the manual chapter on multithreading. To address this, review the current @spawn and @async docs, and add a concrete example using @sync with both macros in the manual chapter. No linked PRs exist; the issue is open with no comments.