Merge pull request #60296 from apple/wip-distributed-docs

[Distributed] More API documentation

Author: swift-ci

stdlib/public/Distributed/DistributedActor.swift

@@ -17,29 +17,185 @@ import _Concurrency
 
 /// Common protocol to which all distributed actors conform implicitly.
 ///
-/// It is not possible to conform to this protocol manually explicitly.
-/// Only a 'distributed actor' declaration or protocol with 'DistributedActor'
-/// requirement may conform to this protocol.
+/// The `DistributedActor` protocol generalizes over all distributed actor types.
+/// Distributed actor types implicitly conform to this protocol.
 ///
-/// The 'DistributedActor' protocol provides the core functionality of any
-/// distributed actor.
+/// It is not possible to conform to this protocol by any other declaration other than a `distributed actor`.
 ///
-/// ## Implicit `Codable` conformance
-/// If created with an actor system whose `ActorID` is `Codable`, the
+/// It is possible to require a type to conform to the
+/// ``DistributedActor`` protocol by refining it with another protocol,
+/// or by using a generic constraint.
+///
+/// ## Synthesized properties
+/// For every concrete distributed actor declaration, the compiler synthesizes two properties: `actorSystem` and `id`.
+/// They witness the ``actorSystem`` and ``id`` protocol requirements of the ``DistributedActor`` protocol.
+///
+/// It is not possible to implement these properties explicitly in user code.
+/// These properties are `nonisolated` and accessible even if the instance is _remote_,
+/// because _all_ distributed actor references must store the actor system remote calls
+/// will be delivered through, as well as the id identifying the target of those calls.
+///
+/// ## The ActorSystem associated type
+/// Every distributed actor must declare what type of actor system
+/// it is part of by implementing the ``ActorSystem`` associated type requirement.
+///
+/// This causes a number of other properties of the actor to be inferred:
+///   - the ``SerializationRequirement`` that will be used at compile time to
+///     verify `distributed` target declarations are well formed,
+///   - if the distributed actor is `Codable`, based on the ``ID`` being Codable or not,
+///   - the type of the ``ActorSystem`` accepted in the synthesized default initializer.
+///
+/// A distributed actor must declare what type of actor system it is ready to
+/// work with by fulfilling the ``ActorSystem`` type member requirement:
+///
+/// ```swift
+/// distributed actor Greeter {
+///   typealias ActorSystem = GreetingSystem // which conforms to DistributedActorSystem
+///
+///   func greet() -> String { "Hello!" }
+/// }
+/// ```
+///
+/// ### The DefaultDistributedActorSystem type alias
+/// Since it is fairly common to only be using one specific type of actor system
+/// within a module or entire codebase, it is possible to declare the default type
+/// of actor system all distributed actors will be using in a module by declaring
+/// a `DefaultDistributedActorSystem` module wide typealias:
+///
+/// ```swift
+/// import Distributed
+/// import AmazingActorSystemLibrary
+///
+/// typealias DefaultDistributedActorSystem = AmazingActorSystem
+///
+/// distributed actor Greeter {} // ActorSystem == AmazingActorSystem
+/// ```
+///
+/// This declaration makes all `distributed actor` declarations
+/// that do not explicitly specify an ``ActorSystem`` type alias to assume the
+/// `AmazingActorSystem` as their `ActorSystem`.
+///
+/// It is possible for a specific actor to override the system it is using,
+/// by declaring an ``ActorSystem`` type alias as usual:
+///
+/// ```swift
+/// typealias DefaultDistributedActorSystem = AmazingActorSystem
+///
+/// distributed actor Amazing {
+///   // ActorSystem == AmazingActorSystem
+/// }
+///
+/// distributed actor Superb {
+///   typealias ActorSystem = SuperbActorSystem
+/// }
+/// ```
+///
+/// In general the `DefaultDistributedActorSystem` should not be declared public,
+/// as picking the default should be left up to each specific module of a project.
+///
+/// ## Default initializer
+/// While classes and actors receive a synthesized *argument-free default
+/// initializer* (`init()`), distributed actors synthesize a default initializer
+/// that accepts a distributed actor system the actor is part of: `init(actorSystem:)`.
+///
+/// The accepted actor system must be of the `Self.ActorSystem` type, which
+/// must conform to the ``DistributedActorSystem`` protocol. This is required
+/// because distributed actors are always managed by a concrete
+/// distributed actor system and cannot exist on their own without one.
+///
+/// It is possible to explicitly declare a parameter-free initializer (`init()`),
+/// however the `actorSystem` property still must be assigned a concrete actor
+/// system instance the actor shall be part of.
+///
+/// In general it is recommended to always have an `actorSystem` parameter as
+/// the last non-defaulted non-closure parameter in every actor's
+/// initializer parameter list. This way it is simple to swap in a "test actor
+/// system" instance in unit tests, and avoid relying on global state which could
+/// make testing more difficult.
+///
+/// ## Implicit properties
+/// Every concrete `distributed actor` type receives two synthesized properties,
+/// which implement the protocol requirements of this protocol: `id` and `actorSystem`.
+///
+/// ### Property: Actor System
+/// The ``actorSystem`` property is an important part of every distributed actor's lifecycle management.
+///
+/// Both initialization as well as de-initialization require interactions with the actor system,
+/// and it is the actor system that handles all remote interactions of an actor, by both sending
+/// or receiving remote calls made on the actor.
+///
+/// The ``actorSystem`` property must be assigned in every designated initializer
+/// of a distributed actor explicitly. It is highly recommended to make it a
+/// parameter of every distributed actor initializer, and simply forward the
+/// value to the stored property, like this:
+///
+/// ```swift
+/// init(name: String, actorSystem: Self.ActorSystem) {
+///   self.name = name
+///   self.actorSystem = actorSystem
+/// }
+/// ```
+///
+/// Forgetting to initialize the actor system, will result in a compile time error:
+///
+/// ```swift
+/// // BAD
+/// init(name: String, actorSystem: Self.ActorSystem) {
+///   self.name = name
+///   // BAD, will cause compile-time error; the `actorSystem` was not initialized.
+/// }
+/// ```
+///
+/// ### Property: Distributed Actor Identity
+/// ``id`` is assigned by the actor system during the distributed actor's
+/// initialization, and cannot be set or mutated by the actor itself.
+///
+/// ``id`` is the effective identity of the actor, and is used in equality checks,
+/// as well as the actor's synthesized ``Codable`` conformance if the ``ID`` type
+/// conforms to ``Codable``.
+///
+/// ## Automatic Conformances
+///
+/// ### Hashable and Identifiable conformance
+/// Every distributed actor conforms to the `Hashable` and `Identifiable` protocols.
+/// Its identity is strictly driven by its ``id``, and therefore hash and equality
+/// implementations directly delegate to the ``id`` property.
+///
+/// Comparing a local distributed actor instance and a remote reference to it
+/// (both using the same ``id``) always returns true, as they both conceptually
+/// point at the same distributed actor.
+///
+/// It is not possible to implement these protocols relying on the actual actor's
+/// state, because it may be remote and the state may not be available. In other
+/// words, since these protocols must be implemented using `nonisolated` functions,
+/// only `nonisolated` `id` and `actorSystem` properties are accessible for their
+/// implementations.
+///
+/// ### Implicit Codable conformance
+/// If created with an actor system whose ``DistributedActorSystem/ActorID`` is ``Codable``, the
 /// compiler will synthesize code for the concrete distributed actor to conform
