Daiki Kato / mbed-os-lychee

mbed-os for GR-LYCHEE

Dependents:   mbed-os-example-blinky-gr-lychee GR-Boads_Camera_sample GR-Boards_Audio_Recoder GR-Boads_Camera_DisplayApp ... more

events/equeue/README.md@0:f782d9c66c49, 2018-02-02 (annotated)

Committer:
dkato
Date:
Fri Feb 02 05:42:23 2018 +0000
Revision:
0:f782d9c66c49
mbed-os for GR-LYCHEE

Who changed what in which revision?

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