Add discussion of global actor isolation inference. [SE-0316] #371

hborla · 2025-06-07T16:21:39Z

This change adds documentation for isolation inference from class inheritance, overridden methods, and protocol conformances.

These rules are buried in old proposal documents, and they deserve documentation in TSPL, especially because they can be difficult to reason about. These rules were originally added in SE-0316.

This does not cover all cases of actor isolation inference; the rules for isolation inference of closures needs to be covered, but I think that belongs in the Sendable section because it's based on whether or not a closure type can be called from outside the current concurrency context.

I started an RFC thread on the forums about this change here: https://forums.swift.org/t/rfc-documentation-for-isolation-inference-from-classes-and-protocols-se-0316/80343.

Fixes: rdar://160642164

This change adds documentation for isolation inference from class inheritance, overridden methods, and protocol conformances.

heckj

I made some suggestions for reframing the sentences to use active voice to make it clear the compiler is the bit doing the inferring in these scenarios. Structurally, this introduces 3 patterns to look for - the 3rd being a "contextual" - but I wasn't super clear on how that tied into the 2 subheadings beneath.

And I asked a couple questions in the review about the logic and what was possible that didn't seem entirely spelled out to me, but I may be misunderstanding.

TSPL.docc/LanguageGuide/Concurrency.md

jasongregori

This is so helpful, thank you! I have some questions below.

jasongregori · 2025-06-07T18:41:19Z

TSPL.docc/LanguageGuide/Concurrency.md