-/// to `Codable` as well. This is necessary to support distributed calls where
-/// the `SerializationRequirement` is `Codable` and thus users may want to pass
-/// actors as arguments to remote calls.
-///
-/// The synthesized implementations use a single `SingleValueContainer` to
-/// encode/decode the `self.id` property of the actor. The `Decoder` required
-/// `init(from:)` is implemented by retrieving an actor system from the
-/// decoders' `userInfo`, effectively like this:
-/// `decoder.userInfo[.actorSystemKey] as? ActorSystem`. The obtained actor
-/// system is then used to `resolve(id:using:)` the decoded ID.
-///
-/// Use the `CodingUserInfoKey.actorSystemKey` to provide the necessary
+/// to ``Codable`` as well.
+///
+/// This is necessary to support distributed calls where the `SerializationRequirement`
+/// is ``Codable`` and thus users may want to pass actors as arguments to remote calls.
+///
+/// The synthesized implementations use a single ``SingleValueEncodingContainer`` to
+/// encode/decode the ``id`` property of the actor. The ``Decoder`` required
+/// ``Decoder/init(from:)`` is implemented by retrieving an actor system from the
+/// decoders' `userInfo`, effectively like as follows:
+///
+/// ```swift
+/// decoder.userInfo[.actorSystemKey] as? ActorSystem
+// ```
+///
+/// The such obtained actor system is then used to ``resolve(id:using:)`` the decoded ``ID``.
+///
+/// Use the ``CodingUserInfoKey/actorSystemKey`` to provide the necessary
 /// actor system for the decoding initializer when decoding a distributed actor.
