(v13) Event handler priority

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

When there are multiple handlers for a particular Event, the order that those handlers are called may be significant. If this were dictated purely by the chronology of handler registrations, constraints would be made on when and how various systems could register their handlers.

Instead, handlers are registered with a priority. The highest priority handler is called first. If it returns SW_EVENT_CONTINUE, the next highest priority handler will be called, and so on until all handlers for that Event have been called.

Higher priority handlers can prevent lower priority handlers receiving the Event by returning something other than SW_EVENT_CONTINUE (for example, SW_EVENT_HANDLED). This means that a higher priority handler can act as a filter, and can also monitor or change an Event. handlers can also call the remaining lower priority handlers for an Event multiple times via the SwEventTail call.

Registering the same handler for the same Event more than once does not actually cause it to be called more than once. Re-registrations are seen as re-prioritization, as they allow the priority of the handler to be changed without first de-registering it. It is permissible for a handler to change its own priority in this way. Note, however, that for the purposes of this definition a “Handler” is a combination of callback function and its private context pointer it is possible to simultaneously register multiple handler structures that use the same callback function.