Events, Callbacks, Event Handlers and Execution Contexts
Events and Contexts
Gecko OS is an event driven system. See App Operation .
There are several types of event, grouped according to the triggers for the event and the context in which the event executes. See Native API Event Types below.
In this documentation we distinguish between the terms
callback
and
event handler
, according to the execution context:
-
A callback executes in the same execution context as the associated event registration.
-
An event handler executes in a different execution context to the associated event registration.
Gecko OS can respond to events with callbacks or event handlers that execute in a particular execution contexts . An Execution Context is a thread, except in the cases of the IRQ Execution Context and the RTOS Timer Context.
Execution contexts are listed below. These are covered in more detail in Execution Contexts .
Event handlers for TCP events are executed in the App context.
Special Context Considerations
Some execution contexts have limited resources. To switch processing to another execution context, you can issue an event with an event handler that executes in another context. For example, you can issue an event with gos_event_issue .
Limited resource contexts include RTOS Timer , IRQ and System Event Thread .
System Event Context
Events executing in the System event thread MUST NOT block as no other events can execute until it completes.
Command Context
Gecko OS commands and custom commands execute in the Command thread context. Custom commands cannot call any of the
gos_cmd_issue
functions, as it would create a deadlock. The Gecko OS API explicitly prevents a deadlock: a call to
gos_cmd_issue*
from within the Command thread fails automatically with a
GOS_NESTED_CMD
result code. See
gos_result_t
.
Native API Event Types
In this section, events are listed according to type, with details of:
- how to register the event
- what triggers the event
- the callback or event handler context
- how to unregister the event
Commands
Issued Events
-
Event API
-
gos_event_issue
- immediately issue an event then automatically unregister
- Event handler: By default the event handler executes in the App thread. Use the GOS_EVENT_FLAG_IN_EVENT_THREAD flag to have the event execute in the system event thread.
-
gos_event_issue
- immediately issue an event then automatically unregister
Timed Events
For more detail see Timed Events .
Event API
-
Event API
- Registering and Unregistering Events
-
gos_event_register_periodic
- Trigger: specified period expires
- Callback context: Execution context in which event registered
-
gos_event_register_timed
- Trigger: specified time occurs
- Callback context: Execution context in which event registered
- gos_event_unregister
RTOS Timer
-
RTOS Timer
-
gos_rtos_timer_init
- Trigger: Called each time the timer expires
- Callback context: RTOS
-
gos_rtos_timer_init
File System Events
-
File System
-
gos_file_list
with callback specified in
gos_file_list_parameters_t
- Trigger: call returns with list of files
- Callback context: Synchronous with API - same context. Callback is invoked for each listed file.
-
gos_file_list
with callback specified in
gos_file_list_parameters_t
Hardware IRQ Events
-
Hardware/GPIO API
-
gos_gpio_irq_enable
- Trigger: Specified gos_gpio_irq_trigger_t GPIO edge event
- Callback context: IRQ
-
gos_gpio_irq_enable
UART Events
-
Hardware/UART
-
gos_uart_set_rx_callback
- Trigger: character received on UART
- Callback context: IRQ
-
gos_uart_set_rx_callback
HTTP/S Server Events
-
HTTP Server
-
gos_hs_register_authorize_callback
- Trigger: a remote client attempts to connect when authorization is enabled
- Callback context: HTTP server thread
-
gos_hs_register_header_callback
- Trigger: corresponding header key is found in a HTTP request.
- Callback context: HTTP server thread
-
gos_hs_register_not_found_callback
- Trigger: HTTP request results in a 404 response
- Callback context: HTTP server thread
-
gos_hs_register_dynamic_page
- Callback context: HTTP server thread
- Custom Dynamic HTTP Pages
-
gos_hs_register_authorize_callback
Network Events
-
Network events
-
gos_network_register_event_handler
-
Triggers:
- network up
- network down
- Event handler context: App
-
Triggers:
-
gos_network_register_softap_event_handler
-
Triggers: softap client
- softap client connect
- softap client disconnect
- Event handler context: App
- Examples:
-
Triggers: softap client
-
gos_network_register_event_handler
Unregistering a Network Event
There is only one network event. To unregister it, pass a
NULL
to the register API:
gos_network_register_event_handler(WLAN, NULL)
gos_network_register_softap_event_handler(NULL)
Periodic Broadcast Events
-
Periodic Broadcast
- gos_broadcast_set_callback
- Trigger: broadcast period expires. See command API broadcast.interval
- Callback context: Network
-
Deregister:
gos_broadcast_set_callback(NULL)
- See
Network Events
above. Ensure this is deregistered in
gos_deinit()
System
System Functions, Miscellaneous
-
System IRQ Callbacks
-
gos_system_set_irq_callback
- Callback context: IRQ
- Deregister:
-
gos_system_set_system_tick_callback
This is triggered on the ARM SystemTick IRQ every 1ms.- Callback context: IRQ
-
gos_system_set_irq_callback
System Monitor Events
-
System Monitor
-
gos_register_system_monitor
- No callback: - Before specified delay, call gos_update_system_monitor , or gos_unregister_system_monitor , otherwise watchdog fault triggers, resulting in software reset.
- Deregister: gos_unregister_system_monitor
-
gos_register_system_monitor
TCP Events
-
TCP
-
gos_tcp_register_client_event_handlers
-
Triggers:
-
gos_stream_event_handler_t disconnect
: Client disconnects- Event handler context: App
-
gos_stream_event_handler_t receive
: Data received from client- Event handler context: App
-
-
Triggers:
-
gos_tcp_register_server_event_handlers
-
Triggers:
-
gos_stream_event_handler_t connect
: Client connects- Event handler context: App
-
gos_stream_event_handler_t disconnect
: Client disconnects- Event handler context: App
-
gos_stream_event_handler_t receive
: Data recieved from client- Event handler context: App
-
- Examples:
-
Triggers:
-
gos_tcp_register_client_event_handlers
UDP Events
-
UDP server
-
gos_udp_register_receive_event_handler
- Trigger: UDP client or server has data to be read
- Event handler context: App
- Examples:
-
gos_udp_register_receive_event_handler
Button Events
-
Utilities/Button API
-
gos_button_init
-
Triggers (callbacks specified in
gos_button_config_t
parameter):
-
gos_event_handler_t click
-
Event handler context: Specify in
gos_button_config_t
button_execution_context_t
: App, System Event, or IRQ
-
Event handler context: Specify in
gos_button_config_t
-
gos_event_handler_t toggle
- Event handler context:
-
gos_event_handler_t change
-
Event handler context: Specify in
gos_button_config_t
button_execution_context_t
: App, System Event, or IRQ
-
Event handler context: Specify in
gos_button_config_t
- unregister: gos_button_deinit
-
- Example: peripheral/button
-
Triggers (callbacks specified in
gos_button_config_t
parameter):
-
gos_button_init
Web Setup Events
-
Web Setup Events
-
gos_setup_register_client_event_handler
- Trigger: Client connects to the setup softap AND client connects to the HTTP server
- Event handler context: App
-
gos_setup_register_finished_event_handler
-
Trigger: Web setup completed by
- Manual stop
- Idle timeout
- Client completes device setup
- Event handler context: App
-
Trigger: Web setup completed by
-
gos_setup_register_client_event_handler
WebSocket Events
-
Web socket
-
gos_websocket_register_client_event_handlers
-
Triggers
-
gos_stream_event_handler_t disconnect
: client disconnects- Event handler context: App
-
gos_stream_event_handler_t receive
: data received from client- Event handler context: App
-
-
Triggers
-
gos_websocket_register_server_event_handlers
-
Triggers
-
gos_stream_event_handler_t connect
: client connects- Event handler context: App
-
gos_stream_event_handler_t disconnect
: client disconnects- Event handler context: App
-
gos_stream_event_handler_t receive
: data received from client- Event handler context: App
-
-
Triggers
-
gos_websocket_register_client_event_handlers