Chapter 2. API Reference
User Event Loops Default Event Loops
esp_event_loop_create() esp_event_loop_create_default()
esp_event_loop_delete() esp_event_loop_delete_default()
esp_event_handler_register_with() esp_event_handler_register()
esp_event_handler_unregister_with() esp_event_handler_unregister()
esp_event_post_to() esp_event_post()
If you compare the signatures for both, they are mostly similar except the for the lack of loop handle specification for
the default event loop APIs.
Other than the API difference and the special designation to which system events are posted to, there is no difference
to how default event loops and user event loops behave. It is even possible for users to post their own events to the
default event loop, should the user opt to not create their own loops to save memory.
Notes on Handler Registration
It is possible to register a single handler to multiple events individually, i.e. using multiple calls to
esp_event_handler_register_with(). For those multiple calls, the specific event base and event ID
can be specified with which the handler should execute.
However, in some cases it is desirable for a handler to execute on (1) all events that get posted to a loop or (2) all events
of a particular base identifier. This is possible using the special event base identifier ESP_EVENT_ANY_BASE and
special event ID ESP_EVENT_ANY_ID. These special identifiers may be passed as the event base and event ID
arguments for esp_event_handler_register_with().
Therefore, the valid arguments to esp_event_handler_register_with() are:
1. <event base>, <event ID> - handler executes when the event with base <event base> and event ID <event ID>
gets posted to the loop
2. <event base>, ESP_EVENT_ANY_ID - handler executes when any event with base <event base> gets posted
to the loop
3. ESP_EVENT_ANY_BASE, ESP_EVENT_ANY_ID - handler executes when any event gets posted to the
loop
As an example, suppose the following handler registrations were performed:
esp_event_handler_register_with(loop_handle, MY_EVENT_BASE, MY_EVENT_ID, run_on_
,→event_1, ...);
esp_event_handler_register_with(loop_handle, MY_EVENT_BASE, ESP_EVENT_ANY_ID, run_
,→on_event_2, ...);
esp_event_handler_register_with(loop_handle, ESP_EVENT_ANY_BASE, ESP_EVENT_ANY_ID,␣
,→run_on_event_3, ...);
If the hypothetical event MY_EVENT_BASE, MY_EVENT_ID is posted, all three handlers run_on_event_1,
run_on_event_2, and run_on_event_3 would execute.
If the hypothetical event MY_EVENT_BASE, MY_OTHER_EVENT_ID is posted, only run_on_event_2 and
run_on_event_3 would execute.
If the hypothetical event MY_OTHER_EVENT_BASE, MY_OTHER_EVENT_ID is posted, only
run_on_event_3 would execute.
Handler Registration and Handler Dispatch Order The general rule is that for handlers that match a certain
posted event during dispatch, those which are registered first also gets executed first. The user can then control which
handlers get executed first by registering them before other handlers, provided that all registrations are performed
using a single task. If the user plans to take advantage of this behavior, caution must be exercised if there are multiple
tasks registering handlers. While the ‘first registered, first executed’behavior still holds true, the task which gets
executed first will also get their handlers registered first. Handlers registered one after the other by a single task
will still be dispatched in the order relative to each other, but if that task gets pre-empted in between registration by
another task which also registers handlers; then during dispatch those handlers will also get executed in between.
Espressif Systems 837
Submit Document Feedback
Release v4.4
To Next Page
Loading...
Need help?
General