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

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
private static final class	HashedWheelTimer.HashedWheelBucket	Bucket that stores HashedWheelTimeouts.
private static final class	HashedWheelTimer.HashedWheelTimeout
private final class	HashedWheelTimer.Worker

Field Summary

Fields

Modifier and Type	Field	Description
private static final AtomicInteger	id
(package private) static final InternalLogger	logger
private final int	mask
private static final SharedResourceMisuseDetector	misuseDetector
private long	startTime
private final CountDownLatch	startTimeInitialized
private final long	tickDuration
private final Queue<HashedWheelTimer.HashedWheelTimeout>	timeouts
private final HashedWheelTimer.HashedWheelBucket[]	wheel
private final HashedWheelTimer.Worker	worker
static final int	WORKER_STATE_INIT
static final int	WORKER_STATE_SHUTDOWN
static final int	WORKER_STATE_STARTED
private static final AtomicIntegerFieldUpdater<HashedWheelTimer>	WORKER_STATE_UPDATER
private int	workerState
private final Thread	workerThread

Constructor Summary

Constructors

Constructor	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.
HashedWheelTimer(ThreadFactory threadFactory, ThreadNameDeterminer determiner, long tickDuration, TimeUnit unit, int ticksPerWheel)	Creates a new timer.

Method Summary

Modifier and Type	Method	Description
private static HashedWheelTimer.HashedWheelBucket[]	createWheel(int ticksPerWheel)
Timeout	newTimeout(TimerTask task, long delay, TimeUnit unit)	Schedules the specified TimerTask for one-time execution after the specified delay.
private static int	normalizeTicksPerWheel(int ticksPerWheel)
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 Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

logger

static final InternalLogger logger

id

private static final AtomicInteger id

misuseDetector

private static final SharedResourceMisuseDetector misuseDetector

WORKER_STATE_UPDATER

private static final AtomicIntegerFieldUpdater<HashedWheelTimer> WORKER_STATE_UPDATER

worker

private final HashedWheelTimer.Worker worker

workerThread

private final Thread workerThread

WORKER_STATE_INIT

public static final int WORKER_STATE_INIT

See Also:

• Constant Field Values

WORKER_STATE_STARTED

public static final int WORKER_STATE_STARTED

See Also:

• Constant Field Values

WORKER_STATE_SHUTDOWN

public static final int WORKER_STATE_SHUTDOWN

See Also:

• Constant Field Values

workerState

private volatile int workerState

tickDuration

private final long tickDuration

wheel

private final HashedWheelTimer.HashedWheelBucket[] wheel

mask

private final int mask

startTimeInitialized

private final CountDownLatch startTimeInitialized

timeouts

private final Queue<HashedWheelTimer.HashedWheelTimeout> timeouts

startTime

private volatile long startTime

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

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

HashedWheelTimer

public HashedWheelTimer(ThreadFactory threadFactory,
 ThreadNameDeterminer determiner,
 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.

determiner - thread name determiner to control thread name.

tickDuration - the duration between tick

unit - the time unit of the tickDuration

ticksPerWheel - the size of the wheel

Method Details

createWheel

private static HashedWheelTimer.HashedWheelBucket[] createWheel(int ticksPerWheel)

normalizeTicksPerWheel

private static int normalizeTicksPerWheel(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