NOTICE!

The code from this project will be included into Akka 2.1 and will no longer be maintained here. Visit the Experimental Modules section in the Akka Documentation for the latest version.

A throttler for Akka 2.0

What is this about?

A typical usage scenario for a throttler is this: your application needs to make calls to an external webservice and this webservice has a restriction in place. You may only make X calls in Y seconds. You get blocked or need to pay gold if you don't stay under this limit. With a throttler, you can ensure that the calls you make do not cross the threshold rate.

You create a throttler by specifying a rate, for example 3 msgsPer (1 second) and a target actor. You can then send the throttler messages at any rate, and the throttler will send the messages to the target at a rate at most 3 msg/s.

Example

// 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 ! Queue("1")
throttler ! Queue("2")
throttler ! Queue("3")

// These two will wait at least until 1 second has passed
throttler ! Queue("4")
throttler ! Queue("5")

Status

Take a look at the API to see what is provided. Most of the functionality is documented here and "described" in the tests. To run them, check out the code and do a sbt test. (You will need at least sbt version 0.11.3.)

Currently, the project only provides a timer-based implementation of a throttler, see TimerBasedThrottler. As described in the class documentation, this throttler only provides weak guarantees.

There are plans to add an implementation of a history-based throttler that provides stronger guarantees, like for example the one by Charles Cordingley.

Download, Maven, SBT

The packages are published to the Maven repository http://hbf.github.com/akka-throttler/maven-repo. You get the latest version using

    resolvers += "akka-throttler-github-repository" at "http://hbf.github.com/akka-throttler/maven-repo"
    
    libraryDependencies ++= Seq(
      // ...
      "akka.pattern.throttle"  %% "akka-throttler"   % "1.0-SNAPSHOT" withSources
    )

The Maven repository contains builds for Scala 2.9.1 and 2.9.2. If you need something else, open an issue to let me know.

For Maven, add the following to your pom.xml:

	<repositories>
		<!-- ... -->
		<repository>
			<id>akka-throttler-github-repository</id>
			<url>http://hbf.github.com/akka-throttler/maven-repo</url>
		</repository>
	</repositories>
	<dependencies>
		<!-- ... -->
		<dependency>
			<groupId>akka-throttler</groupId>
			<artifactId>akka.pattern.throttle_SCALAVERSION</artifactId>
			<version>1.0-SNAPSHOT</version>
		</dependency>
	</dependencies>

Here, SCALAVERSION should be 2.9.1 or 2.9.2.

License

The code is available under the Apache 2 License, which is explained [here](http://www.tldrlegal.com/license/apache-license-2.0-(apache-2.0).

If you use the code in your project/product, please drop us a note – we are always interested in learning about new applications!