Provides utility functions for event handler threads. More...
Detailed Description
Provides utility functions for event handler threads.
Usage
By using the module event_thread, the event queues EVENT_PRIO_HIGHEST, EVENT_PRIO_MEDIUM, and EVENT_PRIO_LOWEST are provided and declared in the header event/thread.h. With default settings, the auto_init module will automatically start one or more threads to handle these queues.
By default, a single thread with priority EVENT_THREAD_MEDIUM_PRIO will handle all three event queues according to their priority. An already started event handler will not be preempted in this case by an incoming higher priority event. Still, lower priority event queues will only be worked on once the higher priority queues are empty. Hence, the worst case latency is increased by the worst case duration of any possible lower priority event in this configuration.
By using module event_thread_highest, the highest priority queue gets its own thread. With this, events of the highest priority can preempt already running event handlers of medium and lowest priority.
By using module event_thread_medium, the lowest priority events are handled in their own thread. With this, events of at least medium priority can preempt already running events of the lowest priority.
By using both module event_thread_highest and event_thread_medium, each event queue gets its own thread. So higher priority events will always preempt events of lower priority in this case.
Managing Stack Size Requirements
A module using the medium priority event queue might require a certain minimum stack size, say 1024, to operate correctly. Instead of just adding CFLAGS += -DDEVENT_THREAD_MEDIUM_STACKSIZE=1024, it can instead add the following to its Makefile.dep:
In the Makefile.include of sys/event the highest value of the minimum requirements declared by any module will be picked and added to the CFLAGS.
- Note
EVENT_THREAD_MEDIUM_STACKSIZE_MINandEVENT_THREAD_HIGHEST_STACKSIZE_MINalways apply to the thread managing the medium priority queue.
E.g. without the module event_thread_medium the lowest priority and medium priority queues are both handled by the lowest priority even thread. In that case, EVENT_THREAD_MEDIUM_STACKSIZE_MIN would ensure a minimum thread statck size on the lowest priority even thread. With event_thread_medium in use, it would instead apply to the stack of the dedicated medium event queue thread.
Event Thread API
Definition in file thread.h.
#include <stddef.h>#include "event.h"
Include dependency graph for thread.h: This graph shows which files directly or indirectly include this file:Go to the source code of this file.
| #define | EVENT_PRIO_HIGHEST (&event_thread_queues[EVENT_QUEUE_PRIO_HIGHEST]) |
| Pointer to the event queue handling highest priority events. | |
| #define | EVENT_PRIO_MEDIUM (&event_thread_queues[EVENT_QUEUE_PRIO_MEDIUM]) |
| Pointer to the event queue handling medium priority events. | |
| #define | EVENT_PRIO_LOWEST (&event_thread_queues[EVENT_QUEUE_PRIO_LOWEST]) |
| Pointer to the event queue handling lowest priority events. | |
| enum | { EVENT_QUEUE_PRIO_HIGHEST , EVENT_QUEUE_PRIO_MEDIUM , EVENT_QUEUE_PRIO_LOWEST , EVENT_QUEUE_PRIO_NUMOF } |
| Event queue priorities. More... | |
| event_queue_t | event_thread_queues [EVENT_QUEUE_PRIO_NUMOF] |
| void | event_thread_init_multi (event_queue_t *queues, size_t queues_numof, char *stack, size_t stack_size, unsigned priority) |
| Convenience function for initializing an event queue thread handling multiple queues. | |
| static void | event_thread_init (event_queue_t *queue, char *stack, size_t stack_size, unsigned priority) |
| Convenience function for initializing an event queue thread. | |
Macro Definition Documentation
◆ EVENT_PRIO_HIGHEST
| #define EVENT_PRIO_HIGHEST (&event_thread_queues[EVENT_QUEUE_PRIO_HIGHEST]) |
◆ EVENT_PRIO_LOWEST
| #define EVENT_PRIO_LOWEST (&event_thread_queues[EVENT_QUEUE_PRIO_LOWEST]) |
◆ EVENT_PRIO_MEDIUM
| #define EVENT_PRIO_MEDIUM (&event_thread_queues[EVENT_QUEUE_PRIO_MEDIUM]) |
Enumeration Type Documentation
◆ anonymous enum
| anonymous enum |
Event queue priorities.
The lower the numeric value, the higher the priority. The highest priority is 0, so that these priorities can be used as index to access arrays.
Function Documentation
◆ event_thread_init()
|
inlinestatic |
◆ event_thread_init_multi()
| void event_thread_init_multi | ( | event_queue_t * | queues, |
| size_t | queues_numof, | ||
| char * | stack, | ||
| size_t | stack_size, | ||
| unsigned | priority ) |
Convenience function for initializing an event queue thread handling multiple queues.
- Parameters
-
[in] queues array of the preallocated queue objects [in] queues_numof number of elements in queues[in] stack ptr to stack space [in] stack_size size of stack [in] priority priority to use
- Precondition
queues_numofis at most 4
