https://github.com/hbf/akka-throttler
A throttler for Akka 2.0+
https://github.com/hbf/akka-throttler
Last synced: 10 days ago
JSON representation
A throttler for Akka 2.0+
- Host: GitHub
- URL: https://github.com/hbf/akka-throttler
- Owner: hbf
- Created: 2012-07-24T15:17:12.000Z (almost 14 years ago)
- Default Branch: master
- Last Pushed: 2013-09-22T22:09:29.000Z (almost 13 years ago)
- Last Synced: 2023-03-25T21:23:07.825Z (over 3 years ago)
- Language: Scala
- Size: 1.18 MB
- Stars: 45
- Watchers: 10
- Forks: 12
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- awesome-java - Akka Throttler
README
NOTICE!
-------
The code from this project will be included into [Akka 2.1][11] and will no longer be maintained here. Visit the [Experimental Modules][9] section in the [Akka Documentation][10] 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
-------
```scala
// 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][3] to see what is provided. Most of the functionality is documented [here][7] and "described" in the [tests][6]. 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][2]. As [described][2] 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][4] by Charles Cordingley.
Download, Maven, SBT
--------------------
The packages are published to the Maven repository [http://hbf.github.com/akka-throttler/maven-repo][8]. You get the latest version using
```scala
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`:
```xml
akka-throttler-github-repository
http://hbf.github.com/akka-throttler/maven-repo
akka-throttler
akka.pattern.throttle_SCALAVERSION
1.0-SNAPSHOT
```
Here, `SCALAVERSION` should be `2.9.1` or `2.9.2`.
License
-------
The code is available under the [Apache 2 License](http://www.apache.org/licenses/LICENSE-2.0.html), 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!
[1]: http://akka.io/
[2]: http://hbf.github.com/akka-throttler/doc/api/#akka.pattern.throttle.TimerBasedThrottler
[3]: http://hbf.github.com/akka-throttler/doc/api/
[4]: http://www.cordinc.com/blog/2010/04/java-multichannel-asynchronous.html
[5]: http://creativecommons.org/licenses/by/3.0/
[6]: https://github.com/hbf/akka-throttler/blob/master/src/test/scala/akka/pattern/throttle/TimerBasedThrottlerSpec.scala
[7]: http://hbf.github.com/akka-throttler/doc/api/#akka.pattern.throttle.Throttler
[8]: http://hbf.github.com/akka-throttler/maven-repo
[9]: http://doc.akka.io/docs/akka/snapshot/experimental/index.html
[10]: http://akka.io/docs/
[11]: http://akka.io