Merge pull request #1147 from maciejbocianski/static_allocation_event

Add documentation for static events/queue

Author: Amanda Butler

docs/api/rtos/EventQueue.md

@@ -57,6 +57,12 @@ To do this, set the `mbed_app.json` configuration option `events.shared-dispatch
 
 [![View code](https://www.mbed.com/embed/?url=https://os.mbed.com/teams/mbed_example/code/Shared_Events_2/)](https://os.mbed.com/teams/mbed_example/code/Shared_Events_2/file/154179bdc39d/main.cpp)
 
+## Static EventQueue example: posting user allocated events to the static queue
+
+Use static EventQueue to prevent your program from failing due to queue memory exhaustion or to prevent dynamic memory allocation:
+
+[![View code](https://www.mbed.com/embed/?url=https://github.com/ARMmbed/mbed-os-examples-docs_only/blob/master/events/static-event-queue/UserAllocatedEvent_ex_1/)](https://github.com/ARMmbed/mbed-os-examples-docs_only/blob/master/events/static-event-queue/UserAllocatedEvent_ex_1/main.cpp)
+
 ## Related content
 
 - [EventQueue tutorial](../tutorials/the-eventqueue-api.html).

docs/api/rtos/UserAllocatedEvent.md

@@ -0,0 +1,30 @@
+# UserAllocatedEvent
+
+The `UserAllocatedEvent` class provides APIs to create and configure static events. The advantage in using `UserAllocatedEvent` instead of `Event` is `UserAllocatedEvent` embeds all underlying event data and doesn't require any memory allocation while posting and dispatching to the EventQueue.
+
+This class includes the following APIs:
+
+- `delay` and `period` to configure event timings.
+- `call` and `try_call` to post an event to the underlying EventQueue.
+- `call_on` and `try_call_on` to bind and post an event to the EventQueue as a function argument.
+- `cancel` to cancel the most recently posted event.
+
+Because the `UserAllocatedEvent` holds event data, you can post only one event object to it at a time. This means that if the event object has to be reused, the previous dispatch has to finish or the event has to be canceled. You can use the `try_call` API to sample the event state. This call tries to post an event and returns false with no action until the previous dispatching finishes.
+
+The UserAllocatedEvent class is thread safe. The `call`, `try_call` and `cancel` APIs are IRQ safe.
+
+## UserAllocatedEvent class reference
+
+[![View code](https://www.mbed.com/embed/?type=library)](https://os.mbed.com/docs/mbed-os/development/mbed-os-api-doxy/classevents_1_1_user_allocated_event.html)
+
+## Static EventQueue example: posting user allocated events to the queue
+
+This example demonstrates how you can instantiate, configure and post events:
+
+[![View code](https://www.mbed.com/embed/?url=https://github.com/ARMmbed/mbed-os-examples-docs_only/blob/master/events/static-event-queue/UserAllocatedEvent_ex_1/)](https://github.com/ARMmbed/mbed-os-examples-docs_only/blob/master/events/static-event-queue/UserAllocatedEvent_ex_1/main.cpp)
+
+
+## Related content
+
+- [RTOS configuration](../reference/configuration-rtos.html).
+- [EventQueue tutorial](../tutorials/the-eventqueue-api.html).

docs/tutorials/using_apis/events_tutorial.md

@@ -152,4 +152,10 @@ Four words of storage are free but only for allocations of one word or less. The
 
 ### More about events
 
-This is only a small part of how event queues work in Mbed OS. The `EventQueue` and `Event` classes in the `mbed-events` library offer a lot of features that this document does not cover, including calling functions with arguments, queueing functions to be called after a delay or queueing functions to be called periodically. The [README of the `mbed-events` library](https://github.com/ARMmbed/mbed-os/blob/master/events/README.md) shows more ways to use events and event queues. To see the implementation of the events library, review [the equeue library](https://os.mbed.com/docs/development/mbed-os-api-doxy/_event_queue_8h_source.html).
+This is only a small part of how event queues work in Mbed OS. The `EventQueue`, `Event` and `UserAllocatedEvent` classes in the `mbed-events` library offer a lot of features that this document does not cover, including calling functions with arguments, queueing functions to be called after a delay or queueing functions to be called periodically. The [README of the `mbed-events` library](https://github.com/ARMmbed/mbed-os/blob/master/events/README.md) shows more ways to use events and event queues. To see the implementation of the events library, review [the equeue library](https://os.mbed.com/docs/development/mbed-os-api-doxy/_event_queue_8h_source.html).
+
+## Static EventQueue
+
+The EventQueue API provides a mechanism for creating a static queue, a queue that doesn't use any dynamic memory allocation and accepts only user-allocated events. After you create a static queue (by passing zero as `size` to its constructor), you can post `UserAllocatedEvent` to it. Using static EventQueue combined with UserAllocatedEvent ensures no dynamic memory allocation will take place during queue creation and events posting and dispatching. You can also declare queues and events as static objects (static in the C++ sense), and then memory for them will be reserved at compile time:
+
+[![View code](https://www.mbed.com/embed/?url=https://github.com/ARMmbed/mbed-os-examples-docs_only/blob/master/events/static-event-queue/UserAllocatedEvent_ex_1/)](https://github.com/ARMmbed/mbed-os-examples-docs_only/blob/master/events/static-event-queue/UserAllocatedEvent_ex_1/main.cpp)