swift-distributed-actors

1.0.0-beta.2

Peer-to-peer cluster implementation for Swift Distributed Actors
apple/swift-distributed-actors

What's New

1.0.0-beta.2

2022-07-28T03:59:38Z

This beta release marks major improvements in all surface APIs and completes most of the public surface move to distributed actors and async await. We also added more documentation and will continue adding more examples and guides about using and deploying distributed actor clusters.

A few API changes may still happen like making more methods async etc.

Documentation

Latest beta documentation is hosted on github pages.

Milestone

The 1.0.0-beta.2 milestone contains all closed issues for your reference.

What's Changed

  • Make sure to cancel listing when task is cancelled by @yim-lee in #966
  • Receptionist should flush registrations in order by version by @yim-lee in #967
  • Update receptionist tests by @yim-lee in #968
  • Make ClusterControl.membershipSnapshot async property by @yim-lee in #969
  • Add API to 'await joining cluster' by @yim-lee in #972
  • Safer lifecycle watch api by @ktoso in #961
  • =docker Fix 5.7 docker image name by @ktoso in #974
  • Codable improvements for ActorID tags by @ktoso in #915
  • !context store lifecycle in DistributedActorContext; internal only by @ktoso in #976
  • fix wrong cross module usage; seems this was not caught by CI / SwiftPM by @ktoso in #981
  • Use #filePath instead of #file by @yim-lee in #984
  • update swift tools version and required apple platforms by @JaapWijnen in #982
  • Fix #filePath related warnings by @yim-lee in #985
  • Use AsyncTimerSequence from swift-async-algorithms by @yim-lee in #986
  • Implement setting actor metadata with property wrapper fields by @ktoso in #988
  • Dead letter when remote call target is dead by @yim-lee in #989
  • Add ability to watch distributed actor with TestProbe by @yim-lee in #991
  • Silence OpLogDistributedReceptionist.sendAckOps timeout logs by @PopFlamingo in #996
  • Use correct error type for timeout error silencing by @PopFlamingo in #997
  • Remove all instances of AskResponse.wait() use by @ruslanskorb in #998
  • Fix logging level setting issue by @PopFlamingo in #1003
  • Implement ActorSingleton for DistributedActor by @yim-lee in #980
  • Support seed nodes by @yim-lee in #1005
  • Remove unused LamportClock type by @ktoso in #1007
  • Skip flaky test: ClusterLeaderActionsClusteredTests.test_singleLeader by @ktoso in #1008
  • Make installSwiftBacktrace public before we remove it by @ktoso in #1006
  • Implement generic distributed actor method call by @yim-lee in #1013
  • Change generic EventStream to ClusterEventStream and convert to actor by @yim-lee in #1012
  • Address remaining feedback in #1012 by @yim-lee in #1015
  • Distributed Actor support in Cluster Singleton by @ktoso in #1010
  • Add .devcontainer by @PopFlamingo in #995
  • Hide VersionVector by @yim-lee in #1023
  • Avoid errors in old toolchains, add to-be-removed convenience keyword by @ktoso in #1026
  • Make remote call errors configurable by @yim-lee in #1020
  • Make public enums into structs or hide them (part 1) by @yim-lee in #1025
  • Final polish and docs for singleton by @ktoso in #1022
  • Improve old betas compatibility by @ktoso in #1029
  • Make public enums into structs or hide them (part 2) by @yim-lee in #1028
  • -build remove toy "exec app" app by @ktoso in #1033
  • =receptionist lookup() trying to cast stub actor by @ktoso in #1032
  • Make public enums into structs or hide them (part 3 - final) by @yim-lee in #1037
  • -jazzy remove jazzy; we're only using docc now by @ktoso in #1038
  • [docc] Fail soundness on docc warnings (bad links), fix a few warnings by @ktoso in #1027

New Contributors

Thank you to all contributors!

Full Changelog: 1.0.0-beta.1.1...1.0.0-beta.2

Swift Distributed Actors

A peer-to-peer cluster actor system implementation for Swift.

NOTE: This project provides a cluster runtime implementation for the distributed actors language feature.

Introduction

Beta software

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.

What are Distributed Actors?

Distributed actors are an extension of the "local only" actor model offered by Swift with its actor keyword.

Distributed actors are declared using the distributed actor keywords (and importing the Distributed module), 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.

Samples

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 SampleDiningPhilosophers.

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.

Documentation

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.

Development

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

IDE Support: Xcode

Latest (beta) Xcode releases include complete support for the distributed language syntax (distributed actor, distributed func), so please use the latest Beta Xcode available to edit the project and any projects using distributed actors.

IDE Support: Other IDEs

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.

VSCode

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!

CLion

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:

Warnings

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 workflow

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:

./scripts/docs/generate_docc.sh

And to preview and browse the documentation as a web-page, run:

./scripts/docs/preview_docc.sh

Which will result in an output similar to this:

========================================
Starting Local Preview Server
	          http://localhost:8000/documentation/distributedactors

Integration tests

Integration tests include running actual multiple nodes of a cluster and e.g. killing them off to test the recovery mechanisms of the cluster.

Requirements:

  • macOS: brew install coreutils to install stdbuf

Supported Versions

This project requires Swift 5.7+.

Description

  • Swift Tools 5.7.0
View More Packages from this Author

Dependencies

Last updated: Sun Sep 25 2022 05:39:32 GMT-0500 (GMT-05:00)