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
!!!
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?
User | Revision | Line number | New contents of line |
---|---|---|---|
Bogdan Marinescu |
0:a792d4bf36c2 | 1 | ## The mbed-events library ## |
Bogdan Marinescu |
0:a792d4bf36c2 | 2 | |
Bogdan Marinescu |
0:a792d4bf36c2 | 3 | The mbed-events library provides a flexible queue for scheduling events. |
Bogdan Marinescu |
0:a792d4bf36c2 | 4 | |
Bogdan Marinescu |
0:a792d4bf36c2 | 5 | ``` cpp |
Bogdan Marinescu |
0:a792d4bf36c2 | 6 | #include "mbed_events.h" |
Bogdan Marinescu |
0:a792d4bf36c2 | 7 | #include <stdio.h> |
Bogdan Marinescu |
0:a792d4bf36c2 | 8 | |
Bogdan Marinescu |
0:a792d4bf36c2 | 9 | int main() { |
Bogdan Marinescu |
0:a792d4bf36c2 | 10 | // creates a queue with the default size |
Bogdan Marinescu |
0:a792d4bf36c2 | 11 | EventQueue queue; |
Bogdan Marinescu |
0:a792d4bf36c2 | 12 | |
Bogdan Marinescu |
0:a792d4bf36c2 | 13 | // events are simple callbacks |
Bogdan Marinescu |
0:a792d4bf36c2 | 14 | queue.call(printf, "called immediately\n"); |
Bogdan Marinescu |
0:a792d4bf36c2 | 15 | queue.call_in(2000, printf, "called in 2 seconds\n"); |
Bogdan Marinescu |
0:a792d4bf36c2 | 16 | queue.call_every(1000, printf, "called every 1 seconds\n"); |
Bogdan Marinescu |
0:a792d4bf36c2 | 17 | |
Bogdan Marinescu |
0:a792d4bf36c2 | 18 | // events are executed by the dispatch method |
Bogdan Marinescu |
0:a792d4bf36c2 | 19 | queue.dispatch(); |
Bogdan Marinescu |
0:a792d4bf36c2 | 20 | } |
Bogdan Marinescu |
0:a792d4bf36c2 | 21 | ``` |
Bogdan Marinescu |
0:a792d4bf36c2 | 22 | |
Bogdan Marinescu |
0:a792d4bf36c2 | 23 | The mbed-events library can be used as a normal event loop, or it can be |
Bogdan Marinescu |
0:a792d4bf36c2 | 24 | backgrounded on a single hardware timer or even another event loop. It is |
Bogdan Marinescu |
0:a792d4bf36c2 | 25 | both thread and irq safe, and provides functions for easily composing |
Bogdan Marinescu |
0:a792d4bf36c2 | 26 | independent event queues. |
Bogdan Marinescu |
0:a792d4bf36c2 | 27 | |
Bogdan Marinescu |
0:a792d4bf36c2 | 28 | The mbed-events library can act as a drop-in scheduler, provide synchronization |
Bogdan Marinescu |
0:a792d4bf36c2 | 29 | between multiple threads, or just act as a mechanism for moving events out of |
Bogdan Marinescu |
0:a792d4bf36c2 | 30 | interrupt contexts. |
Bogdan Marinescu |
0:a792d4bf36c2 | 31 | |
Bogdan Marinescu |
0:a792d4bf36c2 | 32 | ### Usage ### |
Bogdan Marinescu |
0:a792d4bf36c2 | 33 | |
Bogdan Marinescu |
0:a792d4bf36c2 | 34 | The core of the mbed-events library is the [EventQueue](EventQueue.h) class, |
Bogdan Marinescu |
0:a792d4bf36c2 | 35 | which represents a single event queue. The `EventQueue::dispatch` function |
Bogdan Marinescu |
0:a792d4bf36c2 | 36 | runs the queue, providing the context for executing events. |
Bogdan Marinescu |
0:a792d4bf36c2 | 37 | |
Bogdan Marinescu |
0:a792d4bf36c2 | 38 | ``` cpp |
Bogdan Marinescu |
0:a792d4bf36c2 | 39 | // Creates an event queue enough buffer space for 32 Callbacks. This |
Bogdan Marinescu |
0:a792d4bf36c2 | 40 | // is the default if no argument was provided. Alternatively the size |
Bogdan Marinescu |
0:a792d4bf36c2 | 41 | // can just be specified in bytes. |
Bogdan Marinescu |
0:a792d4bf36c2 | 42 | EventQueue queue(32*EVENTS_EVENT_SIZE); |
Bogdan Marinescu |
0:a792d4bf36c2 | 43 | |
Bogdan Marinescu |
0:a792d4bf36c2 | 44 | // Events can be posted to the underlying event queue with dynamic |
Bogdan Marinescu |
0:a792d4bf36c2 | 45 | // context allocated from the specified buffer |
Bogdan Marinescu |
0:a792d4bf36c2 | 46 | queue.call(printf, "hello %d %d %d %d\n", 1, 2, 3, 4); |
Bogdan Marinescu |
0:a792d4bf36c2 | 47 | queue.call(&serial, &Serial::printf, "hi\n"); |
Bogdan Marinescu |
0:a792d4bf36c2 | 48 | |
Bogdan Marinescu |
0:a792d4bf36c2 | 49 | // The dispatch function provides the context for the running the queue |
Bogdan Marinescu |
0:a792d4bf36c2 | 50 | // and can take a millisecond timeout to run for a fixed time or to just |
Bogdan Marinescu |
0:a792d4bf36c2 | 51 | // dispatch any pending events |
Bogdan Marinescu |
0:a792d4bf36c2 | 52 | queue.dispatch(); |
Bogdan Marinescu |
0:a792d4bf36c2 | 53 | ``` |
Bogdan Marinescu |
0:a792d4bf36c2 | 54 | |
Bogdan Marinescu |
0:a792d4bf36c2 | 55 | The EventQueue class provides several call functions for posting events |
Bogdan Marinescu |
0:a792d4bf36c2 | 56 | to the underlying event queue. The call functions are thread and irq safe, |
Bogdan Marinescu |
0:a792d4bf36c2 | 57 | don't need the underlying loop to be running, and provide an easy mechanism |
Bogdan Marinescu |
0:a792d4bf36c2 | 58 | for moving events out of interrupt contexts. |
Bogdan Marinescu |
0:a792d4bf36c2 | 59 | |
Bogdan Marinescu |
0:a792d4bf36c2 | 60 | ``` cpp |
Bogdan Marinescu |
0:a792d4bf36c2 | 61 | // Simple call function registers events to be called as soon as possible |
Bogdan Marinescu |
0:a792d4bf36c2 | 62 | queue.call(doit); |
Bogdan Marinescu |
0:a792d4bf36c2 | 63 | queue.call(printf, "called immediately\n"); |
Bogdan Marinescu |
0:a792d4bf36c2 | 64 | |
Bogdan Marinescu |
0:a792d4bf36c2 | 65 | // The call_in function registers events to be called after a delay |
Bogdan Marinescu |
0:a792d4bf36c2 | 66 | // specified in milliseconds |
Bogdan Marinescu |
0:a792d4bf36c2 | 67 | queue.call_in(2000, doit_in_two_seconds); |
Bogdan Marinescu |
0:a792d4bf36c2 | 68 | queue.call_in(300, printf, "called in 0.3 seconds\n"); |
Bogdan Marinescu |
0:a792d4bf36c2 | 69 | |
Bogdan Marinescu |
0:a792d4bf36c2 | 70 | // The call_every function registers events to be called repeatedly |
Bogdan Marinescu |
0:a792d4bf36c2 | 71 | // with a period specified in milliseconds |
Bogdan Marinescu |
0:a792d4bf36c2 | 72 | queue.call_every(2000, doit_every_two_seconds); |
Bogdan Marinescu |
0:a792d4bf36c2 | 73 | queue.call_every(400, printf, "called every 0.4 seconds\n"); |
Bogdan Marinescu |
0:a792d4bf36c2 | 74 | ``` |
Bogdan Marinescu |
0:a792d4bf36c2 | 75 | |
Bogdan Marinescu |
0:a792d4bf36c2 | 76 | The call functions return an id that uniquely represents the event in the |
Bogdan Marinescu |
0:a792d4bf36c2 | 77 | the event queue. This id can be passed to `EventQueue::cancel` to cancel |
Bogdan Marinescu |
0:a792d4bf36c2 | 78 | an in-flight event. |
Bogdan Marinescu |
0:a792d4bf36c2 | 79 | |
Bogdan Marinescu |
0:a792d4bf36c2 | 80 | ``` cpp |
Bogdan Marinescu |
0:a792d4bf36c2 | 81 | // The event id uniquely represents the event in the queue |
Bogdan Marinescu |
0:a792d4bf36c2 | 82 | int id = queue.call_in(100, printf, "will this work?\n"); |
Bogdan Marinescu |
0:a792d4bf36c2 | 83 | |
Bogdan Marinescu |
0:a792d4bf36c2 | 84 | // If there was not enough memory necessary to allocate the event, |
Bogdan Marinescu |
0:a792d4bf36c2 | 85 | // an id of 0 is returned from the call functions |
Bogdan Marinescu |
0:a792d4bf36c2 | 86 | if (id) { |
Bogdan Marinescu |
0:a792d4bf36c2 | 87 | error("oh no!"); |
Bogdan Marinescu |
0:a792d4bf36c2 | 88 | } |
Bogdan Marinescu |
0:a792d4bf36c2 | 89 | |
Bogdan Marinescu |
0:a792d4bf36c2 | 90 | // Events can be cancelled as long as they have not been dispatched. If the |
Bogdan Marinescu |
0:a792d4bf36c2 | 91 | // event has already expired, cancel has no side-effects. |
Bogdan Marinescu |
0:a792d4bf36c2 | 92 | queue.cancel(id); |
Bogdan Marinescu |
0:a792d4bf36c2 | 93 | ``` |
Bogdan Marinescu |
0:a792d4bf36c2 | 94 | |
Bogdan Marinescu |
0:a792d4bf36c2 | 95 | For a more fine-grain control of event dispatch, the `Event` class can be |
Bogdan Marinescu |
0:a792d4bf36c2 | 96 | manually instantiated and configured. An `Event` represents an event as |
Bogdan Marinescu |
0:a792d4bf36c2 | 97 | a C++ style function object and can be directly passed to other APIs that |
Bogdan Marinescu |
0:a792d4bf36c2 | 98 | expect a callback. |
Bogdan Marinescu |
0:a792d4bf36c2 | 99 | |
Bogdan Marinescu |
0:a792d4bf36c2 | 100 | ``` cpp |
Bogdan Marinescu |
0:a792d4bf36c2 | 101 | // Creates an event bound to the specified event queue |
Bogdan Marinescu |
0:a792d4bf36c2 | 102 | EventQueue queue; |
Bogdan Marinescu |
0:a792d4bf36c2 | 103 | Event<void()> event(&queue, doit); |
Bogdan Marinescu |
0:a792d4bf36c2 | 104 | |
Bogdan Marinescu |
0:a792d4bf36c2 | 105 | // The event can be manually configured for special timing requirements |
Bogdan Marinescu |
0:a792d4bf36c2 | 106 | // specified in milliseconds |
Bogdan Marinescu |
0:a792d4bf36c2 | 107 | event.delay(10); |
Bogdan Marinescu |
0:a792d4bf36c2 | 108 | event.period(10000); |
Bogdan Marinescu |
0:a792d4bf36c2 | 109 | |
Bogdan Marinescu |
0:a792d4bf36c2 | 110 | // Posted events are dispatched in the context of the queue's |
Bogdan Marinescu |
0:a792d4bf36c2 | 111 | // dispatch function |
Bogdan Marinescu |
0:a792d4bf36c2 | 112 | queue.dispatch(); |
Bogdan Marinescu |
0:a792d4bf36c2 | 113 | |
Bogdan Marinescu |
0:a792d4bf36c2 | 114 | // Events can also pass arguments to the underlying callback when both |
Bogdan Marinescu |
0:a792d4bf36c2 | 115 | // initially constructed and posted. |
Bogdan Marinescu |
0:a792d4bf36c2 | 116 | Event<void(int, int)> event(&queue, printf, "recieved %d and %d\n"); |
Bogdan Marinescu |
0:a792d4bf36c2 | 117 | |
Bogdan Marinescu |
0:a792d4bf36c2 | 118 | // Events can be posted multiple times and enqueue gracefully until |
Bogdan Marinescu |
0:a792d4bf36c2 | 119 | // the dispatch function is called. |
Bogdan Marinescu |
0:a792d4bf36c2 | 120 | event.post(1, 2); |
Bogdan Marinescu |
0:a792d4bf36c2 | 121 | event.post(3, 4); |
Bogdan Marinescu |
0:a792d4bf36c2 | 122 | event.post(5, 6); |
Bogdan Marinescu |
0:a792d4bf36c2 | 123 | |
Bogdan Marinescu |
0:a792d4bf36c2 | 124 | queue.dispatch(); |
Bogdan Marinescu |
0:a792d4bf36c2 | 125 | ``` |
Bogdan Marinescu |
0:a792d4bf36c2 | 126 | |
Bogdan Marinescu |
0:a792d4bf36c2 | 127 | Event queues easily align with module boundaries, where internal state can |
Bogdan Marinescu |
0:a792d4bf36c2 | 128 | be implicitly synchronized through event dispatch. Multiple modules can |
Bogdan Marinescu |
0:a792d4bf36c2 | 129 | use independent event queues, but still be composed through the |
Bogdan Marinescu |
0:a792d4bf36c2 | 130 | `EventQueue::chain` function. |
Bogdan Marinescu |
0:a792d4bf36c2 | 131 | |
Bogdan Marinescu |
0:a792d4bf36c2 | 132 | ``` cpp |
Bogdan Marinescu |
0:a792d4bf36c2 | 133 | // Create some event queues with pending events |
Bogdan Marinescu |
0:a792d4bf36c2 | 134 | EventQueue a; |
Bogdan Marinescu |
0:a792d4bf36c2 | 135 | a.call(printf, "hello from a!\n"); |
Bogdan Marinescu |
0:a792d4bf36c2 | 136 | |
Bogdan Marinescu |
0:a792d4bf36c2 | 137 | EventQueue b; |
Bogdan Marinescu |
0:a792d4bf36c2 | 138 | b.call(printf, "hello from b!\n"); |
Bogdan Marinescu |
0:a792d4bf36c2 | 139 | |
Bogdan Marinescu |
0:a792d4bf36c2 | 140 | EventQueue c; |
Bogdan Marinescu |
0:a792d4bf36c2 | 141 | c.call(printf, "hello from c!\n"); |
Bogdan Marinescu |
0:a792d4bf36c2 | 142 | |
Bogdan Marinescu |
0:a792d4bf36c2 | 143 | // Chain c and b onto a's event queue. Both c and b will be dispatched |
Bogdan Marinescu |
0:a792d4bf36c2 | 144 | // in the context of a's dispatch function. |
Bogdan Marinescu |
0:a792d4bf36c2 | 145 | c.chain(&a); |
Bogdan Marinescu |
0:a792d4bf36c2 | 146 | b.chain(&a); |
Bogdan Marinescu |
0:a792d4bf36c2 | 147 | |
Bogdan Marinescu |
0:a792d4bf36c2 | 148 | // Dispatching a will in turn dispatch b and c, printing hello from |
Bogdan Marinescu |
0:a792d4bf36c2 | 149 | // all three queues |
Bogdan Marinescu |
0:a792d4bf36c2 | 150 | a.dispatch(); |
Bogdan Marinescu |
0:a792d4bf36c2 | 151 | ``` |
Bogdan Marinescu |
0:a792d4bf36c2 | 152 | |
Bogdan Marinescu |
0:a792d4bf36c2 | 153 |