Classic Scheduler
Akka Classic pertains to the original Actor APIs, which have been improved by more type safe and guided Actor APIs. Akka Classic is still fully supported and existing applications can continue to use the classic APIs. It is also possible to use the new Actor APIs together with classic actors in the same ActorSystem, see coexistence. For new projects we recommend using the new Actor API.
For the new API see typed scheduling.
Dependency
To use Scheduler, you must add the following dependency in your project:
- sbt
val AkkaVersion = "2.6.21" libraryDependencies += "com.typesafe.akka" %% "akka-actor" % AkkaVersion
- Maven
<properties> <scala.binary.version>2.13</scala.binary.version> </properties> <dependencyManagement> <dependencies> <dependency> <groupId>com.typesafe.akka</groupId> <artifactId>akka-bom_${scala.binary.version}</artifactId> <version>2.6.21</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement> <dependencies> <dependency> <groupId>com.typesafe.akka</groupId> <artifactId>akka-actor_${scala.binary.version}</artifactId> </dependency> </dependencies>
- Gradle
def versions = [ ScalaBinary: "2.13" ] dependencies { implementation platform("com.typesafe.akka:akka-bom_${versions.ScalaBinary}:2.6.21") implementation "com.typesafe.akka:akka-actor_${versions.ScalaBinary}" }
Introduction
Sometimes the need for making things happen in the future arises, and where do you go look then? Look no further than ActorSystem
ActorSystem
! There you find the scheduler
getScheduler()
method that returns an instance of Scheduler
Scheduler
, this instance is unique per ActorSystem and is used internally for scheduling things to happen at specific points in time.
You can schedule sending of messages to actors and execution of tasks (functions or Runnable). You will get a Cancellable
Cancellable
back that you can call cancel
cancel()
on to cancel the execution of the scheduled operation.
When scheduling periodic or single messages in an actor to itself it is recommended to use the Actor Timers instead of using the Scheduler
Scheduler
directly.
The scheduler in Akka is designed for high-throughput of thousands up to millions of triggers. The prime use-case being triggering Actor receive timeouts, Future timeouts, circuit breakers and other time dependent events which happen all-the-time and in many instances at the same time. The implementation is based on a Hashed Wheel Timer, which is a known datastructure and algorithm for handling such use cases, refer to the Hashed and Hierarchical Timing Wheels whitepaper by Varghese and Lauck if you’d like to understand its inner workings.
The Akka scheduler is not designed for long-term scheduling (see akka-quartz-scheduler instead for this use case) nor is it to be used for highly precise firing of the events. The maximum amount of time into the future you can schedule an event to trigger is around 8 months, which in practice is too much to be useful since this would assume the system never went down during that period. If you need long-term scheduling we highly recommend looking into alternative schedulers, as this is not the use-case the Akka scheduler is implemented for.
The default implementation of Scheduler
Scheduler
used by Akka is based on job buckets which are emptied according to a fixed schedule. It does not execute tasks at the exact time, but on every tick, it will run everything that is (over)due. The accuracy of the default Scheduler can be modified by the akka.scheduler.tick-duration
configuration property.
Some examples
- Scala
-
source
import akka.actor.Actor import akka.actor.Props import scala.concurrent.duration._
- Java
-
source
import java.time.Duration;
Schedule to send the “foo”-message to the testActor after 50ms:
- Scala
-
source
//Use the system's dispatcher as ExecutionContext import system.dispatcher //Schedules to send the "foo"-message to the testActor after 50ms system.scheduler.scheduleOnce(50 milliseconds, testActor, "foo")
- Java
-
source
system .scheduler() .scheduleOnce( Duration.ofMillis(50), testActor, "foo", system.dispatcher(), ActorRef.noSender());
Schedule a functionRunnable
, that sends the current time to the testActor, to be executed after 50ms:
- Scala
-
source
//Schedules a function to be executed (send a message to the testActor) after 50ms system.scheduler.scheduleOnce(50 milliseconds) { testActor ! System.currentTimeMillis }
- Java
-
source
system .scheduler() .scheduleOnce( Duration.ofMillis(50), new Runnable() { @Override public void run() { testActor.tell(System.currentTimeMillis(), ActorRef.noSender()); } }, system.dispatcher());
Schedule to send the “Tick”-message to the tickActor
after 0ms repeating every 50ms:
- Scala
-
source
val Tick = "tick" class TickActor extends Actor { def receive = { case Tick => //Do something } } val tickActor = system.actorOf(Props(classOf[TickActor], this)) //Use system's dispatcher as ExecutionContext import system.dispatcher //This will schedule to send the Tick-message //to the tickActor after 0ms repeating every 50ms val cancellable = system.scheduler.scheduleWithFixedDelay(Duration.Zero, 50.milliseconds, tickActor, Tick) //This cancels further Ticks to be sent cancellable.cancel()
- Java
-
source
class Ticker extends AbstractActor { @Override public Receive createReceive() { return receiveBuilder() .matchEquals( "Tick", m -> { // Do something }) .build(); } } ActorRef tickActor = system.actorOf(Props.create(Ticker.class, this)); // This will schedule to send the Tick-message // to the tickActor after 0ms repeating every 50ms Cancellable cancellable = system .scheduler() .scheduleWithFixedDelay( Duration.ZERO, Duration.ofMillis(50), tickActor, "Tick", system.dispatcher(), ActorRef.noSender()); // This cancels further Ticks to be sent cancellable.cancel();
If you schedule functions or Runnable instances you should be extra careful to not close over unstable references. In practice this means not using this
inside the closure in the scope of an Actor instance, not accessing sender
sender()
directly and not calling the methods of the Actor instance directly. If you need to schedule an invocation schedule a message to self
self()
instead (containing the necessary parameters) and then call the method when the message is received.
All scheduled task will be executed when the ActorSystem
ActorSystem
is terminated, i.e. the task may execute before its timeout.
Schedule periodically
Scheduling of recurring tasks or messages can have two different characteristics:
- fixed-delay - The delay between subsequent execution will always be (at least) the given
delay
. UsescheduleWithFixedDelay
. - fixed-rate - The frequency of execution over time will meet the given
interval
. UsescheduleAtFixedRate
.
If you are uncertain of which one to use you should pick scheduleWithFixedDelay
.
When using fixed-delay it will not compensate the delay between tasks or messages if the execution takes long time or if scheduling is delayed longer than specified for some reason. The delay between subsequent execution will always be (at least) the given delay
. In the long run, the frequency of execution will generally be slightly lower than the reciprocal of the specified delay
.
Fixed-delay execution is appropriate for recurring activities that require “smoothness.” In other words, it is appropriate for activities where it is more important to keep the frequency accurate in the short run than in the long run.
When using fixed-rate it will compensate the delay for a subsequent task if the previous tasks took too long to execute. For example, if the given interval
is 1000 milliseconds and a task takes 200 milliseconds to execute the next task will be scheduled to run after 800 milliseconds. In such cases, the actual execution interval will differ from the interval passed to the scheduleAtFixedRate
method.
If the execution of the tasks takes longer than the interval
, the subsequent execution will start immediately after the prior one completes (there will be no overlap of executions). This also has the consequence that after long garbage collection pauses or other reasons when the JVM was suspended all “missed” tasks will execute when the process wakes up again. For example, scheduleAtFixedRate
with an interval of 1 second and the process is suspended for 30 seconds will result in 30 tasks (or messages) being executed in rapid succession to catch up. In the long run, the frequency of execution will be exactly the reciprocal of the specified interval
.
Fixed-rate execution is appropriate for recurring activities that are sensitive to absolute time or where the total time to perform a fixed number of executions is important, such as a countdown timer that ticks once every second for ten seconds.
scheduleAtFixedRate
can result in bursts of scheduled tasks or messages after long garbage collection pauses, which may in worst case cause undesired load on the system. scheduleWithFixedDelay
is often preferred.
The Scheduler interface
The actual scheduler implementation is loaded reflectively upon ActorSystem
ActorSystem
start-up, which means that it is possible to provide a different one using the akka.scheduler.implementation
configuration property. The referenced class must implement the Scheduler
Scheduler
AbstractScheduler
AbstractScheduler
interface.
The Cancellable interface
Scheduling a task will result in a Cancellable
Cancellable
(or throw an IllegalStateException
if attempted after the scheduler’s shutdown). This allows you to cancel something that has been scheduled for execution.