From 3395f66d3de6124d561baad11d2144f1c8617ff7 Mon Sep 17 00:00:00 2001
From: Joe Finney <joe@comp.lancs.ac.uk>
Date: Sat, 12 Sep 2015 11:34:16 +0100
Subject: [PATCH] microbit: Added configurable event processing options into
 MicroBitEvent

Events in the micro:bit runtime are normally launched through making an instance
of the MicroBitEvent class. This update added configuration support to all the
code creating the MicroBitEvent decide if the newly created event should then be
automatically queued on the MessageBus or processed immediately by event handlers.
---
 inc/MicroBitEvent.h           | 36 +++++++++++++++++++++++++++++------
 inc/MicroBitMessageBus.h      |  4 ++--
 source/MicroBitEvent.cpp      | 21 ++++++++++++++++----
 source/MicroBitMessageBus.cpp |  3 ++-
 4 files changed, 51 insertions(+), 13 deletions(-)

diff --git a/inc/MicroBitEvent.h b/inc/MicroBitEvent.h
index d9c05c9..425848b 100644
--- a/inc/MicroBitEvent.h
+++ b/inc/MicroBitEvent.h
@@ -3,6 +3,15 @@
 
 #include "mbed.h"
 
+enum MicroBitEventLaunchMode
+{
+    CREATE_ONLY,                        
+    CREATE_AND_QUEUE,
+    CREATE_AND_FIRE
+};
+
+#define MICROBIT_EVENT_DEFAULT_LAUNCH_MODE     CREATE_AND_QUEUE
+
 /**
   * Class definition for a MicrobitEvent
   * It represents a common event that is generated by the various components on the MB.
@@ -22,15 +31,24 @@ class MicroBitEvent
       * Constructor. 
       * @param src ID of the MicroBit Component that generated the event e.g. MICROBIT_ID_BUTTON_A.
       * @param value Component specific code indicating the cause of the event.
-      * @param fire whether the event should be fire immediately upon construction
+      * @param mode optional definition of how the event should be processed after construction (if at all):
+      *
+      * CREATE_ONLY: MicroBitEvent is initialised, and no further processing takes place.
+      * CREATE_AND_QUEUE: MicroBitEvent is initialised, and queued on the MicroBitMessageBus.
+      * CREATE_AND_FIRE: MicroBitEvent is initialised, and its event handlers are immediately fired (not suitable for use in interrupts!).
       * 
-      * Example:
+      * Example: Create and launch an event using the default configuration
       * @code 
-      * MicrobitEvent evt(id,MICROBIT_BUTTON_EVT_CLICK,true); // auto fire
+      * MicrobitEvent evt(id,MICROBIT_BUTTON_EVT_CLICK); 
+      * @endcode
+      *
+      * Example: Create and launch an event and process all registered event handlers immediately.
+      * @code 
+      * MicrobitEvent evt(id,MICROBIT_BUTTON_EVT_CLICK,CREATE_AND_FIRE); 
       * @endcode
       */
-    
-    MicroBitEvent(uint16_t source, uint16_t value, bool fire = true);  
+   
+    MicroBitEvent(uint16_t source, uint16_t value, MicroBitEventLaunchMode mode = MICROBIT_EVENT_DEFAULT_LAUNCH_MODE);  
     
     /**
       * Default constructor - initialises all values, and sets timestamp to the current time.
@@ -38,9 +56,15 @@ class MicroBitEvent
     MicroBitEvent(); 
 
     /**
-      * Fires the represented event onto the message bus.
+      * Fires the represented event onto the message bus using the default configuration.
       */
     void fire();
+
+    /**
+      * Fires the represented event onto the message bus.
+      * @param mode Configuration of how the event is processed.
+      */
+    void fire(MicroBitEventLaunchMode mode);
 };
 
 /**
diff --git a/inc/MicroBitMessageBus.h b/inc/MicroBitMessageBus.h
index 85990f6..fdace6a 100644
--- a/inc/MicroBitMessageBus.h
+++ b/inc/MicroBitMessageBus.h
@@ -60,10 +60,10 @@ class MicroBitMessageBus : public MicroBitComponent
       * Internal function, used to deliver the given event to all relevant recipients.
       * Normally, this is called once an event has been removed from the event queue.
       *
-      * IT IS RECOMMENDED THAT ALL EXTERNAL CODE USE THE send() FUNCTIONS INSTEAD OF THIS FUNCTION.
+      * IT IS RECOMMENDED THAT ALL EXTERNAL CODE USE THE send() FUNCTIONS INSTEAD OF THIS FUNCTION,
+      * or the constructors provided by MicroBitEvent.
 	  *
 	  * @param evt The event to send. 
-	  * @param c The cache entry to reduce lookups for commonly used channels.
 	  */
 	void process(MicroBitEvent evt);
 
diff --git a/source/MicroBitEvent.cpp b/source/MicroBitEvent.cpp
index c12d33b..330048a 100644
--- a/source/MicroBitEvent.cpp
+++ b/source/MicroBitEvent.cpp
@@ -17,14 +17,14 @@
   * MicrobitEvent evt(id,MICROBIT_BUTTON_EVT_CLICK,true); // auto fire
   * @endcode
   */
-MicroBitEvent::MicroBitEvent(uint16_t source, uint16_t value, bool fire)
+MicroBitEvent::MicroBitEvent(uint16_t source, uint16_t value, MicroBitEventLaunchMode mode)
 {
     this->source = source;
     this->value = value;
     this->timestamp = ticks;
     
-    if(fire)
-        this->fire();
+    if(mode != CREATE_ONLY)
+        this->fire(mode);
 }    
 
 /**
@@ -37,14 +37,27 @@ MicroBitEvent::MicroBitEvent()
     this->timestamp = ticks;
 }
 
+/**
+  * Fires the represented event onto the message bus.
+  */
+void MicroBitEvent::fire(MicroBitEventLaunchMode mode)
+{
+    if (mode == CREATE_AND_QUEUE)
+        uBit.MessageBus.send(*this);
+
+    else if (mode == CREATE_AND_FIRE)
+        uBit.MessageBus.process(*this);
+}
+
 /**
   * Fires the represented event onto the message bus.
   */
 void MicroBitEvent::fire()
 {
-    uBit.MessageBus.send(*this);
+    fire(MICROBIT_EVENT_DEFAULT_LAUNCH_MODE);
 }
 
+
 /**
   * Constructor. 
   * Create a new MicroBitEventQueueItem.
diff --git a/source/MicroBitMessageBus.cpp b/source/MicroBitMessageBus.cpp
index 1223c32..3d7b999 100644
--- a/source/MicroBitMessageBus.cpp
+++ b/source/MicroBitMessageBus.cpp
@@ -189,8 +189,9 @@ int MicroBitMessageBus::isIdleCallbackNeeded()
   *
   * Example:
   * @code 
-  * MicroBitEvent evt(id,MICROBIT_BUTTON_EVT_DOWN,ticks,false);
+  * MicroBitEvent evt(id,MICROBIT_BUTTON_EVT_DOWN,ticks,CREATE_ONLY);
   * evt.fire();
+  *
   * //OR YOU CAN DO THIS...  
   * MicroBitEvent evt(id,MICROBIT_BUTTON_EVT_DOWN);
   * @endcode