3.2 Running One-Shot Timers

One shot timers are used to generate a single timed event a specific period of time after the timed event was requested. There are no constraints over which thread actually issues the request, so it is perfectly legitimate to request a timed event from the main application thread, as shown in Listing 3.3. This code is present in the timer examples package as OneShotTimerExample1.

$\begin{listing} % latex2html id marker 630\begin{small}\begin{verbatim}publi... ...} } }\end{verbatim} \end{small}\caption{Running a One Shot Timer} \end{listing}$

The example shown in Listing 3.3 uses the timed callback to shut down the reactor after a specific amount of time. The reactor startup code is identical to that previously described in Section 2.5. However, rather than issuing the reactor stop request from the main thread it is instead implemented within a timeable callback.

In order for the timeable callback to issue the reactor stop request it must have a handle on the reactor's control interface. In the example this is passed as the timer's reactorCtrl parameter. The reactorCtrl parameter is a reference to the reactor control interface which is held by the timer and then passed on to the timeable callback once the timer has expired. The use of a generic type specification ensures that only objects of the correct type may be passed in this manner.

In the event that an invalid reactorCtrl parameter is passed to a timeable callback an exception will be thrown. All exceptions thrown by timeable callbacks are caught by the reaction framework and will be logged with a log level of warning. The continued operation of the reactor is unaffected. In the example, the second timer request passes a null reference and will therefore generate an exception.

One thing which must be taken into account when using timers is that the specified delay must be treated as a minimum delay parameter. This is because the timer callback will be issued an arbitrary - but usually small - time after the delay period has expired. This delay may be caused by underlying operating system context switches, Java thread scheduling artefacts or long-running callbacks which are active at the point when the delay period expires. Figure 3.1 shows the delay in issuing callbacks relative to the fixed reactor timebase.

**Figure 3.1:** Timing Diagram For One Shot Timeouts
$\includegraphics[width=\textwidth]{thetimer.figs/OneShotTiming.eps}$