mbed.org local branch of microbit-dal. The real version lives in git at https://github.com/lancaster-university/microbit-dal

Dependencies:   BLE_API nRF51822 mbed-dev-bin

Dependents:   microbit Microbit IoTChallenge1 microbit ... more

Embed: (wiki syntax)

« Back to documentation index

Show/hide line numbers MicroBitMessageBus.h Source File

MicroBitMessageBus.h

00001 /*
00002 The MIT License (MIT)
00003 
00004 Copyright (c) 2016 British Broadcasting Corporation.
00005 This software is provided by Lancaster University by arrangement with the BBC.
00006 
00007 Permission is hereby granted, free of charge, to any person obtaining a
00008 copy of this software and associated documentation files (the "Software"),
00009 to deal in the Software without restriction, including without limitation
00010 the rights to use, copy, modify, merge, publish, distribute, sublicense,
00011 and/or sell copies of the Software, and to permit persons to whom the
00012 Software is furnished to do so, subject to the following conditions:
00013 
00014 The above copyright notice and this permission notice shall be included in
00015 all copies or substantial portions of the Software.
00016 
00017 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
00018 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
00019 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
00020 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
00021 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
00022 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
00023 DEALINGS IN THE SOFTWARE.
00024 */
00025 
00026 #ifndef MICROBIT_MESSAGE_BUS_H
00027 #define MICROBIT_MESSAGE_BUS_H
00028 
00029 #include "mbed.h"
00030 #include "MicroBitConfig.h"
00031 #include "MicroBitComponent.h"
00032 #include "MicroBitEvent.h"
00033 #include "MicroBitListener.h"
00034 #include "EventModel.h"
00035 
00036 /**
00037   * Class definition for the MicroBitMessageBus.
00038   *
00039   * The MicroBitMessageBus is the common mechanism to deliver asynchronous events on the
00040   * MicroBit platform. It serves a number of purposes:
00041   *
00042   * 1) It provides an eventing abstraction that is independent of the underlying substrate.
00043   *
00044   * 2) It provides a mechanism to decouple user code from trusted system code
00045   *    i.e. the basis of a message passing nano kernel.
00046   *
00047   * 3) It allows a common high level eventing abstraction across a range of hardware types.e.g. buttons, BLE...
00048   *
00049   * 4) It provides a mechanim for extensibility - new devices added via I/O pins can have OO based
00050   *    drivers and communicate via the message bus with minima impact on user level languages.
00051   *
00052   * 5) It allows for the possiblility of event / data aggregation, which in turn can save energy.
00053   *
00054   * It has the following design principles:
00055   *
00056   * 1) Maintain a low RAM footprint where possible
00057   *
00058   * 2) Make few assumptions about the underlying platform, but allow optimizations where possible.
00059   */
00060 class MicroBitMessageBus : public EventModel, public MicroBitComponent
00061 {
00062     public:
00063 
00064     /**
00065       * Default constructor.
00066       *
00067       * Adds itself as a fiber component, and also configures itself to be the
00068       * default EventModel if defaultEventBus is NULL.
00069       */
00070     MicroBitMessageBus();
00071 
00072     /**
00073       * Queues the given event to be sent to all registered recipients.
00074       *
00075       * @param evt The event to send.
00076       *
00077       * @code
00078       * MicroBitMessageBus bus;
00079       *
00080       * // Creates and sends the MicroBitEvent using bus.
00081       * MicrobitEvent evt(MICROBIT_ID_BUTTON_A, MICROBIT_BUTTON_EVT_CLICK);
00082       *
00083       * // Creates the MicrobitEvent, but delays the sending of that event.
00084       * MicrobitEvent evt1(MICROBIT_ID_BUTTON_A, MICROBIT_BUTTON_EVT_CLICK, CREATE_ONLY);
00085       *
00086       * bus.send(evt1);
00087       *
00088       * // This has the same effect!
00089       * evt1.fire()
00090       * @endcode
00091       */
00092     virtual int send(MicroBitEvent evt);
00093 
00094     /**
00095       * Internal function, used to deliver the given event to all relevant recipients.
00096       * Normally, this is called once an event has been removed from the event queue.
00097       *
00098       * @param evt The event to send.
00099       *
00100       * @param urgent The type of listeners to process (optional). If set to true, only listeners defined as urgent and non-blocking will be processed
00101       *               otherwise, all other (standard) listeners will be processed. Defaults to false.
00102       *
00103       * @return 1 if all matching listeners were processed, 0 if further processing is required.
00104       *
00105       * @note It is recommended that all external code uses the send() function instead of this function,
00106       *       or the constructors provided by MicrobitEvent.
00107       */
00108     int process(MicroBitEvent &evt, bool urgent = false);
00109 
00110     /**
00111       * Returns the microBitListener with the given position in our list.
00112       *
00113       * @param n The position in the list to return.
00114       *
00115       * @return the MicroBitListener at postion n in the list, or NULL if the position is invalid.
00116       */
00117     virtual MicroBitListener *elementAt(int n);
00118 
00119     /**
00120       * Destructor for MicroBitMessageBus, where we deregister this instance from the array of fiber components.
00121       */
00122     ~MicroBitMessageBus();
00123 
00124     /**
00125       * Add the given MicroBitListener to the list of event handlers, unconditionally.
00126       *
00127       * @param listener The MicroBitListener to add.
00128       *
00129       * @return MICROBIT_OK if the listener is valid, MICROBIT_INVALID_PARAMETER otherwise.
00130       */
00131     virtual int add(MicroBitListener *newListener);
00132 
00133     /**
00134       * Remove the given MicroBitListener from the list of event handlers.
00135       *
00136       * @param listener The MicroBitListener to remove.
00137       *
00138       * @return MICROBIT_OK if the listener is valid, MICROBIT_INVALID_PARAMETER otherwise.
00139       */
00140     virtual int remove(MicroBitListener *newListener);
00141 
00142     private:
00143 
00144     MicroBitListener            *listeners;         // Chain of active listeners.
00145     MicroBitEventQueueItem      *evt_queue_head;    // Head of queued events to be processed.
00146     MicroBitEventQueueItem      *evt_queue_tail;    // Tail of queued events to be processed.
00147     uint16_t                    nonce_val;          // The last nonce issued.
00148     uint16_t                    queueLength;        // The number of events currently waiting to be processed.
00149 
00150     /**
00151       * Cleanup any MicroBitListeners marked for deletion from the list.
00152       *
00153       * @return The number of listeners removed from the list.
00154       */
00155     int deleteMarkedListeners();
00156 
00157     /**
00158       * Queue the given event for processing at a later time.
00159       * Add the given event at the tail of our queue.
00160       *
00161       * @param The event to queue.
00162       */
00163     void queueEvent(MicroBitEvent &evt);
00164 
00165     /**
00166       * Extract the next event from the front of the event queue (if present).
00167       *
00168       * @return a pointer to the MicroBitEventQueueItem that is at the head of the list.
00169       */
00170     MicroBitEventQueueItem* dequeueEvent();
00171 
00172     /**
00173       * Periodic callback from MicroBit.
00174       *
00175       * Process at least one event from the event queue, if it is not empty.
00176       * We then continue processing events until something appears on the runqueue.
00177       */
00178     virtual void idleTick();
00179 };
00180 
00181 #endif