Documentation Updates (apple#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`.

Sources/DistributedActors/Cluster/ClusterControl.swift

@@ -38,7 +38,7 @@ public enum OnDownActionStrategySettings {
     /// Take no (automatic) action upon noticing that this member is marked as [.down].
     ///
     /// When using this mode you should take special care to implement some form of shutting down of this node (!).
-    /// As a `Cluster.MemberStatus.down` node is effectively useless for the rest of the cluster -- i.e. other
+    /// As a ``Cluster/MemberStatus/down`` node is effectively useless for the rest of the cluster -- i.e. other
     /// members MUST refuse communication with this down node.
     case none
     /// Upon noticing that this member is marked as [.down], initiate a shutdown.

Sources/DistributedActors/Cluster/ClusterEventStream.swift

@@ -39,7 +39,7 @@ import NIO // Future
 /// e.g. when a partition in the cluster occurs. This is usually beneficial to _liveness_
 ///
 /// ### Leadership Change Cluster Event
-/// If a new member is selected as leader, a ``Cluster.Event`` carrying ``Cluster.LeadershipChange`` will be emitted.
+/// If a new member is selected as leader, a ``Cluster/Event`` carrying ``Cluster/LeadershipChange`` will be emitted.
 /// Other actors may subscribe to `ClusterSystem.cluster.events` in order to receive and react to such changes,
 /// e.g. if an actor should only perform its duties if it is residing on the current leader node.
 public protocol LeaderElection {
@@ -315,7 +315,7 @@ extension Leadership {
 
 extension ClusterSystemSettings {
     public enum LeadershipSelectionSettings {
-        /// No automatic leader selection, you can write your own logic and issue a `Cluster.LeadershipChange` `Cluster.Event` to the `system.cluster.events` event stream.
+        /// No automatic leader selection, you can write your own logic and issue a `Cluster.LeadershipChange` ``Cluster/Event`` to the `system.cluster.events` event stream.
         case none
         /// All nodes get ordered by their node addresses and the "lowest" is always selected as a leader.
         case lowestReachable(minNumberOfMembers: Int)

Sources/DistributedActors/Cluster/ClusterShell.swift

@@ -456,6 +456,15 @@ public class ClusterSystem: DistributedActorSystem, @unchecked Sendable {
         }
     }
 
+    /// Suspends until the ``ClusterSystem`` is terminated by a call to ``shutdown``.
+    var terminated: Void {
+        get async throws {
+            try await Task.detached {
+                try Shutdown(receptacle: self.shutdownReceptacle).wait()
+            }.value
+        }
+    }
+
     /// Forcefully stops this actor system and all actors that live within it.
     /// This is an asynchronous operation and will be executed on a separate thread.
     ///
@@ -856,30 +865,31 @@ extension ClusterSystem {
     public func resolve<Act>(id address: ActorID, as actorType: Act.Type) throws -> Act?
         where Act: DistributedActor
     {
-        self.log.info("RESOLVE: \(address)")
+        self.log.trace("Resolve: \(address)")
         guard self.cluster.uniqueNode == address.uniqueNode else {
-            self.log.info("Resolved \(address) as remote, on node: \(address.uniqueNode)")
+            self.log.trace("Resolved \(address) as remote, on node: \(address.uniqueNode)")
             return nil
         }
 
         return self.namingLock.withLock {
             guard let managed = self._managedDistributedActors.get(identifiedBy: address) else {
-                log.info("Unknown reference on our UniqueNode", metadata: [
-                    "actor/identity": "\(address.detailedDescription)",
+                log.trace("Resolved as remote reference", metadata: [
+                    "actor/identity": "\(address)",
                 ])
                 // TODO(distributed): throw here, this should be a dead letter
                 return nil
             }
 
-            log.info("Resolved as local instance", metadata: [
-                "actor/identity": "\(address)",
-                "actor": "\(managed)",
-            ])
             if let resolved = managed as? Act {
-                log.info("Resolved \(address) as local")
+                log.trace("Resolved as local instance", metadata: [
+                    "actor/identity": "\(address)",
+                    "actor": "\(managed)",
+                ])
                 return resolved
             } else {
-                log.info("Resolved \(address) as remote")
+                log.trace("Resolved as remote reference", metadata: [
+                    "actor/identity": "\(address)",
+                ])
                 return nil
             }
         }
@@ -1175,9 +1185,9 @@ public enum ClusterSystemError: DistributedActorSystemError {
     case shuttingDown(String)
 }
 
-/// Error thrown when unable to resolve an ``ActorIdentity``.
+/// Error thrown when unable to resolve an ``ActorID``.
 ///
-/// Refer to ``ClusterSystem/resolve(_:as:)`` or the distributed actors Swift Evolution proposal for details.
+/// Refer to ``ClusterSystem/resolve(id:as:)`` or the distributed actors Swift Evolution proposal for details.
 public enum ResolveError: DistributedActorSystemError {
     case illegalIdentity(ClusterSystem.ActorID)
 }

Sources/DistributedActors/Cluster/Downing/DowningSettings.swift

@@ -20,8 +20,10 @@ import Logging
 /// A "dead letter" is a message ("letter") that is impossible to deliver to its designated recipient.
 ///
 /// Often the reason for this is that the message was sent to given actor while it was still alive,
-/// yet once it arrived the destination node (or mailbox) the actor had already terminated, leaving the message to be dropped.
-/// Since such races can happen and point to problems in an actor based algorithm, such messages are not silently dropped,
+/// yet once it arrived the destination node the actor had already terminated, leaving the message to be dropped.
+///
+/// Since such races can happen when a distributed remote actor is e.g. passivated before it receives a remote call,
+/// and can be tricky to diagnose otherwise, such messages are  such messages are not silently dropped,
 /// but rather logged, with as much information as available (e.g. about the sender or source location of the initiating tell),
 /// such that when operating the system, bugs regarding undelivered messages can be spotted and fixed.
 ///