raboof/pekko
1
0
Fork 0
Code Issues Pull requests Projects Releases 6 Packages Wiki Activity Actions 11

Merge pull request #1997 from akka/wip-3228-doc-TimerBasedThrottler-patriknw

Browse source 
=con #3228 Adjust structure of TimerBasedThrottler ScalaDoc
This commit is contained in:
Patrik Nordwall 2014-02-13 12:27:30 +01:00
commit c2a932768b
1 changed files with 40 additions and 36 deletions
Download patch file Download diff file Expand all files Collapse all files

76
akka-contrib/src/main/scala/akka/contrib/throttle/TimerBasedThrottler.scala
View file

@ -14,44 +14,10 @@ import java.util.concurrent.TimeUnit
import akka.AkkaException
/**
* == Throttling ==
* A <em>throttler</em> is an actor that is defined through a <em>target actor</em> and a <em>rate</em>
* (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 <em>below</em>
* the threshold rate.
*
* <em>Example:</em> 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 <em>distribute</em> 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 <em>throttler</em> is an actor that is defined through a <em>target actor</em> and a <em>rate</em>
* (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 <em>below</em>
* the threshold rate.
*
* <em>Example:</em> 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 <em>distribute</em> 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