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

hborla · 2025-08-19T15:55:08Z

This change introduces a section on global-actor isolated protocol conformances, which were introduced in SE-0470.

Fixes: rdar://148361008

This change adds a section on global-actor isolated protocol conformances to the Concurrency chapter of the language guide.

DougGregor

Thank you for writing this!

TSPL.docc/LanguageGuide/Concurrency.md

Use semantic line breaks for prose, title case for headings, four spaces for Swift code indentation, and contractions.

Replace a few uses of "called" with "used" when talking about using protocol requirements. Also removed the subheadings in the Using Isolated Conformances section.

Isolated conformance inference is gated behing the InferIsolatedConformances upcoming feature. Add a dedicated section for inference and a note about the upcoming feature identifier per the guidance in Style.md.

ktoso

Looking good! Had some clarification ideas you may want to take, commented inline

TSPL.docc/LanguageGuide/Concurrency.md

amartini51

Thanks for writing all of this! I've marked a bunch of specific places throughout the diff — and some general comments below.

Let's expand the transitions and explanations. Some sections have a main point too far into the section, and we can elevate that to the introductory paragraph. Several of the code listings would benefit from a paragraph after them that takes the reader through what the code's doing in more detail.

Some subsections don't need as many headings, and headings don't need to be nested as deeply. (Although there's no issue with short sections when they're called for.) Let's try to fit more with the level and length of headings in the existing book. Some of the choices around sectioning in the existing content are based on what DocC handles well, some are based on editorial feedback, and some are just convention that we can vary. Here's an outline of this chapter:

Defining and Calling Asynchronous Functions
Asynchronous Sequences
Calling Asynchronous Functions in Parallel
Tasks and Task Groups
- Task Cancellation
- Unstructured Concurrency
Isolation
The Main Actor
Actors
Global Actors
Sendable Types
Isolated Protocol Conformances <——— NEW
- Declaring an Isolated Conformance
- Inferring an Isolated Conformance
- Data-Race Safety for Isolated Conformances
  - Using Isolated Conformances
  - Restricting Isolated Conformances in Concurrent Code
    - Protocols That Require Sendable or SendableMetatype

Prefer active voice and present tense over passive voice and future tense. We'll catch this during the editorial pass too.

amartini51 · 2025-09-30T20:51:34Z

TSPL.docc/LanguageGuide/Concurrency.md

+the conformance is only used on the actor
+that the conformance is isolated to.
+
+### Declaring an Isolated Conformance


You probably don't need a heading here after just one paragraph.

amartini51 · 2025-09-30T20:52:37Z

TSPL.docc/LanguageGuide/Concurrency.md


+## Isolated Protocol Conformances
+
+Protocols that are nonisolated


Let's either define "nonisolated protocol" if it's a new concept being introduced, or find a way to refer to normal protocol conformance that doesn't sound like a new term.

amartini51 · 2025-09-30T20:54:32Z

TSPL.docc/LanguageGuide/Concurrency.md

+while ensuring that state is only accessed
+from within the actor.
+
+### Inferring an Isolated Conformance


The developer reading TSPL isn't doing the inference, the compiler is. Maybe "Inferred" or "Using Inferred" in the heading?

amartini51 · 2025-09-30T20:59:56Z

TSPL.docc/LanguageGuide/Concurrency.md

+This allows the implementation of the conformance
+to use global actor isolated state
+while ensuring that state is only accessed
+from within the actor.


Let's walk through the code listing more step-by-step in its explanation paragraph. For example:

Why is Person marked @MainActor?

Call out that writing @MainActor Equatable is how you mark the conformance as actor-isolated

Expand "This allows" so the reader doesn't have to guess what "this" refers to. Here, probably "This isolated conformance allows"?

amartini51 · 2025-09-30T21:00:16Z

TSPL.docc/LanguageGuide/Concurrency.md

