Event Handling

This contains all functionality needed to register/unregister event handlers. More...

Modules

Types
Event data types.
Macros
Event macros.

Functions

gos_result_t gos_event_issue ( gos_handler_t handler, void *arg, gos_event_flag_t flags)
Register an event to execute immediately then automatically unregister. More...
gos_result_t gos_event_register_timed ( gos_handler_t handler, void *arg, uint32_t timeout_ms, gos_event_flag_t flags)
Register event handler to execute after specified timeout. Once the event executes it is automatically unregistered. More...
gos_result_t gos_event_register_periodic ( gos_handler_t handler, void *arg, uint32_t period_ms, gos_event_flag_t flags)
Register event handler to execute every specified number of milliseconds. More...
gos_result_t gos_event_update_periodic ( gos_handler_t handler, void *arg, uint32_t period_ms, gos_event_flag_t run_now_flag)
Update a periodic event's execution period. More...
gos_result_t gos_event_unregister ( gos_handler_t handler, void *arg)
Unregister a pending event handler. More...
gos_result_t gos_event_unregister_all ( gos_handler_t handler)
Unregister all events with specified handler regardless of argument. More...
gos_result_t gos_event_restart ( gos_handler_t handler, void *arg)
Restart a timed/periodic event's timeout Refer to Registering/Unregistering Events for more information about registering/unregistering. More...
gos_result_t gos_event_trigger ( gos_handler_t handler, void *arg)
Force a timed/periodic event to execute immediately. More...
bool gos_event_is_registered ( gos_handler_t handler, void *arg)
Indicates if an event has previously been registered. More...
gos_result_t gos_event_enable_irq_events (uint16_t max_count)
Enable issuing events from an IRQ callback. More...
void gos_event_disable_irq_events (void)
Free memory allocated by gos_event_enable_irq_events() More...
bool gos_event_irq_events_enabled (void)
Return if IRQ events have been enabled.
gos_result_t gos_event_register_failure_callback ( gos_handler_t handler, gos_handler_t callback)
Register callback to be called if the event fails to execute. More...

Detailed Description

This contains all functionality needed to register/unregister event handlers.

Registering/Unregistering Events

When an event handler is registered both a function pointer and argument pointer are supplied. If the argument pointer is NULL then the function pointer is checked to ensure it has not previously been registered. The registration will fail if it's duplicate (and the GOS_EVENT_FLAG_ALLOW_DUPLICATE is not set). If the argument pointer is not NULL, then both the function pointer AND argument pointer are checked for uniqueness. If no other function pointer and corresponding argument pointer have been registered then they'll be registered as a pair. This allows for the same event handler function pointer to be registered with different argument pointers

Likewise, when unregistering a function pointer and argument pointer are supplied. Again if the argument pointer is NULL then only the function pointer is used to find a match. If the argument pointer is not NULL then both the event handler function pointer AND argument pointer are used to find a match.

Function Documentation

◆ gos_event_disable_irq_events()

void gos_event_disable_irq_events ( void )

Free memory allocated by gos_event_enable_irq_events()

After this is called, gos_event_issue_from_irq() will no longer work.

Returns
gos_result_t result of api call

◆ gos_event_enable_irq_events()

gos_result_t gos_event_enable_irq_events ( uint16_t max_count )

Enable issuing events from an IRQ callback.

This allows for issuing events from an IRQ callback such as those registered by: gos_gpio_irq_enable() or gos_uart_register_rx_callback().

This should be called before gos_event_issue_from_irq() may be used.

Calling this API consumes additional RAM. Call gos_event_disable_irq_events() to free the memory used by this feature.

Parameters
max_count The maximum number of queued events
Returns
gos_result_t result of api call
Examples:
demo/uart_blaster/uart_blaster.c , network/tcp_multiclient/main.c , network/uart_tcp_client/main.c , and system/uart/main.c .

◆ gos_event_is_registered()

bool gos_event_is_registered ( gos_handler_t handler,
void * arg
)

Indicates if an event has previously been registered.

Parameters
[in] handler Pointer to event handler
[in] arg Argument pointer that was used when registering the handler
Returns
gos_result_t result of api call

◆ gos_event_issue()

gos_result_t gos_event_issue ( gos_handler_t handler,
void * arg,
gos_event_flag_t flags
)

Register an event to execute immediately then automatically unregister.

Note
By default the event handler will execute in the app thread. See gos_event_flag_t for the other available event contexts.

Refer to Registering/Unregistering Events for more information about registering/unregistering.

Parameters
[in] handler Pointer to event handler
[in] arg Argument pointer that was used when registering the handler
[in] flags Optional flags for the event, gos_event_flag_t
Returns
gos_result_t result of api call
Examples:
cloud/coap_demo/commands.c , demo/uart_blaster/uart_blaster.c , dms/messages/main.c , dms/ota_update/main.c , network/tcp_client/main.c , network/tcp_multiclient/main.c , network/uart_tcp_client/main.c , network/udp_client/main.c , network/websocket_client/main.c , and system/uart/main.c .

◆ gos_event_register_failure_callback()

gos_result_t gos_event_register_failure_callback ( gos_handler_t handler,
gos_handler_t callback
)

Register callback to be called if the event fails to execute.

Register a callback to be executed if an event fails to execute. This is particularly useful if the argument the event was registered with needs to be cleaned up.

