BTstack Run Loop API
#include "src/btstack_run_loop.h"
BTstack Run Loop Abstraction
Provides generic functionality required by the Bluetooth stack and example applications: - asynchronous IO for various devices Serial, USB, network sockets, console - system time in milliseconds - single shot timers - integration for threaded environments
btstack_run_loop_init
void btstack_run_loop_init(const btstack_run_loop_t * run_loop);
Init main run loop. Must be called before any other run loop call.
Use btstack_run_loop_TYPE_get_instance() from btstack_run_loop_TYPE.h to get instance
Parameters
- run_loop: Platform-specific run loop implementation
btstack_run_loop_set_timer
void btstack_run_loop_set_timer(btstack_timer_source_t * timer, uint32_t timeout_in_ms);
Set timer based on current time.
Parameters
- timer: Timer source to configure
- timeout_in_ms: Delay in milliseconds from the current time
btstack_run_loop_set_timer_handler
void btstack_run_loop_set_timer_handler(btstack_timer_source_t * timer, void (*handler)(btstack_timer_source_t * timer_source));
Set callback that will be executed when timer expires.
Parameters
- timer: Timer source to configure
- handler: Callback invoked with the timer source when it expires
btstack_run_loop_set_timer_context
void btstack_run_loop_set_timer_context(btstack_timer_source_t * timer, void * context);
Set context for this timer
Parameters
- timer: Timer source to configure
- context: User-provided context pointer
btstack_run_loop_get_timer_context
void * btstack_run_loop_get_timer_context(btstack_timer_source_t * timer);
Get context for this timer
Parameters
- timer: Timer source to query
Returns
- void *: User-provided context pointer
btstack_run_loop_add_timer
void btstack_run_loop_add_timer(btstack_timer_source_t * timer);
Add timer source.
Parameters
- timer: Timer source to add, with its timeout and handler already set
btstack_run_loop_remove_timer
int btstack_run_loop_remove_timer(btstack_timer_source_t * timer);
Remove timer source.
Parameters
- timer: Timer source to remove
Returns
- int: Nonzero if the timer was removed, zero otherwise
btstack_run_loop_get_time_ms
uint32_t btstack_run_loop_get_time_ms(void);
Get current time in ms
Note: 32-bit ms counter will overflow after approx. 52 days
Returns
- uint32_t
btstack_run_loop_timer_dump
void btstack_run_loop_timer_dump(void);
Dump timers using log_info
btstack_run_loop_set_data_source_handler
void btstack_run_loop_set_data_source_handler(btstack_data_source_t * data_source, void (*process)(btstack_data_source_t * _data_source, btstack_data_source_callback_type_t callback_type));
Set data source callback.
Parameters
- data_source: Data source to configure
- process: Callback invoked with the data source and the callback type
btstack_run_loop_set_data_source_fd
void btstack_run_loop_set_data_source_fd(btstack_data_source_t * data_source, int fd);
Set data source file descriptor.
Note: No effect if port doesn't have file descriptors
Parameters
- data_source: Data source to configure
- fd: File descriptor to associate with the data source
btstack_run_loop_get_data_source_fd
int btstack_run_loop_get_data_source_fd(btstack_data_source_t * data_source);
Get data source file descriptor.
Parameters
- data_source: Data source to query
Returns
- int: Associated file descriptor
btstack_run_loop_set_data_source_handle
void btstack_run_loop_set_data_source_handle(btstack_data_source_t * data_source, void * handle);
Set data source handle.
Note: No effect if port doesn't have file descriptors
Parameters
- data_source: Data source to configure
- handle: Handle to associate with the data source
btstack_run_loop_get_data_source_handle
void * btstack_run_loop_get_data_source_handle(btstack_data_source_t * data_source);
Get data source handle.
Parameters
- data_source: Data source to query
Returns
- void *: Associated handle
btstack_run_loop_enable_data_source_callbacks
void btstack_run_loop_enable_data_source_callbacks(btstack_data_source_t * data_source, uint16_t callbacks);
Enable callbacks for a data source
Parameters
- data_source: Data source to configure
- callbacks: Bitmask of btstack_data_source_callback_type_t values to enable
btstack_run_loop_disable_data_source_callbacks
void btstack_run_loop_disable_data_source_callbacks(btstack_data_source_t * data_source, uint16_t callbacks);
Disable callbacks for a data source
Parameters
- data_source: Data source to configure
- callbacks: Bitmask of btstack_data_source_callback_type_t values to disable
btstack_run_loop_add_data_source
void btstack_run_loop_add_data_source(btstack_data_source_t * data_source);
Add data source to run loop
Parameters
- data_source: Data source to add, with its handler already set
btstack_run_loop_remove_data_source
int btstack_run_loop_remove_data_source(btstack_data_source_t * data_source);
Remove data source from run loop
Parameters
- data_source: Data source to remove
Returns
- int: Nonzero if the data source was removed, zero otherwise
btstack_run_loop_poll_data_sources_from_irq
void btstack_run_loop_poll_data_sources_from_irq(void);
Poll data sources - called only from IRQ context
Note: Can be used to trigger processing of received peripheral data on the main thread by registering a data source with DATA_SOURCE_CALLBACK_POLL and calling this function from the IRQ handler.
btstack_run_loop_execute
void btstack_run_loop_execute(void);
Execute configured run loop. This function does not return.
btstack_run_loop_execute_on_main_thread
void btstack_run_loop_execute_on_main_thread(btstack_context_callback_registration_t * callback_registration);
Registers callback with run loop and mark main thread as ready
Note: If callback is already registered, the call will be ignored.
This function allows to implement, e.g., a queue-based message passing mechanism: The external thread puts an item into a queue and call this function to trigger processing by the BTstack main thread. If this happens multiple times, it is guaranteed that the callback will run at least once after the last item was added.
This is not interrupt safe. If you need to trigger the main thread from an IRQ handler, please register a data source and enable DATA_SOURCE_CALLBACK_POLL. You can then call btstack_run_loop_poll_data_sources_from_irq() to trigger the main thread.
Parameters
- callback_registration: Registration containing the callback and its context
btstack_run_loop_trigger_exit
void btstack_run_loop_trigger_exit(void);
Trigger exit of active run loop (started via btstack_run_loop_execute) if possible
Note: This is only supported if there's a loop in the btstack_run_loop_execute function. It is not supported if timers and data sources are only mapped to RTOS equivalents, e.g. in the Qt or Core Foundation implementations.
btstack_run_loop_deinit
void btstack_run_loop_deinit(void);
De-Init Run Loop