RFC: Documentation for isolation inference from classes and protocols [SE-0316] (original) (raw)

Hello!

I'd like to add documentation of the isolation inference rules from classes and protocols in SE-0316: Global actors. Here's the relevant section of the proposal: swift-evolution/proposals/0316-global-actors.md at main · swiftlang/swift-evolution · GitHub

I did not include the property-wrapper based inference rule because it was later removed in SE-0401: Remove Actor Isolation Inference caused by Property Wrappers.

I've put up a PR with documentation in TSPL here: Add discussion of global actor isolation inference. [SE-0316] by hborla · Pull Request #371 · swiftlang/swift-book · GitHub

I look forward to your constructive feedback!

-Holly

This is so helpful! Thank you. I added a couple questions to the PR since it was easier to see inline with the changes.

hborla (Holly Borla) June 8, 2025, 5:13pm 3

I would also like to discuss whether this content belongs in the Language Guide or the Language Reference. Per the swift-book Style guide, the Language Guide is not meant to be comprehensive:

Language Guide, commonly referred to as “the guide”, leads you through the Swift language in a pedagogically useful, linear order. It doesn't promise to show you every feature of the language or the Swift standard library, and it hand-waves over the exact details of some of the more complicated underlying bits. The guide leans on the reference to resolve the nitty-gritty detail questions and to exhaustively cover the language. Unlike the reference, it walks you through step-by-step explanations, showing examples of the language features in action, and it assumes very little prior knowledge.

But the Language Reference is meant to cover all details of the language:

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.

However, the Language Guide is currently the only part of TSPL that covers concurrency in any sort of depth. I'm happy to start a new section of the Language Reference on concurrency, and later data-race safety, that is aimed to have comprehensive documentation about all concurrency language rules in one place if we think that's a better approach.

I'm not sure where inference rules fall, and whether we want a basic description of them in the guide with full details in the reference.

hborla (Holly Borla) June 8, 2025, 5:41pm 4

To be clear, I think this is needed either way. My main question is this one:

gwendal.roue (Gwendal Roué) June 8, 2025, 5:42pm 5

Hi, and thanks for this documentation effort. My two cents: enumerations that exhaustively covers all cases, as you did for isolation inference, are very valuable, and it looks like they belong to the Reference part of TSPL. I'd like to find there another enumeration that covers closure isolation (or lack thereof) in depth. Those references will help vetting the "how to" sections that will enter the Guide. They will also help spotting where the proposals have not been implemented exactly as written for one reason or another.

hborla (Holly Borla) June 8, 2025, 5:50pm 6

This is a great point, and I totally agree. I wonder if this is also a possible path to ensuring up-to-date TSPL content with SE proposals. If the Language Reference were fleshed out to contain all language details in one place, we could change the way we write Detailed Design sections to be a PR against swift-book for the Language Reference. That could be the responsibility of proposal authors without duplicating the work it takes to write a proposal. The Language Reference content can inform any additions to the Language Guide, and we will be more critical of the approachability of the Language Guide content because it's meant to be an introduction to the feature. This approach would at least solve the problem of not having a single place where all current language rules are documented, and rules in older SE proposals becoming out of date because they are changed by later SE proposals.

Okay, I'm going to draft up a reference chapter on concurrency / data-race safety with an attempt at a complete set of rules, and I'll start a new discussion thread about that. Then I can take some recent concurrency proposals and see whether:

Their detailed design is fully covered in the reference
Their detailed design section could have just been an addition to the reference

Thanks for your input!

hborla (Holly Borla) June 10, 2025, 4:09am 7

In case anybody here is interested:

Jason_Gregori (Jason Gregori) June 10, 2025, 4:57am 8

I love those ideas! I think this stuff is sorely missing and it’s really hard to understand the big picture without a central guide.