Diff: inc/drivers/MicroBitMessageBus.h

Revision:

1:8aa5cdb4ab67

Child:

41:da05ec75cd5d

diff -r fb15f7887843 -r 8aa5cdb4ab67 inc/drivers/MicroBitMessageBus.h
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/inc/drivers/MicroBitMessageBus.h	Thu Apr 07 01:33:22 2016 +0100
@@ -0,0 +1,188 @@
+/*
+The MIT License (MIT)
+
+Copyright (c) 2016 British Broadcasting Corporation.
+This software is provided by Lancaster University by arrangement with the BBC.
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+*/
+
+#ifndef MICROBIT_MESSAGE_BUS_H
+#define MICROBIT_MESSAGE_BUS_H
+
+#include "mbed.h"
+#include "MicroBitConfig.h"
+#include "MicroBitComponent.h"
+#include "MicroBitEvent.h"
+#include "MicroBitListener.h"
+#include "EventModel.h"
+
+/**
+  * Class definition for the MicroBitMessageBus.
+  *
+  * The MicroBitMessageBus is the common mechanism to deliver asynchronous events on the
+  * MicroBit platform. It serves a number of purposes:
+  *
+  * 1) It provides an eventing abstraction that is independent of the underlying substrate.
+  *
+  * 2) It provides a mechanism to decouple user code from trusted system code
+  *    i.e. the basis of a message passing nano kernel.
+  *
+  * 3) It allows a common high level eventing abstraction across a range of hardware types.e.g. buttons, BLE...
+  *
+  * 4) It provides a mechanim for extensibility - new devices added via I/O pins can have OO based
+  *    drivers and communicate via the message bus with minima impact on user level languages.
+  *
+  * 5) It allows for the possiblility of event / data aggregation, which in turn can save energy.
+  *
+  * It has the following design principles:
+  *
+  * 1) Maintain a low RAM footprint where possible
+  *
+  * 2) Make few assumptions about the underlying platform, but allow optimizations where possible.
+  */
+class MicroBitMessageBus : public EventModel, public MicroBitComponent
+{
+    public:
+
+	/**
+	  * Default constructor.
+      *
+      * Adds itself as a fiber component, and also configures itself to be the
+      * default EventModel if defaultEventBus is NULL.
+	  */
+    MicroBitMessageBus();
+
+	/**
+	  * Queues the given event to be sent to all registered recipients.
+	  *
+	  * @param evt The event to send.
+      *
+      * @code
+      * MicroBitMessageBus bus;
+      *
+      * // Creates and sends the MicroBitEvent using bus.
+	  * MicrobitEvent evt(MICROBIT_ID_BUTTON_A, MICROBIT_BUTTON_EVT_CLICK);
+      *
+      * // Creates the MicrobitEvent, but delays the sending of that event.
+      * MicrobitEvent evt1(MICROBIT_ID_BUTTON_A, MICROBIT_BUTTON_EVT_CLICK, CREATE_ONLY);
+      *
+      * bus.send(evt1);
+      *
+      * // This has the same effect!
+      * evt1.fire()
+      * @endcode
+	  */
+	virtual int send(MicroBitEvent evt);
+
+	/**
+      * 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.
+	  *
+	  * @param evt The event to send.
+      *
+      * @param urgent The type of listeners to process (optional). If set to true, only listeners defined as urgent and non-blocking will be processed
+      *               otherwise, all other (standard) listeners will be processed. Defaults to false.
+      *
+      * @return 1 if all matching listeners were processed, 0 if further processing is required.
+      *
+      * @note It is recommended that all external code uses the send() function instead of this function,
+      *       or the constructors provided by MicrobitEvent.
+      */
+	int process(MicroBitEvent &evt, bool urgent = false);
+
+    /**
+      * Returns the microBitListener with the given position in our list.
+      *
+      * @param n The position in the list to return.
+      *
+      * @return the MicroBitListener at postion n in the list, or NULL if the position is invalid.
+      */
+    virtual MicroBitListener *elementAt(int n);
+
+    /**
+      * Destructor for MicroBitMessageBus, where we deregister this instance from the array of fiber components.
+      */
+    ~MicroBitMessageBus();
+
+    /**
+      * Add the given MicroBitListener to the list of event handlers, unconditionally.
+      *
+      * @param listener The MicroBitListener to add.
+      *
+      * @return MICROBIT_OK if the listener is valid, MICROBIT_INVALID_PARAMETER otherwise.
+      */
+    virtual int add(MicroBitListener *newListener);
+
+    /**
+      * Remove the given MicroBitListener from the list of event handlers.
+      *
+      * @param listener The MicroBitListener to remove.
+      *
+      * @return MICROBIT_OK if the listener is valid, MICROBIT_INVALID_PARAMETER otherwise.
+      */
+    virtual int remove(MicroBitListener *newListener);
+
+	private:
+
+    MicroBitListener            *listeners;		    // Chain of active listeners.
+    MicroBitEventQueueItem      *evt_queue_head;    // Head of queued events to be processed.
+    MicroBitEventQueueItem      *evt_queue_tail;    // Tail of queued events to be processed.
+    uint16_t                    nonce_val;          // The last nonce issued.
+    uint16_t                    queueLength;        // The number of events currently waiting to be processed.
+
+    /**
+      * Cleanup any MicroBitListeners marked for deletion from the list.
+      *
+      * @return The number of listeners removed from the list.
+      */
+    int deleteMarkedListeners();
+
+    /**
+      * Queue the given event for processing at a later time.
+      * Add the given event at the tail of our queue.
+      *
+      * @param The event to queue.
+      */
+    void queueEvent(MicroBitEvent &evt);
+
+    /**
+      * Extract the next event from the front of the event queue (if present).
+      *
+      * @return a pointer to the MicroBitEventQueueItem that is at the head of the list.
+      */
+    MicroBitEventQueueItem* dequeueEvent();
+
+    /**
+      * Periodic callback from MicroBit.
+      *
+      * Process at least one event from the event queue, if it is not empty.
+      * We then continue processing events until something appears on the runqueue.
+      */
+    virtual void idleTick();
+
+    /**
+      * Indicates whether or not we have any background work to do.
+      *
+      * @return 1 if there are any events waitingto be processed, 0 otherwise.
+      */
+    virtual int isIdleCallbackNeeded();
+};
+
+#endif