diff --git a/src/contrib/cluster/Akka.Cluster.Sharding.Tests.MultiNode/AsyncWriteProxyEx.cs b/src/contrib/cluster/Akka.Cluster.Sharding.Tests.MultiNode/AsyncWriteProxyEx.cs index 2583296f5c0..31212646c95 100644 --- a/src/contrib/cluster/Akka.Cluster.Sharding.Tests.MultiNode/AsyncWriteProxyEx.cs +++ b/src/contrib/cluster/Akka.Cluster.Sharding.Tests.MultiNode/AsyncWriteProxyEx.cs @@ -53,15 +53,15 @@ protected AsyncReplayTimeoutException(SerializationInfo info, StreamingContext c } /// - /// TBD + /// Message that supplies the actor used by the proxy as its journal store. /// [Serializable] public sealed class SetStore { /// - /// TBD + /// Creates a message containing the target journal-store actor. /// - /// TBD + /// The actor that handles journal protocol messages. /// /// This exception is thrown when the specified is undefined. /// @@ -69,7 +69,7 @@ public SetStore(IActorRef store) => Store = store ?? throw new ArgumentNullException(nameof(store), "SetStore requires non-null reference to store actor"); /// - /// TBD + /// The journal-store actor supplied to the proxy. /// public readonly IActorRef Store; } @@ -92,7 +92,7 @@ private InitTimeout() { } private IActorRef _store; /// - /// TBD + /// Initializes the journal proxy and prepares a timeout while it waits for its store actor. /// protected AsyncWriteProxyEx() { @@ -102,12 +102,12 @@ protected AsyncWriteProxyEx() } /// - /// TBD + /// The maximum wait before the proxy stops stashing messages for store initialization. /// public abstract TimeSpan Timeout { get; } /// - /// TBD + /// Starts the initialization timeout before the journal's base startup logic runs. /// public override void AroundPreStart() { @@ -116,11 +116,11 @@ public override void AroundPreStart() } /// - /// TBD + /// Stashes messages until a store is supplied or the initialization timeout expires, then delegates normal handling. /// - /// TBD - /// TBD - /// TBD + /// The journal's receive handler. + /// The incoming message to process or stash. + /// true when initialization handling consumes the message; otherwise, the base journal result. protected internal override bool AroundReceive(Receive receive, object message) { if (_isInitialized) @@ -198,18 +198,18 @@ protected override Task DeleteMessagesToAsync(string persistenceId, long toSeque } /// - /// TBD + /// Replays messages from the configured store through a mediator that invokes the recovery callback and completes the replay task. /// - /// TBD - /// TBD - /// TBD - /// TBD - /// TBD - /// TBD + /// The actor context used to create a local replay mediator. + /// The persistence identifier being recovered. + /// The first sequence number to replay. + /// The last sequence number to replay. + /// The maximum number of messages to replay. + /// The callback invoked for each replayed persistent representation. /// /// This exception is thrown when the store has not been initialized. /// - /// TBD + /// A task that completes when replay succeeds and faults when the store reports failure or the local inactivity timeout elapses. public override Task ReplayMessagesAsync(IActorContext context, string persistenceId, long fromSequenceNr, long toSequenceNr, long max, Action recoveryCallback) { if (_store == null) @@ -253,7 +253,7 @@ private Task StoreNotInitialized() } /// - /// TBD + /// The stash used while waiting for the store actor to be set. /// public IStash Stash { get; set; } @@ -261,7 +261,7 @@ private Task StoreNotInitialized() } /// - /// TBD + /// Receives replay messages from the journal store, invokes the recovery callback, and completes or times out the replay request. /// internal class ReplayMediator : ActorBase { @@ -270,11 +270,11 @@ internal class ReplayMediator : ActorBase private readonly TimeSpan _replayTimeout; /// - /// TBD + /// Creates a mediator for one journal replay request. /// - /// TBD - /// TBD - /// TBD + /// The callback invoked for each replayed persistent representation. + /// The task completion source completed when replay succeeds or fails. + /// The inactivity timeout for receiving replay messages. public ReplayMediator(Action replayCallback, TaskCompletionSource replayCompletionPromise, TimeSpan replayTimeout) { _replayCallback = replayCallback; @@ -285,13 +285,13 @@ public ReplayMediator(Action replayCallback, TaskComp } /// - /// TBD + /// Processes replayed records, completion or failure notifications, and replay inactivity timeouts. /// - /// TBD + /// A replay protocol message or receive-timeout notification. /// /// This exception is thrown when the replay timed out due to inactivity. /// - /// TBD + /// true for replay protocol messages and timeouts handled here; otherwise, false. protected override bool Receive(object message) { switch (message) diff --git a/src/contrib/cluster/Akka.Cluster.Sharding.Tests.MultiNode/SnapshotStoreProxy.cs b/src/contrib/cluster/Akka.Cluster.Sharding.Tests.MultiNode/SnapshotStoreProxy.cs index a7964da8924..0f6e71de06d 100644 --- a/src/contrib/cluster/Akka.Cluster.Sharding.Tests.MultiNode/SnapshotStoreProxy.cs +++ b/src/contrib/cluster/Akka.Cluster.Sharding.Tests.MultiNode/SnapshotStoreProxy.cs @@ -32,7 +32,7 @@ private InitTimeout() { } private IActorRef _store; /// - /// TBD + /// Initializes the snapshot-store proxy in an uninitialized state with no target store actor. /// protected SnapshotStoreProxy() { @@ -42,19 +42,19 @@ protected SnapshotStoreProxy() } /// - /// TBD + /// The maximum wait before the proxy stops stashing messages for store initialization. /// public abstract TimeSpan Timeout { get; } /// - /// TBD + /// The stash used while waiting for the store actor to be set. /// public IStash Stash { get; set; } public ITimerScheduler Timers { get; set; } /// - /// TBD + /// Starts the initialization timeout before the snapshot store's base startup logic runs. /// public override void AroundPreStart() { @@ -63,11 +63,11 @@ public override void AroundPreStart() } /// - /// TBD + /// Stashes messages until a store is supplied or initialization times out, then delegates normal snapshot-store handling. /// - /// TBD - /// TBD - /// TBD + /// The snapshot store's receive handler. + /// The incoming message to process or stash. + /// true when initialization handling consumes the message; otherwise, the base snapshot-store result. protected internal override bool AroundReceive(Receive receive, object message) { if (_isInitialized) diff --git a/src/contrib/cluster/Akka.Cluster.Sharding/ClusterSharding.cs b/src/contrib/cluster/Akka.Cluster.Sharding/ClusterSharding.cs index 1f14a7f1444..0a11485d2e7 100644 --- a/src/contrib/cluster/Akka.Cluster.Sharding/ClusterSharding.cs +++ b/src/contrib/cluster/Akka.Cluster.Sharding/ClusterSharding.cs @@ -129,16 +129,16 @@ public static HashCodeMessageExtractor Create(int maxNumberOfShards, Func new Implementation(maxNumberOfShards, entityIdExtractor, messageExtractor); /// - /// TBD + /// Gets the maximum shard count configured for this hash-based extractor. /// public readonly int MaxNumberOfShards; private readonly Dictionary _cachedIds; /// - /// TBD + /// Initializes the cache of shard ids from the configured shard count. /// - /// TBD + /// The number of shard id strings to cache, numbered from zero. protected HashCodeMessageExtractor(int maxNumberOfShards) { MaxNumberOfShards = maxNumberOfShards; @@ -150,18 +150,18 @@ protected HashCodeMessageExtractor(int maxNumberOfShards) } /// - /// TBD + /// Extracts the entity id from the incoming message. /// - /// TBD - /// TBD + /// The message received by the shard region. + /// The entity id, or when the message has no entity id. [MethodImpl(MethodImplOptions.AggressiveInlining)] public abstract EntityId? EntityId(Msg message); /// /// Default implementation pass on the message as is. /// - /// TBD - /// TBD + /// The message received by the shard region. + /// The message to deliver to the entity; the default implementation returns . [MethodImpl(MethodImplOptions.AggressiveInlining)] public virtual Msg? EntityMessage(Msg message) { @@ -169,10 +169,10 @@ protected HashCodeMessageExtractor(int maxNumberOfShards) } /// - /// TBD + /// Computes a shard id from the entity id in the message using this extractor's hash partitioning. /// - /// TBD - /// TBD + /// The message from which to extract an entity id. + /// A shard id, or when the extracted entity id is null or empty. [MethodImpl(MethodImplOptions.AggressiveInlining)] [Obsolete("Use ShardId(string, object?) instead. Since v1.5.15")] public virtual ShardId? ShardId(Msg message) @@ -373,7 +373,7 @@ public ClusterSharding(ExtendedActorSystem system) /// /// Default HOCON settings for cluster sharding. /// - /// TBD + /// The default cluster-sharding configuration with distributed-data defaults as fallback. public static Config DefaultConfig() { return ConfigurationFactory.FromResource("Akka.Cluster.Sharding.reference.conf") @@ -1422,11 +1422,11 @@ public async Task StartProxyAsync(string typeName, string role, IMess /// method before it /// can be used here. Messages to the entity is always sent via the . /// - /// TBD + /// The entity type name registered with sharding. /// /// Thrown when shard region for provided has not been started yet. /// - /// TBD + /// The registered local shard region or proxy for the entity type. public IActorRef ShardRegion(string typeName) #pragma warning restore CS0419 // Ambiguous reference in cref attribute { @@ -1518,8 +1518,8 @@ public interface IMessageExtractor /// If is returned the message will be `unhandled`, i.e. posted as `Unhandled` /// messages on the event stream /// - /// TBD - /// TBD + /// The incoming message to inspect. + /// The entity id extracted from the message, or when the message is not handled. EntityId? EntityId(Msg message); /// @@ -1528,8 +1528,8 @@ public interface IMessageExtractor /// message to support wrapping in message envelope that is unwrapped before /// sending to the entity actor. /// - /// TBD - /// TBD + /// The incoming message to inspect. + /// The message to send to the entity, which may be a wrapper or the original message. Msg? EntityMessage(Msg message); /// diff --git a/src/contrib/cluster/Akka.Cluster.Sharding/ClusterShardingGuardian.cs b/src/contrib/cluster/Akka.Cluster.Sharding/ClusterShardingGuardian.cs index 0048f25f3e7..45e1cbd9784 100644 --- a/src/contrib/cluster/Akka.Cluster.Sharding/ClusterShardingGuardian.cs +++ b/src/contrib/cluster/Akka.Cluster.Sharding/ClusterShardingGuardian.cs @@ -28,20 +28,20 @@ private sealed record ReplicatorTerminated(string Role, IActorRef Replicator) : INoSerializationVerificationNeeded; /// - /// TBD + /// Internal reply indicating that a shard region or proxy has been started. /// [Serializable] public sealed class Started : INoSerializationVerificationNeeded { /// - /// TBD + /// The actor reference of the started shard region or proxy. /// public readonly IActorRef ShardRegion; /// - /// TBD + /// Creates a successful guardian reply for the started shard region or proxy. /// - /// TBD + /// The actor reference of the started region or proxy. public Started(IActorRef shardRegion) { ShardRegion = shardRegion; @@ -49,44 +49,44 @@ public Started(IActorRef shardRegion) } /// - /// TBD + /// Internal guardian command to start a shard region for an entity type. /// [Serializable] public sealed class Start : INoSerializationVerificationNeeded { /// - /// TBD + /// The entity type name to register with sharding. /// public readonly string TypeName; /// - /// TBD + /// Factory that creates actor properties for an entity id. /// public readonly Func EntityProps; /// - /// TBD + /// The sharding settings for the region and its coordinator. /// public readonly ClusterShardingSettings Settings; public readonly IMessageExtractor MessageExtractor; /// - /// TBD + /// The allocation and rebalance strategy for shards of this entity type. /// public readonly IShardAllocationStrategy AllocationStrategy; /// - /// TBD + /// The message sent to an entity during shard handoff to request that it stops. /// public readonly object HandOffStopMessage; /// - /// TBD + /// Creates a guardian command containing the configuration needed to start a shard region. /// - /// TBD - /// TBD - /// TBD - /// - /// TBD - /// TBD + /// The entity type name to register. + /// A factory that creates actor properties for an entity id. + /// The settings for this shard region and its coordinator. + /// The functions used to extract entity ids, shard ids, and entity messages. + /// The strategy used to allocate and rebalance shards. + /// The message sent to an entity when its shard is handed off. /// /// This exception is thrown when the specified or is undefined. /// @@ -110,28 +110,28 @@ public Start( } /// - /// TBD + /// Internal guardian command to start a proxy for an entity type without hosting its entities on this node. /// [Serializable] public sealed class StartProxy : INoSerializationVerificationNeeded { /// - /// TBD + /// The entity type name to register with the proxy. /// public readonly string TypeName; /// - /// TBD + /// The sharding settings used by the proxy. /// public readonly ClusterShardingSettings Settings; public IMessageExtractor MessageExtractor; /// - /// TBD + /// Creates a guardian command containing the configuration needed to start a shard proxy. /// - /// TBD - /// TBD - /// + /// The entity type name to register. + /// The settings used by the proxy. + /// The functions used to extract entity ids, shard ids, and entity messages. /// /// This exception is thrown when the specified is undefined. /// @@ -163,7 +163,7 @@ public StartProxy( private readonly ConcurrentDictionary _typeLookup = new(); /// - /// TBD + /// Creates the guardian with the dictionaries used to track started regions and proxies. /// public ClusterShardingGuardian( ConcurrentDictionary regions, diff --git a/src/contrib/cluster/Akka.Cluster.Sharding/ClusterShardingSettings.cs b/src/contrib/cluster/Akka.Cluster.Sharding/ClusterShardingSettings.cs index edcbd5fd380..391225c949f 100644 --- a/src/contrib/cluster/Akka.Cluster.Sharding/ClusterShardingSettings.cs +++ b/src/contrib/cluster/Akka.Cluster.Sharding/ClusterShardingSettings.cs @@ -15,45 +15,45 @@ namespace Akka.Cluster.Sharding { /// - /// TBD + /// Timing, buffering, persistence, recovery, and shard-rebalance values used by cluster sharding. /// [Serializable] public class TuningParameters { /// - /// TBD + /// The backoff duration used when the coordinator is restarted after failure. /// public readonly TimeSpan CoordinatorFailureBackoff; /// - /// TBD + /// The interval at which a shard region retries unanswered coordinator requests. /// public readonly TimeSpan RetryInterval; /// - /// TBD + /// The maximum number of messages buffered by a shard region while waiting for shard location or startup. /// public readonly int BufferSize; /// - /// TBD + /// The timeout for a shard handoff to complete. /// public readonly TimeSpan HandOffTimeout; /// - /// TBD + /// The time a coordinator waits for a region to acknowledge that it is hosting a shard. /// public readonly TimeSpan ShardStartTimeout; /// - /// TBD + /// The backoff duration before restarting a shard after a failure while remembering entity state. /// public readonly TimeSpan ShardFailureBackoff; /// - /// TBD + /// The delay before a remembered entity that stopped without passivating is restarted, unless a message for it arrives first. /// public readonly TimeSpan EntityRestartBackoff; /// - /// TBD + /// The interval between coordinator checks for shards that may need rebalancing. /// public readonly TimeSpan RebalanceInterval; /// - /// TBD + /// The number of persisted events after which a snapshot is attempted for persistence-backed sharding state. /// public readonly int SnapshotAfter; /// @@ -65,11 +65,11 @@ public class TuningParameters /// public readonly int KeepNrOfBatches; /// - /// TBD + /// The shard-count difference that the legacy least-shard strategy must exceed before it selects shards for rebalance. /// public readonly int LeastShardAllocationRebalanceThreshold; /// - /// TBD + /// The maximum number of shards that the legacy least-shard strategy permits to rebalance concurrently. /// public readonly int LeastShardAllocationMaxSimultaneousRebalance; @@ -88,29 +88,29 @@ public class TuningParameters public readonly double LeastShardAllocationRelativeLimit; /// - /// TBD + /// Creates tuning parameters for shard-region buffering, coordinator and shard timing, entity recovery, snapshots, and rebalance behavior. /// - /// TBD - /// TBD - /// TBD - /// TBD - /// TBD - /// TBD - /// TBD - /// TBD - /// TBD + /// The backoff duration used when restarting a failed coordinator. + /// The interval between retries of unanswered coordinator requests. + /// The maximum number of messages a shard region buffers while resolving shard locations. + /// The timeout for shard handoff. + /// The time allowed for a region to acknowledge hosting a shard. + /// The delay before a shard is restarted after it terminates outside handoff when remembered entities are enabled. + /// The delay before restarting a remembered entity that stopped without passivating, if no message for it arrives first. + /// The interval between checks for shards to rebalance. + /// The number of persisted events after which sharding state snapshotting is attempted. /// Keep this number of old persistent batches - /// TBD - /// TBD - /// TBD - /// TBD - /// TBD - /// TBD - /// TBD - /// TBD - /// TBD - /// TBD - /// TBD + /// The eligible shard-count difference that the legacy strategy must exceed before selecting shards. + /// The maximum number of concurrent shard rebalances allowed by the legacy strategy. + /// The timeout for reading initial distributed sharding state and shard state. + /// The timeout for updating distributed sharding state and writing remembered-entity state. + /// The recovery strategy for remembered entities: all starts them together, while constant starts them in batches. + /// The interval between batches when is constant. + /// The number of entities started in each batch when is constant. + /// The number of replicas beyond a majority required for a coordinator-state write; selects all replicas. + /// The number of replicas beyond a majority required for a coordinator-state read; selects all replicas. + /// The absolute per-round shard-move limit used by the bounded least-shard strategy. + /// The fraction of known shards used to calculate the per-round limit for the bounded least-shard strategy. /// /// This exception is thrown when the specified is invalid. /// Acceptable values include: all | constant @@ -278,7 +278,7 @@ public enum RememberEntitiesStore } /// - /// TBD + /// Settings that control shard placement, coordinator state storage, entity passivation, and shard-region behavior. /// [Serializable] public sealed class ClusterShardingSettings : INoSerializationVerificationNeeded @@ -329,12 +329,12 @@ public sealed class ClusterShardingSettings : INoSerializationVerificationNeeded public readonly TuningParameters TuningParameters; /// - /// TBD + /// The settings used to run the sharding coordinator as a cluster singleton. /// public readonly ClusterSingletonManagerSettings CoordinatorSingletonSettings; /// - /// TBD + /// The optional lease configuration used by the coordinator singleton. /// public readonly LeaseUsageSettings LeaseSettings; @@ -343,8 +343,8 @@ public sealed class ClusterShardingSettings : INoSerializationVerificationNeeded /// /// Create settings from the default configuration `akka.cluster.sharding`. /// - /// TBD - /// TBD + /// The actor system whose akka.cluster.sharding and singleton configuration are read. + /// Settings populated from the actor system configuration. public static ClusterShardingSettings Create(ActorSystem system) { var config = system.Settings.Config.GetConfig("akka.cluster.sharding"); @@ -357,11 +357,11 @@ public static ClusterShardingSettings Create(ActorSystem system) } /// - /// TBD + /// Creates settings from the supplied sharding and coordinator-singleton configuration objects. /// - /// TBD - /// TBD - /// TBD + /// The akka.cluster.sharding configuration. + /// The configuration for the coordinator singleton. + /// Settings populated from the supplied configurations. public static ClusterShardingSettings Create(Config config, Config singletonConfig) { if (config.IsNullOrEmpty()) @@ -430,16 +430,16 @@ int ConfigMajorityPlus(string p) } /// - /// TBD + /// Creates settings with the selected role, entity memory behavior, persistence plugins, state-store mode, tuning values, and singleton configuration. /// - /// TBD - /// TBD - /// TBD - /// TBD - /// TBD - /// TBD - /// TBD - /// TBD + /// The cluster role required for nodes that host shard regions, or to allow any role. + /// Whether shards restore their previously active entities after restart or rebalance. + /// The journal plugin id used for persistence-backed sharding state. + /// The snapshot plugin id used for persistence-backed sharding state. + /// The idle period before automatic entity passivation; a non-positive value disables it, and remembered entities are not passivated this way. + /// The storage mode used for coordinator and shard state. + /// Timeouts, buffer limits, recovery options, snapshot settings, and rebalance limits. + /// The settings for the coordinator singleton. public ClusterShardingSettings( string role, bool rememberEntities, @@ -454,17 +454,17 @@ public ClusterShardingSettings( } /// - /// TBD + /// Creates settings with an optional lease for the coordinator singleton. /// - /// TBD - /// TBD - /// TBD - /// TBD - /// TBD - /// TBD - /// TBD - /// TBD - /// TBD + /// The cluster role required for nodes that host shard regions, or to allow any role. + /// Whether shards restore their previously active entities after restart or rebalance. + /// The journal plugin id used for persistence-backed sharding state. + /// The snapshot plugin id used for persistence-backed sharding state. + /// The idle period before automatic entity passivation; a non-positive value disables it, and remembered entities are not passivated this way. + /// The storage mode used for coordinator and shard state. + /// Timeouts, buffer limits, recovery options, snapshot settings, and rebalance limits. + /// The settings for the coordinator singleton. + /// Optional lease settings for the coordinator singleton. public ClusterShardingSettings( string role, bool rememberEntities, @@ -480,19 +480,19 @@ public ClusterShardingSettings( } /// - /// TBD + /// Creates settings with explicit remembered-entity storage and shard-region query timeout values. /// - /// TBD - /// TBD - /// TBD - /// TBD - /// TBD - /// TBD - /// TBD - /// TBD - /// TBD - /// TBD - /// TBD + /// The cluster role required for nodes that host shard regions, or to allow any role. + /// Whether shards restore their previously active entities after restart or rebalance. + /// The journal plugin id used for persistence-backed sharding state. + /// The snapshot plugin id used for persistence-backed sharding state. + /// The idle period before automatic entity passivation; a non-positive value disables it, and remembered entities are not passivated this way. + /// The storage mode used for coordinator and shard state. + /// The store used to remember entity ids when is enabled. + /// The timeout for queries that collect information from shard regions. + /// Timeouts, buffer limits, recovery options, snapshot settings, and rebalance limits. + /// The settings for the coordinator singleton. + /// Optional lease settings for the coordinator singleton. public ClusterShardingSettings( string role, bool rememberEntities, @@ -563,40 +563,40 @@ internal bool ShouldHostShard(Cluster cluster) internal bool ShouldPassivateIdleEntities => PassivateIdleEntityAfter > TimeSpan.Zero && !RememberEntities; /// - /// TBD + /// Returns a copy configured to host shard regions only on nodes with the specified cluster role. /// - /// TBD - /// TBD + /// The required cluster role, or to retain the current role. + /// A copy of these settings with the specified role. public ClusterShardingSettings WithRole(string role) { return Copy(role: role); } /// - /// TBD + /// Returns a copy with the selected remembered-entity behavior. /// - /// TBD - /// TBD + /// Whether active entity ids are remembered for shard restart and rebalance recovery. + /// A copy of these settings with the specified entity-memory behavior. public ClusterShardingSettings WithRememberEntities(bool rememberEntities) { return Copy(rememberEntities: rememberEntities); } /// - /// TBD + /// Returns a copy with the journal plugin id used for persistence-backed sharding state. /// - /// TBD - /// TBD + /// The plugin id, or to use an empty plugin id. + /// A copy of these settings with the specified journal plugin id. public ClusterShardingSettings WithJournalPluginId(string journalPluginId) { return Copy(journalPluginId: journalPluginId ?? string.Empty); } /// - /// TBD + /// Returns a copy with the snapshot plugin id used for persistence-backed sharding state. /// - /// TBD - /// TBD + /// The plugin id, or to use an empty plugin id. + /// A copy of these settings with the specified snapshot plugin id. public ClusterShardingSettings WithSnapshotPluginId(string snapshotPluginId) { return Copy(snapshotPluginId: snapshotPluginId ?? string.Empty); @@ -608,13 +608,13 @@ public ClusterShardingSettings WithStateStoreMode(StateStoreMode mode) } /// - /// TBD + /// Returns a copy with updated shard timing, buffering, recovery, persistence, and allocation parameters. /// - /// TBD + /// The tuning parameters to use. /// /// This exception is thrown when the specified is undefined. /// - /// TBD + /// A copy of these settings with the supplied tuning parameters. public ClusterShardingSettings WithTuningParameters(TuningParameters tuningParameters) { if (tuningParameters == null) @@ -639,13 +639,13 @@ public ClusterShardingSettings WithSupervisorStrategy(SupervisorStrategy supervi } /// - /// TBD + /// Returns a copy with the selected coordinator-singleton settings. /// - /// TBD + /// The settings to use for the coordinator singleton. /// /// This exception is thrown when the specified is undefined. /// - /// TBD + /// A copy of these settings with the supplied coordinator-singleton settings. public ClusterShardingSettings WithCoordinatorSingletonSettings(ClusterSingletonManagerSettings coordinatorSingletonSettings) { if (coordinatorSingletonSettings == null) diff --git a/src/contrib/cluster/Akka.Cluster.Sharding/EntityRecoveryStrategy.cs b/src/contrib/cluster/Akka.Cluster.Sharding/EntityRecoveryStrategy.cs index 2a143762723..e6cc57ee9df 100644 --- a/src/contrib/cluster/Akka.Cluster.Sharding/EntityRecoveryStrategy.cs +++ b/src/contrib/cluster/Akka.Cluster.Sharding/EntityRecoveryStrategy.cs @@ -68,12 +68,12 @@ private Task> ScheduleEntities(TimeSpan interval, IImmut } /// - /// Returns a Task that will be completed with the success or failure of the provided value after the specified duration. + /// Schedules the supplied asynchronous value factory after the specified duration and returns its result as a task. /// - /// TBD - /// TBD - /// TBD - /// TBD + /// The result type produced by the value factory. + /// The asynchronous factory to invoke after the delay. + /// The delay before invoking the factory. + /// The scheduler used to invoke the factory. private static Task After(TimeSpan timeout, IScheduler scheduler, Func> value) { var promise = new TaskCompletionSource(); @@ -99,7 +99,7 @@ public static class EnumerableExtensions /// Partitions elements in fixed size /// Credits to http://stackoverflow.com/a/13731854/465132 /// - /// TBD + /// The sequence whose elements are grouped. /// The number of elements per group public static IEnumerable> Grouped(this IEnumerable items, int size) { diff --git a/src/contrib/cluster/Akka.Cluster.Sharding/External/ExternalShardAllocation.cs b/src/contrib/cluster/Akka.Cluster.Sharding/External/ExternalShardAllocation.cs index a0342d1ef03..8fa278c1edc 100644 --- a/src/contrib/cluster/Akka.Cluster.Sharding/External/ExternalShardAllocation.cs +++ b/src/contrib/cluster/Akka.Cluster.Sharding/External/ExternalShardAllocation.cs @@ -42,10 +42,10 @@ private IExternalShardAllocationClient Client(string typeName) public class ExternalShardAllocationExtensionProvider : ExtensionIdProvider { /// - /// TBD + /// Creates the external shard-allocation extension for an actor system. /// - /// TBD - /// TBD + /// The extended actor system that owns the extension. + /// The new external shard-allocation extension. public override ExternalShardAllocation CreateExtension(ExtendedActorSystem system) { var extension = new ExternalShardAllocation(system); diff --git a/src/contrib/cluster/Akka.Cluster.Sharding/Internal/LeastShardAllocationStrategy.cs b/src/contrib/cluster/Akka.Cluster.Sharding/Internal/LeastShardAllocationStrategy.cs index 94903159906..79bd843ca9e 100644 --- a/src/contrib/cluster/Akka.Cluster.Sharding/Internal/LeastShardAllocationStrategy.cs +++ b/src/contrib/cluster/Akka.Cluster.Sharding/Internal/LeastShardAllocationStrategy.cs @@ -40,7 +40,7 @@ internal class LeastShardAllocationStrategy : AbstractLeastShardAllocationStrate private readonly double _relativeLimit; /// - /// TBD + /// Creates a strategy with per-round absolute and relative rebalance limits. /// /// The maximum number of shards that will be rebalanced in one rebalance round /// Fraction (< 1.0) of total number of (known) shards that will be rebalanced in one rebalance round @@ -51,11 +51,11 @@ public LeastShardAllocationStrategy(int absoluteLimit, double relativeLimit) } /// - /// TBD + /// Selects shards to rebalance when there is no rebalance already in progress. /// - /// TBD - /// TBD - /// TBD + /// The shards currently allocated to each region. + /// The shard identifiers whose rebalance has not completed. + /// The shard identifiers selected for a rebalance round, or an empty set when no rebalance is started. public override Task> Rebalance(IImmutableDictionary> currentShardAllocations, IImmutableSet rebalanceInProgress) { int Limit(int numberOfShards) diff --git a/src/contrib/cluster/Akka.Cluster.Sharding/PersistentShardCoordinator.cs b/src/contrib/cluster/Akka.Cluster.Sharding/PersistentShardCoordinator.cs index 81361b494ff..22aae3babeb 100644 --- a/src/contrib/cluster/Akka.Cluster.Sharding/PersistentShardCoordinator.cs +++ b/src/contrib/cluster/Akka.Cluster.Sharding/PersistentShardCoordinator.cs @@ -30,10 +30,10 @@ internal sealed class PersistentShardCoordinator : PersistentActor /// /// Factory method for the of the actor. /// - /// TBD - /// TBD - /// TBD - /// TBD + /// The sharding entity type name coordinated by this actor. + /// The settings used by the coordinator. + /// The strategy used to allocate and rebalance shards. + /// Local actor properties that construct a persistent coordinator with these arguments. internal static Props Props(string typeName, ClusterShardingSettings settings, IShardAllocationStrategy allocationStrategy) { return Actor.Props.Create(() => new PersistentShardCoordinator(typeName, settings, allocationStrategy)) @@ -69,10 +69,10 @@ IShardAllocationStrategy allocationStrategy public override string PersistenceId { get; } /// - /// TBD + /// Applies recognized coordinator events and snapshots during recovery, and initializes recovery-dependent state when recovery completes. /// - /// TBD - /// TBD + /// A persisted coordinator event, snapshot offer, or recovery lifecycle message. + /// true when this method handles the recovery message; false for an unsupported message. protected override bool ReceiveRecover(object message) { switch (message) @@ -146,10 +146,10 @@ protected override bool ReceiveRecover(object message) /// - /// TBD + /// Handles commands received before coordinator state initialization completes. /// - /// TBD - /// TBD + /// A coordinator command or persistence result received during initialization. + /// true when initialization handling recognizes the message; otherwise false. protected override bool ReceiveCommand(object message) { return WaitingForStateInitialized(message); @@ -213,12 +213,11 @@ private bool ReceiveSnapshotResult(object message) } /// - /// TBD + /// Requests a snapshot when due, then persists a coordinator event and invokes its handler after persistence. /// - /// TBD - /// TBD - /// TBD - /// TBD + /// The coordinator domain-event type being persisted. + /// The event to persist. + /// The callback passed to persistence for the persisted event. private void Update(TEvent e, Action handler) where TEvent : IDomainEvent { SaveSnapshotWhenNeeded(); diff --git a/src/contrib/cluster/Akka.Cluster.Sharding/Shard.cs b/src/contrib/cluster/Akka.Cluster.Sharding/Shard.cs index 3e5322f1775..c4a9a031526 100644 --- a/src/contrib/cluster/Akka.Cluster.Sharding/Shard.cs +++ b/src/contrib/cluster/Akka.Cluster.Sharding/Shard.cs @@ -141,13 +141,13 @@ public interface IShardQuery } /// - /// TBD + /// Query requesting the current shard id and the entity ids currently active in that shard. /// [Serializable] public sealed class GetCurrentShardState : IShardQuery, IClusterShardingSerializable { /// - /// TBD + /// Singleton query requesting the current state of a shard. /// public static readonly GetCurrentShardState Instance = new(); @@ -157,26 +157,26 @@ private GetCurrentShardState() } /// - /// TBD + /// Reply containing a shard id and the entity ids currently active in that shard. /// [Serializable] public sealed class CurrentShardState : IClusterShardingSerializable, IEquatable { /// - /// TBD + /// Gets the id of the shard described by this reply. /// public readonly ShardId ShardId; /// - /// TBD + /// Gets the entity ids currently active in this shard. /// public readonly IImmutableSet EntityIds; /// - /// TBD + /// Creates a shard-state reply from a shard id and its active entity ids. /// - /// TBD - /// TBD + /// The id of the shard. + /// The entity ids currently active in the shard. public CurrentShardState(ShardId shardId, IImmutableSet entityIds) { ShardId = shardId; @@ -220,13 +220,13 @@ public override string ToString() => } /// - /// TBD + /// Query requesting the id and entity count for this shard. /// [Serializable] public sealed class GetShardStats : IShardQuery, IClusterShardingSerializable { /// - /// TBD + /// Singleton query requesting shard statistics. /// public static readonly GetShardStats Instance = new(); @@ -239,26 +239,26 @@ private GetShardStats() } /// - /// TBD + /// Reply containing a shard id and the entity count reported by that shard. /// [Serializable] public sealed class ShardStats : IClusterShardingSerializable, IEquatable { /// - /// TBD + /// Gets the id of the shard described by this reply. /// public readonly ShardId ShardId; /// - /// TBD + /// Gets the entity count reported by the shard. /// public readonly int EntityCount; /// - /// TBD + /// Creates a shard-statistics reply. /// - /// TBD - /// TBD + /// The id of the shard. + /// The entity count reported by the shard. public ShardStats(ShardId shardId, int entityCount) { ShardId = shardId; diff --git a/src/contrib/cluster/Akka.Cluster.Sharding/ShardAllocationStrategy.cs b/src/contrib/cluster/Akka.Cluster.Sharding/ShardAllocationStrategy.cs index d44223d2ea0..9aeb7a49509 100644 --- a/src/contrib/cluster/Akka.Cluster.Sharding/ShardAllocationStrategy.cs +++ b/src/contrib/cluster/Akka.Cluster.Sharding/ShardAllocationStrategy.cs @@ -146,10 +146,10 @@ public class LeastShardAllocationStrategy : AbstractLeastShardAllocationStrategy private readonly int _maxSimultaneousRebalance; /// - /// TBD + /// Creates the legacy least-shard allocation strategy with the supplied rebalance threshold and concurrency limit. /// - /// TBD - /// TBD + /// The eligible shard-count difference that must be exceeded before this strategy selects shards for rebalancing. + /// The maximum number of shards this strategy permits to be in rebalance at once. public LeastShardAllocationStrategy(int rebalanceThreshold, int maxSimultaneousRebalance) { _rebalanceThreshold = rebalanceThreshold; @@ -157,11 +157,11 @@ public LeastShardAllocationStrategy(int rebalanceThreshold, int maxSimultaneousR } /// - /// TBD + /// Selects shards for another rebalance round when the eligible shard-count difference exceeds the configured threshold. /// - /// TBD - /// TBD - /// TBD + /// The shard regions and the shard ids currently allocated to each region. + /// Shard ids already being moved; these are excluded from selection and count toward the concurrency limit. + /// A task containing the shard ids selected for this round, or an empty set when no rebalance is selected. public override Task> Rebalance(IImmutableDictionary> currentShardAllocations, IImmutableSet rebalanceInProgress) { if (rebalanceInProgress.Count < _maxSimultaneousRebalance) diff --git a/src/contrib/cluster/Akka.Cluster.Sharding/ShardCoordinator.cs b/src/contrib/cluster/Akka.Cluster.Sharding/ShardCoordinator.cs index ece1f65338c..c3dca1bdad8 100644 --- a/src/contrib/cluster/Akka.Cluster.Sharding/ShardCoordinator.cs +++ b/src/contrib/cluster/Akka.Cluster.Sharding/ShardCoordinator.cs @@ -60,7 +60,7 @@ internal sealed class Register : ICoordinatorCommand, IDeadLetterSuppression, IE /// /// Creates a new request for a given . /// - /// TBD + /// The region actor registering with the coordinator. public Register(IActorRef shardRegion) { ShardRegion = shardRegion; @@ -108,7 +108,7 @@ internal sealed class RegisterProxy : ICoordinatorCommand, IDeadLetterSuppressio /// /// Creates a new request for a given . /// - /// TBD + /// The proxy actor registering with the coordinator. public RegisterProxy(IActorRef shardRegionProxy) { ShardRegionProxy = shardRegionProxy; @@ -148,14 +148,14 @@ public override int GetHashCode() internal sealed class RegisterAck : ICoordinatorMessage, IEquatable { /// - /// TBD + /// Gets the coordinator actor reference returned in the registration acknowledgement. /// public readonly IActorRef Coordinator; /// - /// TBD + /// Creates a successful registration acknowledgement containing the coordinator reference. /// - /// TBD + /// The coordinator actor that accepted the registration. public RegisterAck(IActorRef coordinator) { Coordinator = coordinator; @@ -198,14 +198,14 @@ public override int GetHashCode() internal sealed class GetShardHome : ICoordinatorCommand, IDeadLetterSuppression, IEquatable { /// - /// TBD + /// Gets the shard id whose responsible region is requested. /// public readonly ShardId Shard; /// - /// TBD + /// Creates a request for the coordinator to resolve a shard's responsible region. /// - /// TBD + /// The id of the shard to resolve. public GetShardHome(ShardId shard) { Shard = shard; @@ -246,19 +246,19 @@ public override int GetHashCode() internal sealed class ShardHome : ICoordinatorMessage, IEquatable { /// - /// TBD + /// Gets the shard id associated with this region reference. /// public readonly ShardId Shard; /// - /// TBD + /// Gets the actor reference of the region responsible for the shard. /// public readonly IActorRef Ref; /// - /// TBD + /// Creates a shard-home reply containing the shard id and its responsible region. /// - /// TBD - /// TBD + /// The id of the shard. + /// The actor reference of the region responsible for the shard. public ShardHome(ShardId shard, IActorRef @ref) { Shard = shard; @@ -306,14 +306,14 @@ public override int GetHashCode() internal sealed class HostShard : ICoordinatorMessage, IEquatable { /// - /// TBD + /// Gets the id of the shard the coordinator has asked this region to host. /// public readonly ShardId Shard; /// - /// TBD + /// Creates a request for a region to host the specified shard. /// - /// TBD + /// The id of the shard to host. public HostShard(ShardId shard) { Shard = shard; @@ -348,20 +348,20 @@ public override int GetHashCode() } /// - /// replies with this message for requests which lead to it hosting the shard + /// Acknowledges that a region accepted hosting a shard; it does not confirm that the shard has initialized. /// [Serializable] internal sealed class ShardStarted : ICoordinatorMessage, IEquatable { /// - /// TBD + /// Gets the id of the shard whose hosting was acknowledged. /// public readonly ShardId Shard; /// - /// TBD + /// Creates an acknowledgement that the region accepted hosting the requested shard. /// - /// TBD + /// The id of the shard whose hosting was accepted. public ShardStarted(ShardId shard) { Shard = shard; @@ -407,14 +407,14 @@ public override int GetHashCode() internal sealed class BeginHandOff : ICoordinatorMessage, IEquatable { /// - /// TBD + /// Gets the id of the shard whose handoff is being prepared. /// public readonly ShardId Shard; /// - /// TBD + /// Creates a notification asking regions to stop routing to the shard before handoff. /// - /// TBD + /// The id of the shard entering handoff. public BeginHandOff(ShardId shard) { Shard = shard; @@ -456,14 +456,14 @@ public override int GetHashCode() internal sealed class BeginHandOffAck : ICoordinatorCommand, IEquatable { /// - /// TBD + /// Gets the id of the shard for which a region acknowledged . /// public readonly ShardId Shard; /// - /// TBD + /// Creates an acknowledgement that a region has received the begin-handoff request. /// - /// TBD + /// The id of the shard entering handoff. public BeginHandOffAck(ShardId shard) { Shard = shard; @@ -507,14 +507,14 @@ public override int GetHashCode() internal sealed class HandOff : ICoordinatorMessage, IEquatable { /// - /// TBD + /// Gets the id of the shard whose entities should be stopped for handoff. /// public readonly ShardId Shard; /// - /// TBD + /// Creates a request for the responsible region to stop entities in a shard for handoff. /// - /// TBD + /// The id of the shard to hand off. public HandOff(ShardId shard) { Shard = shard; @@ -555,14 +555,14 @@ public override int GetHashCode() internal sealed class ShardStopped : ICoordinatorCommand, IEquatable { /// - /// TBD + /// Gets the id of the shard whose handoff has completed. /// public readonly ShardId Shard; /// - /// TBD + /// Creates a notification that the shard's entities have stopped for handoff. /// - /// TBD + /// The id of the stopped shard. public ShardStopped(ShardId shard) { Shard = shard; @@ -604,14 +604,14 @@ public override int GetHashCode() internal sealed class RegionStopped : ICoordinatorCommand, IEquatable { /// - /// TBD + /// Gets the actor reference of the shard region that stopped. /// public IActorRef ShardRegion { get; } /// - /// TBD + /// Creates a notification that a shard region actor has stopped. /// - /// TBD + /// The actor reference of the stopped region. public RegionStopped(IActorRef shardRegion) { ShardRegion = shardRegion; @@ -653,14 +653,14 @@ public override int GetHashCode() internal sealed class GracefulShutdownRequest : ICoordinatorCommand, IDeadLetterSuppression, IEquatable { /// - /// TBD + /// Gets the region requesting graceful handoff of its hosted shards. /// public readonly IActorRef ShardRegion; /// - /// TBD + /// Creates a request for the coordinator to hand off all shards hosted by a region. /// - /// TBD + /// The region actor requesting graceful shutdown. public GracefulShutdownRequest(IActorRef shardRegion) { ShardRegion = shardRegion; @@ -700,20 +700,20 @@ public override int GetHashCode() public interface IDomainEvent : IClusterShardingSerializable { } /// - /// TBD + /// Coordinator state-change event recording shard-region registration. Persistence-backed coordinators journal this event; the distributed-data coordinator applies it to replicated state. /// [Serializable] public sealed class ShardRegionRegistered : IDomainEvent, IEquatable { /// - /// TBD + /// Gets the actor reference of the registered shard region. /// public readonly IActorRef Region; /// - /// TBD + /// Creates an event recording shard-region registration. /// - /// TBD + /// The actor reference of the registered region. public ShardRegionRegistered(IActorRef region) { Region = region; @@ -748,20 +748,20 @@ public override int GetHashCode() } /// - /// TBD + /// Coordinator state-change event recording registration of a proxy-only shard region. Persistence-backed coordinators journal this event; the distributed-data coordinator applies it to replicated state. /// [Serializable] public sealed class ShardRegionProxyRegistered : IDomainEvent, IEquatable { /// - /// TBD + /// Gets the actor reference of the registered shard-region proxy. /// public readonly IActorRef RegionProxy; /// - /// TBD + /// Creates an event recording shard-region proxy registration. /// - /// TBD + /// The actor reference of the registered proxy. public ShardRegionProxyRegistered(IActorRef regionProxy) { RegionProxy = regionProxy; @@ -796,20 +796,20 @@ public override int GetHashCode() } /// - /// TBD + /// Coordinator state-change event recording termination of a registered shard region. Persistence-backed coordinators journal this event; the distributed-data coordinator applies it to replicated state. /// [Serializable] public sealed class ShardRegionTerminated : IDomainEvent, IEquatable { /// - /// TBD + /// Gets the actor reference of the terminated shard region. /// public readonly IActorRef Region; /// - /// TBD + /// Creates an event recording shard-region termination. /// - /// TBD + /// The actor reference of the terminated region. public ShardRegionTerminated(IActorRef region) { Region = region; @@ -844,20 +844,20 @@ public override int GetHashCode() } /// - /// TBD + /// Coordinator state-change event recording termination of a registered shard-region proxy. Persistence-backed coordinators journal this event; the distributed-data coordinator applies it to replicated state. /// [Serializable] public sealed class ShardRegionProxyTerminated : IDomainEvent, IEquatable { /// - /// TBD + /// Gets the actor reference of the terminated proxy. /// public readonly IActorRef RegionProxy; /// - /// TBD + /// Creates an event recording shard-region proxy termination. /// - /// TBD + /// The actor reference of the terminated proxy. public ShardRegionProxyTerminated(IActorRef regionProxy) { RegionProxy = regionProxy; @@ -892,25 +892,25 @@ public override int GetHashCode() } /// - /// TBD + /// Coordinator state-change event recording allocation of a shard to a region. Persistence-backed coordinators journal this event; the distributed-data coordinator applies it to replicated state. /// [Serializable] public sealed class ShardHomeAllocated : IDomainEvent, IEquatable { /// - /// TBD + /// Gets the id of the allocated shard. /// public readonly ShardId Shard; /// - /// TBD + /// Gets the region responsible for the allocated shard. /// public readonly IActorRef Region; /// - /// TBD + /// Creates an event recording the region assignment for a shard. /// - /// TBD - /// TBD + /// The id of the allocated shard. + /// The actor reference of the region assigned to the shard. public ShardHomeAllocated(ShardId shard, IActorRef region) { Shard = shard; @@ -952,20 +952,20 @@ public override int GetHashCode() } /// - /// TBD + /// Coordinator state-change event recording removal of a shard's region assignment. Persistence-backed coordinators journal this event; the distributed-data coordinator applies it to replicated state. /// [Serializable] public sealed class ShardHomeDeallocated : IDomainEvent, IEquatable { /// - /// TBD + /// Gets the id of the shard whose allocation was removed. /// public readonly ShardId Shard; /// - /// TBD + /// Creates an event recording shard deallocation. /// - /// TBD + /// The id of the deallocated shard. public ShardHomeDeallocated(ShardId shard) { Shard = shard; @@ -1000,7 +1000,7 @@ public override int GetHashCode() } /// - /// TBD + /// Singleton persistence event marking coordinator initialization. /// [Serializable] public sealed class ShardCoordinatorInitialized : IDomainEvent, IEquatable @@ -1039,13 +1039,13 @@ public override int GetHashCode() /// - /// TBD + /// Internal signal that the coordinator's backing state has finished initialization. /// [Serializable] internal sealed class StateInitialized { /// - /// TBD + /// The singleton signal that the coordinator's backing state is initialized. /// public static readonly StateInitialized Instance = new(); @@ -1060,7 +1060,7 @@ private StateInitialized() { } internal sealed class CoordinatorState : IClusterShardingSerializable, IEquatable { /// - /// TBD + /// Empty coordinator state with no registered regions, proxies, or shard allocations. /// public static readonly CoordinatorState Empty = new(); @@ -1074,11 +1074,11 @@ internal sealed class CoordinatorState : IClusterShardingSerializable, IEquatabl /// public readonly IImmutableDictionary> Regions; /// - /// TBD + /// Registered region proxies that can route messages but do not host shards. /// public readonly IImmutableSet RegionProxies; /// - /// TBD + /// Shard ids remembered after their former region terminated or their allocation was removed. /// public readonly IImmutableSet UnallocatedShards; @@ -1093,13 +1093,13 @@ private CoordinatorState() : this( { } /// - /// TBD + /// Creates coordinator state from its shard allocations, registered regions and proxies, and remembered unallocated shards. /// - /// TBD - /// TBD - /// TBD - /// TBD - /// TBD + /// A map from allocated shard ids to their hosting regions. + /// A map from registered regions to their allocated shard ids. + /// The registered proxy-only regions. + /// Remembered shard ids that currently have no hosting region. + /// Whether shard ids are retained for later reallocation when their region terminates. public CoordinatorState( IImmutableDictionary shards, IImmutableDictionary> regions, @@ -1144,11 +1144,11 @@ public override string ToString() } /// - /// TBD + /// Applies a recognized coordinator domain event and returns the resulting immutable state. /// - /// TBD - /// TBD - /// TBD + /// The coordinator event to apply. + /// An event conflicts with the current state, such as registering an existing region or allocating an already allocated shard. + /// The state after applying the event; events that require no state change return the current state. public CoordinatorState Updated(IDomainEvent e) { switch (e) @@ -1217,14 +1217,14 @@ public CoordinatorState Updated(IDomainEvent e) } /// - /// TBD + /// Returns coordinator state with the specified components replaced and all other components retained. /// - /// TBD - /// TBD - /// TBD - /// TBD - /// TBD - /// TBD + /// Replacement map from allocated shard ids to hosting regions, or to retain the current map. + /// Replacement map from registered regions to their shard ids, or to retain the current map. + /// Replacement set of registered proxies, or to retain the current set. + /// Replacement set of remembered, currently unallocated shard ids, or to retain the current set. + /// Replacement remembered-entities flag, or to retain the current value. + /// This instance if no replacement values are supplied; otherwise a new coordinator state with the requested values. public CoordinatorState Copy( IImmutableDictionary shards = null, IImmutableDictionary> regions = null, @@ -1299,7 +1299,7 @@ public override int GetHashCode() private sealed class RebalanceTick { /// - /// TBD + /// Singleton tick that asks the coordinator to evaluate shard rebalancing. /// public static readonly RebalanceTick Instance = new(); @@ -1312,19 +1312,19 @@ private RebalanceTick() { } private sealed class RebalanceDone { /// - /// TBD + /// Gets the id of the shard processed by the rebalance worker. /// public readonly ShardId Shard; /// - /// TBD + /// Gets whether the handoff worker signaled successful completion; indicates timeout. /// public readonly bool Ok; /// - /// TBD + /// Creates a result message reporting completion status for a shard handoff. /// - /// TBD - /// TBD + /// The id of the shard processed by the worker. + /// Whether the worker signaled successful handoff completion. public RebalanceDone(ShardId shard, bool ok) { Shard = shard; @@ -1339,19 +1339,19 @@ public RebalanceDone(ShardId shard, bool ok) private sealed class ResendShardHost { /// - /// TBD + /// Gets the id of the shard for which the coordinator is retrying the host request. /// public readonly ShardId Shard; /// - /// TBD + /// Gets the region currently recorded as responsible for the shard. /// public readonly IActorRef Region; /// - /// TBD + /// Creates a retry message for a shard-host request that has not been acknowledged. /// - /// TBD - /// TBD + /// The id of the shard to request again. + /// The region expected to host the shard. public ResendShardHost(ShardId shard, IActorRef region) { Shard = shard; @@ -1360,20 +1360,20 @@ public ResendShardHost(ShardId shard, IActorRef region) } /// - /// TBD + /// Internal message deferring a region-termination update until the cluster-removal margin has elapsed. /// [Serializable] private sealed class DelayedShardRegionTerminated { /// - /// TBD + /// Gets the actor reference of the region whose termination is being applied. /// public readonly IActorRef Region; /// - /// TBD + /// Creates a delayed termination message for a shard region. /// - /// TBD + /// The actor reference of the terminated region. public DelayedShardRegionTerminated(IActorRef region) { Region = region; @@ -1387,24 +1387,24 @@ public DelayedShardRegionTerminated(IActorRef region) private sealed class AllocateShardResult { /// - /// TBD + /// Gets the shard id for the completed asynchronous allocation request. /// public readonly ShardId Shard; /// - /// TBD + /// Gets the selected region, or when allocation failed. /// public readonly IActorRef ShardRegion; /// - /// TBD + /// Gets the actor that requested the shard's location. /// public readonly IActorRef GetShardHomeSender; /// - /// TBD + /// Creates a message carrying the result of an allocation-strategy request. /// - /// TBD - /// TBD - /// TBD + /// The id of the shard being allocated. + /// The selected region, or if the allocation operation failed. + /// The actor that requested the shard's location. public AllocateShardResult(ShardId shard, IActorRef shardRegion, IActorRef getShardHomeSender) { Shard = shard; @@ -1423,14 +1423,14 @@ public AllocateShardResult(ShardId shard, IActorRef shardRegion, IActorRef getSh private sealed class RebalanceResult { /// - /// TBD + /// Gets the shard ids selected by the allocation strategy for rebalance. /// public readonly IImmutableSet Shards; /// - /// TBD + /// Creates a message carrying the result of a rebalance-strategy request. /// - /// TBD + /// The shard ids selected for this rebalance round. public RebalanceResult(IImmutableSet shards) { Shards = shards; @@ -1463,15 +1463,15 @@ public ShardRegionTerminated(IActorRef region) } /// - /// TBD + /// Creates local actor properties for a worker that coordinates a shard handoff. /// - /// TBD - /// TBD - /// TBD - /// TBD - /// TBD - /// TBD - /// TBD + /// The entity type name used in worker logs. + /// The shard id to hand off. + /// The region currently hosting the shard. + /// The timeout for the handoff operation. + /// The registered regions and proxies that must acknowledge before handoff proceeds. + /// when the handoff is part of rebalancing; when it is for region shutdown. + /// Actor properties for the handoff worker. public static Props Props( string typeName, string shard, @@ -1493,14 +1493,14 @@ public static Props Props( public ITimerScheduler Timers { get; set; } = null!; /// - /// TBD + /// Creates a worker that asks regions to stop routing to a shard, then asks its current region to stop the shard. /// - /// TBD - /// TBD - /// TBD - /// TBD - /// TBD - /// TBD + /// The entity type name used in worker logs. + /// The shard id to hand off. + /// The region currently hosting the shard. + /// The timeout for the handoff operation. + /// The registered regions and proxies that must acknowledge before handoff proceeds. + /// when the handoff is part of rebalancing; when it is for region shutdown. public RebalanceWorker( string typeName, string shard, @@ -1533,10 +1533,10 @@ public RebalanceWorker( } /// - /// TBD + /// Handles acknowledgements and region termination during the handoff phases, and reports timeout when a phase exceeds its deadline. /// - /// TBD - /// TBD + /// A begin-handoff acknowledgement, region-termination notification, or handoff timeout. + /// true when the message is handled in the current phase; otherwise false. protected override bool Receive(object message) { switch (message) diff --git a/src/contrib/cluster/Akka.Cluster.Sharding/ShardRegion.cs b/src/contrib/cluster/Akka.Cluster.Sharding/ShardRegion.cs index 9ed890a776b..920ab3f8336 100644 --- a/src/contrib/cluster/Akka.Cluster.Sharding/ShardRegion.cs +++ b/src/contrib/cluster/Akka.Cluster.Sharding/ShardRegion.cs @@ -46,7 +46,7 @@ public sealed class ShardRegion : ActorBase, IWithTimers internal sealed class Retry : IShardRegionCommand, INoSerializationVerificationNeeded { /// - /// TBD + /// Singleton housekeeping tick sent periodically to this shard region. /// public static readonly Retry Instance = new(); @@ -70,7 +70,7 @@ private Retry() internal sealed class RegisterRetry : IShardRegionCommand { /// - /// TBD + /// Singleton tick for the accelerated shard-region registration retry during startup or coordinator movement. /// public static readonly RegisterRetry Instance = new(); @@ -87,14 +87,14 @@ private RegisterRetry() internal sealed class RestartShard { /// - /// TBD + /// Gets the id of the shard to restart after its backoff interval. /// public readonly ShardId ShardId; /// - /// TBD + /// Creates a delayed restart notification for a shard. /// - /// TBD + /// The id of the shard to restart. public RestartShard(ShardId shardId) { ShardId = shardId; @@ -247,15 +247,15 @@ private StopTimeoutWarning() public ITimerScheduler Timers { get; set; } = null!; /// - /// TBD + /// Creates local actor properties for an actor that stops entities during shard handoff. /// - /// TBD - /// TBD - /// TBD - /// TBD - /// TBD - /// TBD - /// TBD + /// The entity type name used in handoff log messages. + /// The shard id being handed off. + /// The actor to notify with after the entities terminate. + /// The entity actor references to stop and watch. + /// The message sent to each entity to request termination. + /// The delay before the actor forcefully stops entities that have not terminated. + /// Local actor properties for the handoff stopper. public static Props Props( string typeName, ShardId shard, @@ -274,12 +274,12 @@ public static Props Props( /// them have terminated it replies with `ShardStopped`. /// If the entities don't terminate after `handoffTimeout` it will try stopping them forcefully. /// - /// TBD - /// TBD - /// TBD - /// TBD - /// TBD - /// TBD + /// The entity type name used in handoff log messages. + /// The shard id being handed off. + /// The actor to notify with after the entities terminate. + /// The entity actor references to stop and watch. + /// The message sent to each entity to request termination. + /// The delay before the actor forcefully stops entities that have not terminated. public HandOffStopper( string typeName, ShardId shard, @@ -338,14 +338,14 @@ public HandOffStopper( /// /// Factory method for the of the actor. /// - /// TBD - /// TBD - /// TBD - /// TBD + /// The entity type name served by the region. + /// The factory used to create entity actor properties for each entity id. + /// The cluster-sharding settings used by this region. + /// The actor selection path used to locate the shard coordinator. /// - /// TBD - /// TBD - /// TBD + /// The message sent to entities when their shard is handed off. + /// The optional provider used to store and recover remembered entity ids. + /// Local actor properties for the region. internal static Props Props( string typeName, Func entityProps, @@ -369,11 +369,11 @@ internal static Props Props( /// /// Factory method for the of the actor when used in proxy only mode. /// - /// TBD - /// TBD - /// TBD + /// The entity type name served by the proxy. + /// The cluster-sharding settings used by this proxy. + /// The actor selection path used to locate the shard coordinator. /// - /// TBD + /// Local actor properties for a proxy-only region. internal static Props ProxyProps( string typeName, ClusterShardingSettings settings, @@ -433,15 +433,15 @@ internal static Props ProxyProps( private readonly IShardingBufferMessageAdapter _bufferMessageAdapter; /// - /// TBD + /// Creates a shard region that routes entity messages and, when configured, stores remembered entity state. /// - /// TBD - /// TBD - /// TBD - /// TBD + /// The entity type name served by the region. + /// The factory used to create entity actor properties; for proxy-only operation. + /// The cluster-sharding settings used by this region. + /// The actor selection path used to locate the shard coordinator. /// - /// TBD - /// TBD + /// The message sent to entities when their shard is handed off. + /// The optional provider used to store and recover remembered entity ids. public ShardRegion( string typeName, Func? entityProps, diff --git a/src/contrib/cluster/Akka.Cluster.Sharding/ShardedDaemonProcess.cs b/src/contrib/cluster/Akka.Cluster.Sharding/ShardedDaemonProcess.cs index 9b3ca930a0b..25516fde4c5 100644 --- a/src/contrib/cluster/Akka.Cluster.Sharding/ShardedDaemonProcess.cs +++ b/src/contrib/cluster/Akka.Cluster.Sharding/ShardedDaemonProcess.cs @@ -165,8 +165,8 @@ public static ShardedDaemonProcess Get(ActorSystem system) => /// /// Start a specific number of actors that is then kept alive in the cluster. /// - /// TBD - /// TBD + /// The name identifying this daemon-process set. + /// The number of actors to run, each assigned an identifier from zero through this count minus one. /// Given a unique id of `0` until `numberOfInstance` create an entity actor. /// A reference to a router actor that will distribute all messages evenly across the workers /// using round-robin message routing. null if the ShardedDaemonProcess is misconfigured. diff --git a/src/contrib/cluster/Akka.Cluster.Sharding/ShardedDaemonProcessSettings.cs b/src/contrib/cluster/Akka.Cluster.Sharding/ShardedDaemonProcessSettings.cs index 7e292d8dc18..4742b156ccb 100644 --- a/src/contrib/cluster/Akka.Cluster.Sharding/ShardedDaemonProcessSettings.cs +++ b/src/contrib/cluster/Akka.Cluster.Sharding/ShardedDaemonProcessSettings.cs @@ -72,7 +72,7 @@ private ShardedDaemonProcessSettings Copy(TimeSpan? keepAliveInterval = null, Cl /// Some settings can not be changed (remember-entities and related settings, passivation, number-of-shards), /// changing those settings will be ignored. /// - /// TBD + /// The sharding settings to use for this daemon process. public ShardedDaemonProcessSettings WithShardingSettings(ClusterShardingSettings shardingSettings) => Copy(shardingSettings: shardingSettings); /// @@ -80,7 +80,7 @@ private ShardedDaemonProcessSettings Copy(TimeSpan? keepAliveInterval = null, Cl /// If the role is not specified all nodes in the cluster are used. If the given role does /// not match the role of the current node the ShardedDaemonProcess will not be started. /// - /// TBD + /// The cluster role required for nodes hosting this daemon process, or null to retain the current role. public ShardedDaemonProcessSettings WithRole(string role) => Copy(role: role); } } diff --git a/src/contrib/cluster/Akka.Cluster.Sharding/ShardingMessages.cs b/src/contrib/cluster/Akka.Cluster.Sharding/ShardingMessages.cs index 8302fcde08d..6d9dbc900ee 100644 --- a/src/contrib/cluster/Akka.Cluster.Sharding/ShardingMessages.cs +++ b/src/contrib/cluster/Akka.Cluster.Sharding/ShardingMessages.cs @@ -35,11 +35,11 @@ public interface IShardRegionQuery { } /// the entity actors for example by defining receive timeout (). /// If a message is already enqueued to the entity when it stops itself the enqueued message /// in the mailbox will be dropped. To support graceful passivation without losing such - /// messages the entity actor can send this message to its parent . - /// The specified wrapped will be sent back to the entity, which is - /// then supposed to stop itself. Incoming messages will be buffered by the - /// between reception of and termination of the entity. Such buffered messages - /// are thereafter delivered to a new incarnation of the entity. + /// messages the entity actor can send this message to its parent shard. + /// If the shard starts passivation in response to this command, it sends the specified wrapped + /// to the entity, which is then expected to stop itself. The shard + /// buffers incoming messages between the start of passivation and entity termination, then delivers + /// those buffered messages to a new entity incarnation. /// /// is a perfectly fine . /// @@ -47,16 +47,16 @@ public interface IShardRegionQuery { } public sealed class Passivate : IShardRegionCommand { /// - /// TBD + /// Creates a passivation command containing the stop message that the shard sends if it starts passivation. /// - /// TBD + /// The message to send to the entity to request that it stops. public Passivate(object stopMessage) { StopMessage = stopMessage; } /// - /// TBD + /// Gets the message the shard sends to the entity if it starts passivation. /// public object StopMessage { get; } } @@ -64,15 +64,16 @@ public Passivate(object stopMessage) internal sealed record SupervisorStopDirectivePassivation(IActorRef Child, string Reason, Exception LastCause) : IShardRegionCommand; /// - /// Send this message to the actor to handoff all shards that are hosted by - /// the and then the actor will be stopped. You can - /// it to know when it is completed. + /// Send this message to a to request handoff of its hosted shards and then + /// stop the region. The region stops after its shards and buffered messages are drained, but its + /// graceful-shutdown timeout can stop it while some shards or buffered messages remain. You can + /// the region to observe termination. /// [Serializable] public sealed class GracefulShutdown : IShardRegionCommand { /// - /// TBD + /// Singleton message requesting graceful shard handoff followed by region shutdown. /// public static readonly GracefulShutdown Instance = new(); @@ -85,7 +86,7 @@ private GracefulShutdown() internal sealed class GracefulShutdownTimeout : IShardRegionCommand { /// - /// TBD + /// Internal message sent when the shard region's graceful-shutdown timeout expires. /// public static readonly GracefulShutdownTimeout Instance = new(); @@ -103,14 +104,14 @@ private GracefulShutdownTimeout() internal sealed class ShardInitialized : IEquatable { /// - /// TBD + /// Gets the id of the shard whose initialization completed. /// public readonly string ShardId; /// - /// TBD + /// Creates a notification that a shard has completed initialization. /// - /// TBD + /// The id of the initialized shard. public ShardInitialized(string shardId) { ShardId = shardId; @@ -151,7 +152,7 @@ public override int GetHashCode() public sealed class GetCurrentRegions : IShardRegionQuery, IClusterShardingSerializable { /// - /// TBD + /// Singleton query requesting the addresses of the registered shard regions. /// public static readonly GetCurrentRegions Instance = new(); @@ -240,13 +241,13 @@ public EntityLocation(string entityId, string shardId, Address shardRegion, Opti public sealed class CurrentRegions : IClusterShardingSerializable, IEquatable { /// - /// TBD + /// Gets the addresses of the shard regions reported by the reply to . /// public readonly IImmutableSet
Regions; /// - /// TBD + /// Creates a reply containing the reported shard-region addresses. /// - /// TBD + /// The addresses of the shard regions included in this reply. public CurrentRegions(IImmutableSet
regions) { Regions = regions; @@ -399,7 +400,7 @@ public override int GetHashCode() public sealed class GetShardRegionStats : IShardRegionQuery, IClusterShardingSerializable { /// - /// TBD + /// Singleton query requesting allocation statistics for the shard region. /// public static readonly GetShardRegionStats Instance = new(); @@ -493,7 +494,7 @@ public override string ToString() public sealed class GetShardRegionState : IShardRegionQuery, IClusterShardingSerializable { /// - /// TBD + /// Singleton query requesting the current shard and entity state of the shard region. /// public static readonly GetShardRegionState Instance = new(); @@ -513,15 +514,15 @@ private GetShardRegionState() public sealed class CurrentShardRegionState : IClusterShardingSerializable, IEquatable { /// - /// TBD + /// Gets the shard states included in this region-state reply. /// public readonly IImmutableSet Shards; public readonly IImmutableSet Failed; /// - /// TBD + /// Creates a region-state reply with the supplied shard states and no failed shard queries. /// - /// TBD + /// The shard states gathered for the region. [Obsolete("Use constructor with `failed` argument. Obsolete since 1.5.0-alpha1")] public CurrentShardRegionState(IImmutableSet shards) : this(shards, ImmutableHashSet.Empty) @@ -529,10 +530,10 @@ public CurrentShardRegionState(IImmutableSet shards) } /// - /// TBD + /// Creates a region-state reply with the gathered shard states and failed shard ids. /// - /// TBD - /// + /// The shard states gathered successfully for the region. + /// The ids of shards whose state could not be gathered. public CurrentShardRegionState(IImmutableSet shards, IImmutableSet failed) { Shards = shards; @@ -578,25 +579,25 @@ public override string ToString() /// - /// TBD + /// Describes the entity ids reported for one shard in a reply. /// [Serializable] public sealed class ShardState : IClusterShardingSerializable, IEquatable { /// - /// TBD + /// Gets the id of this shard. /// public readonly string ShardId; /// - /// TBD + /// Gets the entity ids reported for this shard. /// public readonly IImmutableSet EntityIds; /// - /// TBD + /// Creates a shard-state value from the shard id and its reported entity ids. /// - /// TBD - /// TBD + /// The id of the shard. + /// The entity ids reported as running on the shard. public ShardState(string shardId, IImmutableSet entityIds) { ShardId = shardId; diff --git a/src/contrib/cluster/Akka.Cluster.Sharding/ShardingQueries.cs b/src/contrib/cluster/Akka.Cluster.Sharding/ShardingQueries.cs index 264fc3b4beb..b0ae7f8eab7 100644 --- a/src/contrib/cluster/Akka.Cluster.Sharding/ShardingQueries.cs +++ b/src/contrib/cluster/Akka.Cluster.Sharding/ShardingQueries.cs @@ -70,7 +70,7 @@ public override string ToString() } /// - /// TBD + /// Creates query-result metadata by separating completed task results from failed or cancelled queries. /// /// the results of actors queried that did not reply by /// the timeout or returned another failure and those that did