swift-book icon indicating copy to clipboard operation
swift-book copied to clipboard

Add a chapter to the Language Reference for data-race safety.

Open hborla opened this issue 6 months ago • 0 comments

This change adds a chapter to the TSPL Language Reference on data-race safety. This is meant to be an exhaustive list of semantic rules that define away low-level data races in Swift code. This is not meant to be an introduction to concurrency -- that's the job of the Concurrency chapter of the Language Guide -- and it's not meant to contain all semantic rules about the concurrency model (such as when async functions are guaranteed to not suspend dynamically, etc). This reference will subsume the data-race safety reference in the Swift migration guide, and is largely inspired by the content there, originally written by @mattmassicotte (thank you!)

I think this documentation is appropriate for the TSPL Language Reference based on the statement in the style guide on the purpose of the reference:

Language Reference, commonly referred to as “the reference”, describes every aspect of the Swift language in complete detail, but it makes no attempt to be an instructional text. Its material is ordered according to the shape of the formal grammar, and it hand-waves over examples and applications. Several places explicitly link back to the guide for examples. It doesn't need to be as approachable for beginners, because the guide handles that, but it does need to be accurate and unambiguous, shining its flashlight into infrequently explored areas of the language. To accomplish that, it sometimes must sacrifice approachability or user-friendliness. That's ok — many readers won't even need the reference, but if the reference is unclear, the readers who need an answer have nowhere else to go.

This data-race safety reference is currently not comprehensive, hence the draft state of this PR, and there are a number of missing concepts off the top of my head, including:

  • Isolated parameters
  • sending parameters
  • Isolated closure capture rules
  • Many detailed rules around region-based isolation, such as async let
  • Isolated conformances
  • Sendable inference for methods references and key paths

I also have not done a sweep over all concurrency-related proposals to make sure their data race safety rules are covered by this reference.

hborla avatar Jun 10 '25 03:06 hborla