3.5 Running Repeating Timers

Repeating timers are used to generate multiple timed event callbacks at fixed intervals. Each timer is associated with a single timeable callback handler implementing the Timeable interface. The onTick callback method of the timeable callback object will then be called repeatedly at the specified interval until the timer is either cancelled or rescheduled. In other respects, repeating timers behave identically to the one-shot timers previously discussed.

$\begin{listing} % latex2html id marker 687\begin{small}\begin{verbatim}publi... ... } }\end{verbatim} \end{small}\caption{Running a Repeating Timer} \end{listing}$

An example of a repeating timer in use is shown in Listing 3.6. This is similar to previous one-shot timer examples, except that a number of callbacks have to be made before the callback handler stops the reactor. The full code for this example is included in the timer examples package as RepeatingTimerExample1.

When running a repeating timer there are two timing parameters which are passed; the first sets the delay before the initial callback is made and the second sets the interval between successive callbacks. In this example the first callback will occur 5 seconds after the timer is initiated, with successive callbacks occurring at 1 second intervals.

One thing to consider when using repeating timers is that while the timebase interval is constant, each callback can be subject to an arbitrary - but usually short - delay. As for the case with one-shot timers, these additional delays may be down to waiting for a running callback to complete or may be artefacts of the underlying operating system and the Java thread library. The variability in the callback timing is referred to as the timer jitter and is illustrated in Figure 3.2.

**Figure 3.2:** Example of Timing Jitter For Repeating Timers
$\includegraphics[width=\textwidth]{thetimer.figs/RepeatingTiming.eps}$

**Figure 3.3:** Example of Callback Merging For Repeating Timers
$\includegraphics[width=\textwidth]{thetimer.figs/RepeatingTimingFallback.eps}$

In extreme cases it is possible that a timer callback will be delayed by more than the specified timer interval. In this case, two or more delayed callbacks will be merged into a single timer callback, as shown in Figure 3.3. Such a situation should be treated as an indication that the system is overloaded and is unable to process all application callbacks in a timely manner. Therefore, all such conditions are logged as warning conditions.

The most pathological case of timer event merging occurs when the callback itself takes longer to execute than the specified timer interval. This is demonstrated by adding an excess delay to the timer callback shown in Listing 3.6. The full example demonstrating this behaviour is included in the timer examples package as RepeatingTimerExample2. While the minimum viable timer interval will be platform and application dependent, it is generally recommended that only timer intervals in excess of a quarter of a second (250ms) are used.