ST / ST_Events-old

This is a fork of the `events` subdirectory of https://github.com/ARMmbed/mbed-os

Dependents:   HelloWorld_CCA01M1 HelloWorld_CCA02M1 CI-data-logger-server HelloWorld_CCA02M1 ... more

This is a fork of the events subdirectory of https://github.com/ARMmbed/mbed-os.

Note, you must import this library with import name: events!!!

equeue/README.md@9832:b95afde9ef7e, 2017-09-05 (annotated)

Committer:
Wolfgang Betz
Date:
Tue Sep 05 09:09:24 2017 +0200
Revision:
9832:b95afde9ef7e
Parent:
0:a792d4bf36c2 
Merge branch 'master' of hg::http://developer.mbed.org/teams/ST/code/ST_Events into events-split

Who changed what in which revision?

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