Add documentation for static events/queue

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
+
+If you want to be 100% sure that you program won't fail due to queue memory exhaustion or you don't want no dynamic memory allocation in it you should use static EventQueue.
+
+TODO: example code here
+
 ## Related content
 
 - [EventQueue tutorial](../tutorials/the-eventqueue-api.html).

docs/api/rtos/UserAllocatedEvent.md

@@ -0,0 +1,20 @@
+# UserAllocatedEvent
+
+The `UserAllocatedEvent` class provides APIs to create and configure static events. `UserAllocatedEvent` advantage over `Event` is that it embeds all underlying event data and doesn't require any memory allocation while posting and dispatching on to the EventQueue. To configure timings use `delay` and `period` APIs. You can use `call` and `try_call` API to post an event to the underlying EventQueue or `call_on` and `try_call_on` API to bind and post an event to the EventQueue passed as function argument, and you can use `cancel` to cancel the most recently posted event.
+
+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/development/mbed-os-api-doxy/_event_8h_source.html)
+
+## Static EventQueue example: posting user allocated events to the queue
+
+The code below demonstrates how you can instantiate, configure and post events.
+
+[![View code](https://www.mbed.com/embed/?url=https://os.mbed.com/teams/mbed_example/code/mbed-os-example-events/)](https://os.mbed.com/teams/mbed_example/code/mbed-os-example-events/file/86c4bf2d90fa/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,27 @@ 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 queue
+
+EventQueue API provides mechanism for creating so called static queue, a queue that doesn't use any dynamic memory allocation at all and accepts only user allocated events. Once you created static queue (by passing zero as `size` to its constructor) you can post any number of `UserAllocatedEvent` to it. Using static EventQueue combined with UserAllocatedEvent gives the warranty that no dynamic memory allocation will take place while queue creation and events posting & dispatching. Going even further you can declare queue and events as static objects (static in C++ sense) and then memory for them will be reserved at compile time as on below example.
+
+```
+void handler(int data) { ... }
+
+// Static queue with not internal storage for dynamic events
+// accepts only user allocated events
+static EventQueue queue(0);
+// Create user allocated events
+static auto e1 = make_user_allocated_event(handler, 2);
+static auto e2 = queue.make_user_allocated_event(handler, 3);
+
+int main()
+{
+    e1.call_on(&queue);
+    e2.call();
+
+   queue.dispatch(1);
+}
+```