From 13a8ba8967364a57baeba277c1b0217d6964dc7f Mon Sep 17 00:00:00 2001 From: Jakob Hasse Date: Tue, 21 Mar 2023 18:45:34 +0800 Subject: [PATCH] esp_event: Clarify event handler un-registering Related to https://github.com/espressif/esp-idf/issues/10848 --- docs/en/api-reference/system/esp_event.rst | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/docs/en/api-reference/system/esp_event.rst b/docs/en/api-reference/system/esp_event.rst index bfa0876737..a1a26bba99 100644 --- a/docs/en/api-reference/system/esp_event.rst +++ b/docs/en/api-reference/system/esp_event.rst @@ -192,6 +192,28 @@ If the hypothetical event ``MY_EVENT_BASE``, ``MY_OTHER_EVENT_ID`` is posted, on If the hypothetical event ``MY_OTHER_EVENT_BASE``, ``MY_OTHER_EVENT_ID`` is posted, only ``run_on_event_3`` would execute. +Handler Un-registering Itself +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In general, an event handler run by an event loop is *not allowed to do any (un)registering activity on that event loop*. There is one exception, though: un-registering itself is allowed for the handler. E.g., it is possible to do the following: + +.. code-block:: c + + void run_on_event(void* handler_arg, esp_event_base_t base, int32_t id, void* event_data) + { + esp_event_loop_handle_t *loop_handle = (esp_event_loop_handle_t*) handler_arg; + esp_event_handler_unregister_with(*loop_handle, MY_EVENT_BASE, MY_EVENT_ID, run_on_event); + } + + void app_main(void) + { + esp_event_loop_handle_t loop_handle; + esp_event_loop_create(&loop_args, &loop_handle); + esp_event_handler_register_with(loop_handle, MY_EVENT_BASE, MY_EVENT_ID, run_on_event, &loop_handle); + // ... post event MY_EVENT_BASE, MY_EVENT_ID and run loop at some point + } + + Handler Registration and Handler Dispatch Order ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^