TSPL Pitch: Distributed

Swift Documentation
1

The Distributed module is an important part of Swift and has been shipping with it ever since Swift 5.7 (WWDC talk), but for various reasons feature never got its own section in the language guide -- it's time to fix that.

Distributed actors are a fundamental building block for writing distributed systems in Swift and are deeply embedded in Swift's type system and isolation checking and therefore deserve to be documented alongside the Concurrency module in the TSPL.

--

Distributed actors are a little bit unique in the sense that they're a "bring your own runtime" feature, which means that the documentation can only speak in general terms about the core language feature and usual ways distributed actor systems are expected to behave.

Specific DistributedActorSystem implementations, such as DistributedCluster, ordo-one/distributed-system-package or swift-subprocess, are free to complement and document the general feature with transport specific details (such as, what happens when a node/process crashes, how actor discovery works etc.)

Currently language documentation exists API docs, primarily on the DistributedActorSystem and DistributedActor types, as well as some general guidance and clustering specific documentation in the DistributedCluster package docs.

This documentation effort has two parts:

  • add new section to the TSPL to document the Distributed module and distributed actor language feature.
    • This going to answer the "how to use distributed actors?" question.
  • add in-depth article to the API documentation for DistributedActorSystem implementation authors.
    • This will aim to address the "how to implement a runtime?" question.

This proposal is about the prior, but I wanted to explain why this guide will not be going into the "how to implement..." side of things: it will be in a different article.

Outline proposal:

  • Thinking in Distributed Actors - where we explain a little bit about how to think about the "it can be remote" concept and location transparency
    • Distributed Actor Systems Are Transports - it can be confusing to newcomers that the Swift-language does not offer any "runtime" so it's best to explain right away that you need to "pick" a runtime you want to use, i.e. a cluster, websocket or ipc system etc.
  • Distributed Actors
    • Distributed Actor Isolation - one of the more important pieces where we explain the additional isolation rules
    • Default Protocol Conformances -- distributed actors conform to some protocols by default, so we explain the logic behind this; This discusses Equatable, Hashable and Codable.
    • Default actor system typealias - we should put this somewhere so that snippets can avoid doing the typealias ActorSystem = ... constantly
  • Distributed Actor Initialization - initialization needs to discuss their relationship with ID assignment and the actor system
    • Synthesized Distributed Actor Properties - we explain the id and actorSystem properties of actor systems
    • User-defined Initializers - will discuss that initializers have to assign the actorSystem
  • Distributed Methods - further expanding on isolation really, as these are the only way to call potentially-remote actors. We also discuss where they can be declared, including extensions.
    • Implicit Effects of Distributed Methods - explaining the implicit async+throws effect; This includes discussion about error handling.
    • Serialization Requirement - explains the impact on distributed methods of a system's SerializationRequirement
    • Conforming to Protocols with Distributed Actors - examples how conformances work with distributed actors, as well as nonisolated examples
  • Resolving Distributed Actors - explains obtaining potentially remote actor references
    • Distributed Actor Protocols - explains how to design and constrain protocol types, e.g. ones which work for "any actor system". This discusses the latest @Resolvable feature from Swift 6.0.
  • Distributed Actors and Custom Executors - a small section explaining how executors work with distributed actors when a reference is remote or local
  • Common Distributed Actor Patterns
    • Distributed actors generic over Actor Systems
    • Emulating callbacks

I think we'll use a running example throughout all the sections that will be a "game lobby" or maybe a "chat room" where we keep communicating with distributed actors. Without going into details about transport mechanisms.

I have started an initial PR with some text already, but I'd like to focus on getting the outline right and I'll adjust the content accordingly :slight_smile: It'll also need editorial voice/tone cleanup, so primarily let's focus on the content for now.

I'd like to hear from you folks @jaleel @mlienert @ser-0xff since you've dabbed around with distributed actors a bit more -- what else needs to be explained for end users?

If there's anything that people feel needs more attention or reordering please chime in this forums thread. Thank you!

13 Likes
2

I will have a look deeply and response a bit later, but so far have one comment: later was thinking that distributed in Swift looks like some random feature for people, when in reality it's something more fundamental and a tool to build distributed systems. Feels like something to highlight, probably in Thinking in Distributed Actors section, but not going too deep, something balanced.

3 Likes