+}
+```
+
+In the above example, `Togglable` and all of its requirements


The first example says “Vehicle and all of its methods and properties are isolated to the main actor”. This one says “all of its requirements”. After reading the next example, I think (?) that all of Switch’s methods and properties are also isolated to the main actor? Is that right? If so I find the first wording very helpful and clearer and I think it would help to use it here as well. If not, perhaps that fact could be made clearer?

I used the language "methods and properties" when talking about concrete types and "requirements" when talking about protocols. But you're right that I should state that when @MainActor is inferred on Switch, all of its methods and properties become isolated to the main actor too.

Thanks, yeah I think that’s really helpful because it’s changing more than just the requirements.

Changed in bee33b2:

In the example above, the Togglable protocol is marked @MainActor to indicate that all of its requirements are isolated to the main actor. Swift infers main-actor isolation on types that conform to Togglable, so all methods and properties of Switch are isolated to the main actor, including the isOn property and the toggle method.

jasongregori · 2025-06-07T18:44:40Z

TSPL.docc/LanguageGuide/Concurrency.md

+
+extension Switch: Togglable {
+    mutating func toggle() {
+        isOn.toggle()


In this example the function toggle is isolated to the main actor but isOn is not isolated to the main actor, is it? And if that’s the case, isn’t it not allowed to use it here?

In this example, isOn is nonisolated, which is fine to access from a main actor isolated method.

Ah, is that because you can only access the toggle function if your Switch is currently living in the main actor and thus any access to isOn would necessarily be on the main actor as well? I always forget about that. Very cool.

@jasongregori Do you think it's worth calling out in the explanation of this code listing that isOn is nonisolated? Or ok to make this conversation thread as resolved?

is the subject performing inference.

hborla · 2025-06-08T17:18:43Z

I also think there's a meta discussion about whether inference rules belong in the Language Guide. I think we are long over due for a section in the Language Reference on concurrency, and we'll need that regardless of whether we want this change in the guide. I am happy to start working on a concurrency and data-race safety chapter for the Language Reference!

If you have thoughts on this, I'd love to hear them: https://forums.swift.org/t/rfc-documentation-for-isolation-inference-from-classes-and-protocols-se-0316/80343/3

TSPL.docc/LanguageGuide/Concurrency.md

jasongregori · 2025-06-10T13:51:31Z

TSPL.docc/LanguageGuide/Concurrency.md

+
+extension Switch: Togglable {
+    mutating func toggle() {
+        isOn.toggle()


Ah, is that because you can only access the toggle function if your Switch is currently living in the main actor and thus any access to isOn would necessarily be on the main actor as well? I always forget about that. Very cool.

heckj

One sentence felt really odd to read, so I made a suggestion, but otherwise the changes for active voice were super useful to me. Thank you!

TSPL.docc/LanguageGuide/Concurrency.md

@mainactor

- Adjusted the framing of the examples to be specifically about main-actor isolation, since they use @mainactor, as a concrete example of the global-actor isolation rules. - Removed the headings for classes and protocols -- both of them can be explained in one section together. Although level 4 headings are supported by the tools, using them should be rare. - Added announceDeparture() so the code shows an example of each listed inference rule. - Marked a few places to discuss/fill in with XXX.

amartini51 · 2025-07-11T23:16:47Z

@hborla — I took a first pass over these additions today in commit bee33b2 mostly looking at style and flow. I'll come back Monday and check what other comments on this PR apply to the rewritten version, and we can make additional changes to incorporate them.

colleenish

First pass edits. Please let me know if you have any questions.

colleenish · 2025-09-29T17:37:03Z

TSPL.docc/LanguageGuide/Concurrency.md

+class Vehicle {
+    var currentSpeed = 0.0
+    func makeNoise() {
+        // do nothing - an arbitrary vehicle doesn't necessarily make a noise


Suggested change

// do nothing - an arbitrary vehicle doesn't necessarily make a noise

// Do nothing: an arbitrary vehicle doesn't necessarily make a noise.

What does this comment mean? "An arbitrary vehicle doesn't necessary make a noise"? What makes it "arbitrary"?

Changed

The Vehicle class is a sort of abstract or placeholder superclass — it doesn't implement much behavior, but its subclasses like Train do. In real Swift code, abstract base classes like this are somewhat rare (unlike some other languages) because protocols or generics are often better tools. However, it does make a pretty approachable teaching example.

For additional context, this code listing follows the running code listing example from the Inheritance chapter earlier in the book. So we might also want to cross-apply edits there.

Also, if there's an editorial preference for colons rather than dashes, I can spin up a tracking bug for that. (Thinking of this because I have a related fix to normalize "OK" vs "Ok" in comments, per Apple Style, on a different branch that includes similar punctuation.)

colleenish · 2025-09-29T17:40:16Z

TSPL.docc/LanguageGuide/Concurrency.md

 [`MainActor`]: https://developer.apple.com/documentation/swift/mainactor

 You can define your own singleton global actors
 using the `@globalActor` attribute,


The paragraph under "Global Actors" needs some work:

Global Actors

"The main actor is a global singleton instance of the [MainActor][] type.
Normally, an actor can have multiple instances,
each of which provide independent isolation.
The possibility of multiple instances is why you declare all of an actor's isolated data
as instance properties of that actor.
However, because MainActor is singleton ---
there is only ever a single instance of this type ---
the type alone is sufficient to identify the actor,
allowing you to mark main-actor isolation using just an attribute.
This approach gives you more flexibility to organize your code
in the way that works best for you."

Changed. Did you want to revisit this paragraph more together, or does the edit above fix the issues?

colleenish · 2025-09-29T17:40:51Z

TSPL.docc/LanguageGuide/Concurrency.md

+```
+
+In the example above,
+the `Vehicle` class is isolated to the main actor ---


Suggested change

the `Vehicle` class is isolated to the main actor ---

the `Vehicle` class isolates to the main actor ---

Let's discuss wording here.

colleenish · 2025-09-29T17:41:40Z

TSPL.docc/LanguageGuide/Concurrency.md