+///
+/// - SeeAlso: ``DistributedActorSystem``
+/// - SeeAlso: ``Actor``
+/// - SeeAlso: ``AnyActor``
 @available(SwiftStdlib 5.7, *)
 public protocol DistributedActor: AnyActor, Identifiable, Hashable
   where ID == ActorSystem.ActorID,
@@ -58,17 +214,32 @@ public protocol DistributedActor: AnyActor, Identifiable, Hashable
   /// to return the same exact resolved actor instance, however all the references would
   /// represent logically references to the same distributed actor, e.g. on a different node.
   ///
-  /// Conformance to this requirement is synthesized automatically for any
-  /// `distributed actor` declaration.
+  /// Depending on the capabilities of the actor system producing the identifiers,
+  /// the `ID` may also be used to store instance specific metadata.
+  ///
+  /// ## Synthesized property
+  ///
+  /// In concrete distributed actor declarations, a witness for this protocol requirement is synthesized by the compiler.
+  ///
+  /// It is not possible to assign a value to the `id` directly; instead, it is assigned during an actors `init` (or `resolve`),
+  /// by the managing actor system.
   nonisolated override var id: ID { get }
 
-  /// The `ActorSystem` that is managing this distributed actor.
+  /// The ``DistributedActorSystem`` that is managing this distributed actor.
   ///
-  /// It is immutable and equal to the system passed in the local/resolve
-  /// initializer.
+  /// It is immutable and equal to the system assigned during the distributed actor's local initializer
+  /// (or to the system passed to the ``resolve(id:using:)`` static function).
   ///
-  /// Conformance to this requirement is synthesized automatically for any
-  /// `distributed actor` declaration.
+  /// ## Synthesized property
+  ///
+  /// In concrete distributed actor declarations, a witness for this protocol requirement is synthesized by the compiler.
+  ///
+  /// It is required to assign an initial value to the `actorSystem` property inside a distributed actor's designated initializer.
+  /// Semantically, it can be treated as a `let` declaration, that must be assigned in order to fully-initialize the instance.
+  ///
+  /// If a distributed actor declares no initializer, its default initializer will take the shape of `init(actorSystem:)`,
+  /// and initialize this property using the passed ``DistributedActorSystem``. If any user-defined initializer exists,
+  /// the default initializer is not synthesized, and all the user-defined initializers must take care to initialize this property.
   nonisolated var actorSystem: ActorSystem { get }
 
   /// Resolves the passed in `id` against the `system`, returning
@@ -81,6 +252,8 @@ public protocol DistributedActor: AnyActor, Identifiable, Hashable
   /// the system, allowing it to take over the remote messaging with the
   /// remote actor instance.
   ///
+  /// - Postcondition: upon successful return, the returned actor's ``id`` and ``actorSystem`` properties
+  ///                  will be equal to the values passed as parameters to this method.
   /// - Parameter id: identity uniquely identifying a, potentially remote, actor in the system
   /// - Parameter system: `system` which should be used to resolve the `identity`, and be associated with the returned actor
   static func resolve(id: ID, using system: ActorSystem) throws -> Self