Note
Failure to execute is different than failure to register. Failure to execute occurrs AFTER the event was registered. i.e. The event was successfully registered with gos_event_issue() , gos_event_register_timed() , gos_event_update_periodic() but failed to execute when the event was next in the execution queue.

An event will fail to execute if:

Note
This API may be called multiple times with the same handler argument. The last callback to be registered will be used.
Parameters
[in] handler Event handler to register failure callback with, the event handler does NOT need to be currently registered
[in] callback Callback to be called if given handler failures to execute
Returns
gos_result_t result of api call

◆ gos_event_register_periodic()

gos_result_t gos_event_register_periodic ( gos_handler_t handler,
void * arg,
uint32_t period_ms,
gos_event_flag_t flags
)

Register event handler to execute every specified number of milliseconds.

Note
By default the event handler will execute in the app thread. See gos_event_flag_t for the other available event contexts.
This API is not allowed from an IRQ context.
The period_ms argument MUST be greater than 0.

Refer to Registering/Unregistering Events for more information about registering/unregistering.

Parameters
[in] handler Pointer to event handler
[in] arg Argument to pass to event handler
[in] period_ms Period in milliseconds for event handler to execute
[in] flags Optional flags for the event, gos_event_flag_t
Returns
gos_result_t result of api call
Examples:
file/log_file/main.c , file/log_file_encrypted/main.c , intro/blinky/main.c , network/tcp_client/main.c , network/udp_client/main.c , network/websocket_client/main.c , peripheral/adc/main.c , system/custom_commands/main.c , system/system_monitor/main.c , and wifi/wifi_scan/main.c .

◆ gos_event_register_timed()

gos_result_t gos_event_register_timed ( gos_handler_t handler,
void * arg,
uint32_t timeout_ms,
gos_event_flag_t flags
)

Register event handler to execute after specified timeout. Once the event executes it is automatically unregistered.

Note
By default the event handler will execute in the app thread. See gos_event_flag_t for the other available event contexts.
GOS_EVENT_FLAG_UPDATE_TIMEOUT may be used to update an already registered timed event. If this flag is specified and:
  • The event IS currently pending then the timeout will be updated
  • The event is NOT currently pending then the a new event with the given timeout will be registered
This API is not allowed from an IRQ context.
If the timeout_ms is 0 or the GOS_EVENT_FLAG_RUN_NOW flag is set then this does the same thing as gos_event_issue() .

Refer to Registering/Unregistering Events for more information about registering/unregistering.

Parameters
[in] handler Pointer to event handler
[in] arg Argument to pass to event handler
[in] timeout_ms Time in milliseconds to wait before handler executes
[in] flags Optional flags for the event, gos_event_flag_t
Returns
gos_result_t result of api call
Examples:
demo/uart_blaster/uart_blaster.c , dms/messages/main.c , dms/ota_update/main.c , network/tcp_client/main.c , network/uart_tcp_client/main.c , network/udp_client/main.c , and network/websocket_client/main.c .

◆ gos_event_restart()

gos_result_t gos_event_restart ( gos_handler_t handler,
void * arg
)

Restart a timed/periodic event's timeout Refer to Registering/Unregistering Events for more information about registering/unregistering.

Parameters
[in] handler Pointer to event handler
[in] arg Argument pointer that was used when registering the handler
Returns
gos_result_t result of api call

◆ gos_event_trigger()

gos_result_t gos_event_trigger ( gos_handler_t handler,
void * arg
)

Force a timed/periodic event to execute immediately.

Refer to Registering/Unregistering Events for more information about registering/unregistering.

Parameters
[in] handler Pointer to event handler
[in] arg Argument pointer that was used when registering the handler
Returns
gos_result_t result of api call

◆ gos_event_unregister()

gos_result_t gos_event_unregister ( gos_handler_t handler,
void * arg
)

Unregister a pending event handler.

Refer to Registering/Unregistering Events for more information about registering/unregistering.

Note
This does NOT unregister events pending in the IRQ event queue. i.e. Events issued from an IRQ context are NOT unregistered with this API.
Parameters
[in] handler Pointer to event handler
[in] arg Argument pointer that was used when registering the handler
Returns
gos_result_t result of api call
Examples:
demo/uart_blaster/uart_blaster.c , dms/messages/main.c , file/log_file/main.c , file/log_file_encrypted/main.c , network/tcp_client/main.c , network/uart_tcp_client/main.c , network/udp_client/main.c , network/websocket_client/main.c , system/custom_commands/main.c , and system/system_monitor/main.c .

◆ gos_event_unregister_all()

gos_result_t gos_event_unregister_all ( gos_handler_t handler )

Unregister all events with specified handler regardless of argument.

Note
This does NOT unregister events pending in the IRQ event queue. i.e. Events issued from an IRQ context are NOT unregistered with this API.
Parameters
[in] handler Pointer to event handler
Returns
gos_result_t result of api call

◆ gos_event_update_periodic()

gos_result_t gos_event_update_periodic ( gos_handler_t handler,
void * arg,
uint32_t period_ms,
gos_event_flag_t run_now_flag
)

Update a periodic event's execution period.

Refer to Registering/Unregistering Events for more information about registering/unregistering.

Parameters
[in] handler Pointer to event handler
[in] arg Argument to pass to event handler
[in] period_ms Period in milliseconds for event handler to execute
[in] run_now_flag specify GOS_EVENT_FLAG_RUN_NOW to execute the event immediately, all other flags ignored
Returns
gos_result_t result of api call