EventBroker.md

-The **EventBroker** is a special singleton active object that allows to post events to specific topics, as in a Publish-Subscribe architecture.  
+The **EventBroker** is a special singleton active object that allows to post events to specific topics, as in a [Publish-Subscribe architecture](https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern).  
 [EventHandlers](EventHandler) in turn can ask the EventBroker to subscribe to a specific topic: this way a subscriber will receive all the events that are posted on the topics it is subscribed to.  
   
 In order to manage this events exchange, the broker maintains a map that associates each topic ID to a vector of EventHandlerBase objects:
@@ -17,6 +17,11 @@ In addition to the [singleton](Singleton) and [active object](Active-Object) met
 - **void unsubscribe(EventHandlerBase\* subscriber, uint8_t topic)**: unsubscribe the given subscriber to the specified topic. If no topic is passed, the unsubscribe the subscriber from every topic it was subscribed to.
 - **void clearDelayedEvents()**: remove all pending events.
 
+Moreover the EventBroker module also defines a macro that can be seen as a shortcut to retrieve the broker's instance:
+```cpp
+#define sEventBroker Singleton<EventBroker>::getInstance()
+```
+
 You can find the complete definition of the EventBroker in `src/shared/events/EventBroker.h`.
 
 > :warning: **WARNING: note that the current *EventBroker* implementation does not support posting events that contain a payload. See the [events basics](Events) page to know how events are structured.**
@@ -29,7 +34,6 @@ First of all we need to include the required dependencies. We also need to speci
 ```cpp
 #pragma once
 
-#include "Common.h"
 #include "events/EventHandler.h"
 #include "events/EventBroker.h"
 
@@ -57,10 +61,16 @@ public:
     MyEventHandler()
         : EventHandler(), // call parent constructor
           last_event(0) 
-          {
-              // make this object to subscribe to TOPIC_1
-              EventBroker::getInstance()->subscribe(this, TOPIC_1);
-          }
+    {
+        // make this object to subscribe to TOPIC_1
+        sEventBroker->subscribe(this, TOPIC_1);
+    }
+
+    ~MyEventHandler()
+    {
+        // unsubscribe from all the topics this object was subscribed to
+        sEventBroker->unsubscribe(this);
+    }
 
 protected:
     void handleEvent(const Event& ev) override
@@ -97,7 +107,7 @@ using namespace miosix;
 
 int main()
 {
-    EventBroker broker = EventBroker::getInstance(); // singleton object
+    EventBroker* broker = EventBroker::getInstance(); // singleton object
     broker->start();
 
     MyEventHandler evh;
@@ -108,8 +118,20 @@ int main()
         broker->post(Event{EV_1}, TOPIC_1);
         Thread::sleep(100);
         // post another event on a different topic
+        // this event will not be received by the MyEventHandler
+        // object, since it is subscribed only to TOPIC_1
         broker->post(Event{EV_2}, TOPIC_2);
         Thread::sleep(100);
+        // post an event with a delay of 1 second
+        const unsigned int DELAY_MS = 1000;
+        broker->postDelayed<DELAY_MS>(Event{EV_2}, TOPIC_1);
+
+        // wait for the delayed event to be posted 
+        // before stopping the active objects
+        Thread::sleep(2000);
+
+        evh.stop();  // it posts an EV_EMPTY to wake up the thread
+        broker->stop();
     }
     else {
         TRACE("Failed to start MyEventHandler\n");
@@ -121,6 +143,8 @@ int main()
 #### Output
 What we can observe is that the program output will be only something like:
 ```sh
-0.12> Received EV_1
+0.12> Received EV_1 
+1.32> Received EV_2 
+2.32> Invalid event
 ```
-In fact our MyEventHandler object will not receive the event `EV_2` since it is only subscribed to topic `TOPIC_1`.
\ No newline at end of file
+The last "Invalid event" is due to the `EV_EMPTY` posted by the `stop()` method of the EventHandler object.
\ No newline at end of file