Akka/Scala example source code file (throttle.rst)

This example Akka source code file (throttle.rst) is included in my "Source Code Warehouse" project. The intent of this project is to help you more easily find Akka and Scala source code examples by using tags.

All credit for the original source code belongs to akka.io; I'm just trying to make examples easier to find. (For my Scala work, see my Scala examples and tutorials.)

Akka tags/keywords

charles, cordingley, if, in, introduction, messages, the, this, timerbasedthrottler, you

The throttle.rst Akka example source code

Throttling Actor Messages
=========================

Introduction
------------

Suppose you are writing an application that makes HTTP requests to an external
web service and that this web service has a restriction in place: you may not
make more than 10 requests in 1 minute. You will get blocked or need to pay if
you don’t stay under this limit. In such a scenario you will want to employ
a *message throttler*.

This extension module provides a simple implementation of a throttling actor,
the :class:`TimerBasedThrottler`.


How to use it
-------------

You can use a :class:`TimerBasedThrottler` as follows. From Java it looks
like this:

.. includecode:: @contribSrc@/src/test/java/akka/contrib/throttle/TimerBasedThrottlerTest.java#demo-code

And from Scala like this:

.. includecode:: @contribSrc@/src/test/scala/akka/contrib/throttle/TimerBasedThrottlerSpec.scala#demo-code

Please refer to the JavaDoc/ScalaDoc documentation for the details.


The guarantees
--------------

:class:`TimerBasedThrottler` uses a timer internally. When the throttler’s rate is 3 msg/s,
for example, the throttler will start a timer that triggers
every second and each time will give the throttler exactly three "vouchers";
each voucher gives the throttler a right to deliver a message. In this way,
at most 3 messages will be sent out by the throttler in each interval.

It should be noted that such timer-based throttlers provide relatively **weak guarantees**:

* Only *start times* are taken into account. This may be a problem if, for example, the
  throttler is used to throttle requests to an external web service. If a web request
  takes very long on the server then the rate *observed on the server* may be higher.
* A timer-based throttler only makes guarantees for the intervals of its own timer. In
  our example, no more than 3 messages are delivered within such intervals. Other
  intervals on the timeline, however, may contain more calls.

The two cases are illustrated in the two figures below, each showing a timeline and three
intervals of the timer. The message delivery times chosen by the throttler are indicated
by dots, and as you can see, each interval contains at most 3 point, so the throttler
works correctly. Still, there is in each example an interval (the red one) that is
problematic. In the first scenario, this is because the delivery times are merely the
start times of longer requests (indicated by the four bars above the timeline that start
at the dots), so that the server observes four requests during the red interval. In the
second scenario, the messages are centered around one of the points in time where the
timer triggers, causing the red interval to contain too many messages.

.. image:: throttler.png

For some application scenarios, the guarantees provided by a timer-based throttler might
be too weak. Charles Cordingley’s `blog post <http://www.cordinc.com/blog/2010/04/java-multichannel-asynchronous.html>`_
discusses a throttler with stronger guarantees (it solves problem 2 from above).
Future versions of this module may feature throttlers with better guarantees.