EL4121 Embedded System / mbed-os

mbed-os

Dependents:   cobaLCDJoyMotor_Thread odometry_omni_3roda_v3 odometry_omni_3roda_v1 odometry_omni_3roda_v2 ... more

events/equeue/README.md@0:b74591d5ab33, 2017-12-11 (annotated)

Committer:
be_bryan
Date:
Mon Dec 11 17:54:04 2017 +0000
Revision:
0:b74591d5ab33
motor ++

Who changed what in which revision?

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