4.3 Generating Signal Events
The example given in Listing 4.4 demonstrated the way in which signalable event handlers can be registered with a signal event object in order to receive notification of signal events. In that example signal events are generated internally to the reactor core to provide notification of reactor shutdown. However, in the general case signal events will need to be generated by application code instead.
The way in which signal events may be generated by application code is shown in Listing 4.5. The full source code for this example is available in the signal examples package as SignalEventExample1.
New signal event objects are created using the newSignal factory method on the Reactor interface. In common with the reactor shutdown signal in the previous example, signal event handlers may then be attached to the signal event object using its subscribe method. Once signal event handlers have been registered they will then receive any signal events which are generated by calling the signal method on the signal event object.
One feature of signal event generation demonstrated by Listing 4.5 is the passing of arbitrary data as part of signal event generation. In this example a handle on the reactor's control interface is passed, allowing the signal event handler to shut down the reactor when called.
Given that the event parameter is passed as an opaque data object, the type of data passed by any given signal event object needs to be carefully documented. Passing incompatible data types will result in the signal event handler throwing an exception which will then be caught by the reactor and logged as a warning. This may be demonstrated by adding a call to the signal method which passes and invalid parameter type, as shown in 4.6. The full code for this example is included in the signal examples package as SignalEventExample2.