@@ -90,10 +263,17 @@ public protocol DistributedActor: AnyActor, Identifiable, Hashable
 
 @available(SwiftStdlib 5.7, *)
 extension DistributedActor {
+
+  /// A distributed actor's hash and equality is implemented by directly delegating to its ``id``.
+  ///
+  /// For more details see the "Hashable and Identifiable conformance" section of ``DistributedActor``.
   nonisolated public func hash(into hasher: inout Hasher) {
     self.id.hash(into: &hasher)
   }
 
+  /// A distributed actor's hash and equality is implemented by directly delegating to its ``id``.
+  ///
+  /// For more details see the "Hashable and Identifiable conformance" section of ``DistributedActor``.
   nonisolated public static func ==(lhs: Self, rhs: Self) -> Bool {
     lhs.id == rhs.id
   }
@@ -102,12 +282,31 @@ extension DistributedActor {
 // ==== Codable conformance ----------------------------------------------------
 
 extension CodingUserInfoKey {
+
+  /// Key which is required to be set on a `Decoder`'s `userInfo` while attempting
+  /// to `init(from:)` a `DistributedActor`. The stored value under this key must
+  /// conform to ``DistributedActorSystem``.
+  ///
+  /// Forgetting to set this key will result in that initializer throwing, because
+  /// an actor system is required in order to call ``DistributedActor/resolve(id:using:)`` using it.
   @available(SwiftStdlib 5.7, *)
   public static let actorSystemKey = CodingUserInfoKey(rawValue: "$distributed_actor_system")!
 }
 
 @available(SwiftStdlib 5.7, *)
 extension DistributedActor /*: implicitly Decodable */ where Self.ID: Decodable {
+
+  /// Initializes an instance of this distributed actor by decoding its ``id``,
+  /// and passing it to the ``DistributedActorSystem`` obtained from `decoder.userInfo[actorSystemKey]`.
+  ///
+  /// ## Requires: The decoder must have the ``CodingUserInfoKey/actorSystemKey`` set to
+  /// the ``ActorSystem`` that this actor expects, as it will be used to call ``DistributedActor/resolve(id:using:)``
+  /// on, in order to obtain the instance this initializer should return.
+  ///
+  /// - Parameter decoder: used to decode the ``ID`` of this distributed actor.
+  /// - Throws: If the actor system value in `decoder.userInfo` is missing or mis-typed;
+  ///           the `ID` fails to decode from the passed `decoder`;
+  //            or if the ``DistributedActor/resolve(id:using:)`` method invoked by this initializer throws.
   nonisolated public init(from decoder: Decoder) throws {
     guard let system = decoder.userInfo[.actorSystemKey] as? ActorSystem else {
       throw DistributedActorCodingError(message:
@@ -122,6 +321,8 @@ extension DistributedActor /*: implicitly Decodable */ where Self.ID: Decodable
 
 @available(SwiftStdlib 5.7, *)
 extension DistributedActor /*: implicitly Encodable */ where Self.ID: Encodable {
+
+  /// Encodes the `actor.id` as a single value into the passed `encoder`.
   nonisolated public func encode(to encoder: Encoder) throws {
     var container = encoder.singleValueContainer()
     try container.encode(self.id)
@@ -157,9 +358,17 @@ extension DistributedActor {
 
 // ==== isRemote / isLocal -----------------------------------------------------
 
+/// Verifies if the passed ``DistributedActor`` conforming type is a remote reference.
+/// Passing a type not conforming to ``DistributedActor`` may result in undefined behavior.
+///
+/// Official API to perform this task is `whenLocal`.
 @_silgen_name("swift_distributed_actor_is_remote")
 public func __isRemoteActor(_ actor: AnyObject) -> Bool
 
+/// Verifies if the passed ``DistributedActor`` conforming type is a local reference.
+/// Passing a type not conforming to ``DistributedActor`` may result in undefined behavior.
+///
+/// Official API to perform this task is `whenLocal`.
 public func __isLocalActor(_ actor: AnyObject) -> Bool {
   return !__isRemoteActor(actor)
 }