org.jboss.netty.util

## Class HashedWheelTimer

- java.lang.Object
- - org.jboss.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 `TimerTask`s 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 `TimerTask`s 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

    Constructors
    Constructor and Description
    `HashedWheelTimer()` Creates a new timer with the default thread factory (`Executors.defaultThreadFactory()`), default tick duration, and default number of ticks per wheel.
    `HashedWheelTimer(long tickDuration, TimeUnit unit)` Creates a new timer with the default thread factory (`Executors.defaultThreadFactory()`) and default number of ticks per wheel.
    `HashedWheelTimer(long tickDuration, TimeUnit unit, int ticksPerWheel)` Creates a new timer with the default thread factory (`Executors.defaultThreadFactory()`).
    `HashedWheelTimer(ThreadFactory threadFactory)` Creates a new timer with the default tick duration and default number of ticks per wheel.
    `HashedWheelTimer(ThreadFactory threadFactory, long tickDuration, TimeUnit unit)` Creates a new timer with the default number of ticks per wheel.
    `HashedWheelTimer(ThreadFactory threadFactory, long tickDuration, TimeUnit unit, int ticksPerWheel)` Creates a new timer.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Timeout` | `newTimeout(TimerTask task, long delay, TimeUnit unit)` Schedules the specified `TimerTask` for one-time execution after the specified delay.
    `void` | `start()` Starts the background thread explicitly.
    `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()

      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`

    - #### 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

    - #### 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.

    - #### 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`

    - #### 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

  - ### 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:
        `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

Copyright © 2008-2012 The Netty Project. All Rights Reserved.