Documentation Updates (#942)

* fix readme

* rename StashError

* rename ActorSystem files to ClusterSystem files; document init

* introduction

* document lifecycle watch

* cluster lifecycle image

* fix rename refactoring not having worked...

* [System] implement system.terminated

* wip on more cluster docs

* no more warnings except in NIO

Author: ktoso

Docs/images/remote_watch_terminated.graffle/data.plist

@@ -43,7 +43,7 @@ typealias DefaultDistributedActorSystem = ClusterSystem
         let time = TimeAmount.seconds(20)
 
         switch CommandLine.arguments.dropFirst().first {
-        case "dist":
+        case "dist", "distributed":
             try! await DistributedDiningPhilosophers().run(for: time)
         default:
             try! await DiningPhilosophers().run(for: time)

Docs/images/remote_watch_terminated.png

@@ -68,7 +68,7 @@ internal class ActorSingletonProxy<Message: ActorMessage> {
     var behavior: _Behavior<Message> {
         .setup { context in
             if context.system.settings.enabled {
-                // Subscribe to `Cluster.Event` in order to update `targetNode`
+                // Subscribe to ``Cluster/Event`` in order to update `targetNode`
                 context.system.cluster.events.subscribe(
                     context.subReceive(_SubReceiveId(id: "clusterEvent-\(context.name)"), Cluster.Event.self) { event in
                         try self.receiveClusterEvent(context, event)
@@ -196,7 +196,7 @@ internal class ActorSingletonProxy<Message: ActorMessage> {
                 context.log.trace("Stashed message: \(message)", metadata: self.metadata(context))
             } catch {
                 switch error {
-                case StashError.full:
+                case _StashError.full:
                     // TODO: log this warning only "once in while" after buffer becomes full
                     context.log.warning("Buffer is full. Messages might start getting disposed.", metadata: self.metadata(context))
                     // Move the oldest message to dead letters to make room

README.md

@@ -17,6 +17,9 @@ import Distributed
 // ==== ----------------------------------------------------------------------------------------------------------------
 // MARK: ActorAddress
 
+/// The type of `ID` assigned to all distributed actors managed by the ``ClusterSystem``.
+public typealias ActorID = ActorAddress
+
 /// Uniquely identifies a DistributedActor within the cluster.
 ///
 /// It is assigned by the `ClusterSystem` at initialization time of a distributed actor,
@@ -50,7 +53,6 @@ import Distributed
 ///
 /// For example: `sact://[email protected]:7337/user/wallet/id-121242`.
 /// Note that the `ActorIncarnation` is not printed by default in the String representation of a path, yet may be inspected on demand.
-@available(macOS 10.15, *)
 public struct ActorAddress: @unchecked Sendable {
     /// Knowledge about a node being `local` is purely an optimization, and should not be relied on by actual code anywhere.
     /// It is on purpose not exposed to end-user code as well, and must remain so to not break the location transparency promises made by the runtime.

Samples/Sources/SampleDiningPhilosophers/boot.swift

@@ -114,7 +114,7 @@ extension Cluster {
             self.members(withStatus: [status], reachability: reachability)
         }
 
-        /// Returns all members that are part of this membership, and have the any ``Cluster.MemberStatus`` that is part
+        /// Returns all members that are part of this membership, and have the any ``Cluster/MemberStatus`` that is part
         /// of the `statuses` passed in and `reachability` status.
         ///
         /// - Parameters:
@@ -574,7 +574,7 @@ extension Cluster.Membership {
 // MARK: Applying Cluster.Event to Membership
 
 extension Cluster.Membership {
-    /// Applies any kind of `Cluster.Event` to the `Membership`, modifying it appropriately.
+    /// Applies any kind of ``Cluster/Event`` to the `Membership`, modifying it appropriately.
     /// This apply does not yield detailed information back about the type of change performed,
     /// and is useful as a catch-all to keep a `Membership` copy up-to-date, but without reacting on any specific transition.
     ///

Sources/ActorSingletonPlugin/ActorSingletonProxy.swift

@@ -35,7 +35,7 @@ public struct ClusterControl {
     ///
     /// Consider subscribing to `cluster.events` in order to react to membership changes dynamically, and never miss a change.
     ///
-    /// It is guaranteed that a `membershipSnapshot` is always at-least as up-to-date as an emitted `Cluster.Event`.
+    /// It is guaranteed that a `membershipSnapshot` is always at-least as up-to-date as an emitted ``Cluster/Event``.
     /// It may be "ahead" however, for example if a series of 3 events are published closely one after another,
     /// if one were to observe the `cluster.membershipSnapshot` when receiving the first event, it may already contain
     /// information related to the next two incoming events. For that reason is recommended to stick to one of the ways
@@ -115,7 +115,7 @@ public struct ClusterControl {
         self.ref.tell(.command(.downCommand(self.uniqueNode.node)))
     }
 
-    /// Mark *any* currently known member as `Cluster.MemberStatus.down`.
+    /// Mark *any* currently known member as ``Cluster/MemberStatus/down``.
     ///
     /// Beware that this API is not very precise and, if possible, the `down(Cluster.Member)` is preferred, as it indicates
     /// the downing intent of a *specific* actor system instance, rather than any system running on the given host-port pair.

Sources/DistributedActors/ActorAddress.swift

@@ -15,7 +15,7 @@
 import Logging
 
 /// Specialized event stream behavior which takes into account emitting a snapshot event on first subscription,
-/// followed by a stream of `Cluster.Event`s.
+/// followed by a stream of ``Cluster/Event``s.
 ///
 /// This ensures that every subscriber to cluster events never misses any of the membership events, meaning
 /// it is possible for anyone to maintain a local up-to-date copy of `Membership` by applying all these events to that copy.
@@ -26,7 +26,7 @@ internal enum ClusterEventStream {
 
                 // We maintain a snapshot i.e. the "latest version of the membership",
                 // in order to eagerly publish it to anyone who subscribes immediately,
-                // followed by joining them to the subsequent `Cluster.Event` publishes.
+                // followed by joining them to the subsequent ``Cluster/Event`` publishes.
                 //
                 // Thanks to this, any subscriber immediately gets a pretty recent view of the membership,
                 // followed by the usual updates via events. Since all events are published through this

Sources/DistributedActors/Cluster/Cluster+Membership.swift

@@ -313,7 +313,7 @@ internal class ClusterShell {
         case inbound(InboundMessage)
         /// Used to request making a change to the membership owned by the ClusterShell;
         /// Issued by downing or leader election and similar facilities. Thanks to centralizing the application of changes,
-        /// we can ensure that a `Cluster.Event` is signalled only once, and only when it is really needed.
+        /// we can ensure that a ``Cluster/Event`` is signalled only once, and only when it is really needed.
         /// E.g. signalling a down twice for whatever reason, needs not be notified two times to all subscribers of cluster events.
         ///
         /// If the passed in event applied to the current membership is an effective change, the change will be published using the `system.cluster.events`.