org.agrona

Class TimerWheel

java.lang.Object

org.agrona.TimerWheel

public class TimerWheel
extends java.lang.Object

Timer Wheel (NOT thread safe)

Assumes single-writer principle and timers firing on processing thread. Low (or NO) garbage.

Implementation Details

Based on netty's HashedTimerWheel, which 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.

Wheel is backed by arrays. Timer cancellation is O(1). Timer scheduling might be slightly longer if a lot of timers are in the same tick. The underlying tick contains an array. That array grows when needed, but does not currently shrink.

Timer objects may be reused if desired, but all reuse must be done with timer cancellation, expiration, and timeouts in consideration.

Caveats

Timers that expire in the same tick will not be ordered with one another. As ticks are fairly large normally, this means that some timers may expire out of order.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	TimerWheel.Timer
static class	TimerWheel.TimerState

Field Summary

Fields

Modifier and Type	Field and Description
static int	INITIAL_TICK_DEPTH

Constructor Summary

Constructors

Constructor and Description
TimerWheel(long tickDuration, java.util.concurrent.TimeUnit timeUnit, int ticksPerWheel) Construct a timer wheel for use in scheduling timers.
TimerWheel(NanoClock clock, long tickDuration, java.util.concurrent.TimeUnit timeUnit, int ticksPerWheel) Construct a timer wheel for use in scheduling timers.

Method Summary

Modifier and Type	Method and Description
NanoClock	clock() Get the NanoClock used by this timer wheel.
long	computeDelayInMs() Compute delay in milliseconds until next tick.
int	expireTimers() Process timers and execute any expired timers.
TimerWheel.Timer	newBlankTimer() Return a blank TimerWheel.Timer suitable for rescheduling.
TimerWheel.Timer	newTimeout(long delay, java.util.concurrent.TimeUnit unit, java.lang.Runnable task) Schedule a new timer that runs task when it expires.
void	rescheduleTimeout(long delay, java.util.concurrent.TimeUnit unit, TimerWheel.Timer timer) Reschedule an expired timer, reusing the TimerWheel.Timer object.
void	rescheduleTimeout(long delay, java.util.concurrent.TimeUnit unit, TimerWheel.Timer timer, java.lang.Runnable task) Reschedule an expired timer, reusing the TimerWheel.Timer object.

Methods inherited from class java.lang.Object

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

Field Detail

INITIAL_TICK_DEPTH

public static final int INITIAL_TICK_DEPTH

See Also:

Constant Field Values

Constructor Detail

TimerWheel

public TimerWheel(long tickDuration,
                  java.util.concurrent.TimeUnit timeUnit,
                  int ticksPerWheel)

Construct a timer wheel for use in scheduling timers.

Parameters:

tickDuration - of each tick of the wheel

timeUnit - for the tick duration

ticksPerWheel - of the wheel. Must be a power of 2.

TimerWheel

public TimerWheel(NanoClock clock,
                  long tickDuration,
                  java.util.concurrent.TimeUnit timeUnit,
                  int ticksPerWheel)

Construct a timer wheel for use in scheduling timers.

This constructor allows a custom function to return the current time instead of System.nanoTime().

Parameters:

clock - to use for system time

tickDuration - of each tick of the wheel

timeUnit - for the tick duration

ticksPerWheel - of the wheel. Must be a power of 2.

Method Detail

clock

public NanoClock clock()

Get the NanoClock used by this timer wheel.

Returns:

the NanoClock used by this timer wheel.

newBlankTimer

public TimerWheel.Timer newBlankTimer()

Return a blank TimerWheel.Timer suitable for rescheduling.

NOTE: Appears to be a cancelled timer

Returns:

new blank timer

newTimeout

public TimerWheel.Timer newTimeout(long delay,
                                   java.util.concurrent.TimeUnit unit,
                                   java.lang.Runnable task)

Schedule a new timer that runs task when it expires.

Parameters:

delay - until timer should expire

unit - of time for delay

task - to execute when timer expires

Returns:

TimerWheel.Timer for timer

rescheduleTimeout

public void rescheduleTimeout(long delay,
                              java.util.concurrent.TimeUnit unit,
                              TimerWheel.Timer timer)

Reschedule an expired timer, reusing the TimerWheel.Timer object.

Parameters:

delay - until timer should expire

unit - of time for delay

timer - to reschedule

Throws:

java.lang.IllegalArgumentException - if timer is active

rescheduleTimeout

public void rescheduleTimeout(long delay,
                              java.util.concurrent.TimeUnit unit,
                              TimerWheel.Timer timer,
                              java.lang.Runnable task)

Reschedule an expired timer, reusing the TimerWheel.Timer object.

Parameters:

delay - until timer should expire

unit - of time for delay

timer - to reschedule

task - to execute when timer expires

Throws:

java.lang.IllegalArgumentException - if timer is active

computeDelayInMs

public long computeDelayInMs()

Compute delay in milliseconds until next tick.

Returns:

number of milliseconds to next tick of the wheel.

expireTimers

public int expireTimers()

Process timers and execute any expired timers.

Returns:

number of timers expired.