diff --git a/src/core/Akka/Routing/Broadcast.cs b/src/core/Akka/Routing/Broadcast.cs index 90eefac31c4..2269ba022e3 100644 --- a/src/core/Akka/Routing/Broadcast.cs +++ b/src/core/Akka/Routing/Broadcast.cs @@ -13,8 +13,17 @@ namespace Akka.Routing { + /// + /// This class contains logic used by a to route a message to multiple routees. + /// public class BroadcastRoutingLogic : RoutingLogic { + /// + /// Picks all the routees in to receive the . + /// + /// The message that is being routed. + /// A collection of routees that receives the . + /// A that contains all the given that receives the . public override Routee Select(object message, Routee[] routees) { if (routees == null || !routees.Any()) @@ -24,24 +33,54 @@ public override Routee Select(object message, Routee[] routees) } /// - /// Class BroadcastPool. + /// This class represents a router that sends messages it receives to all of its routees. /// public class BroadcastPool : Pool { + /// + /// This class represents a surrogate of a router. + /// Its main use is to help during the serialization process. + /// public class BroadcastPoolSurrogate : ISurrogate { + /// + /// Creates a encapsulated by this surrogate. + /// + /// The actor system that owns this router. + /// The encapsulated by this surrogate. public ISurrogated FromSurrogate(ActorSystem system) { return new BroadcastPool(NrOfInstances, Resizer, SupervisorStrategy, RouterDispatcher, UsePoolDispatcher); } + /// + /// The number of routees associated with this pool. + /// public int NrOfInstances { get; set; } + /// + /// Determine whether or not to use the pool dispatcher. The dispatcher is defined in the + /// 'pool-dispatcher' configuration property in the deployment section of the router. + /// public bool UsePoolDispatcher { get; set; } + /// + /// The resizer to use when dynamically allocating routees to the pool. + /// public Resizer Resizer { get; set; } + /// + /// The strategy to use when supervising the pool. + /// public SupervisorStrategy SupervisorStrategy { get; set; } + /// + /// The dispatcher to use when passing messages to the routees. + /// public string RouterDispatcher { get; set; } } + /// + /// Creates a surrogate representation of the current . + /// + /// The actor system that owns this router. + /// The surrogate representation of the current . public override ISurrogate ToSurrogate(ActorSystem system) { return new BroadcastPoolSurrogate @@ -50,81 +89,136 @@ public override ISurrogate ToSurrogate(ActorSystem system) UsePoolDispatcher = UsePoolDispatcher, Resizer = Resizer, SupervisorStrategy = SupervisorStrategy, - RouterDispatcher = RouterDispatcher, + RouterDispatcher = RouterDispatcher }; } /// /// Initializes a new instance of the class. /// - /// The configuration. + /// The configuration used to configure the pool. public BroadcastPool(Config config) : base(config) { - } + /// /// Initializes a new instance of the class. /// - /// The nr of instances. - /// The resizer. - /// The supervisor strategy. - /// The router dispatcher. - /// if set to true [use pool dispatcher]. + /// The initial number of routees in the pool. + /// The resizer to use when dynamically allocating routees to the pool. + /// The strategy to use when supervising the pool. + /// The dispatcher to use when passing messages to the routees. + /// true to use the pool dispatcher; otherwise false. public BroadcastPool(int nrOfInstances, Resizer resizer,SupervisorStrategy supervisorStrategy, string routerDispatcher, bool usePoolDispatcher = false) : base(nrOfInstances, resizer, supervisorStrategy, routerDispatcher, usePoolDispatcher) { - } /// - /// Simple form of BroadcastPool constructor + /// Initializes a new instance of the class. + /// + /// + /// A configured in this way uses the supervisor strategy. + /// /// - /// The nr of instances. + /// The initial number of routees in the pool. public BroadcastPool(int nrOfInstances) : base(nrOfInstances, null, DefaultStrategy, null) { } /// - /// Creates the router. + /// Creates a router that is responsible for routing messages to routees within the provided . /// - /// The system. - /// Router. + /// The actor system that owns this router. + /// The newly created router tied to the given system. public override Router CreateRouter(ActorSystem system) { return new Router(new BroadcastRoutingLogic()); } + /// + /// Creates a new router with a given . + /// + /// + /// This method is immutable and returns a new instance of the router. + /// + /// + /// The used to configure the new router. + /// A new router with the provided . public override Pool WithSupervisorStrategy(SupervisorStrategy strategy) { return new BroadcastPool(NrOfInstances, Resizer, strategy, RouterDispatcher, UsePoolDispatcher); } + /// + /// Creates a new router with a given . + /// + /// + /// This method is immutable and returns a new instance of the router. + /// + /// + /// The used to configure the new router. + /// A new router with the provided . public override Pool WithResizer(Resizer resizer) { return new BroadcastPool(NrOfInstances, resizer, SupervisorStrategy, RouterDispatcher, UsePoolDispatcher); } + /// + /// Creates a new router with a given dispatcher id. + /// + /// + /// This method is immutable and returns a new instance of the router. + /// + /// + /// The dispatcher id used to configure the new router. + /// A new router with the provided dispatcher id. public override Pool WithDispatcher(string dispatcher) { return new BroadcastPool(NrOfInstances, Resizer, SupervisorStrategy, dispatcher, UsePoolDispatcher); } + /// + /// Configure the current router with an auxiliary router for routes that it does not know how to handle. + /// + /// The router to use as an auxiliary source. + /// The router configured with the auxiliary information. public override RouterConfig WithFallback(RouterConfig routerConfig) { return OverrideUnsetConfig(routerConfig); } } + /// + /// This class represents a router that sends messages it receives to all of its routees. + /// public class BroadcastGroup : Group { + /// + /// This class represents a surrogate of a router. + /// Its main use is to help during the serialization process. + /// public class BroadcastGroupSurrogate : ISurrogate { + /// + /// Creates a encapsulated by this surrogate. + /// + /// The actor system that owns this router. + /// The encapsulated by this surrogate. public ISurrogated FromSurrogate(ActorSystem system) { return new BroadcastGroup(Paths); } + /// + /// The actor paths used by this router during routee selection. + /// public string[] Paths { get; set; } } + /// + /// Creates a surrogate representation of the current . + /// + /// The actor system that owns this router. + /// The surrogate representation of the current . public override ISurrogate ToSurrogate(ActorSystem system) { return new BroadcastGroupSurrogate @@ -134,53 +228,68 @@ public override ISurrogate ToSurrogate(ActorSystem system) } /// - /// Initializes a new instance of the class. + /// Initializes a new instance of the class. /// - /// The configuration. + /// + /// The configuration to use to lookup paths used by the group router. + /// + /// + /// If 'routees.path' is defined in the provided configuration then those paths will be used by the router. + /// + /// public BroadcastGroup(Config config) : base(config.GetStringList("routees.paths")) { } /// - /// Initializes a new instance of the class. + /// Initializes a new instance of the class. /// - /// The paths. + /// A list of actor paths used by the group router. public BroadcastGroup(params string[] paths) : base(paths) { } /// - /// Initializes a new instance of the class. + /// Initializes a new instance of the class. /// - /// The paths. + /// An enumeration of actor paths used by the group router. public BroadcastGroup(IEnumerable paths) : base(paths) { } /// - /// Initializes a new instance of the class. + /// Initializes a new instance of the class. /// - /// The routees. + /// An enumeration of routees used by the group router. public BroadcastGroup(IEnumerable routees) : base(routees) { } /// - /// Creates the router. + /// Creates a router that is responsible for routing messages to routees within the provided . /// - /// Router. + /// The actor system that owns this router. + /// The newly created router tied to the given system. public override Router CreateRouter(ActorSystem system) { return new Router(new BroadcastRoutingLogic()); } + /// + /// Creates a new router with a given dispatcher id. + /// + /// + /// This method is immutable and returns a new instance of the router. + /// + /// + /// The dispatcher id used to configure the new router. + /// A new router with the provided dispatcher id. public override Group WithDispatcher(string dispatcher) { return new BroadcastGroup(Paths){ RouterDispatcher = dispatcher }; } } } - diff --git a/src/core/Akka/Routing/ConsistentHashRouter.cs b/src/core/Akka/Routing/ConsistentHashRouter.cs index b5e6ecaeb9d..7a9583e59c4 100644 --- a/src/core/Akka/Routing/ConsistentHashRouter.cs +++ b/src/core/Akka/Routing/ConsistentHashRouter.cs @@ -71,24 +71,28 @@ public object ConsistentHashKey public delegate object ConsistentHashMapping(object msg); /// - /// Uses consistent hashing to select a based on the sent message. + /// This class contains logic used by a to route a message to a + /// determined using consistent-hashing. This process has the router select a routee based on a message's + /// consistent hash key. There are 3 ways to define the key, which can be used individually or combined + /// to form the key. The is tried first. /// - /// There are 3 ways to define what data to use for the consistent hash key. - /// - /// 1. You can define a or use + ///
    + ///
  1. + /// You can define a or use /// of the router to map incoming messages to their consistent hash key. /// This makes the decision transparent for the sender. - /// - /// 2. Messages may implement . The hash key is part + ///
    2. + ///
  2. + /// Messages may implement . The hash key is part /// of the message and it's convenient to define it together with the message /// definition. - /// - /// 3. The message can be wrapped in a to + ///
    3. + ///
  3. + /// The message can be wrapped in a to /// define what data to use for the consistent hash key. The sender knows what key /// to use. - /// - /// These ways to define the consistent hash key can be used together and at the - /// same time for one router. The is tried first. + ///
    4. + ///
/// public class ConsistentHashingRoutingLogic : RoutingLogic { @@ -103,11 +107,27 @@ public class ConsistentHashingRoutingLogic : RoutingLogic private readonly Address _selfAddress; private readonly int _vnodes; + /// + /// Initializes a new instance of the class. + /// + /// + /// A configured in this way uses the + /// as the hash + /// mapping function with a virtual node factor of 0 (zero). + /// + /// + /// The actor system that owns the router with this logic. public ConsistentHashingRoutingLogic(ActorSystem system) : this(system, 0, ConsistentHashingRouter.EmptyConsistentHashMapping) { } + /// + /// Initializes a new instance of the class. + /// + /// The actor system that owns the router with this logic. + /// The number of virtual nodes to use on the hash ring. + /// The consistent hash mapping function to use on incoming messages. public ConsistentHashingRoutingLogic(ActorSystem system, int virtualNodesFactor, ConsistentHashMapping hashMapping) { @@ -118,7 +138,12 @@ public ConsistentHashingRoutingLogic(ActorSystem system, int virtualNodesFactor, _vnodes = virtualNodesFactor == 0 ? system.Settings.DefaultVirtualNodesFactor : virtualNodesFactor; } - + /// + /// Picks a to receive the . + /// + /// The message that is being routed + /// A collection of routees to choose from when receiving the . + /// A that receives the . public override Routee Select(object message, Routee[] routees) { if (message == null || routees == null || routees.Length == 0) @@ -188,6 +213,16 @@ public override Routee Select(object message, Routee[] routees) } } + /// + /// Creates a new router logic with a given . + /// + /// + /// This method is immutable and returns a new instance of the router. + /// + /// + /// The used to configure the new router. + /// A new router logic with the provided . + /// The mapping can not be null. public ConsistentHashingRoutingLogic WithHashMapping(ConsistentHashMapping mapping) { if (mapping == null) @@ -195,7 +230,6 @@ public ConsistentHashingRoutingLogic WithHashMapping(ConsistentHashMapping mappi return new ConsistentHashingRoutingLogic(_system, _vnodes, mapping); } - } /// @@ -246,17 +280,30 @@ private string ToStringWithFullAddress(ActorPath path) } /// - /// implementation of the consistent hashing router. + /// This class represents a router that sends messages to a determined using consistent-hashing. + /// Please refer to for more information on consistent hashing. /// public class ConsistentHashingGroup : Group { + /// + /// This class represents a surrogate of a router. + /// Its main use is to help during the serialization process. + /// public class ConsistentHashingGroupSurrogate : ISurrogate { + /// + /// Creates a encapsulated by this surrogate. + /// + /// The actor system that owns this router. + /// The encapsulated by this surrogate. public ISurrogated FromSurrogate(ActorSystem system) { return new ConsistentHashingGroup(Paths); } + /// + /// The actor paths used by this router during routee selection. + /// public string[] Paths { get; set; } } @@ -265,19 +312,43 @@ public ISurrogated FromSurrogate(ActorSystem system) /// public int VirtualNodesFactor { get; private set; } + /// + /// The consistent hash mapping function to use on incoming messages. + /// protected ConsistentHashMapping HashMapping; + /// + /// Initializes a new instance of the class. + /// + /// + /// The configuration to use to lookup paths used by the group router. + /// + /// + /// If 'routees.path' is defined in the provided configuration then those paths will be used by the router. + /// 'virtual-nodes-factor' defaults to 0 (zero) if it is not defined in the provided configuration. + /// + /// public ConsistentHashingGroup(Config config) : base(config.GetStringList("routees.paths")) { VirtualNodesFactor = config.GetInt("virtual-nodes-factor", 0); } + /// + /// Initializes a new instance of the class. + /// + /// A list of actor paths used by the group router. public ConsistentHashingGroup(params string[] paths) : base(paths) { } + /// + /// Initializes a new instance of the class. + /// + /// An enumeration of actor paths used by the group router. + /// The number of virtual nodes to use on the hash ring. + /// The consistent hash mapping function to use on incoming messages. public ConsistentHashingGroup(IEnumerable paths, int virtualNodesFactor = 0, ConsistentHashMapping hashMapping = null) : base(paths) @@ -286,6 +357,12 @@ public ConsistentHashingGroup(IEnumerable paths, int virtualNodesFactor HashMapping = hashMapping; } + /// + /// Initializes a new instance of the class. + /// + /// An enumeration of routees used by the group router. + /// The number of virtual nodes to use on the hash ring. + /// The consistent hash mapping function to use on incoming messages. public ConsistentHashingGroup(IEnumerable routees, int virtualNodesFactor = 0, ConsistentHashMapping hashMapping = null) : base(routees) @@ -295,25 +372,38 @@ public ConsistentHashingGroup(IEnumerable routees, int virtualNodesFa } /// - /// Apply a to the + /// Creates a new router with a given . /// - /// Note: this method is immutable and will return a new instance. + /// + /// This method is immutable and returns a new instance of the router. + /// /// + /// The used to configure the new router. + /// A new router with the provided . public ConsistentHashingGroup WithVirtualNodesFactor(int vnodes) { return new ConsistentHashingGroup(Paths, vnodes, HashMapping); } /// - /// Apply a to the . + /// Creates a new router with a given . /// - /// Note: this method is immutable and will return a new instance. + /// + /// This method is immutable and returns a new instance of the router. + /// /// + /// The used to configure the new router. + /// A new router with the provided . public ConsistentHashingGroup WithHashMapping(ConsistentHashMapping mapping) { return new ConsistentHashingGroup(Paths, VirtualNodesFactor, mapping); } + /// + /// Creates a router that is responsible for routing messages to routees within the provided . + /// + /// The actor system that owns this router. + /// The newly created router tied to the given system. public override Router CreateRouter(ActorSystem system) { return @@ -321,11 +411,26 @@ public override Router CreateRouter(ActorSystem system) HashMapping ?? ConsistentHashingRouter.EmptyConsistentHashMapping)); } + /// + /// Creates a new router with a given dispatcher id. + /// + /// + /// This method is immutable and returns a new instance of the router. + /// + /// + /// The dispatcher id used to configure the new router. + /// A new router with the provided dispatcher id. public override Group WithDispatcher(string dispatcher) { return new ConsistentHashingGroup(Paths, VirtualNodesFactor, HashMapping){ RouterDispatcher = dispatcher}; } + /// + /// Configure the current router with an auxiliary router for routes that it does not know how to handle. + /// + /// The router to use as an auxiliary source. + /// The router configured with the auxiliary information. + /// Expected ConsistentHashingGroup, got . public override RouterConfig WithFallback(RouterConfig routerConfig) { if (routerConfig is FromConfig || routerConfig is NoRouter) @@ -344,6 +449,11 @@ public override RouterConfig WithFallback(RouterConfig routerConfig) } } + /// + /// Creates a surrogate representation of the current . + /// + /// The actor system that owns this router. + /// The surrogate representation of the current . public override ISurrogate ToSurrogate(ActorSystem system) { return new ConsistentHashingGroupSurrogate @@ -354,11 +464,14 @@ public override ISurrogate ToSurrogate(ActorSystem system) } /// - /// implementation of a consistent hash router. + /// This class represents a router that sends messages to a determined using consistent-hashing. + /// Please refer to for more information on consistent hashing. /// - /// NOTE: Using with is potentially harmful, as hash ranges + /// + /// Using with is potentially harmful, as hash ranges /// might change radically during live message processing. This router works best with fixed-sized pools or fixed /// number of routees per node in the event of clustered deployments. + /// /// public class ConsistentHashingPool : Pool { @@ -371,8 +484,12 @@ public class ConsistentHashingPool : Pool /// /// Initializes a new instance of the class. + /// + /// + /// 'virtual-nodes-factor' defaults to 0 (zero) if it is not defined in the provided configuration. + /// /// - /// The configuration. + /// The configuration used to configure the pool. public ConsistentHashingPool(Config config) : base(config) { @@ -382,13 +499,13 @@ public ConsistentHashingPool(Config config) /// /// Initializes a new instance of the class. /// - /// The nr of instances. - /// The resizer. - /// The supervisor strategy. - /// The router dispatcher. - /// if set to true [use pool dispatcher]. - /// The number of virtual nodes to use on the hash ring - /// The consistent hash mapping function to use on incoming messages + /// The initial number of routees in the pool. + /// The resizer to use when dynamically allocating routees to the pool. + /// The strategy to use when supervising the pool. + /// The dispatcher to use when passing messages to the routees. + /// true to use the pool dispatcher; otherwise false. + /// The number of virtual nodes to use on the hash ring. + /// The consistent hash mapping function to use on incoming messages. public ConsistentHashingPool(int nrOfInstances, Resizer resizer, SupervisorStrategy supervisorStrategy, string routerDispatcher, bool usePoolDispatcher = false, int virtualNodesFactor = 0, ConsistentHashMapping hashMapping = null) @@ -399,10 +516,14 @@ public ConsistentHashingPool(int nrOfInstances, Resizer resizer, SupervisorStrat } /// - /// Apply a to the + /// Creates a new router with a given . /// - /// Note: this method is immutable and will return a new instance. + /// + /// This method is immutable and returns a new instance of the router. + /// /// + /// The used to configure the new router. + /// A new router with the provided . public ConsistentHashingPool WithVirtualNodesFactor(int vnodes) { return new ConsistentHashingPool(NrOfInstances, Resizer, SupervisorStrategy, RouterDispatcher, @@ -410,10 +531,14 @@ public ConsistentHashingPool WithVirtualNodesFactor(int vnodes) } /// - /// Apply a to the . + /// Creates a new router with a given . /// - /// Note: this method is immutable and will return a new instance. + /// + /// This method is immutable and returns a new instance of the router. + /// /// + /// The used to configure the new router. + /// A new router with the provided . public ConsistentHashingPool WithHashMapping(ConsistentHashMapping mapping) { return new ConsistentHashingPool(NrOfInstances, Resizer, SupervisorStrategy, RouterDispatcher, @@ -421,13 +546,22 @@ public ConsistentHashingPool WithHashMapping(ConsistentHashMapping mapping) } /// - /// Simple form of ConsistentHashingPool constructor + /// Initializes a new instance of the class. + /// + /// + /// A configured in this way uses the supervisor strategy. + /// /// - /// The nr of instances. + /// The initial number of routees in the pool. public ConsistentHashingPool(int nrOfInstances) : base(nrOfInstances, null, Pool.DefaultStrategy, null) { } + /// + /// Creates a router that is responsible for routing messages to routees within the provided . + /// + /// The actor system that owns this router. + /// The newly created router tied to the given system. public override Router CreateRouter(ActorSystem system) { return @@ -435,24 +569,63 @@ public override Router CreateRouter(ActorSystem system) _hashMapping ?? ConsistentHashingRouter.EmptyConsistentHashMapping)); } + /// + /// Creates a new router with a given . + /// + /// + /// This method is immutable and returns a new instance of the router. + /// + /// + /// The used to configure the new router. + /// A new router with the provided . public override Pool WithSupervisorStrategy(SupervisorStrategy strategy) { return new ConsistentHashingPool(NrOfInstances, Resizer, strategy, RouterDispatcher, UsePoolDispatcher, VirtualNodesFactor, _hashMapping); } + /// + /// Creates a new router with a given . + /// + /// + /// This method is immutable and returns a new instance of the router. + /// + /// + /// + /// Using with is potentially harmful, as hash ranges + /// might change radically during live message processing. This router works best with fixed-sized pools or fixed + /// number of routees per node in the event of clustered deployments. + /// + /// + /// The used to configure the new router. + /// A new router with the provided . public override Pool WithResizer(Resizer resizer) { return new ConsistentHashingPool(NrOfInstances, resizer, SupervisorStrategy, RouterDispatcher, UsePoolDispatcher, VirtualNodesFactor, _hashMapping); } + /// + /// Creates a new router with a given dispatcher id. + /// + /// + /// This method is immutable and returns a new instance of the router. + /// + /// + /// The dispatcher id used to configure the new router. + /// A new router with the provided dispatcher id. public override Pool WithDispatcher(string dispatcher) { return new ConsistentHashingPool(NrOfInstances, Resizer, SupervisorStrategy, dispatcher, UsePoolDispatcher, VirtualNodesFactor, _hashMapping); } + /// + /// Configure the current router with an auxiliary router for routes that it does not know how to handle. + /// + /// The router to use as an auxiliary source. + /// The router configured with the auxiliary information. + /// routerConfig public override RouterConfig WithFallback(RouterConfig routerConfig) { if (routerConfig is FromConfig || routerConfig is NoRouter) @@ -471,20 +644,50 @@ public override RouterConfig WithFallback(RouterConfig routerConfig) } } + /// + /// This class represents a surrogate of a router. + /// Its main use is to help during the serialization process. + /// public class ConsistentHashingPoolSurrogate : ISurrogate { + /// + /// Creates a encapsulated by this surrogate. + /// + /// The actor system that owns this router. + /// The encapsulated by this surrogate. public ISurrogated FromSurrogate(ActorSystem system) { return new ConsistentHashingPool(NrOfInstances, Resizer, SupervisorStrategy, RouterDispatcher, UsePoolDispatcher); } + /// + /// The number of routees associated with this pool. + /// public int NrOfInstances { get; set; } + /// + /// Determine whether or not to use the pool dispatcher. The dispatcher is defined in the + /// 'pool-dispatcher' configuration property in the deployment section of the router. + /// public bool UsePoolDispatcher { get; set; } + /// + /// The resizer to use when dynamically allocating routees to the pool. + /// public Resizer Resizer { get; set; } + /// + /// The strategy to use when supervising the pool. + /// public SupervisorStrategy SupervisorStrategy { get; set; } + /// + /// The dispatcher to use when passing messages to the routees. + /// public string RouterDispatcher { get; set; } } + /// + /// Creates a surrogate representation of the current . + /// + /// The actor system that owns this router. + /// The surrogate representation of the current . public override ISurrogate ToSurrogate(ActorSystem system) { return new ConsistentHashingPoolSurrogate @@ -498,4 +701,3 @@ public override ISurrogate ToSurrogate(ActorSystem system) } } } - diff --git a/src/core/Akka/Routing/Random.cs b/src/core/Akka/Routing/Random.cs index 21da93545fa..26ab7bd0995 100644 --- a/src/core/Akka/Routing/Random.cs +++ b/src/core/Akka/Routing/Random.cs @@ -13,16 +13,16 @@ namespace Akka.Routing { /// - /// Class RandomLogic. + /// This class contains logic used by a to route a message to a random . /// public class RandomLogic : RoutingLogic { /// - /// Selects the routee for the given message. + /// Picks a random to receive the . /// - /// The message. - /// The routees. - /// Routee. + /// The message that is being routed. + /// A collection of routees to randomly choose from when receiving the . + /// A that receives the . public override Routee Select(object message, Routee[] routees) { if (routees == null || routees.Length == 0) @@ -34,37 +34,48 @@ public override Routee Select(object message, Routee[] routees) } /// - /// Class RandomGroup. + /// This class represents a router that sends messages to a random . /// public class RandomGroup : Group { /// - /// Initializes a new instance of the class. + /// Initializes a new instance of the class. /// - /// The configuration. + /// + /// The configuration to use to lookup paths used by the group router. + /// + /// + /// If 'routees.path' is defined in the provided configuration then those paths will be used by the router. + /// + /// public RandomGroup(Config config) : base(config.GetStringList("routees.paths")) { } /// - /// Initializes a new instance of the class. + /// Initializes a new instance of the class. /// - /// The paths. + /// A list of paths used by the group router. public RandomGroup(params string[] paths) : base(paths) { } /// - /// Initializes a new instance of the class. + /// Initializes a new instance of the class. /// - /// The paths. + /// An enumeration of paths used by the group router. public RandomGroup(IEnumerable paths) : base(paths) { } + /// + /// Creates a surrogate representation of the current . + /// + /// The actor system that owns this router. + /// The surrogate representation of the current . public override ISurrogate ToSurrogate(ActorSystem system) { return new RandomGroupSurrogate @@ -74,23 +85,45 @@ public override ISurrogate ToSurrogate(ActorSystem system) } /// - /// Creates the router. + /// Creates a router that is responsible for routing messages to routees within the provided . /// - /// Router. + /// The actor system that owns this router. + /// The newly created router tied to the given system. public override Router CreateRouter(ActorSystem system) { return new Router(new RandomLogic()); } + /// + /// Creates a new router with a given dispatcher id. + /// + /// + /// This method is immutable and returns a new instance of the router. + /// + /// + /// The dispatcher id used to configure the new router. + /// A new router with the provided dispatcher id. public override Group WithDispatcher(string dispatcher) { return new RandomGroup(Paths){ RouterDispatcher = dispatcher}; } + /// + /// This class represents a surrogate of a router. + /// Its main use is to help during the serialization process. + /// public class RandomGroupSurrogate : ISurrogate { + /// + /// The actor paths used by this router during routee selection. + /// public string[] Paths { get; set; } + /// + /// Creates a encapsulated by this surrogate. + /// + /// The actor system that owns this router. + /// The encapsulated by this surrogate. public ISurrogated FromSurrogate(ActorSystem system) { return new RandomGroup(Paths); @@ -98,46 +131,64 @@ public ISurrogated FromSurrogate(ActorSystem system) } } + /// + /// This class represents a router that sends messages to a random . + /// public class RandomPool : Pool { /// + /// Initializes a new instance of the class. /// - /// The nr of instances. - /// The resizer. - /// The supervisor strategy. - /// The router dispatcher. - /// if set to true [use pool dispatcher]. + /// The initial number of routees in the pool. + /// The resizer to use when dynamically allocating routees to the pool. + /// The strategy to use when supervising the pool. + /// The dispatcher to use when passing messages to the routees. + /// true to use the pool dispatcher; otherwise false. public RandomPool(int nrOfInstances, Resizer resizer, SupervisorStrategy supervisorStrategy, string routerDispatcher, bool usePoolDispatcher = false) : base(nrOfInstances, resizer, supervisorStrategy, routerDispatcher, usePoolDispatcher) { } + /// + /// Initializes a new instance of the class. + /// + /// The configuration used to configure the pool. public RandomPool(Config config) : base(config) { } /// - /// Simple form of RandomPool constructor + /// Initializes a new instance of the class. + /// + /// + /// A configured in this way uses the supervisor strategy. + /// /// - /// The nr of instances. + /// The initial number of routees in the pool. public RandomPool(int nrOfInstances) : base(nrOfInstances, null, DefaultStrategy, null) { } /// - /// Simple form of RandomPool constructor + /// Initializes a new instance of the class. + /// + /// + /// A configured in this way uses the supervisor strategy. + /// /// - /// The nr of instances. - /// - /// A for specifying how to grow the pool of underlying routees based on - /// pressure - /// + /// The initial number of routees in the pool. + /// The resizer to use when dynamically allocating routees to the pool. public RandomPool(int nrOfInstances, Resizer resizer) : base(nrOfInstances, resizer, DefaultStrategy, null) { } + /// + /// Creates a surrogate representation of the current . + /// + /// The actor system that owns this router. + /// The surrogate representation of the current . public override ISurrogate ToSurrogate(ActorSystem system) { return new RandomPoolSurrogate @@ -151,47 +202,104 @@ public override ISurrogate ToSurrogate(ActorSystem system) } /// - /// Creates the router. + /// Creates a router that is responsible for routing messages to routees within the provided . /// - /// Router. + /// The actor system that owns this router. + /// The newly created router tied to the given system. public override Router CreateRouter(ActorSystem system) { return new Router(new RoundRobinRoutingLogic()); } + /// + /// This class represents a surrogate of a router. + /// Its main use is to help during the serialization process. + /// public class RandomPoolSurrogate : ISurrogate { + /// + /// The number of routees associated with this pool. + /// public int NrOfInstances { get; set; } + /// + /// Determine whether or not to use the pool dispatcher. The dispatcher is defined in the + /// 'pool-dispatcher' configuration property in the deployment section of the router. + /// public bool UsePoolDispatcher { get; set; } + /// + /// The resizer to use when dynamically allocating routees to the pool. + /// public Resizer Resizer { get; set; } + /// + /// The strategy to use when supervising the pool. + /// public SupervisorStrategy SupervisorStrategy { get; set; } + /// + /// The dispatcher to use when passing messages to the routees. + /// public string RouterDispatcher { get; set; } + /// + /// Creates a encapsulated by this surrogate. + /// + /// The actor system that owns this router. + /// The encapsulated by this surrogate. public ISurrogated FromSurrogate(ActorSystem system) { return new RandomPool(NrOfInstances, Resizer, SupervisorStrategy, RouterDispatcher, UsePoolDispatcher); } } + /// + /// Creates a new router with a given . + /// + /// + /// This method is immutable and returns a new instance of the router. + /// + /// + /// The used to configure the new router. + /// A new router with the provided . public override Pool WithSupervisorStrategy(SupervisorStrategy strategy) { return new RandomPool(NrOfInstances, Resizer, strategy, RouterDispatcher, UsePoolDispatcher); } + /// + /// Creates a new router with a given . + /// + /// + /// This method is immutable and returns a new instance of the router. + /// + /// + /// The used to configure the new router. + /// A new router with the provided . public override Pool WithResizer(Resizer resizer) { return new RandomPool(NrOfInstances, resizer, SupervisorStrategy, RouterDispatcher, UsePoolDispatcher); } + /// + /// Creates a new router with a given dispatcher id. + /// + /// + /// This method is immutable and returns a new instance of the router. + /// + /// + /// The dispatcher id used to configure the new router. + /// A new router with the provided dispatcher id. public override Pool WithDispatcher(string dispatcher) { return new RandomPool(NrOfInstances, Resizer, SupervisorStrategy, dispatcher, UsePoolDispatcher); } + /// + /// Configure the current router with an auxiliary router for routes that it does not know how to handle. + /// + /// The router to use as an auxiliary source. + /// The router configured with the auxiliary information. public override RouterConfig WithFallback(RouterConfig routerConfig) { return OverrideUnsetConfig(routerConfig); } } } - diff --git a/src/core/Akka/Routing/RoundRobin.cs b/src/core/Akka/Routing/RoundRobin.cs index 9120204e56e..6293a98515d 100644 --- a/src/core/Akka/Routing/RoundRobin.cs +++ b/src/core/Akka/Routing/RoundRobin.cs @@ -14,29 +14,38 @@ namespace Akka.Routing { /// - /// Class RoundRobinRoutingLogic. + /// This class contains logic used by a to route a message to a determined using round-robin. + /// This process has the router select from a list of routees in sequential order. When the list has been exhausted, the router iterates + /// again from the beginning of the list. + /// + /// + /// For concurrent calls, round robin is just a best effort. + /// /// public class RoundRobinRoutingLogic : RoutingLogic { - + /// + /// Initializes a new instance of the class. + /// public RoundRobinRoutingLogic() : this(-1) {} + /// + /// Initializes a new instance of the class. + /// + /// The index to use when starting the selection process. Note that it will start at (next + 1). public RoundRobinRoutingLogic(int next) { _next = next; } - /// - /// The next - /// private int _next; /// - /// Selects the specified message. + /// Picks the next in the collection to receive the . /// - /// The message. - /// The routees. - /// Routee. + /// The message that is being routed. + /// A collection of routees to choose from when receiving the . + /// A that is receives the . public override Routee Select(object message, Routee[] routees) { if (routees == null || routees.Length == 0) @@ -48,25 +57,49 @@ public override Routee Select(object message, Routee[] routees) } /// - /// A router group that uses round-robin to select a routee. For concurrent calls, - /// round robin is just a best effort. - /// + /// This class represents a router that sends messages to a determined using round-robin. + /// This process has the router select from a list of routees in sequential order. When the list has been exhausted, the router + /// iterates again from the beginning of the list. + /// + /// + /// For concurrent calls, round robin is just a best effort. + /// + /// + /// /// The configuration parameter trumps the constructor arguments. This means that /// if you provide `paths` during instantiation they will be ignored if /// the router is defined in the configuration file for the actor being used. + /// /// public class RoundRobinGroup : Group { + /// + /// This class represents a surrogate of a router. + /// Its main use is to help during the serialization process. + /// public class RoundRobinGroupSurrogate : ISurrogate { + /// + /// Creates a encapsulated by this surrogate. + /// + /// The actor system that owns this router. + /// The encapsulated by this surrogate. public ISurrogated FromSurrogate(ActorSystem system) { return new RoundRobinGroup(Paths); } + /// + /// The actor paths used by this router during routee selection. + /// public string[] Paths { get; set; } } + /// + /// Creates a surrogate representation of the current . + /// + /// The actor system that owns this router. + /// The surrogate representation of the current . public override ISurrogate ToSurrogate(ActorSystem system) { return new RoundRobinGroupSurrogate @@ -76,48 +109,63 @@ public override ISurrogate ToSurrogate(ActorSystem system) } /// - /// Initializes a new instance of the class. + /// Initializes a new instance of the class. /// - /// The configuration. + /// + /// The configuration to use to lookup paths used by the group router. + /// + /// + /// If 'routees.path' is defined in the provided configuration then those paths will be used by the router. + /// + /// public RoundRobinGroup(Config config) : base(config.GetStringList("routees.paths")) { } /// - /// Initializes a new instance of the class. + /// Initializes a new instance of the class. /// - /// The paths. + /// A list of paths used by the group router. public RoundRobinGroup(params string[] paths) : base(paths) { } /// - /// Initializes a new instance of the class. + /// Initializes a new instance of the class. /// - /// The paths. + /// An enumeration of actor paths used by the group router. public RoundRobinGroup(IEnumerable paths) : base(paths) { } /// - /// Initializes a new instance of the class. + /// Initializes a new instance of the class. /// - /// The routees. + /// An enumeration of routees used by the group router. public RoundRobinGroup(IEnumerable routees) : base(routees) { } /// - /// Creates the router. + /// Creates a router that is responsible for routing messages to routees within the provided . /// - /// Router. + /// The actor system that owns this router. + /// The newly created router tied to the given system. public override Router CreateRouter(ActorSystem system) { return new Router(new RoundRobinRoutingLogic()); } + /// + /// Creates a new router with a given dispatcher id. + /// + /// This method is immutable and returns a new instance of the router. + /// + /// + /// The dispatcher id used to configure the new router. + /// A new router with the provided dispatcher id. public override Group WithDispatcher(string dispatcher) { return new RoundRobinGroup(Paths){ RouterDispatcher = dispatcher}; @@ -125,24 +173,60 @@ public override Group WithDispatcher(string dispatcher) } /// - /// Class RoundRobinPool. + /// This class represents a router that sends messages to a determined using round-robin. + /// This process has the router select from a list of routees in sequential order. When the list has been exhausted, the router + /// iterates again from the beginning of the list. + /// + /// + /// For concurrent calls, round robin is just a best effort. + /// /// public class RoundRobinPool : Pool { + /// + /// This class represents a surrogate of a router. + /// Its main use is to help during the serialization process. + /// public class RoundRobinPoolSurrogate : ISurrogate { + /// + /// Creates a encapsulated by this surrogate. + /// + /// The actor system that owns this router. + /// The encapsulated by this surrogate. public ISurrogated FromSurrogate(ActorSystem system) { return new RoundRobinPool(NrOfInstances, Resizer, SupervisorStrategy, RouterDispatcher, UsePoolDispatcher); } + /// + /// The number of routees associated with this pool. + /// public int NrOfInstances { get; set; } + /// + /// Determine whether or not to use the pool dispatcher. The dispatcher is defined in the + /// 'pool-dispatcher' configuration property in the deployment section of the router. + /// public bool UsePoolDispatcher { get; set; } + /// + /// The resizer to use when dynamically allocating routees to the pool. + /// public Resizer Resizer { get; set; } + /// + /// The strategy to use when supervising the pool. + /// public SupervisorStrategy SupervisorStrategy { get; set; } + /// + /// The dispatcher to use when passing messages to the routees. + /// public string RouterDispatcher { get; set; } } + /// + /// Creates a surrogate representation of the current . + /// + /// The actor system that owns this router. + /// The surrogate representation of the current . public override ISurrogate ToSurrogate(ActorSystem system) { return new RoundRobinPoolSurrogate @@ -156,65 +240,108 @@ public override ISurrogate ToSurrogate(ActorSystem system) } /// - + /// Initializes a new instance of the class. /// - /// The nr of instances. - /// The resizer. - /// The supervisor strategy. - /// The router dispatcher. - /// if set to true [use pool dispatcher]. + /// The initial number of routees in the pool. + /// The resizer to use when dynamically allocating routees to the pool. + /// The strategy to use when supervising the pool. + /// The dispatcher to use when passing messages to the routees. + /// true to use the pool dispatcher; otherwise false. public RoundRobinPool(int nrOfInstances, Resizer resizer, SupervisorStrategy supervisorStrategy, string routerDispatcher, bool usePoolDispatcher = false) : base(nrOfInstances, resizer, supervisorStrategy, routerDispatcher, usePoolDispatcher) { } + /// + /// Initializes a new instance of the class. + /// + /// The configuration used to configure the pool. public RoundRobinPool(Config config) : base(config) { - } /// - /// Simple form of RoundRobin constructor + /// Initializes a new instance of the class. + /// + /// + /// A configured in this way uses the supervisor strategy. + /// /// - /// The nr of instances. + /// The initial number of routees in the pool. public RoundRobinPool(int nrOfInstances) : base(nrOfInstances, null, DefaultStrategy, null) { } /// - /// Simple form of RoundRobin constructor + /// Initializes a new instance of the class. + /// + /// + /// A configured in this way uses the supervisor strategy. + /// /// - /// The nr of instances. - /// A for specifying how to grow the pool of underlying routees based on pressure + /// The initial number of routees in the pool. + /// The resizer to use when dynamically allocating routees to the pool. public RoundRobinPool(int nrOfInstances, Resizer resizer) : base(nrOfInstances, resizer, DefaultStrategy, null) { } /// - /// Creates the router. + /// Creates a router that is responsible for routing messages to routees within the provided . /// - /// Router. + /// The actor system that owns this router. + /// The newly created router tied to the given system. public override Router CreateRouter(ActorSystem system) { return new Router(new RoundRobinRoutingLogic()); } + /// + /// Creates a new router with a given . + /// + /// + /// This method is immutable and returns a new instance of the router. + /// + /// + /// The used to configure the new router. + /// A new router with the provided . public override Pool WithSupervisorStrategy(SupervisorStrategy strategy) { return new RoundRobinPool(NrOfInstances, Resizer, strategy, RouterDispatcher, UsePoolDispatcher); } + /// + /// Creates a new router with a given . + /// + /// + /// This method is immutable and returns a new instance of the router. + /// + /// + /// The used to configure the new router. + /// A new router with the provided . public override Pool WithResizer(Resizer resizer) { return new RoundRobinPool(NrOfInstances, resizer, SupervisorStrategy, RouterDispatcher, UsePoolDispatcher); } + /// + /// Creates a new router with a given dispatcher id. + /// + /// + /// This method is immutable and returns a new instance of the router. + /// + /// + /// The dispatcher id used to configure the new router. + /// A new router with the provided dispatcher id. public override Pool WithDispatcher(string dispatcher) { return new RoundRobinPool(NrOfInstances, Resizer, SupervisorStrategy, dispatcher, UsePoolDispatcher); } + /// + /// Configure the current router with an auxiliary router for routes that it does not know how to handle. + /// + /// The router to use as an auxiliary source. + /// The router configured with the auxiliary information. public override RouterConfig WithFallback(RouterConfig routerConfig) { return OverrideUnsetConfig(routerConfig); } } } - diff --git a/src/core/Akka/Routing/Router.cs b/src/core/Akka/Routing/Router.cs index be1d12302d8..80b2a271da7 100644 --- a/src/core/Akka/Routing/Router.cs +++ b/src/core/Akka/Routing/Router.cs @@ -159,8 +159,22 @@ public override void Send(object message, IActorRef sender) } } + /// + /// This class contains logic used by a to route messages to one or more actors. + /// These actors are known in the system as a . + /// public abstract class RoutingLogic { + /// + /// Picks a to receive the . + /// + /// Normally it picks one of the passed routees, but it is up to the implementation + /// to return whatever to use for sending a specific message. + /// + /// + /// The message that is being routed + /// A collection of routees to choose from when receiving the . + /// A that receives the . public abstract Routee Select(object message, Routee[] routees); } diff --git a/src/core/Akka/Routing/RouterConfig.cs b/src/core/Akka/Routing/RouterConfig.cs index 6ffe55b6005..bad1e59ca66 100644 --- a/src/core/Akka/Routing/RouterConfig.cs +++ b/src/core/Akka/Routing/RouterConfig.cs @@ -18,26 +18,56 @@ namespace Akka.Routing { /// - /// Configuration for router actors + /// This class provides base functionality used in the creation and configuration of the various routers in the system. /// public abstract class RouterConfig : IEquatable, ISurrogated { // public abstract RoutingLogic GetLogic(); + /// + /// A configuration that specifies that no router is to be used. + /// public static readonly RouterConfig NoRouter = new NoRouter(); + /// + /// The id of the dispatcher that the router uses to pass messages to its routees. + /// public virtual string RouterDispatcher { get; protected set; } + /// + /// Configure the current router with an auxiliary router for routes that it does not know how to handle. + /// + /// + /// This method defaults to ignoring the supplied router and returning itself. + /// + /// + /// The router to use as an auxiliary source. + /// The router configured with the auxiliary information. public virtual RouterConfig WithFallback(RouterConfig routerConfig) { return this; } + /// + /// Creates a router that is responsible for routing messages to routees within the provided . + /// + /// The actor system that owns this router. + /// The newly created router tied to the given system. public abstract Router CreateRouter(ActorSystem system); internal abstract RouterActor CreateRouterActor(); + /// + /// Retrieves an enumeration of routees that belong to the provided . + /// + /// The router to query for a list of its routees. + /// The enumeration of routees that belong to the provided . public abstract IEnumerable GetRoutees(RoutedActorCell routedActorCell); + /// + /// Determines whether a provided message is handled by the router. + /// + /// The message to inspect. + /// true if this message is handled by the router; otherwise false. public virtual bool IsManagementMessage(object message) { return @@ -46,6 +76,11 @@ message is IAutoReceivedMessage || message is RouterManagementMessage; } + /// + /// Determines whether the specified router, is equal to this instance. + /// + /// The router to compare. + /// true if the specified router is equal to this instance; otherwise, false. public virtual bool Equals(RouterConfig other) { if (other == null) return false; @@ -54,12 +89,28 @@ public virtual bool Equals(RouterConfig other) || String.Equals(RouterDispatcher, other.RouterDispatcher)); } + /// + /// Creates a surrogate representation of the current router. + /// + /// The actor system that owns this router. + /// The surrogate representation of the current router. public abstract ISurrogate ToSurrogate(ActorSystem system); + /// + /// Initializes a new instance of the class. + /// protected RouterConfig() { } + /// + /// Initializes a new instance of the class. + /// + /// + /// This method defaults to setting the dispatcher to use the . + /// + /// + /// The dispatcher to use when passing messages to routees. protected RouterConfig(string routerDispatcher) { // ReSharper disable once DoNotCallOverridableMethodsInConstructor @@ -67,8 +118,16 @@ protected RouterConfig(string routerDispatcher) } } + /// + /// This class contains extension methods used by s. + /// public static class RouterConfigExtensions { + /// + /// Determines whether or not the provided router is a . + /// + /// The router to check. + /// true if the provided router is a ; otherwise, false. public static bool NoRouter(this RouterConfig config) { return config == null || config is NoRouter; @@ -76,10 +135,18 @@ public static bool NoRouter(this RouterConfig config) } /// - /// Signals that no Router is to be used with a given + /// This class represents a router that does not route messages. /// public class NoRouter : RouterConfig { + /// + /// The id of the dispatcher that the router uses to pass messages to its routees. + /// + /// + /// THIS METHOD IS NOT IMPLEMENTED. + /// + /// + /// NoRouter has no router public override string RouterDispatcher { get { throw new NotSupportedException("NoRouter has no router"); } @@ -90,30 +157,76 @@ internal override RouterActor CreateRouterActor() throw new NotImplementedException(); } + /// + /// Creates a router that is responsible for routing messages to routees within the provided . + /// + /// + /// THIS METHOD IS NOT IMPLEMENTED. + /// + /// + /// The actor system that owns this router. + /// + /// The newly created router tied to the given system. + /// + /// public override Router CreateRouter(ActorSystem system) { throw new NotImplementedException(); } + /// + /// Retrieves an enumeration of routees that belong to the provided . + /// + /// + /// THIS METHOD IS NOT IMPLEMENTED. + /// + /// + /// The router to query for a list of its routees. + /// + /// The enumeration of routees that belong to the provided . + /// + /// public override IEnumerable GetRoutees(RoutedActorCell routedActorCell) { throw new NotImplementedException(); } + /// + /// This class represents a surrogate of a router. + /// Its main use is to help during the serialization process. + /// public class NoRouterSurrogate : ISurrogate { - + /// + /// Creates a encapsulated by this surrogate. + /// + /// The actor system that owns this router. + /// The encapsulated by this surrogate. public ISurrogated FromSurrogate(ActorSystem system) { return new NoRouter(); } } + /// + /// Creates a surrogate representation of the current . + /// + /// The actor system that owns this router. + /// The surrogate representation of the current . public override ISurrogate ToSurrogate(ActorSystem system) { return new NoRouterSurrogate(); } + /// + /// Configure the current router with an auxiliary router for routes that it does not know how to handle. + /// + /// + /// This method returns the provided . + /// + /// + /// The router to use as an auxiliary source. + /// The router configured with the auxiliary information. public override RouterConfig WithFallback(RouterConfig routerConfig) { return routerConfig; @@ -121,10 +234,18 @@ public override RouterConfig WithFallback(RouterConfig routerConfig) } /// - /// Base class for defining Group routers. + /// This class provides base functionality for all group routers in the system. + /// Group routers are routers that use already created routees. These routees + /// are supplied to the router and are addressed through + /// paths. /// public abstract class Group : RouterConfig, IEquatable { + /// + /// Determines whether the specified , is equal to this instance. + /// + /// The group to compare. + /// true if the specified is equal to this instance; otherwise, false. public bool Equals(Group other) { if (ReferenceEquals(null, other)) return false; @@ -132,6 +253,13 @@ public bool Equals(Group other) return _paths.SequenceEqual(other._paths); } + /// + /// Determines whether the specified , is equal to this instance. + /// + /// The to compare with this instance. + /// + /// true if the specified is equal to this instance; otherwise, false. + /// public override bool Equals(object obj) { if (ReferenceEquals(null, obj)) return false; @@ -140,6 +268,12 @@ public override bool Equals(object obj) return Equals((Group) obj); } + /// + /// Returns a hash code for this instance. + /// + /// + /// A hash code for this instance, suitable for use in hashing algorithms and data structures like a hash table. + /// public override int GetHashCode() { return (_paths != null ? _paths.GetHashCode() : 0); @@ -147,36 +281,66 @@ public override int GetHashCode() private readonly string[] _paths; + /// + /// Retrieves the actor paths used by this router during routee selection. + /// public string[] Paths { get { return _paths; } } + /// + /// Initializes a new instance of the class. + /// + /// + /// This constructor sets up the group to use the default dispatcher . + /// + /// + /// An enumeration of actor paths used by the group router. protected Group(IEnumerable paths) : base(Dispatchers.DefaultDispatcherId) { _paths = paths.ToArray(); } + /// + /// Initializes a new instance of the class. + /// + /// + /// If a is not provided, this constructor sets up + /// the pool to use the default dispatcher . + /// + /// + /// An enumeration of actor paths used by the group router. + /// The dispatcher to use when passing messages to the routees. protected Group(IEnumerable paths, string routerDispatcher) : base(routerDispatcher ?? Dispatchers.DefaultDispatcherId) { _paths = paths.ToArray(); } + /// + /// Initializes a new instance of the class. + /// + /// + /// This constructor sets up the group to use the default dispatcher . + /// + /// + /// An enumeration of routees used by the group router. protected Group(IEnumerable routees) : base(Dispatchers.DefaultDispatcherId) { _paths = routees.Select(x => x.Path.ToStringWithAddress()).ToArray(); } - /// - /// INTERNAL API - /// internal Routee RouteeFor(string path, IActorContext context) { return new ActorSelectionRoutee(context.ActorSelection(path)); } + /// + /// Adds the current router to an empty . + /// + /// An empty configured to use the current router. public Props Props() { return Actor.Props.Empty.WithRouter(this); @@ -187,18 +351,41 @@ internal override RouterActor CreateRouterActor() return new RouterActor(); } + /// + /// Creates a router that is responsible for routing messages to routees within the provided . + /// + /// + /// THIS METHOD IS NOT IMPLEMENTED. + /// + /// + /// The actor system that owns this router. + /// + /// The newly created router tied to the given system. + /// + /// public override Router CreateRouter(ActorSystem system) { throw new NotImplementedException(); } /// - /// Returns a new instance of the router with a new dispatcher id. + /// Creates a new router with a given dispatcher id. /// - /// NOTE: this method is immutable and returns a new instance of the . + /// + /// This method is immutable and returns a new instance of the router. + /// /// + /// The dispatcher id used to configure the new router. + /// A new router with the provided dispatcher id. public abstract Group WithDispatcher(string dispatcher); + /// + /// Retrieves an enumeration of routees that belong to the provided . + /// + /// The router to query for a list of its routees. + /// + /// The enumeration of routees that belong to the provided . + /// public override IEnumerable GetRoutees(RoutedActorCell routedActorCell) { if (_paths == null) return new Routee[0]; @@ -207,6 +394,13 @@ public override IEnumerable GetRoutees(RoutedActorCell routedActorCell) .Select(actor => new ActorSelectionRoutee(actor)); } + /// + /// Determines whether the specified router, is equal to this instance. + /// + /// The router to compare. + /// + /// true if the specified router is equal to this instance; otherwise, false. + /// public override bool Equals(RouterConfig other) { if (!base.Equals(other)) return false; @@ -218,7 +412,9 @@ public override bool Equals(RouterConfig other) /// - /// Base class for defining Pool routers + /// This class provides base functionality for all pool routers in the system. + /// Pool routers are routers that create their own routees based on the provided + /// configuration. /// public abstract class Pool : RouterConfig, IEquatable { @@ -227,6 +423,12 @@ public abstract class Pool : RouterConfig, IEquatable private readonly Resizer _resizer; private readonly SupervisorStrategy _supervisorStrategy; //TODO: add supervisor strategy to the equality compare + + /// + /// Determines whether the specified , is equal to this instance. + /// + /// The pool to compare. + /// true if the specified is equal to this instance; otherwise, false. public bool Equals(Pool other) { if (ReferenceEquals(null, other)) return false; @@ -235,6 +437,13 @@ public bool Equals(Pool other) NrOfInstances == other.NrOfInstances; } + /// + /// Determines whether the specified , is equal to this instance. + /// + /// The to compare with this instance. + /// + /// true if the specified is equal to this instance; otherwise, false. + /// public override bool Equals(object obj) { if (ReferenceEquals(null, obj)) return false; @@ -243,6 +452,12 @@ public override bool Equals(object obj) return Equals((Pool) obj); } + /// + /// Returns a hash code for this instance. + /// + /// + /// A hash code for this instance, suitable for use in hashing algorithms and data structures like a hash table. + /// public override int GetHashCode() { unchecked @@ -254,6 +469,19 @@ public override int GetHashCode() } } + /// + /// Initializes a new instance of the class. + /// + /// + /// If a is not provided, this constructor sets up + /// the pool to use the default dispatcher . + /// + /// + /// The initial number of routees in the pool. + /// The resizer to use when dynamically allocating routees to the pool. + /// The strategy to use when supervising the pool. + /// The dispatcher to use when passing messages to the routees. + /// true to use the pool dispatcher; otherwise false. protected Pool(int nrOfInstances, Resizer resizer, SupervisorStrategy supervisorStrategy, string routerDispatcher, bool usePoolDispatcher = false) : base(routerDispatcher ?? Dispatchers.DefaultDispatcherId) @@ -268,6 +496,14 @@ protected Pool(int nrOfInstances, Resizer resizer, SupervisorStrategy supervisor _usePoolDispatcher = usePoolDispatcher; } + /// + /// Initializes a new instance of the class. + /// + /// + /// This constructor sets up the pool to use the default dispatcher . + /// + /// + /// The configuration used to configure the pool. protected Pool(Config config) : base(Dispatchers.DefaultDispatcherId) { _nrOfInstances = config.GetInt("nr-of-instances"); @@ -278,7 +514,7 @@ protected Pool(Config config) : base(Dispatchers.DefaultDispatcherId) } /// - /// The number of instances in the pool. + /// Retrieves the number of routees associated with this pool. /// public virtual int NrOfInstances { @@ -288,15 +524,20 @@ public virtual int NrOfInstances /// /// Used by the to determine the initial number of routees. /// + /// /// Needs to be connected to an for clustered deployment scenarios. + /// /// + /// + /// The number of routees associated with this pool. public virtual int GetNrOfInstances(ActorSystem system) { return NrOfInstances; } /// - /// Whether or not to use the pool dispatcher. + /// Retrieve whether or not to use the pool dispatcher. The dispatcher is defined in the + /// 'pool-dispatcher' configuration property in the deployment section of the router. /// public virtual bool UsePoolDispatcher { @@ -304,7 +545,7 @@ public virtual bool UsePoolDispatcher } /// - /// An instance of the resizer for this pool. + /// Retrieve the resizer to use when dynamically allocating routees to the pool. /// public virtual Resizer Resizer { @@ -312,13 +553,23 @@ public virtual Resizer Resizer } /// - /// An instance of the supervisor strategy for this pool. + /// Retrieve the strategy to use when supervising the pool. /// public virtual SupervisorStrategy SupervisorStrategy { get { return _supervisorStrategy; } } + /// + /// Creates a new configured to use the provided + /// and the pool dispatcher if enabled. + /// + /// The to configure with the pool dispatcher. + /// The context for the provided . + /// + /// A new configured to use the provided + /// and the pool dispatcher if enabled. + /// public virtual Routee NewRoutee(Props routeeProps, IActorContext context) { var routee = new ActorRefRoutee(context.ActorOf(EnrichWithPoolDispatcher(routeeProps, context))); @@ -342,6 +593,11 @@ internal Props EnrichWithPoolDispatcher(Props routeeProps, IActorContext context return routeeProps; } + /// + /// Adds the current router to the provided . + /// + /// The to configure with the current router. + /// The provided configured to use the current router. public Props Props(Props routeeProps) { return routeeProps.WithRouter(this); @@ -354,6 +610,13 @@ internal override RouterActor CreateRouterActor() return new ResizablePoolActor(SupervisorStrategy); } + /// + /// Retrieves an enumeration of routees that belong to the provided . + /// + /// The router to query for a list of its routees. + /// + /// The enumeration of routees that belong to the provided . + /// public override IEnumerable GetRoutees(RoutedActorCell routedActorCell) { for (var i = 0; i < NrOfInstances; i++) @@ -363,6 +626,11 @@ public override IEnumerable GetRoutees(RoutedActorCell routedActorCell) } } + /// + /// Overrides the settings of the current router with those in the provided configuration. + /// + /// The configuration whose settings are used to overwrite the current router. + /// The current router whose settings have been overwritten. protected RouterConfig OverrideUnsetConfig(RouterConfig other) { if (other is NoRouter) return this; // NoRouter is the default, hence "neutral" @@ -384,31 +652,48 @@ protected RouterConfig OverrideUnsetConfig(RouterConfig other) } /// - /// Returns a new instance of the router with a new . + /// Creates a new router with a given . /// - /// NOTE: this method is immutable and returns a new instance of the . + /// + /// This method is immutable and returns a new instance of the router. + /// /// + /// The used to configure the new router. + /// A new router with the provided . public abstract Pool WithSupervisorStrategy(SupervisorStrategy strategy); /// - /// Returns a new instance of the router with a new . + /// Creates a new router with a given . /// - /// NOTE: this method is immutable and returns a new instance of the . + /// + /// This method is immutable and returns a new instance of the router. + /// /// + /// The used to configure the new router. + /// A new router with the provided . public abstract Pool WithResizer(Resizer resizer); /// - /// Returns a new instance of the router with a new dispatcher id. + /// Creates a new router with a given dispatcher id. /// - /// NOTE: this method is immutable and returns a new instance of the . + /// + /// This method is immutable and returns a new instance of the router. + /// /// + /// The dispatcher id used to configure the new router. + /// A new router with the provided dispatcher id. public abstract Pool WithDispatcher(string dispatcher); #region Static methods /// - /// When supervisorStrategy is not specified for an actor this - /// is used by default. OneForOneStrategy with a decider which escalates by default. + /// Retrieves the default used by this router when one has not been specified. + /// When supervisorStrategy is not specified for an actor this + /// is used by default. + /// + /// + /// The default strategy used is with an decider. + /// /// public static SupervisorStrategy DefaultStrategy { @@ -434,11 +719,11 @@ public static SupervisorStrategy DefaultStrategy } /// - /// Used to tell to create router based on what's stored in configuration. + /// This class represents a router that gets it's configuration from the system. /// /// For example: /// - /// ActorRef router1 = Sys.ActorOf(Props.Create{Echo}().WithRouter(FromConfig.Instance), "router1"); + /// IActorRef router1 = Sys.ActorOf(Props.Create{Echo}().WithRouter(FromConfig.Instance), "router1"); /// /// public class FromConfig : RouterConfig @@ -449,11 +734,30 @@ private FromConfig(string routerDispatcher) : base(routerDispatcher) { } + /// + /// Retrieves a based on what's stored in the configuration. + /// + /// + /// This router is set to use the default dispatcher . + /// + /// public static FromConfig Instance { get { return _instance; } } + /// + /// Creates a router that is responsible for routing messages to routees within the provided . + /// + /// + /// THIS METHOD IS NOT SUPPORTED. + /// + /// + /// The actor system that owns this router. + /// + /// The newly created router tied to the given system. + /// + /// public override Router CreateRouter(ActorSystem system) { throw new NotSupportedException(); @@ -464,20 +768,45 @@ internal override RouterActor CreateRouterActor() throw new NotSupportedException(); } + /// + /// Retrieves an enumeration of routees that belong to a provided . + /// + /// + /// THIS METHOD IS NOT SUPPORTED. + /// + /// + /// The router to query for a list of its routees. + /// + /// The enumeration of routees that belong to the provided . + /// + /// public override IEnumerable GetRoutees(RoutedActorCell routedActorCell) { throw new NotSupportedException(); } + /// + /// This class represents a surrogate of a router. + /// Its main use is to help during the serialization process. + /// public class FromConfigSurrogate : ISurrogate { - + /// + /// Creates a encapsulated by this surrogate. + /// + /// The actor system that owns this router. + /// The encapsulated by this surrogate. public ISurrogated FromSurrogate(ActorSystem system) { return Instance; } } + /// + /// Creates a surrogate representation of the current . + /// + /// The actor system that owns this router. + /// The surrogate representation of the current . public override ISurrogate ToSurrogate(ActorSystem system) { return new FromConfigSurrogate(); diff --git a/src/core/Akka/Routing/ScatterGatherFirstCompleted.cs b/src/core/Akka/Routing/ScatterGatherFirstCompleted.cs index 800b080e2a7..82c9044246a 100644 --- a/src/core/Akka/Routing/ScatterGatherFirstCompleted.cs +++ b/src/core/Akka/Routing/ScatterGatherFirstCompleted.cs @@ -14,13 +14,31 @@ namespace Akka.Routing { + /// + /// This class contains logic used by a to route a message to a determined + /// using scatter-gather-first-completed. This process has the router send a message to all of its routees. The first + /// response is used and the remaining are discarded. If the none of the routees respond within a specified time + /// limit, a timeout failure occurs. + /// public class ScatterGatherFirstCompletedRoutingLogic : RoutingLogic { private TimeSpan _within; + + /// + /// Initializes a new instance of the class. + /// + /// The amount of time to wait for a response. public ScatterGatherFirstCompletedRoutingLogic(TimeSpan within) { _within = within; } + + /// + /// Picks all the provided to receive the . + /// + /// The message that is being routed + /// A collection of routees to choose from when receiving the . + /// A that receives the . public override Routee Select(object message, Routee[] routees) { if (routees == null || routees.Length == 0) @@ -31,22 +49,39 @@ public override Routee Select(object message, Routee[] routees) } } + /// + /// This class represents a single point that sends messages to a determined + /// using scatter-gather-first-completed. This process has the router send a message to all of its routees. The first + /// response is used and the remaining are discarded. If the none of the routees respond within a specified time limit, + /// a timeout failure occurs. + /// public class ScatterGatherFirstCompletedRoutees : Routee { private Routee[] _routees; private TimeSpan _within; + + /// + /// Initializes a new instance of the class. + /// + /// The list of routees that the router uses to send messages. + /// The time within which at least one response is expected. public ScatterGatherFirstCompletedRoutees(Routee[] routees, TimeSpan within) { _routees = routees; _within = within; } + /// + /// Sends a message to the collection of routees. + /// + /// The message that is being sent. + /// The actor sending the message. public override void Send(object message, IActorRef sender) { var tasks = new List(); foreach(var routee in _routees) { - var ask = routee.Ask(message, _within); + var ask = routee.Ask(message, _within); tasks.Add(ask); } var any = Task.WhenAny(tasks); @@ -54,19 +89,44 @@ public override void Send(object message, IActorRef sender) } } + /// + /// This class represents a router that sends messages to a determined using scatter-gather-first-completed. + /// This process has the router send a message to all of its routees. The first response is used and the remaining are discarded. If the none of the + /// routees respond within a specified time limit, a timeout failure occurs. + /// public class ScatterGatherFirstCompletedGroup : Group { + /// + /// This class represents a surrogate of a router. + /// Its main use is to help during the serialization process. + /// public class ScatterGatherFirstCompletedGroupSurrogate : ISurrogate { + /// + /// Creates a encapsulated by this surrogate. + /// + /// The actor system that owns this router. + /// The encapsulated by this surrogate. public ISurrogated FromSurrogate(ActorSystem system) { return new ScatterGatherFirstCompletedGroup(Paths,Within); } + /// + /// The amount of time to wait for a response. + /// public TimeSpan Within { get; set; } + /// + /// The actor paths used by this router during routee selection. + /// public string[] Paths { get; set; } } + /// + /// Creates a surrogate representation of the current . + /// + /// The actor system that owns this router. + /// The surrogate representation of the current . public override ISurrogate ToSurrogate(ActorSystem system) { return new ScatterGatherFirstCompletedGroupSurrogate @@ -77,9 +137,16 @@ public override ISurrogate ToSurrogate(ActorSystem system) } /// - /// Initializes a new instance of the class. + /// Initializes a new instance of the class. /// - /// The configuration. + /// + /// The configuration to use to lookup paths used by the group router. + /// + /// + /// If 'routees.path' is defined in the provided configuration then those paths will be used by the router. + /// If 'within' is defined in the provided configuration then that will be used as the interval. + /// + /// public ScatterGatherFirstCompletedGroup(Config config) : base(config.GetStringList("routees.paths")) { @@ -87,10 +154,10 @@ public ScatterGatherFirstCompletedGroup(Config config) } /// - /// Initializes a new instance of the class. + /// Initializes a new instance of the class. /// - /// Expect a response within the given timespan - /// The paths. + /// The amount of time to wait for a response. + /// A list of actor paths used by the group router. public ScatterGatherFirstCompletedGroup(TimeSpan within,params string[] paths) : base(paths) { @@ -98,36 +165,48 @@ public ScatterGatherFirstCompletedGroup(TimeSpan within,params string[] paths) } /// - /// Initializes a new instance of the class. + /// Initializes a new instance of the class. /// - /// The paths. - /// Expect a response within the given timespan + /// An enumeration of actor paths used by the group router. + /// The amount of time to wait for a response. public ScatterGatherFirstCompletedGroup(IEnumerable paths,TimeSpan within) : base(paths) { Within = within; } /// - /// Initializes a new instance of the class. + /// Initializes a new instance of the class. /// - /// The routees. - /// Expect a response within the given timespan + /// An enumeration of routees used by the group router. + /// The amount of time to wait for a response. public ScatterGatherFirstCompletedGroup(IEnumerable routees,TimeSpan within) : base(routees) { Within = within; } + /// + /// The amount of time to wait for a response. + /// public TimeSpan Within { get;private set; } /// - /// Creates the router. + /// Creates a router that is responsible for routing messages to routees within the provided . /// - /// Router. + /// The actor system that owns this router. + /// The newly created router tied to the given system. public override Router CreateRouter(ActorSystem system) { return new Router(new ScatterGatherFirstCompletedRoutingLogic(Within)); } + /// + /// Creates a new router with a given dispatcher id. + /// + /// This method is immutable and returns a new instance of the router. + /// + /// + /// The dispatcher id used to configure the new router. + /// A new router with the provided dispatcher id. public override Group WithDispatcher(string dispatcher) { return new ScatterGatherFirstCompletedGroup(Within, Paths){ RouterDispatcher = dispatcher}; @@ -135,25 +214,60 @@ public override Group WithDispatcher(string dispatcher) } /// - /// Class RoundRobinPool. + /// This class represents a router that sends messages to a determined using scatter-gather-first-completed. + /// This process has the router send a message to all of its routees. The first response is used and the remaining are discarded. If the none of the + /// routees respond within a specified time limit, a timeout failure occurs. /// public class ScatterGatherFirstCompletedPool : Pool { + /// + /// This class represents a surrogate of a router. + /// Its main use is to help during the serialization process. + /// public class ScatterGatherFirstCompletedPoolSurrogate : ISurrogate { + /// + /// Creates a encapsulated by this surrogate. + /// + /// The actor system that owns this router. + /// The encapsulated by this surrogate. public ISurrogated FromSurrogate(ActorSystem system) { return new ScatterGatherFirstCompletedPool(NrOfInstances, Resizer, SupervisorStrategy, RouterDispatcher,Within, UsePoolDispatcher); } + /// + /// The amount of time to wait for a response. + /// public TimeSpan Within { get; set; } + /// + /// The number of routees associated with this pool. + /// public int NrOfInstances { get; set; } + /// + /// Determine whether or not to use the pool dispatcher. The dispatcher is defined in the + /// 'pool-dispatcher' configuration property in the deployment section of the router. + /// public bool UsePoolDispatcher { get; set; } + /// + /// The resizer to use when dynamically allocating routees to the pool. + /// public Resizer Resizer { get; set; } + /// + /// The strategy to use when supervising the pool. + /// public SupervisorStrategy SupervisorStrategy { get; set; } + /// + /// The dispatcher to use when passing messages to the routees. + /// public string RouterDispatcher { get; set; } } + /// + /// Creeates a surrogate representation of the current . + /// + /// The actor system that owns this router. + /// The surrogate representation of the current . public override ISurrogate ToSurrogate(ActorSystem system) { return new ScatterGatherFirstCompletedPoolSurrogate @@ -168,14 +282,16 @@ public override ISurrogate ToSurrogate(ActorSystem system) } private TimeSpan _within; + /// + /// Initializes a new instance of the class. /// - /// The nr of instances. - /// The resizer. - /// The supervisor strategy. - /// The router dispatcher. - /// Expect a response within the given timespan - /// if set to true [use pool dispatcher]. + /// The initial number of routees in the pool. + /// The resizer to use when dynamically allocating routees to the pool. + /// The strategy to use when supervising the pool. + /// The dispatcher to use when passing messages to the routees. + /// The amount of time to wait for a response. + /// true to use the pool dispatcher; otherwise false. public ScatterGatherFirstCompletedPool(int nrOfInstances, Resizer resizer, SupervisorStrategy supervisorStrategy, string routerDispatcher,TimeSpan within, bool usePoolDispatcher = false) : base(nrOfInstances, resizer, supervisorStrategy, routerDispatcher, usePoolDispatcher) @@ -184,53 +300,99 @@ public ScatterGatherFirstCompletedPool(int nrOfInstances, Resizer resizer, Super } /// + /// Initializes a new instance of the class. /// - /// The nr of instances. - /// Expect a response within the given timespan + /// The initial number of routees in the pool. + /// The amount of time to wait for a response. public ScatterGatherFirstCompletedPool(int nrOfInstances, TimeSpan within) : this(nrOfInstances) { _within = within; } + /// + /// Initializes a new instance of the class. + /// + /// + /// The configuration to use to lookup paths used by the group router. + /// + /// + /// 'within' must be defined in the provided configuration. + /// + /// public ScatterGatherFirstCompletedPool(Config config) : base(config) { _within = config.GetTimeSpan("within"); } /// - /// Simple form of RoundRobin constructor + /// Initializes a new instance of the class. + /// + /// + /// A configured in this way uses the supervisor strategy. + /// /// - /// The nr of instances. + /// The initial number of routees in the pool. public ScatterGatherFirstCompletedPool(int nrOfInstances) : base(nrOfInstances, null, DefaultStrategy, null) { } /// - /// Creates the router. + /// Creates a router that is responsible for routing messages to routees within the provided . /// - /// Router. + /// The actor system that owns this router. + /// The newly created router tied to the given system. public override Router CreateRouter(ActorSystem system) { return new Router(new ScatterGatherFirstCompletedRoutingLogic(_within)); } + /// + /// Creates a new router with a given . + /// + /// + /// This method is immutable and returns a new instance of the router. + /// + /// + /// The used to configure the new router. + /// A new router with the provided . public override Pool WithSupervisorStrategy(SupervisorStrategy strategy) { return new ScatterGatherFirstCompletedPool(NrOfInstances, Resizer, strategy, RouterDispatcher, _within, UsePoolDispatcher); } + /// + /// Creates a new router with a given . + /// + /// This method is immutable and returns a new instance of the router. + /// + /// + /// The used to configure the new router. + /// A new router with the provided . public override Pool WithResizer(Resizer resizer) { return new ScatterGatherFirstCompletedPool(NrOfInstances, resizer, SupervisorStrategy, RouterDispatcher, _within, UsePoolDispatcher); } + /// + /// Creates a new router with a given dispatcher id. + /// + /// + /// This method is immutable and returns a new instance of the router. + /// + /// + /// The dispatcher id used to configure the new router. + /// A new router with the provided dispatcher id. public override Pool WithDispatcher(string dispatcher) { return new ScatterGatherFirstCompletedPool(NrOfInstances, Resizer, SupervisorStrategy, dispatcher, _within, UsePoolDispatcher); } + /// + /// Configure the current router with an auxiliary router for routes that it does not know how to handle. + /// + /// The router to use as an auxiliary source. + /// The router configured with the auxiliary information. public override RouterConfig WithFallback(RouterConfig routerConfig) { return OverrideUnsetConfig(routerConfig); } } } - diff --git a/src/core/Akka/Routing/TailChoppingRoutingLogic.cs b/src/core/Akka/Routing/TailChoppingRoutingLogic.cs index ee945c71e4e..7f6dadbe449 100644 --- a/src/core/Akka/Routing/TailChoppingRoutingLogic.cs +++ b/src/core/Akka/Routing/TailChoppingRoutingLogic.cs @@ -16,33 +16,25 @@ namespace Akka.Routing { /// - /// The routing logic for the TailChoppingRouter. This router will send a message to a randomly chosen - /// routee, and after a delay, send to a different randomly chosen routee. The first response is forwarded, - /// and all other responses are discarded. + /// This class contains logic used by a to route a message to a determined using tail-chopping. + /// This process has the router select a random routee, then waits an interval before sending to a different randomly chosen routee. + /// The first response is used and the remaining are discarded. If the none of the routees respond within a specified time limit, + /// a timeout failure occurs. /// public sealed class TailChoppingRoutingLogic : RoutingLogic { - /// - /// The amount of time to wait for a response. - /// private readonly TimeSpan _within; - /// - /// The interval to delay between choosing a new random routee. - /// private readonly TimeSpan _interval; - /// - /// An instance of the actor system scheduler. - /// private readonly IScheduler _scheduler; /// - /// Creates an instance of the TailChoppingRoutingLogic. + /// Initializes a new instance of the class. /// /// The time within which at least one response is expected. /// The duration after which the next routee will be picked. - /// The scheduler to use + /// The used to force deadlines. public TailChoppingRoutingLogic(TimeSpan within, TimeSpan interval, IScheduler scheduler) { _within = within; @@ -51,11 +43,11 @@ public TailChoppingRoutingLogic(TimeSpan within, TimeSpan interval, IScheduler s } /// - /// Selects all routees and creates a TailChoppingRoutee. + /// Picks all of the provided to receive the . /// - /// The message to use. - /// The routees to select from. - /// A TailChoppingRoutee to handle the tail chopping routing. + /// The message that is being routed + /// A collection of routees used when receiving the . + /// A that receives the . public override Routee Select(object message, Routee[] routees) { if(routees.IsNullOrEmpty()) @@ -67,37 +59,28 @@ public override Routee Select(object message, Routee[] routees) } /// - /// A single point routee that routes to randomly chosen routees at a given interval. Accepts the first response. + /// This class represents a single point that sends messages to a determined using tail-chopping. + /// This process has the routee select a random routee, then waits an interval before sending to a different randomly chosen routee. + /// The first response is used and the remaining are discarded. If the none of the routees respond within a specified time limit, + /// a timeout failure occurs. /// internal sealed class TailChoppingRoutee : Routee { - /// - /// The collection of possible routees to send messages to. - /// private readonly Routee[] _routees; - /// - /// The amount of time to wait for a response. - /// private readonly TimeSpan _within; - /// - /// The interval to wait before sending to the next routee. - /// private readonly TimeSpan _interval; - /// - /// An instance of the actor system scheduler. - /// private readonly IScheduler _scheduler; /// - /// Creates an instance of the TailChoppingRoutee. + /// Initializes a new instance of the class. /// - /// The routees to route to. + /// The list of routees that the router uses to send messages. /// The time within which at least one response is expected. /// The duration after which the next routee will be picked. - /// Access to a instance, used to force deadlines. + /// The used to force deadlines. public TailChoppingRoutee(Routee[] routees, TimeSpan within, TimeSpan interval, IScheduler scheduler) { _routees = routees; @@ -107,10 +90,10 @@ public TailChoppingRoutee(Routee[] routees, TimeSpan within, TimeSpan interval, } /// - /// Sends a message to the tail chopping router's collection of routees. + /// Sends a message to the collection of routees. /// - /// The message to send. - /// The sender of the message. + /// The message that is being sent. + /// The actor sending the message. public override void Send(object message, IActorRef sender) { _routees.Shuffle(); @@ -153,27 +136,61 @@ public override void Send(object message, IActorRef sender) } /// - /// A router pool that selects a random routee, then waits an interval before sending to a - /// different routee. The first response is used and the remaining discarded. + /// This class represents a router that sends messages to a determined using tail-chopping. + /// This process has the router select a random routee, then waits an interval before sending to a different randomly chosen routee. + /// The first response is used and the remaining are discarded. If the none of the routees respond within a specified time limit, + /// a timeout failure occurs. /// public sealed class TailChoppingPool : Pool { + /// + /// This class represents a surrogate of a router. + /// Its main use is to help during the serialization process. + /// public class TailChoppingPoolSurrogate : ISurrogate { + /// + /// Creates a encapsulated by this surrogate. + /// + /// The actor system that owns this router. + /// The encapsulated by this surrogate. public ISurrogated FromSurrogate(ActorSystem system) { return new TailChoppingPool(NrOfInstances, Resizer, SupervisorStrategy, RouterDispatcher, Within, Interval, UsePoolDispatcher); } + /// The interval to wait before sending to the next routee. public TimeSpan Interval { get; set; } + /// The amount of time to wait for a response. public TimeSpan Within { get; set; } + /// + /// The number of routees associated with this pool. + /// public int NrOfInstances { get; set; } + /// + /// Determine whether or not to use the pool dispatcher. The dispatcher is defined in the + /// 'pool-dispatcher' configuration property in the deployment section of the router. + /// public bool UsePoolDispatcher { get; set; } + /// + /// The resizer to use when dynamically allocating routees to the pool. + /// public Resizer Resizer { get; set; } + /// + /// The strategy to use when supervising the pool. + /// public SupervisorStrategy SupervisorStrategy { get; set; } + /// + /// The dispatcher to use when passing messages to the routees. + /// public string RouterDispatcher { get; set; } } + /// + /// Creates a surrogate representation of the current . + /// + /// The actor system that owns this router. + /// The surrogate representation of the current . public override ISurrogate ToSurrogate(ActorSystem system) { return new TailChoppingPoolSurrogate @@ -188,26 +205,20 @@ public override ISurrogate ToSurrogate(ActorSystem system) }; } - /// - /// The amount of time to wait for a response. - /// private readonly TimeSpan _within; - /// - /// The interval to wait before sending to the next routee. - /// private readonly TimeSpan _interval; /// - /// Creates an instance of the TailChoppingPool. + /// Initializes a new instance of the class. /// /// The initial number of routees in the pool. - /// The resizer to use with this instance. - /// The supervision strategy to use with this pool. - /// The router dispatcher to use with this instance. + /// The resizer to use when dynamically allocating routees to the pool. + /// The strategy to use when supervising the pool. + /// The dispatcher to use when passing messages to the routees. /// The amount of time to wait for a response. /// The interval to wait before sending to the next routee. - /// Whether or not to use the pool dispatcher. + /// true to use the pool dispatcher; otherwise false. public TailChoppingPool(int nrOfInstances, Resizer resizer, SupervisorStrategy supervisorStrategy, string routerDispatcher, TimeSpan within, TimeSpan interval, bool usePoolDispatcher = false) : base(nrOfInstances, resizer, supervisorStrategy, routerDispatcher, usePoolDispatcher) @@ -217,9 +228,14 @@ public TailChoppingPool(int nrOfInstances, Resizer resizer, SupervisorStrategy s } /// - /// Creates an instance of the TailChoppingPool. + /// Initializes a new instance of the class. + /// + /// + /// 'nr-of-instances', 'within', and 'tail-chopping-router.interval' + /// must be defined in the provided configuration. + /// /// - /// The configuration to use with this instance. + /// The configuration used to configure the pool. public TailChoppingPool(Config config) : this(config.GetInt("nr-of-instances"), DefaultResizer.FromConfig(config), @@ -233,7 +249,7 @@ public TailChoppingPool(Config config) } /// - /// Creates an instance of the TailChoppingPool. + /// Initializes a new instance of the class. /// /// The initial number of routees in the pool. /// The amount of time to wait for a response. @@ -245,45 +261,62 @@ public TailChoppingPool(int nrOfInstances, TimeSpan within, TimeSpan interval) } /// - /// Sets the supervisor strategy to use for the pool. + /// Creates a new router with a given . + /// + /// + /// This method is immutable and returns a new instance of the router. + /// /// - /// The strategy to use. - /// The tail chopping pool. + /// The used to configure the new router. + /// A new router with the provided . public override Pool WithSupervisorStrategy(SupervisorStrategy strategy) { return new TailChoppingPool(NrOfInstances, Resizer, strategy, RouterDispatcher, _within, _interval, UsePoolDispatcher); } /// - /// Sets the resizer to use for the pool. + /// Creates a new router with a given . + /// + /// + /// This method is immutable and returns a new instance of the router. + /// /// - /// The resizer to use. - /// The tail chopping pool. + /// The used to configure the new router. + /// A new router with the provided . public override Pool WithResizer(Resizer resizer) { return new TailChoppingPool(NrOfInstances, resizer, SupervisorStrategy, RouterDispatcher, _within, _interval, UsePoolDispatcher); } /// - /// Sets the router dispatcher to use for the pool. + /// Creates a new router with a given dispatcher id. + /// + /// + /// This method is immutable and returns a new instance of the router. + /// /// - /// The router dispatcher to use. - /// The tail chopping pool. - public override Pool WithDispatcher(string routerDispatcher) + /// The dispatcher id used to configure the new router. + /// A new router with the provided dispatcher id. + public override Pool WithDispatcher(string dispatcher) { - return new TailChoppingPool(NrOfInstances, Resizer, SupervisorStrategy, routerDispatcher, _within, _interval, UsePoolDispatcher); + return new TailChoppingPool(NrOfInstances, Resizer, SupervisorStrategy, dispatcher, _within, _interval, UsePoolDispatcher); } /// - /// Creates a tail chopping router. + /// Creates a router that is responsible for routing messages to routees within the provided . /// - /// The actor system to use to create this router. - /// The created router. + /// The actor system that owns this router. + /// The newly created router tied to the given system. public override Router CreateRouter(ActorSystem system) { return new Router(new TailChoppingRoutingLogic(_within, _interval, system.Scheduler)); } + /// + /// Configure the current router with an auxiliary router for routes that it does not know how to handle. + /// + /// The router to use as an auxiliary source. + /// The router configured with the auxiliary information. public override RouterConfig WithFallback(RouterConfig routerConfig) { return OverrideUnsetConfig(routerConfig); @@ -291,23 +324,42 @@ public override RouterConfig WithFallback(RouterConfig routerConfig) } /// - /// A router group that selects a random routee, then waits an interval before sending to a - /// different routee. The first response is used and the remaining discarded. + /// This class represents a router that sends messages to a determined using tail-chopping. + /// This process has the router select a random routee, then waits an interval before sending to a different randomly chosen routee. + /// The first response is used and the remaining are discarded. If the none of the routees respond within a specified time limit, + /// a timeout failure occurs. /// public sealed class TailChoppingGroup : Group { + /// + /// This class represents a surrogate of a router. + /// Its main use is to help during the serialization process. + /// public class TailChoppingGroupSurrogate : ISurrogate { + /// + /// Creates a encapsulated by this surrogate. + /// + /// The actor system that owns this router. + /// The encapsulated by this surrogate. public ISurrogated FromSurrogate(ActorSystem system) { return new TailChoppingGroup(Paths, Within,Interval); } + /// The amount of time to wait for a response. public TimeSpan Within { get; set; } + /// The actor paths used by this router during routee selection. public string[] Paths { get; set; } + /// The interval to wait before sending to the next routee. public TimeSpan Interval { get; set; } } + /// + /// Creates a surrogate representation of the current . + /// + /// The actor system that owns this router. + /// The surrogate representation of the current . public override ISurrogate ToSurrogate(ActorSystem system) { return new TailChoppingGroupSurrogate @@ -318,20 +370,22 @@ public override ISurrogate ToSurrogate(ActorSystem system) }; } - /// - /// The amount of time to wait for a response. - /// private readonly TimeSpan _within; - /// - /// The interval to wait before sending to the next routee. - /// private readonly TimeSpan _interval; - + /// - /// Creates an instance of the TailChoppingGroup. + /// Initializes a new instance of the class. /// - /// The configuration to use with this instance. + /// + /// The configuration to use to lookup paths used by the group router. + /// + /// + /// If 'routees.path' is defined in the provided configuration then those paths will be used by the router. + /// If 'within' is defined in the provided configuration then that will be used as the timeout. + /// If 'tail-chopping-router.interval' is defined in the provided configuration then that will be used as the interval. + /// + /// public TailChoppingGroup(Config config) : base(config.GetStringList("routees.paths").ToArray()) { @@ -340,9 +394,9 @@ public TailChoppingGroup(Config config) } /// - /// Creates an instance of the TailChoppingGroup. + /// Initializes a new instance of the class. /// - /// The configured routee paths to use with this instance. + /// The actor paths used by this router during routee selection. /// The amount of time to wait for a response. /// The interval to wait before sending to the next routee. public TailChoppingGroup(string[] routeePaths, TimeSpan within, TimeSpan interval) : base(routeePaths) @@ -352,19 +406,27 @@ public TailChoppingGroup(string[] routeePaths, TimeSpan within, TimeSpan interva } /// - /// Creates a tail chopping router. + /// Creates a router that is responsible for routing messages to routees within the provided . /// - /// The actor system to use to create this router. - /// The created router. + /// The actor system that owns this router. + /// The newly created router tied to the given system. public override Router CreateRouter(ActorSystem system) { return new Router(new TailChoppingRoutingLogic(_within, _interval, system.Scheduler)); } + /// + /// Creates a new router with a given dispatcher id. + /// + /// + /// This method is immutable and returns a new instance of the router. + /// + /// + /// The dispatcher id used to configure the new router. + /// A new router with the provided dispatcher id. public override Group WithDispatcher(string dispatcher) { return new TailChoppingGroup(Paths, _within, _interval){ RouterDispatcher = dispatcher}; } } } -