Package io.netty.util

Class HashedWheelTimer

java.lang.Object
io.netty.util.HashedWheelTimer
All Implemented Interfaces:
Timer

public class HashedWheelTimer extends 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 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.
  • Field Details

  • Constructor Details

    • HashedWheelTimer

      public HashedWheelTimer()
      Creates a new timer with the default thread factory (Executors.defaultThreadFactory()), default tick duration, and default number of ticks per wheel.
    • HashedWheelTimer

      public HashedWheelTimer(long tickDuration, TimeUnit unit)
      Creates a new timer with the default thread factory (Executors.defaultThreadFactory()) and default number of ticks per wheel.
      Parameters:
      tickDuration - the duration between tick
      unit - the time unit of the tickDuration
      Throws:
      NullPointerException - if unit is null
      IllegalArgumentException - if tickDuration is <= 0
    • HashedWheelTimer

      public HashedWheelTimer(long tickDuration, TimeUnit unit, int ticksPerWheel)
      Creates a new timer with the default thread factory (Executors.defaultThreadFactory()).
      Parameters:
      tickDuration - the duration between tick
      unit - the time unit of the tickDuration
      ticksPerWheel - the size of the wheel
      Throws:
      NullPointerException - if unit is null
      IllegalArgumentException - if either of tickDuration and ticksPerWheel is <= 0
    • HashedWheelTimer

      public HashedWheelTimer(ThreadFactory threadFactory)
      Creates a new timer with the default tick duration and default number of ticks per wheel.
      Parameters:
      threadFactory - a ThreadFactory that creates a background Thread which is dedicated to TimerTask execution.
      Throws:
      NullPointerException - if threadFactory is null
    • HashedWheelTimer

      public HashedWheelTimer(ThreadFactory threadFactory, long tickDuration, TimeUnit unit)
      Creates a new timer with the default number of ticks per wheel.
      Parameters:
      threadFactory - a ThreadFactory that creates a background Thread which is dedicated to TimerTask execution.
      tickDuration - the duration between tick
      unit - the time unit of the tickDuration
      Throws:
      NullPointerException - if either of threadFactory and unit is null
      IllegalArgumentException - if tickDuration is <= 0
    • HashedWheelTimer

      public HashedWheelTimer(ThreadFactory threadFactory, long tickDuration, TimeUnit unit, int ticksPerWheel)
      Creates a new timer.
      Parameters:
      threadFactory - a ThreadFactory that creates a background Thread which is dedicated to TimerTask execution.
      tickDuration - the duration between tick
      unit - the time unit of the tickDuration
      ticksPerWheel - the size of the wheel
      Throws:
      NullPointerException - if either of threadFactory and unit is null
      IllegalArgumentException - if either of tickDuration and ticksPerWheel is <= 0
    • HashedWheelTimer

      public HashedWheelTimer(ThreadFactory threadFactory, long tickDuration, TimeUnit unit, int ticksPerWheel, boolean leakDetection)
      Creates a new timer.
      Parameters:
      threadFactory - a ThreadFactory that creates a background Thread which is dedicated to TimerTask execution.
      tickDuration - the duration between tick
      unit - the time unit of the tickDuration
      ticksPerWheel - the size of the wheel
      leakDetection - true if leak detection should be enabled always, if false it will only be enabled if the worker thread is not a daemon thread.
      Throws:
      NullPointerException - if either of threadFactory and unit is null
      IllegalArgumentException - if either of tickDuration and ticksPerWheel is <= 0
    • HashedWheelTimer

      public HashedWheelTimer(ThreadFactory threadFactory, long tickDuration, TimeUnit unit, int ticksPerWheel, boolean leakDetection, long maxPendingTimeouts)
      Creates a new timer.
      Parameters:
      threadFactory - a ThreadFactory that creates a background Thread which is dedicated to TimerTask execution.
      tickDuration - the duration between tick
      unit - the time unit of the tickDuration
      ticksPerWheel - the size of the wheel
      leakDetection - true if leak detection should be enabled always, if false it will only be enabled if the worker thread is not a daemon thread.
      maxPendingTimeouts - The maximum number of pending timeouts after which call to newTimeout will result in RejectedExecutionException being thrown. No maximum pending timeouts limit is assumed if this value is 0 or negative.
      Throws:
      NullPointerException - if either of threadFactory and unit is null
      IllegalArgumentException - if either of tickDuration and ticksPerWheel is <= 0
    • HashedWheelTimer

      public HashedWheelTimer(ThreadFactory threadFactory, long tickDuration, TimeUnit unit, int ticksPerWheel, boolean leakDetection, long maxPendingTimeouts, Executor taskExecutor)
      Creates a new timer.
      Parameters:
      threadFactory - a ThreadFactory that creates a background Thread which is dedicated to TimerTask execution.
      tickDuration - the duration between tick
      unit - the time unit of the tickDuration
      ticksPerWheel - the size of the wheel
      leakDetection - true if leak detection should be enabled always, if false it will only be enabled if the worker thread is not a daemon thread.
      maxPendingTimeouts - The maximum number of pending timeouts after which call to newTimeout will result in RejectedExecutionException being thrown. No maximum pending timeouts limit is assumed if this value is 0 or negative.
      taskExecutor - The Executor that is used to execute the submitted TimerTasks. The caller is responsible to shutdown the Executor once it is not needed anymore.
      Throws:
      NullPointerException - if either of threadFactory and unit is null
      IllegalArgumentException - if either of tickDuration and ticksPerWheel is <= 0
  • Method Details

    • finalize

      protected void finalize() throws Throwable
      Overrides:
      finalize in class Object
      Throws:
      Throwable
    • createWheel

      private static HashedWheelTimer.HashedWheelBucket[] createWheel(int ticksPerWheel)
    • 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:
      IllegalStateException - if this timer has been stopped already
    • stop

      public 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
    • newTimeout

      public Timeout newTimeout(TimerTask task, long delay, TimeUnit unit)
      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
    • pendingTimeouts

      public long pendingTimeouts()
      Returns the number of pending timeouts of this Timer.
    • reportTooManyInstances

      private static void reportTooManyInstances()