From fbe44134b78e259bd720119bcc96065219acbe19 Mon Sep 17 00:00:00 2001 From: Irit Arkin Date: Thu, 20 Oct 2016 15:05:40 +0100 Subject: [PATCH 1/2] Edit Started just because the line breaks were rendered badly on docs.mbed, but then I also did some proofreading. --- events/README.md | 58 +++++++++++++++++------------------------------- 1 file changed, 20 insertions(+), 38 deletions(-) diff --git a/events/README.md b/events/README.md index 9e0263ce37f..d7edb97c67a 100644 --- a/events/README.md +++ b/events/README.md @@ -1,42 +1,35 @@ -## The mbed-events library ## +# The mbed-events library -The mbed-events library provides a flexible queue for scheduling events. +The mbed-events library provides a flexible queue for scheduling events. It can be used as a normal event loop, or it can be backgrounded on a single hardware timer or even another event loop. It is both thread and IRQ safe, and provides functions for easily composing independent event queues. + +The library can act as a drop-in scheduler, provide synchronization between multiple threads, or just act as a mechanism for moving events out of interrupt contexts. + +## Example ``` cpp #include "mbed_events.h" #include int main() { - // creates a queue with the default size + // Creates a queue with the default size EventQueue queue; - // events are simple callbacks + // Events are simple callbacks queue.call(printf, "called immediately\n"); queue.call_in(2000, printf, "called in 2 seconds\n"); queue.call_every(1000, printf, "called every 1 seconds\n"); - // events are executed by the dispatch method + // Events are executed by the dispatch method queue.dispatch(); } ``` -The mbed-events library can be used as a normal event loop, or it can be -backgrounded on a single hardware timer or even another event loop. It is -both thread and irq safe, and provides functions for easily composing -independent event queues. - -The mbed-events library can act as a drop-in scheduler, provide synchronization -between multiple threads, or just act as a mechanism for moving events out of -interrupt contexts. - -### Usage ### +## Usage -The core of the mbed-events library is the [EventQueue](EventQueue.h) class, -which represents a single event queue. The `EventQueue::dispatch` function -runs the queue, providing the context for executing events. +The core of the mbed-events library is the [EventQueue](EventQueue.h) class, which represents a single event queue. The `EventQueue::dispatch` function runs the queue, providing the context for executing events: ``` cpp -// Creates an event queue enough buffer space for 32 Callbacks. This +// Creates an event queue with enough buffer space for 32 Callbacks. This // is the default if no argument was provided. Alternatively the size // can just be specified in bytes. EventQueue queue(32*EVENTS_EVENT_SIZE); @@ -46,16 +39,13 @@ EventQueue queue(32*EVENTS_EVENT_SIZE); queue.call(printf, "hello %d %d %d %d\n", 1, 2, 3, 4); queue.call(&serial, &Serial::printf, "hi\n"); -// The dispatch function provides the context for the running the queue +// The dispatch function provides the context for running the queue // and can take a millisecond timeout to run for a fixed time or to just // dispatch any pending events queue.dispatch(); ``` -The EventQueue class provides several call functions for posting events -to the underlying event queue. The call functions are thread and irq safe, -don't need the underlying loop to be running, and provide an easy mechanism -for moving events out of interrupt contexts. +The EventQueue class provides several call functions for posting events to the underlying event queue. The call functions are thread and IRQ safe, don't need the underlying loop to be running, and provide an easy mechanism for moving events out of interrupt contexts: ``` cpp // Simple call function registers events to be called as soon as possible @@ -73,16 +63,14 @@ queue.call_every(2000, doit_every_two_seconds); queue.call_every(400, printf, "called every 0.4 seconds\n"); ``` -The call functions return an id that uniquely represents the event in the -the event queue. This id can be passed to `EventQueue::cancel` to cancel -an in-flight event. +The call functions return an ID that uniquely represents the event in the event queue. This ID can be passed to `EventQueue::cancel` to cancel an in-flight event: ``` cpp -// The event id uniquely represents the event in the queue +// The event ID uniquely represents the event in the queue int id = queue.call_in(100, printf, "will this work?\n"); // If there was not enough memory necessary to allocate the event, -// an id of 0 is returned from the call functions +// an ID of 0 is returned from the call functions if (id) { error("oh no!"); } @@ -92,10 +80,7 @@ if (id) { queue.cancel(id); ``` -For a more fine-grain control of event dispatch, the `Event` class can be -manually instantiated and configured. An `Event` represents an event as -a C++ style function object and can be directly passed to other APIs that -expect a callback. +For a more fine-grain control of event dispatch, the `Event` class can be manually instantiated and configured. An `Event` represents an event as a C++ style function object and can be directly passed to other APIs that expect a callback: ``` cpp // Creates an event bound to the specified event queue @@ -112,7 +97,7 @@ event.period(10000); queue.dispatch(); // Events can also pass arguments to the underlying callback when both -// initially constructed and posted. +// are initially constructed and posted. Event event(&queue, printf, "recieved %d and %d\n"); // Events can be posted multiple times and enqueue gracefully until @@ -124,10 +109,7 @@ event.post(5, 6); queue.dispatch(); ``` -Event queues easily align with module boundaries, where internal state can -be implicitly synchronized through event dispatch. Multiple modules can -use independent event queues, but still be composed through the -`EventQueue::chain` function. +Event queues easily align with module boundaries, where internal state can be implicitly synchronized through event dispatch. Multiple modules can use independent event queues, but still be composed through the `EventQueue::chain` function: ``` cpp // Create some event queues with pending events From bd5aebee87afeb8b618eb9298fffbfda068949ed Mon Sep 17 00:00:00 2001 From: Irit Arkin Date: Thu, 20 Oct 2016 15:08:49 +0100 Subject: [PATCH 2/2] Also replacing link Going to the rendered Doxy; the current link won't work on docs.mbed anyway, since it's relative to the repo --- events/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/events/README.md b/events/README.md index d7edb97c67a..826c2b0d7e0 100644 --- a/events/README.md +++ b/events/README.md @@ -26,7 +26,7 @@ int main() { ## Usage -The core of the mbed-events library is the [EventQueue](EventQueue.h) class, which represents a single event queue. The `EventQueue::dispatch` function runs the queue, providing the context for executing events: +The core of the mbed-events library is the [EventQueue](https://docs.mbed.com/docs/mbed-os-api/en/mbed-os-5.2/api/classevents_1_1EventQueue.html) class, which represents a single event queue. The `EventQueue::dispatch` function runs the queue, providing the context for executing events: ``` cpp // Creates an event queue with enough buffer space for 32 Callbacks. This