Distributed actors

Active contributors: ktoso

Purpose

stdlib/public/Distributed/ implements the language and runtime support for distributed actors -- actors whose calls can be transparently dispatched across processes or networks. A distributed actor is associated with a user-implemented DistributedActorSystem that handles serialization and transport. See SE-0336, SE-0344, and follow-ons.

Directory layout

stdlib/public/Distributed/
├── Distributed.swift
├── DistributedActor.swift
├── DistributedActorSystem.swift
├── DistributedAssertions.swift
├── DistributedDefaultExecutor.swift
├── DistributedMacros.swift
├── DistributedMetadata.swift
├── DistributedRuntime.cpp           # C++ runtime support
├── ExecuteDistributedTarget.swift
└── LocalTestingDistributedActorSystem.swift

Key abstractions

Type	File	Description
DistributedActor	stdlib/public/Distributed/DistributedActor.swift	The base protocol. Every distributed actor declaration conforms to this.
DistributedActorSystem	stdlib/public/Distributed/DistributedActorSystem.swift	The user-provided transport.
RemoteCallTarget	stdlib/public/Distributed/Distributed.swift	The mangled identifier of a remote distributed method.
DistributedTargetInvocation*	stdlib/public/Distributed/Distributed.swift	Encoder / decoder protocols for arguments + return values.
LocalTestingDistributedActorSystem	stdlib/public/Distributed/LocalTestingDistributedActorSystem.swift	A simple in-process system for tests / examples.

How it works

sequenceDiagram
    participant Caller
    participant Local as Local stub
    participant System as ActorSystem (transport)
    participant Remote as Remote node
    Caller->>Local: try await actor.greet(name)
    Local->>Local: encode args via InvocationEncoder
    Local->>System: remoteCall(target, encoder)
    System->>Remote: ship payload
    Remote->>Remote: executeDistributedTarget(...)
    Remote->>Remote: decode args, run method
    Remote->>System: ship reply
    System->>Local: result
    Local->>Caller: return value

When the compiler sees:

distributed actor Greeter {
  distributed func greet(name: String) async -> String {
    "hello, \(name)"
  }
}

it synthesizes:

• A local implementation (the actual function body) that runs when called on a local instance.
• A thunk that encodes the call and forwards through the actor system when called on a remote instance.
• The check that the user's DistributedActorSystem supports the method's argument/return types via the SerializationRequirement associated type.

SILGenDistributed.cpp (in SILGen) handles the lowering. The Distributed module provides the runtime types and the executeDistributedTarget entry point that the system uses on the receiving side.

Local testing system

LocalTestingDistributedActorSystem is shipped for unit tests and examples -- it simulates a distributed system in one process. Production systems are user-implemented (or come from third-party libraries like swift-distributed-actors).

Integration points

• Builds on the Concurrency actor model -- a distributed actor is also a regular actor.
• Macros (DistributedMacros.swift) expand @Resolvable and similar attached macros via the macro infrastructure.
• SILGen has a dedicated lowering path (lib/SILGen/SILGenDistributed.cpp).
• Sema enforces the rules: distributed func requires async throws, Sendable arguments, etc. (lib/Sema/TypeCheckDistributed.cpp).

Entry points for modification

• Loosening or tightening rules: lib/Sema/TypeCheckDistributed.cpp. Tests in test/Distributed/.
• Improving the runtime: the C++ entry points are in DistributedRuntime.cpp; the Swift layer is in the .swift files.

Related pages

• Concurrency -- the layer below.
• SILGen -- where distributed-actor lowering lives.