An abstract implementation of a timeout.

Subclasses should implement onTimeoutExpired().

This implementation is optimised assuming that the timeout will mostly be cancelled and then reused with a similar value.

The typical scenario to use this class is when you have events that postpone (by re-scheduling), or cancel then re-schedule, a timeout for a single entity. For example: connection idleness, where for each connection there is a CyclicTimeout and a read/write postpones the timeout; when the timeout expires, the implementation checks against a timestamp if the connection is really idle. Another example: HTTP session expiration, where for each HTTP session there is a CyclicTimeout and at the beginning of the request processing the timeout is canceled (via cancel()), but at the end of the request processing the timeout is re-scheduled.

This implementation has a Timeout holding the time at which the scheduled task should fire, and a linked list of Wakeup, each holding the actual scheduled task.

Calling schedule(long, TimeUnit) the first time will create a Timeout with an associated Wakeup and submit a task to the scheduler. Calling schedule(long, TimeUnit) again with the same or a larger delay will cancel the previous Timeout, but keep the previous Wakeup without submitting a new task to the scheduler, therefore reducing the pressure on the scheduler and avoid it becomes a bottleneck. When the Wakeup task fires, it will see that the Timeout is now in the future and will attach a new Wakeup with the future time to the Timeout, and submit a scheduler task for the new Wakeup.