[doc-only] docs: clarify cuda.core concurrency and thread-safety policy#2318
Open
Andy-Jost wants to merge 1 commit into
Open
[doc-only] docs: clarify cuda.core concurrency and thread-safety policy#2318Andy-Jost wants to merge 1 commit into
Andy-Jost wants to merge 1 commit into
Conversation
Andy-Jost
added
documentation
|
Document the concurrency contract that was previously agreed only in review threads: concurrent reads of a cuda.core object are supported, but concurrent mutation of the same object requires application-provided synchronization. Distinct objects can still collide through shared CUDA driver/context state (e.g. peer device access), which is also the caller's responsibility. - docs/source/concurrency.rst: new user-facing "Concurrency and Thread Safety" page, linked into the docs toctree. - cuda_core/AGENTS.md: contributor-facing invariants (reads-safe/mutation boundary, prefer immutable designs, shared-driver-state collisions, guarding internal cached state only for legitimately-shared objects, GIL-held entry points, and releasing the GIL before entering the driver from callback/__del__ paths).
Andy-Jost
force-pushed
the
ajost/docs-concurrency-thread-safety
branch
from
f3b7a51 to
d826eb3
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Writes down cuda.core's concurrency and thread-safety expectations, which were previously agreed only in review threads (#2280) and a follow-up Slack discussion, but never documented. Adds a short user-facing policy page and a matching set of contributor-facing invariants. Docs only; no code or behavior changes.
The policy is intentionally minimal, per the discussion: state what users can rely on today without overcommitting to guarantees we would have to maintain long-term.
Policy
Changes
docs/source/concurrency.rst: new user-facing "Concurrency and Thread Safety" page, linked into the docs toctree (docs/source/index.rst).cuda_core/AGENTS.md: new "Concurrency and free-threading" section for contributors and reviewers -- reads-safe/mutation boundary, prefer immutable designs, shared-driver-state collisions, guarding internal cached state only for legitimately-shared objects (not thread-local ones likeDevice, cf. Revert SMResource splitting fix, the problem was the test #2321), GIL-held entry points, and releasing the GIL before entering the driver from callback/__del__paths.Related Work