akka.contrib.throttle
Class TimerBasedThrottler
java.lang.Object
akka.contrib.throttle.TimerBasedThrottler
- All Implemented Interfaces:
- Actor, ActorLogging, FSM<akka.contrib.throttle.TimerBasedThrottler.State,akka.contrib.throttle.TimerBasedThrottler.Data>, Throttler, Listeners
public class TimerBasedThrottler
- extends java.lang.Object
- implements Actor, Throttler, FSM<akka.contrib.throttle.TimerBasedThrottler.State,akka.contrib.throttle.TimerBasedThrottler.Data>
A Throttler
that uses a timer to control the message delivery rate.
==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
sending out further messages:
// A simple actor that prints whatever it receives
val printer = system.actorOf(Props(new Actor {
def receive = {
case x => println(x)
}
}))
// The throttler for this example, setting the rate
val throttler = system.actorOf(Props(new TimerBasedThrottler(3 msgsPer (1.second))))
// Set the target
throttler ! SetTarget(Some(printer))
// These three messages will be sent to the printer immediately
throttler ! "1"
throttler ! "2"
throttler ! "3"
// These two will wait at least until 1 second has passed
throttler ! "4"
throttler ! "5"
==Implementation notes==
This throttler implementation internally installs a timer that repeats every rate.durationInMillis
and enables rate.numberOfCalls
additional calls to take place. A TimerBasedThrottler
uses very few system resources, provided the rate's duration is not too
fine-grained (which would cause a lot of timer invocations); for example, it does not store the calling history
as other throttlers may need to do.
However, a TimerBasedThrottler
only provides ''weak guarantees'' on the rate (see also
this blog post):
- Only ''delivery'' times are taken into account: if, for example, the throttler is used to throttle
requests to an external web service then only the start times of the web requests are considered.
If a web request takes very long on the server then more than rate.numberOfCalls
-many requests
may be observed on the server in an interval of duration rate.durationInMillis()
.
- There may be intervals of duration rate.durationInMillis()
that contain more than rate.numberOfCalls
message deliveries: a TimerBasedThrottler
only makes guarantees for the intervals
of its ''own'' timer, namely that no more than rate.numberOfCalls
-many messages are delivered within such intervals. Other intervals on the
timeline may contain more calls.
For some applications, these guarantees may not be sufficient.
==Known issues==
- If you change the rate using SetRate(rate)
, the actual rate may in fact be higher for the
overlapping period (i.e., durationInMillis()
) of the new and old rate. Therefore,
changing the rate frequently is not recommended with the current implementation.
- The queue of messages to be delivered is not persisted in any way; actor or system failure will
cause the queued messages to be lost.
- See Also:
Throttler
Nested classes/interfaces inherited from interface akka.actor.FSM |
FSM.$minus$greater$, FSM.CurrentState<S>, FSM.CurrentState$, FSM.Event, FSM.Event$, FSM.Failure, FSM.Failure$, FSM.LogEntry<S,D>, FSM.LogEntry$, FSM.Normal$, FSM.NullFunction$, FSM.Reason, FSM.Shutdown$, FSM.State$, FSM.StateTimeout$, FSM.StopEvent, FSM.StopEvent$, FSM.SubscribeTransitionCallBack, FSM.SubscribeTransitionCallBack$, FSM.TransformHelper, FSM.Transition<S>, FSM.Transition$, FSM.UnsubscribeTransitionCallBack, FSM.UnsubscribeTransitionCallBack$ |
Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Methods inherited from interface akka.actor.Actor |
context, noSender, postRestart, postStop, preRestart, preStart, receive, self, sender, supervisorStrategy, unhandled |
Methods inherited from interface akka.actor.FSM |
applyState, cancelTimer, currentState, debugEvent, generation, handleEvent, handleEventDefault, handleTransition, initialize, makeTransition, nextState, nextStateData, onTermination, onTransition, postStop, processEvent, processMsg, receive, register, setStateTimeout, setTimer, startWith, stateData, stateFunctions, stateName, StateTimeout, stateTimeouts, stay, stop, stop, stop, terminate, terminateEvent, timeoutFuture, timerGen, timers, total2pf, transform, transitionEvent, when, whenUnhandled |
TimerBasedThrottler
public TimerBasedThrottler(Throttler.Rate rate)
rate
public Throttler.Rate rate()