BA / SerialCom

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.

Fork of OmniWheels by Gustav Atmel

mbed-os/events/equeue/README.md@1:9c5af431a1f1, 2018-05-01 (annotated)

Committer:
gustavatmel
Date:
Tue May 01 15:47:08 2018 +0000
Revision:
1:9c5af431a1f1
sdf

Who changed what in which revision?

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