Add a chapter to the Language Reference for data-race safety. by hborla · Pull Request #372 · swiftlang/swift-book

hborla · 2025-06-10T03:54:48Z

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.

bhelyer · 2025-06-10T08:26:33Z

+concurrent executor.
+
+A non-isolated asynchronous function that runs on the caller's actor is
+deonated with the `nonisolated(nonsending)` keyword:


Hah, yes, thank you. I should use a spell checker :)

heckj

spell check updates - no wording changes.

heckj · 2025-06-10T15:50:13Z

+Eliminate data races at compile time.
+
+The Swift 6 language mode eliminates data races at compile time by
+identifying and diagnosing risk of concurrent access to shared state.


Suggested change

identifying and diagnosing risk of concurrent access to shared state.

identifying and diagnosing the risk of concurrent access to shared state.

heckj · 2025-06-10T15:51:22Z

+3. The variable is a property of a struct and the type of the property
+   conforms to `Sendable`.
+
+Extensions be marked with `nonisolated`, which promptes Swift to infer


Suggested change

Extensions be marked with `nonisolated`, which promptes Swift to infer

Extensions can be marked with `nonisolated`, which promptes Swift to infer

heckj · 2025-06-10T15:51:46Z

+concurrent executor.
+
+A non-isolated asynchronous function that runs on the caller's actor is
+deonated with the `nonisolated(nonsending)` keyword:


Suggested change

deonated with the `nonisolated(nonsending)` keyword:

denoted with the `nonisolated(nonsending)` keyword:

heckj · 2025-06-10T15:52:38Z

+to an actor to a different actor or a concurrent task. Swift ensures
+that access to actor-isolated state only happens within the actor. You
+can access `nonisolated` properties and methods from outside the actor,
+but access to isolated properties and methods must be done asynchornously.


Suggested change

but access to isolated properties and methods must be done asynchornously.

but access to isolated properties and methods must be done asynchronously.

heckj · 2025-06-10T15:53:20Z

+are either:
+
+1. Non-isolated and have `Sendable` type, or
+2. Isolated to a global actor


Suggested change

2. Isolated to a global actor

2. Isolated to a global actor.

heckj · 2025-06-10T15:53:40Z

+A global variable is safe from data races if one of the following
+conditions applies:
+
+1. It is a `let`-constant and the type conforms to `Sendable`


Suggested change

1. It is a `let`-constant and the type conforms to `Sendable`

1. It is a `let`-constant and the type conforms to `Sendable`.

heckj · 2025-06-10T15:53:48Z

+conditions applies:
+
+1. It is a `let`-constant and the type conforms to `Sendable`
+2. It is isolated to a global actor


Suggested change

2. It is isolated to a global actor

2. It is isolated to a global actor.

MrTheSaw · 2025-06-11T05:18:32Z

+}
+```
+
+The implementation of an `@concurrent` function will always switch off


An @Concurrent? Or do we say the "at"?

rayx · 2025-06-12T07:28:09Z

+
+* If `r` is synchronous, then `r'` is safe from data races if one of the
+  following conditions applies:
+  * The isolation of `r'` matches the isolation of `r'`


Suggested change

* The isolation of `r'` matches the isolation of `r'`

* The isolation of `r'` matches the isolation of `r`

rayx · 2025-06-12T07:28:36Z

+  * `r'` is `nonisolated`
+* If `r` is asynchronous, then the implementation `r'` is safe from data
+  races if one of the following conditions applies:
+  * The isolation of `r'` matches the isolation of `r'`


Suggested change

* The isolation of `r'` matches the isolation of `r'`

* The isolation of `r'` matches the isolation of `r`

rayx · 2025-06-13T13:32:21Z

+    mutating func toggle()
+}
+
+struct Switch: Togglable {


Suggested change

struct Switch: Togglable {

struct Switch {

rayx · 2025-06-14T14:06:56Z

+You specify that a declaration is non-isolated with the `nonisolated`
+keyword. Swift guarantees that non-isolated declarations are safe
+to call from anywhere by ensuring that they do not access actor-isolated
+state in their implementation. Non-isolated functions safely call other


It's also OK for non-isolated function to access actor properties which are let-constants and of Sendable types. I think it might be worth adding this information, because it's common when conforming an actor to protocols.

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

7c3b01a

hborla changed the title ~~Add a draft chapter to the Language Reference for data-race safety.~~ Add a chapter to the Language Reference for data-race safety. Jun 10, 2025

bhelyer reviewed Jun 10, 2025

View reviewed changes

heckj reviewed Jun 10, 2025

View reviewed changes

MrTheSaw reviewed Jun 11, 2025

View reviewed changes

stzn mentioned this pull request Jun 11, 2025

データ競合安全のチャプターを追加する stzn/the-swift-programming-language-jp#632

Open

rayx reviewed Jun 13, 2025

View reviewed changes

rayx reviewed Jun 14, 2025

View reviewed changes

	identifying and diagnosing risk of concurrent access to shared state.
	identifying and diagnosing the risk of concurrent access to shared state.

	Extensions be marked with `nonisolated`, which promptes Swift to infer
	Extensions can be marked with `nonisolated`, which promptes Swift to infer

	deonated with the `nonisolated(nonsending)` keyword:
	denoted with the `nonisolated(nonsending)` keyword:

	but access to isolated properties and methods must be done asynchornously.
	but access to isolated properties and methods must be done asynchronously.

	1. It is a `let`-constant and the type conforms to `Sendable`
	1. It is a `let`-constant and the type conforms to `Sendable`.

	2. It is isolated to a global actor
	2. It is isolated to a global actor.

	* The isolation of `r'` matches the isolation of `r'`
	* The isolation of `r'` matches the isolation of `r`

Uh oh!

Conversation

hborla commented Jun 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

heckj left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

hborla commented Jun 10, 2025 •

edited

Loading