diff --git a/akka-contrib/src/main/scala/akka/contrib/throttle/TimerBasedThrottler.scala b/akka-contrib/src/main/scala/akka/contrib/throttle/TimerBasedThrottler.scala index 3eb3689fc3..edff9d6598 100644 --- a/akka-contrib/src/main/scala/akka/contrib/throttle/TimerBasedThrottler.scala +++ b/akka-contrib/src/main/scala/akka/contrib/throttle/TimerBasedThrottler.scala @@ -14,44 +14,10 @@ import java.util.concurrent.TimeUnit import akka.AkkaException /** - * == Throttling == - * A throttler is an actor that is defined through a target actor and a rate - * (of type [[akka.contrib.throttle.Throttler.Rate]]). You set or change the target and rate at any time through the `SetTarget(target)` - * and `SetRate(rate)` messages, respectively. When you send the throttler any other message `msg`, it will - * put the message `msg` into an internal queue and eventually send all queued messages to the target, at - * a speed that respects the given rate. If no target is currently defined then the messages will be queued - * and will be delivered as soon as a target gets set. - * - * A throttler understands actor messages of type - * [[akka.contrib.throttle.Throttler.SetTarget]], [[akka.contrib.throttle.Throttler.SetRate]], in - * addition to any other messages, which the throttler will consider as messages to be sent to - * the target. - * - * == Transparency == - * Notice that the throttler `forward`s messages, i.e., the target will see the original message sender (and not the throttler) as the sender of the message. - * - * == Persistence == - * Throttlers usually use an internal queue to keep the messages that need to be sent to the target. - * You therefore cannot rely on the throttler's inbox size in order to learn how much messages are - * outstanding. - * - * It is left to the implementation whether the internal queue is persisted over application restarts or - * actor failure. - * - * == Processing messages == - * The target should process messages as fast as possible. If the target requires substantial time to - * process messages, it should distribute its work to other actors (using for example something like - * a `BalancingDispatcher`), otherwise the resulting system will always work below - * the threshold rate. - * - * Example: Suppose the throttler has a rate of 3msg/s and the target requires 1s to process a message. - * This system will only process messages at a rate of 1msg/s: the target will receive messages at at most 3msg/s - * but as it handles them synchronously and each of them takes 1s, its inbox will grow and grow. In such - * a situation, the target should distribute its messages to a set of worker actors so that individual messages - * can be handled in parallel. - * * @see [[akka.contrib.throttle.TimerBasedThrottler]] * @see [[akka.contrib.throttle.Throttler.Rate]] + * @see [[akka.contrib.throttle.Throttler.SetRate]] + * @see [[akka.contrib.throttle.Throttler.SetTarget]] */ object Throttler { /** @@ -155,6 +121,44 @@ private[throttle] object TimerBasedThrottler { /** * A throttler that uses a timer to control the message delivery rate. * + * == Throttling == + * A throttler is an actor that is defined through a target actor and a rate + * (of type [[akka.contrib.throttle.Throttler.Rate]]). You set or change the target and rate at any time through the + * [[akka.contrib.throttle.Throttler.SetTarget]] and [[akka.contrib.throttle.Throttler.SetRate]] + * messages, respectively. When you send the throttler any other message `msg`, it will + * put the message `msg` into an internal queue and eventually send all queued messages to the target, at + * a speed that respects the given rate. If no target is currently defined then the messages will be queued + * and will be delivered as soon as a target gets set. + * + * A throttler understands actor messages of type + * [[akka.contrib.throttle.Throttler.SetTarget]], [[akka.contrib.throttle.Throttler.SetRate]], in + * addition to any other messages, which the throttler will consider as messages to be sent to + * the target. + * + * == Transparency == + * Notice that the throttler `forward`s messages, i.e., the target will see the original message sender + * (and not the throttler) as the sender of the message. + * + * == Persistence == + * Throttlers usually use an internal queue to keep the messages that need to be sent to the target. + * You therefore cannot rely on the throttler's inbox size in order to learn how much messages are + * outstanding. + * + * It is left to the implementation whether the internal queue is persisted over application restarts or + * actor failure. + * + * == Processing messages == + * The target should process messages as fast as possible. If the target requires substantial time to + * process messages, it should distribute its work to other actors (using for example something like + * a `BalancingDispatcher`), otherwise the resulting system will always work below + * the threshold rate. + * + * Example: Suppose the throttler has a rate of 3msg/s and the target requires 1s to process a message. + * This system will only process messages at a rate of 1msg/s: the target will receive messages at at most 3msg/s + * but as it handles them synchronously and each of them takes 1s, its inbox will grow and grow. In such + * a situation, the target should distribute its messages to a set of worker actors so that individual messages + * can be handled in parallel. + * * ==Example== * For example, if you set a rate like "3 messages in 1 second", the throttler * will send the first three messages immediately to the target actor but will need to impose a delay before