A peer-to-peer cluster actor system implementation for Swift.
NOTE: This project provides a cluster runtime implementation for the distributed actors language feature.
Important: This library is currently released as beta preview software. While we anticipate very few changes, please be mindful that until a stable 1.0 version is announced, this library does not guarantee source compatibility.
We anticipate to release a number of
1.0.0-beta-n releases during the beta phase of Swift 5.7, before releasing a source stable 1.0 soon after.
Most APIs and runtime are rather stable, and have proven itself for a long time already. Most of the remaining work is around making sure all APIs work nicely with the latest revision of the
distributed actor language feature.
Important: Please ignore and do not use any functionality that is prefixed with an
_(such as types and methods), as they are intended to be removed as we reach the stable 1.0 release.
Distributed actors are an extension of the "local only" actor model offered by Swift with its
Distributed actors are declared using the
distributed actor keywords (and importing the
and enable the declaring of
distributed func methods inside such actor. Such methods may then be invoked remotely,
from other peers in a distributed actor system.
The distributed actor language feature does not include any specific runtime, and only defines the language and semantic rules surrounding distributed actors. This library provides a feature-rich clustering server-side focused implementation of such runtime (i.e. a
DistributedActorSystem implementation) for distributed actors.
To learn more about both the language feature and library, please refer to the reference documentation of this project.
The primary purpose of open sourcing this library early is proving the ability to implement a feature complete, compelling clustering solution using the
distributed actor language feature, and co-evolving the two in tandem.
You can refer to the
Samples/ directory to view a number of more realistic sample apps which showcase how distributed actors can be used in a cluster.
The most "classical" example of distributed actors is the
You can run it all in a single node (
run --package-path Samples/ SampleDiningPhilosophers), or in 3 cluster nodes hosted on the same physical machine:
run --package-path Samples/ SampleDiningPhilosophers distributed. Notice how one does not need to change implementation of the distributed actors to run them in either "local" or "distributed" mode.
Please refer to the rendered docc reference documentation to learn about distributed actors and how to use this library and its various features.
Note: Documentation is still work in progress, please feel free to submit issues or patches about missing or unclear documentation.
This library requires beta releases of Swift (5.7+) and Xcode to function property as the
distributed actor feature is part of that Swift release.
When developing on macOS, please also make sure to update to the latest beta of macOS, as some parts of the Swift runtime necessary for distributed actors to work are part of the Swift runtime library which is shipped with the OS.
Distributed actors are not back-deployed and require the latest versions of iOS, macOS, watchOS etc.
When developing on Linux systems, you can download the latest Swift 5.7 toolchains from swift.org/downloads, and use it to try out or run the library like this:
$ export TOOLCHAIN=/path/to/toolchain $ $TOOLCHAIN/usr/bin/swift test $ $TOOLCHAIN/usr/bin/swift run --package-path Samples/ SampleDiningPhilosophers dist
Latest (beta) Xcode releases include complete support for the
distributed language syntax (
distributed func), so please use the latest Beta Xcode available to edit the project and any projects using distributed actors.
It is possible to open and edit this project in other IDEs, however most IDEs have not yet caught up with the latest language syntax (i.e.
distributed actor) and therefore may have trouble understanding the new syntax.
You can use the Swift Server Work Group maintained VSCode plugin to edit this project from VSCode.
You can install the VSCode extension from here.
The extension uses sourcekit-lsp and thus should be able to highlight and edit distributed actor using sources just fine. If it does not, please report issues!
The project is possible to open in CLion as a SwiftPM package project, however CLion and AppCode do not yet support the new
distributed syntax, so they might have issues formatting the code until this is implemented.
See also the following guides by community members about using CLion for Swift development:
The project currently is emitting many warnings about
Sendable, this is expected and we are slowly working towards removing them.
Much of the project's internals use advanced synchronization patterns not recognized by sendable checks, so many of the warnings are incorrect but the compiler has no way of knowing this. We will be removing much of these internals as we move them to use the Swift actor runtime instead.
Documentation for this project is using the Doc Compiler, via the SwiftPM DocC plugin.
If you are not familiar with DocC syntax and general style, please refer to its documentation: https://developer.apple.com/documentation/docc
The project includes two helper scripts, to build and preview documentation.
To build documentation:
And to preview and browse the documentation as a web-page, run:
Which will result in an output similar to this:
======================================== Starting Local Preview Server http://localhost:8000/documentation/distributecluster
Integration tests include running actual multiple nodes of a cluster and e.g. killing them off to test the recovery mechanisms of the cluster.
brew install coreutilsto install
This project requires Swift 5.7+.
|Last commit: 2 weeks ago|
This release fixes a number of bugs preventing stable usage of the beta.2 release in a long running cluster (https://github.com/apple/swift-distributed-actors/pull/1059).
It also performs a number of destructive renames while we still have the ability to do so.
Module rename (!) The
DistributedActors module has been renamed to
DistributedCluster as it explains more precisely what this module is offering (the
UniqueNode types have been changed to
Cluster.Node respectively. See https://github.com/apple/swift-distributed-actors/pull/1077 for a more detailed explanation.
Internally we also adopted a new integration testing framework - offering MultiNode tests. This multi node testing framework will initially be matured internally before making it available to users outside the package. https://github.com/apple/swift-distributed-actors/pull/1055
mainby @ktoso in https://github.com/apple/swift-distributed-actors/pull/1067