akka.util.internal
Class HashedWheelTimer

java.lang.Object
  extended by akka.util.internal.HashedWheelTimer
All Implemented Interfaces:
Timer

public class HashedWheelTimer
extends java.lang.Object
implements Timer

A Timer optimized for approximated I/O timeout scheduling.

Tick Duration

As described with 'approximated', this timer does not execute the scheduled TimerTask on time. HashedWheelTimer, on every tick, will check if there are any TimerTasks behind the schedule and execute them.

You can increase or decrease the accuracy of the execution timing by specifying smaller or larger tick duration in the constructor. In most network applications, I/O timeout does not need to be accurate. Therefore, the default tick duration is 100 milliseconds and you will not need to try different configurations in most cases.

Ticks per Wheel (Wheel Size)

HashedWheelTimer maintains a data structure called 'wheel'. To put simply, a wheel is a hash table of TimerTasks whose hash function is 'dead line of the task'. The default number of ticks per wheel (i.e. the size of the wheel) is 512. You could specify a larger value if you are going to schedule a lot of timeouts.

Do not create many instances.

HashedWheelTimer creates a new thread whenever it is instantiated and started. Therefore, you should make sure to create only one instance and share it across your application. One of the common mistakes, that makes your application unresponsive, is to create a new instance in ChannelPipelineFactory, which results in the creation of a new thread for every connection.

Implementation Details

HashedWheelTimer is based on George Varghese and Tony Lauck's paper, 'Hashed and Hierarchical Timing Wheels: data structures to efficiently implement a timer facility'. More comprehensive slides are located here.


Constructor Summary
HashedWheelTimer(LoggingAdapter logger, java.util.concurrent.ThreadFactory threadFactory, scala.concurrent.duration.Duration duration, int ticksPerWheel)
          Creates a new timer.
 
Method Summary
 akka.util.internal.HashedWheelTimer.HashedWheelTimeout createTimeout(TimerTask task, long time)
           
 Timeout newTimeout(TimerTask task, scala.concurrent.duration.FiniteDuration delay)
          Schedules the specified TimerTask for one-time execution after the specified delay.
 void start()
          Starts the background thread explicitly.
 java.util.Set<Timeout> stop()
          Releases all resources acquired by this Timer and cancels all tasks which were scheduled but not executed yet.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

HashedWheelTimer

public HashedWheelTimer(LoggingAdapter logger,
                        java.util.concurrent.ThreadFactory threadFactory,
                        scala.concurrent.duration.Duration duration,
                        int ticksPerWheel)
Creates a new timer.

Parameters:
threadFactory - a ThreadFactory that creates a background Thread which is dedicated to TimerTask execution.
duration - the duration between ticks
ticksPerWheel - the size of the wheel
Method Detail

start

public void start()
Starts the background thread explicitly. The background thread will start automatically on demand even if you did not call this method.

Throws:
java.lang.IllegalStateException - if this timer has been stopped already

stop

public java.util.Set<Timeout> stop()
Description copied from interface: Timer
Releases all resources acquired by this Timer and cancels all tasks which were scheduled but not executed yet.

Specified by:
stop in interface Timer
Returns:
the handles associated with the tasks which were canceled by this method

createTimeout

public akka.util.internal.HashedWheelTimer.HashedWheelTimeout createTimeout(TimerTask task,
                                                                            long time)

newTimeout

public Timeout newTimeout(TimerTask task,
                          scala.concurrent.duration.FiniteDuration delay)
Description copied from interface: Timer
Schedules the specified TimerTask for one-time execution after the specified delay.

Specified by:
newTimeout in interface Timer
Returns:
a handle which is associated with the specified task