Add documentation for static events/queue

Author: maciejbocianski

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 event 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. As the `UserAllocatedEvent` holds event data it can't be posted more then one at the time. It means that if the event object has to be reused the previous dispatch has to finish or event has to be canceled. `try_call` API can be used to sample the event state. `try_call` call will try to post event and will return false with no action until the previous dispatching won't finish.
+
+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);
+}
+```