From 3b1500a526c5af532d0a12df212601714156cd48 Mon Sep 17 00:00:00 2001 From: Michael Richters Date: Fri, 13 Nov 2020 16:15:47 -0600 Subject: [PATCH] Add `EventHandlerResult::ABORT` This will allow plugin handlers to send one of three different signals to the calling hook functions, with three different interpretations: `OK`: Continue calling the next handler. `EVENT_CONSUMED`: Don't proceed to the next handler, but signal to the hook function's caller that an event was handled successfully. `ABORT`: Stop processing, and signal to the hook function's caller that the event should be ignored. Signed-off-by: Michael Richters --- src/kaleidoscope/event_handler_result.h | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/src/kaleidoscope/event_handler_result.h b/src/kaleidoscope/event_handler_result.h index 9b5d6caf..f22bffee 100644 --- a/src/kaleidoscope/event_handler_result.h +++ b/src/kaleidoscope/event_handler_result.h @@ -18,9 +18,33 @@ namespace kaleidoscope { +// This is the set of return values for event handlers. Event handlers for +// plugins are called in sequence by the corresponding hook function, in plugin +// initialization order. The interpretation of these return values can vary +// based on the needs of the hook function, but should be as follows: +// +// - OK: Continue processing the event. The calling hook function should +// continue calling next event handler in the sequence. If all event +// handlers return `OK`, finish processing the event. +// +// - EVENT_CONSUMED: Stop processing event handlers. The calling hook function +// should not call any further handlers, but may continue to take some +// actions to finish processing the event. This should be used to indicate +// that the event has been successfully handled. +// +// - ABORT: Ignore the event. The calling hook function should not call any +// further handlers, and should treat the event as if it didn't +// happen. This should be used by plugin handlers that need to either +// suppress an event or queue the event in order to delay it. +// +// - ERROR: Undefined error. The calling hook function should not call any +// further handlers. There is currently no specification for what should +// happen if this is returned. + enum class EventHandlerResult { OK, EVENT_CONSUMED, + ABORT, ERROR, };