(v13) Multi-threading issues with events

This page applies to Harlequin v13.1r0 and later; both Harlequin Core and Harlequin MultiRIP

The Event and RDR systems can be used to connect anything to anything, across the Skin/Core boundary and from thread to thread. For example, the Core interpretation thread uses Events to communicate job start, job end, interpretation stage and so on, to the Skin, which is running its own thread. Event handlers are called in the thread of the Event issuer, not necessarily the thread that registered the handlers. If the Skin registers a handler for a Core Event, that handler will be called in a Core thread. Handlers that modify some context that is not part of the Event message must therefore be thread safe.

Because handlers often are called by some other thread, it is theoretically possible for one thread to try to de-register a handler whilst that handler is actually running in some other thread. Note that it is permissible for a handler to de-register itself, which may be the most natural response to a particular scenario.

However, if a thread wishes to de-register a handler and discard the context that the handler modifies, care must be taken to ensure the handler is not still running (despite having been de-registered) when that context is destroyed. As the Event system is built on the RDR system it makes use of RDR locking to achieve this.

If a handler is still running when SwDeregisterHandler is called, SW_RDR_ERROR_IN_USE is returned. Because waiting for the handler to exit, so that context can be safely discarded, is such a common idiom there is an additional call that may be more convenient in such cases, SwSafeDeregisterHandler , which will not return while the handler is running. Note, therefore, that a handler must not use this call in an attempt to de-register itself.

Where code must register, or de-register multiple handlers two convenience functions may prove useful: SwRegisterHandlers and SwDeregisterHandlers . Both take a list of handlers to register or de-register in one go. Note that in this case the de-registration is “Safe”, so also must not be done from the handler in question.