+
+    @MainActor
+    func makeNoise() {
+        // do nothing - an arbitrary vehicle doesn't necessarily make a noise


Suggested change

// do nothing - an arbitrary vehicle doesn't necessarily make a noise

// Do nothing: an arbitrary vehicle doesn't necessarily make a noise.

Again, I'm not clear what this comment means.

colleenish · 2025-09-29T17:44:01Z

TSPL.docc/LanguageGuide/Concurrency.md

+so all methods and properties of `Switch` are isolated to the main actor,
+including the `isOn` property and the `toggle` method.
+
+Swift infers isolation from protocols


Suggested change

Swift infers isolation from protocols

Swift only infers isolation from protocols

Changed.

My original placement of "only" is right next to the word that it modifies, to avoid ambiguity — do you think there's any risk of a reader misreading this? For example, to misread as "Swift infers isolation" but it doesn't do anything else. The original was based on editorial guidance I've gotten in the past, moving the "only" to the most specific location.

Revert to "only when...". Sounds good to me!

colleenish · 2025-09-29T17:44:25Z

TSPL.docc/LanguageGuide/Concurrency.md

+including the `isOn` property and the `toggle` method.
+
+Swift infers isolation from protocols
+only when you write the conformance as part of the type's declaration.


Suggested change

only when you write the conformance as part of the type's declaration.

when you write the conformance as part of the type's declaration.

colleenish · 2025-09-29T17:44:51Z

TSPL.docc/LanguageGuide/Concurrency.md

+Swift infers isolation from protocols
+only when you write the conformance as part of the type's declaration.
+If you write the conformance in an extension,
+then isolation inference applies to


Suggested change

then isolation inference applies to

then isolation inference only applies to

Changed. Same reason for my original wording as above — although I think the risk of misreading is much lower here.

colleenish · 2025-09-29T17:45:00Z

TSPL.docc/LanguageGuide/Concurrency.md

+only when you write the conformance as part of the type's declaration.
+If you write the conformance in an extension,
+then isolation inference applies to
+only requirements that are part of that the extension.


Suggested change

only requirements that are part of that the extension.

requirements that are part of that extension.

Co-authored-by: Colleen Toporek <colleen_toporek@apple.com>

Both the previous commit and a commit already on 'main' added a missing word in the Global Actors section.

Add discussion of global actor isolation inference. [SE-0316]

5e5349e

This change adds documentation for isolation inference from class inheritance, overridden methods, and protocol conformances.

hborla requested review from amartini51 and heckj June 7, 2025 16:42

heckj reviewed Jun 7, 2025

View reviewed changes

jasongregori reviewed Jun 7, 2025

View reviewed changes

stzn mentioned this pull request Jun 7, 2025

Actor isolationの推論に関する説明を追加 stzn/the-swift-programming-language-jp#630

Open

Reframe the isolation inference section to make it clear that Swift

0f1df57

is the subject performing inference.

jasongregori reviewed Jun 10, 2025

View reviewed changes

heckj approved these changes Jun 10, 2025

View reviewed changes

TSPL.docc/LanguageGuide/Concurrency.md Outdated Show resolved Hide resolved

hborla mentioned this pull request Aug 20, 2025

Add a section on isolated conformances to the guide [SE-0470] #381

Open

amartini51 assigned hborla Aug 21, 2025

Add "that" for clarity

bfd27fd

amartini51 assigned amartini51 and unassigned hborla Sep 15, 2025

amartini51 added 2 commits September 15, 2025 14:58

Remove stale TR query

6841627

Add a section intro

0d7cf4a

colleenish suggested changes Sep 29, 2025

View reviewed changes

amartini51 and others added 2 commits September 29, 2025 16:27

Apply edits from <rdar://161365818>

481f72e

Co-authored-by: Colleen Toporek <colleen_toporek@apple.com>

Track 'main' to resolve a trivial merge conflict

223091d

Both the previous commit and a commit already on 'main' added a missing word in the Global Actors section.

	// do nothing - an arbitrary vehicle doesn't necessarily make a noise
	// Do nothing: an arbitrary vehicle doesn't necessarily make a noise.

	the `Vehicle` class is isolated to the main actor ---
	the `Vehicle` class isolates to the main actor ---

	Swift infers isolation from protocols
	Swift only infers isolation from protocols

	only when you write the conformance as part of the type's declaration.
	when you write the conformance as part of the type's declaration.

	then isolation inference applies to
	then isolation inference only applies to

	only requirements that are part of that the extension.
	requirements that are part of that extension.

Add discussion of global actor isolation inference. [SE-0316] #371

Are you sure you want to change the base?

Add discussion of global actor isolation inference. [SE-0316] #371

Uh oh!

Conversation

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

Uh oh!

Uh oh!

heckj left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jasongregori 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!

hborla commented Jun 8, 2025

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

heckj left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

amartini51 commented Jul 11, 2025

Uh oh!

colleenish 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

Global Actors

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

amartini51 Sep 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

hborla commented Jun 7, 2025 •

edited by amartini51

Loading

amartini51 Sep 29, 2025 •

edited

Loading