Marco Mayer / Mbed OS Queue

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

mbed-os/events/equeue/README.md@0:6bf0743ece18, 2020-03-28 (annotated)

Committer:
demayer
Date:
Sat Mar 28 15:28:19 2020 +0000
Revision:
0:6bf0743ece18
IMU Thread with an event-queue running parallel to handle tasks like a 5 times blinking LED. Button with interrupt detected.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
demayer 0:6bf0743ece18 1 ## The equeue library ##
demayer 0:6bf0743ece18 2
demayer 0:6bf0743ece18 3 The equeue library is designed as a simple but powerful library for scheduling
demayer 0:6bf0743ece18 4 events on composable queues.
demayer 0:6bf0743ece18 5
demayer 0:6bf0743ece18 6 ``` c
demayer 0:6bf0743ece18 7 #include "equeue.h"
demayer 0:6bf0743ece18 8 #include <stdio.h>
demayer 0:6bf0743ece18 9
demayer 0:6bf0743ece18 10 int main() {
demayer 0:6bf0743ece18 11 // creates a queue with space for 32 basic events
demayer 0:6bf0743ece18 12 equeue_t queue;
demayer 0:6bf0743ece18 13 equeue_create(&queue, 32*EQUEUE_EVENT_SIZE);
demayer 0:6bf0743ece18 14
demayer 0:6bf0743ece18 15 // events can be simple callbacks
demayer 0:6bf0743ece18 16 equeue_call(&queue, print, "called immediately");
demayer 0:6bf0743ece18 17 equeue_call_in(&queue, 2000, print, "called in 2 seconds");
demayer 0:6bf0743ece18 18 equeue_call_every(&queue, 1000, print, "called every 1 seconds");
demayer 0:6bf0743ece18 19
demayer 0:6bf0743ece18 20 // events are executed in equeue_dispatch
demayer 0:6bf0743ece18 21 equeue_dispatch(&queue, 3000);
demayer 0:6bf0743ece18 22
demayer 0:6bf0743ece18 23 print("called after 3 seconds");
demayer 0:6bf0743ece18 24
demayer 0:6bf0743ece18 25 equeue_destroy(&queue);
demayer 0:6bf0743ece18 26 }
demayer 0:6bf0743ece18 27 ```
demayer 0:6bf0743ece18 28
demayer 0:6bf0743ece18 29 The equeue library can be used as a normal event loop, or it can be
demayer 0:6bf0743ece18 30 backgrounded on a single hardware timer or even another event loop. It
demayer 0:6bf0743ece18 31 is both thread and irq safe, and provides functions for easily composing
demayer 0:6bf0743ece18 32 multiple queues.
demayer 0:6bf0743ece18 33
demayer 0:6bf0743ece18 34 The equeue library can act as a drop-in scheduler, provide synchronization
demayer 0:6bf0743ece18 35 between multiple threads, or just act as a mechanism for moving events
demayer 0:6bf0743ece18 36 out of interrupt contexts.
demayer 0:6bf0743ece18 37
demayer 0:6bf0743ece18 38 ## Documentation ##
demayer 0:6bf0743ece18 39
demayer 0:6bf0743ece18 40 The in-depth documentation on specific functions can be found in
demayer 0:6bf0743ece18 41 [equeue.h](equeue.h).
demayer 0:6bf0743ece18 42
demayer 0:6bf0743ece18 43 The core of the equeue library is the `equeue_t` type which represents a
demayer 0:6bf0743ece18 44 single event queue, and the `equeue_dispatch` function which runs the equeue,
demayer 0:6bf0743ece18 45 providing the context for executing events.
demayer 0:6bf0743ece18 46
demayer 0:6bf0743ece18 47 On top of this, `equeue_call`, `equeue_call_in`, and `equeue_call_every`
demayer 0:6bf0743ece18 48 provide easy methods for posting events to execute in the context of the
demayer 0:6bf0743ece18 49 `equeue_dispatch` function.
demayer 0:6bf0743ece18 50
demayer 0:6bf0743ece18 51 ``` c
demayer 0:6bf0743ece18 52 #include "equeue.h"
demayer 0:6bf0743ece18 53 #include "game.h"
demayer 0:6bf0743ece18 54
demayer 0:6bf0743ece18 55 equeue_t queue;
demayer 0:6bf0743ece18 56 struct game game;
demayer 0:6bf0743ece18 57
demayer 0:6bf0743ece18 58 // button_isr may be in interrupt context
demayer 0:6bf0743ece18 59 void button_isr(void) {
demayer 0:6bf0743ece18 60 equeue_call(&queue, game_button_update, &game);
demayer 0:6bf0743ece18 61 }
demayer 0:6bf0743ece18 62
demayer 0:6bf0743ece18 63 // a simple user-interface framework
demayer 0:6bf0743ece18 64 int main() {
demayer 0:6bf0743ece18 65 equeue_create(&queue, 4096);
demayer 0:6bf0743ece18 66 game_create(&game);
demayer 0:6bf0743ece18 67
demayer 0:6bf0743ece18 68 // call game_screen_udpate at 60 Hz
demayer 0:6bf0743ece18 69 equeue_call_every(&queue, 1000/60, game_screen_update, &game);
demayer 0:6bf0743ece18 70
demayer 0:6bf0743ece18 71 // dispatch forever
demayer 0:6bf0743ece18 72 equeue_dispatch(&queue, -1);
demayer 0:6bf0743ece18 73 }
demayer 0:6bf0743ece18 74 ```
demayer 0:6bf0743ece18 75
demayer 0:6bf0743ece18 76 In addition to simple callbacks, an event can be manually allocated with
demayer 0:6bf0743ece18 77 `equeue_alloc` and posted with `equeue_post` to allow passing an arbitrary
demayer 0:6bf0743ece18 78 amount of context to the execution of the event. This memory is allocated out
demayer 0:6bf0743ece18 79 of the equeue's buffer, and dynamic memory can be completely avoided.
demayer 0:6bf0743ece18 80
demayer 0:6bf0743ece18 81 The equeue allocator is designed to minimize jitter in interrupt contexts as
demayer 0:6bf0743ece18 82 well as avoid memory fragmentation on small devices. The allocator achieves
demayer 0:6bf0743ece18 83 both constant-runtime and zero-fragmentation for fixed-size events, however
demayer 0:6bf0743ece18 84 grows linearly as the quantity of differently-sized allocations increases.
demayer 0:6bf0743ece18 85
demayer 0:6bf0743ece18 86 ``` c
demayer 0:6bf0743ece18 87 #include "equeue.h"
demayer 0:6bf0743ece18 88
demayer 0:6bf0743ece18 89 equeue_t queue;
demayer 0:6bf0743ece18 90
demayer 0:6bf0743ece18 91 // arbitrary data can be moved to a different context
demayer 0:6bf0743ece18 92 int enet_consume(void *buffer, int size) {
demayer 0:6bf0743ece18 93 if (size > 512) {
demayer 0:6bf0743ece18 94 size = 512;
demayer 0:6bf0743ece18 95 }
demayer 0:6bf0743ece18 96
demayer 0:6bf0743ece18 97 void *data = equeue_alloc(&queue, 512);
demayer 0:6bf0743ece18 98 memcpy(data, buffer, size);
demayer 0:6bf0743ece18 99 equeue_post(&queue, handle_data_elsewhere, data);
demayer 0:6bf0743ece18 100
demayer 0:6bf0743ece18 101 return size;
demayer 0:6bf0743ece18 102 }
demayer 0:6bf0743ece18 103 ```
demayer 0:6bf0743ece18 104
demayer 0:6bf0743ece18 105 Additionally, in-flight events can be cancelled with `equeue_cancel`. Events
demayer 0:6bf0743ece18 106 are given unique ids on post, allowing safe cancellation of expired events.
demayer 0:6bf0743ece18 107
demayer 0:6bf0743ece18 108 ``` c
demayer 0:6bf0743ece18 109 #include "equeue.h"
demayer 0:6bf0743ece18 110
demayer 0:6bf0743ece18 111 equeue_t queue;
demayer 0:6bf0743ece18 112 int sonar_value;
demayer 0:6bf0743ece18 113 int sonar_timeout_id;
demayer 0:6bf0743ece18 114
demayer 0:6bf0743ece18 115 void sonar_isr(int value) {
demayer 0:6bf0743ece18 116 equeue_cancel(&queue, sonar_timeout_id);
demayer 0:6bf0743ece18 117 sonar_value = value;
demayer 0:6bf0743ece18 118 }
demayer 0:6bf0743ece18 119
demayer 0:6bf0743ece18 120 void sonar_timeout(void *) {
demayer 0:6bf0743ece18 121 sonar_value = -1;
demayer 0:6bf0743ece18 122 }
demayer 0:6bf0743ece18 123
demayer 0:6bf0743ece18 124 void sonar_read(void) {
demayer 0:6bf0743ece18 125 sonar_timeout_id = equeue_call_in(&queue, 300, sonar_timeout, 0);
demayer 0:6bf0743ece18 126 sonar_start();
demayer 0:6bf0743ece18 127 }
demayer 0:6bf0743ece18 128 ```
demayer 0:6bf0743ece18 129
demayer 0:6bf0743ece18 130 From an architectural standpoint, event queues easily align with module
demayer 0:6bf0743ece18 131 boundaries, where internal state can be implicitly synchronized through
demayer 0:6bf0743ece18 132 event dispatch.
demayer 0:6bf0743ece18 133
demayer 0:6bf0743ece18 134 On platforms where multiple threads are unavailable, multiple modules
demayer 0:6bf0743ece18 135 can use independent event queues and still be composed through the
demayer 0:6bf0743ece18 136 `equeue_chain` function.
demayer 0:6bf0743ece18 137
demayer 0:6bf0743ece18 138 ``` c
demayer 0:6bf0743ece18 139 #include "equeue.h"
demayer 0:6bf0743ece18 140
demayer 0:6bf0743ece18 141 // run a simultaneous localization and mapping loop in one queue
demayer 0:6bf0743ece18 142 struct slam {
demayer 0:6bf0743ece18 143 equeue_t queue;
demayer 0:6bf0743ece18 144 };
demayer 0:6bf0743ece18 145
demayer 0:6bf0743ece18 146 void slam_create(struct slam *s, equeue_t *target) {
demayer 0:6bf0743ece18 147 equeue_create(&s->queue, 4096);
demayer 0:6bf0743ece18 148 equeue_chain(&s->queue, target);
demayer 0:6bf0743ece18 149 equeue_call_every(&s->queue, 100, slam_filter);
demayer 0:6bf0743ece18 150 }
demayer 0:6bf0743ece18 151
demayer 0:6bf0743ece18 152 // run a sonar with it's own queue
demayer 0:6bf0743ece18 153 struct sonar {
demayer 0:6bf0743ece18 154 equeue_t equeue;
demayer 0:6bf0743ece18 155 struct slam *slam;
demayer 0:6bf0743ece18 156 };
demayer 0:6bf0743ece18 157
demayer 0:6bf0743ece18 158 void sonar_create(struct sonar *s, equeue_t *target) {
demayer 0:6bf0743ece18 159 equeue_create(&s->queue, 64);
demayer 0:6bf0743ece18 160 equeue_chain(&s->queue, target);
demayer 0:6bf0743ece18 161 equeue_call_in(&s->queue, 5, sonar_update, s);
demayer 0:6bf0743ece18 162 }
demayer 0:6bf0743ece18 163
demayer 0:6bf0743ece18 164 // all of the above queues can be combined into a single thread of execution
demayer 0:6bf0743ece18 165 int main() {
demayer 0:6bf0743ece18 166 equeue_t queue;
demayer 0:6bf0743ece18 167 equeue_create(&queue, 1024);
demayer 0:6bf0743ece18 168
demayer 0:6bf0743ece18 169 struct sonar s1, s2, s3;
demayer 0:6bf0743ece18 170 sonar_create(&s1, &queue);
demayer 0:6bf0743ece18 171 sonar_create(&s2, &queue);
demayer 0:6bf0743ece18 172 sonar_create(&s3, &queue);
demayer 0:6bf0743ece18 173
demayer 0:6bf0743ece18 174 struct slam slam;
demayer 0:6bf0743ece18 175 slam_create(&slam, &queue);
demayer 0:6bf0743ece18 176
demayer 0:6bf0743ece18 177 // dispatches events from all of the modules
demayer 0:6bf0743ece18 178 equeue_dispatch(&queue, -1);
demayer 0:6bf0743ece18 179 }
demayer 0:6bf0743ece18 180 ```
demayer 0:6bf0743ece18 181
demayer 0:6bf0743ece18 182 ## Platform ##
demayer 0:6bf0743ece18 183
demayer 0:6bf0743ece18 184 The equeue library has a minimal porting layer that is flexible depending
demayer 0:6bf0743ece18 185 on the requirements of the underlying platform. Platform specific declarations
demayer 0:6bf0743ece18 186 and more information can be found in [equeue_platform.h](equeue_platform.h).
demayer 0:6bf0743ece18 187
demayer 0:6bf0743ece18 188 ## Tests ##
demayer 0:6bf0743ece18 189
demayer 0:6bf0743ece18 190 The equeue library uses a set of local tests based on the posix implementation.
demayer 0:6bf0743ece18 191
demayer 0:6bf0743ece18 192 Runtime tests are located in [tests.c](tests/tests.c):
demayer 0:6bf0743ece18 193
demayer 0:6bf0743ece18 194 ``` bash
demayer 0:6bf0743ece18 195 make test
demayer 0:6bf0743ece18 196 ```
demayer 0:6bf0743ece18 197
demayer 0:6bf0743ece18 198 Profiling tests based on rdtsc are located in [prof.c](tests/prof.c):
demayer 0:6bf0743ece18 199
demayer 0:6bf0743ece18 200 ``` bash
demayer 0:6bf0743ece18 201 make prof
demayer 0:6bf0743ece18 202 ```
demayer 0:6bf0743ece18 203
demayer 0:6bf0743ece18 204 To make profiling results more tangible, the profiler also supports percentage
demayer 0:6bf0743ece18 205 comparison with previous runs:
demayer 0:6bf0743ece18 206 ``` bash
demayer 0:6bf0743ece18 207 make prof | tee results.txt
demayer 0:6bf0743ece18 208 cat results.txt | make prof
demayer 0:6bf0743ece18 209 ```
demayer 0:6bf0743ece18 210