+}
+
+extension Person: @MainActor Equatable {
+    static func ==(lhs: Person, rhs: Person) -> Bool {


To match TSPL style elsewhere:

Suggested change

static func ==(lhs: Person, rhs: Person) -> Bool {

static func == (lhs: Person, rhs: Person) -> Bool {

Likewise below; marking it just here.

amartini51 · 2025-09-30T21:31:18Z

TSPL.docc/LanguageGuide/Concurrency.md

+In generic code,
+a conformance requirement to `Sendable` or `SendableMetatype`
+tells Swift that an instance or metatype value is safe to use concurrently.


This reads like a definition of Sendable but I think it's about the where D: Sendable clause in the code below? We can check terminology here too — I see "conformance requirement" only twice in TSPL, and in both places it refers to the requirements that a type must implement in order to conform to a protocol.

amartini51 · 2025-09-30T21:36:21Z

TSPL.docc/LanguageGuide/Concurrency.md

+The above code would admit data races
+if the conformance to `Dancer` was isolated,
+because the implementation of `perform`
+may access global actor isolated state.


I'm having a hard time with this sentence, probably because of the irrealis mood on the verbs (would admit, was isolated, may access). Are you saying that the code above is safe, and then describing why by telling me about something that can't happen? Or are you describing a scenario where the code has possible data races?

amartini51 · 2025-09-30T21:37:14Z

TSPL.docc/LanguageGuide/Concurrency.md

+    func perform()
+}
+
+func performConcurrently<D: Dancer>(n: Int, for: D.Type) async where T: SendableMetatype {


I think the T is just a leftover from a previous version that had different type names?

Suggested change

func performConcurrently<D: Dancer>(n: Int, for: D.Type) async where T: SendableMetatype {

func performConcurrently<D: Dancer>(n: Int, for: D.Type) async where D: SendableMetatype {

amartini51 · 2025-09-30T21:37:35Z

TSPL.docc/LanguageGuide/Concurrency.md

+Note that `Sendable` requires `SendableMetatype`,
+so an explicit conformance to `SendableMetatype` is only necessary
+if the type is non-`Sendable`.


This information seems like it should come earlier.

amartini51 · 2025-09-30T21:38:15Z

TSPL.docc/LanguageGuide/Concurrency.md

+let items = performConcurrently(n: 10, for: Ballerina.self)  // Error
+```
+
+##### Protocols That Require `Sendable` or `SendableMetatype`


We can't use H5 or code voice in headings.

hborla changed the title ~~[SE-0470] Add a section on isolated conformances to the Concurrency chapter of the language guide.~~ Add a section on isolated conformances to the Concurrency chapter of the language guide. [SE-0470] Aug 19, 2025

hborla assigned DougGregor and amartini51 Aug 19, 2025

[SE-0470] Document isolated conformances.

1ad8fee

This change adds a section on global-actor isolated protocol conformances to the Concurrency chapter of the language guide.

hborla force-pushed the se-0470 branch from 2831b72 to 1ad8fee Compare August 19, 2025 17:27

amartini51 changed the title ~~Add a section on isolated conformances to the Concurrency chapter of the language guide. [SE-0470]~~ Add a section on isolated conformances to the guide [SE-0470] Aug 19, 2025

DougGregor reviewed Aug 19, 2025

View reviewed changes

amartini51 and others added 8 commits August 19, 2025 10:51

Start a clean-up pass

e46557f

Use semantic line breaks for prose, title case for headings, four spaces for Swift code indentation, and contractions.

Minor wording and heading changes.

45826d2

Replace a few uses of "called" with "used" when talking about using protocol requirements. Also removed the subheadings in the Using Isolated Conformances section.

Add an existential isolated conformance example.

1ecd2ba

Make isolated conformances explicit in code.

d32afa1

Fix a typo in isolated conformance example.

834c63b

Clarify SendableMetatype conformance restriction.

7a0fc92

Add a note about InferIsolatedConformances.

f1f8c33

Isolated conformance inference is gated behing the InferIsolatedConformances upcoming feature. Add a dedicated section for inference and a note about the upcoming feature identifier per the guidance in Style.md.

Briefly introduce metatype values.

439e38b

ktoso approved these changes Aug 21, 2025

View reviewed changes

slavapestov reviewed Aug 23, 2025

View reviewed changes

Clarify the introduction of isolated conformances.

7fc52b1

hborla force-pushed the se-0470 branch 2 times, most recently from 88db53c to d657461 Compare September 6, 2025 01:50

Minor editorial changes.

e53a81c

hborla force-pushed the se-0470 branch from d657461 to e53a81c Compare September 6, 2025 01:51

Replace single-letter names with real words in code.

b17e906

stzn mentioned this pull request Sep 6, 2025

isolated conformanceの説明追加 stzn/the-swift-programming-language-jp#651

Open

amartini51 added 2 commits September 25, 2025 16:09

Remove trailing space

6c7806a

Wrap long lines

9c98fe5

amartini51 reviewed Sep 30, 2025

View reviewed changes


		## Isolated Protocol Conformances

		Protocols that are nonisolated

	static func ==(lhs: Person, rhs: Person) -> Bool {
	static func == (lhs: Person, rhs: Person) -> Bool {

	func performConcurrently<D: Dancer>(n: Int, for: D.Type) async where T: SendableMetatype {
	func performConcurrently<D: Dancer>(n: Int, for: D.Type) async where D: SendableMetatype {

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

Are you sure you want to change the base?

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

Uh oh!

Conversation

hborla commented Aug 19, 2025

Uh oh!

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

Uh oh!

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants