Neil Johnson / microbit-ARMBand

Official Sheffield ARMBand micro:bit program

microbit/microbit-dal/inc/drivers/MicroBitMessageBus.h@0:b9164b348919, 2016-10-17 (annotated)

Committer:
MrBedfordVan
Date:
Mon Oct 17 12:41:20 2016 +0000
Revision:
0:b9164b348919
Official Sheffield ARMBand Micro:bit program

Who changed what in which revision?

UserRevisionLine numberNew contents of line
MrBedfordVan 0:b9164b348919 1 /*
MrBedfordVan 0:b9164b348919 2 The MIT License (MIT)
MrBedfordVan 0:b9164b348919 3
MrBedfordVan 0:b9164b348919 4 Copyright (c) 2016 British Broadcasting Corporation.
MrBedfordVan 0:b9164b348919 5 This software is provided by Lancaster University by arrangement with the BBC.
MrBedfordVan 0:b9164b348919 6
MrBedfordVan 0:b9164b348919 7 Permission is hereby granted, free of charge, to any person obtaining a
MrBedfordVan 0:b9164b348919 8 copy of this software and associated documentation files (the "Software"),
MrBedfordVan 0:b9164b348919 9 to deal in the Software without restriction, including without limitation
MrBedfordVan 0:b9164b348919 10 the rights to use, copy, modify, merge, publish, distribute, sublicense,
MrBedfordVan 0:b9164b348919 11 and/or sell copies of the Software, and to permit persons to whom the
MrBedfordVan 0:b9164b348919 12 Software is furnished to do so, subject to the following conditions:
MrBedfordVan 0:b9164b348919 13
MrBedfordVan 0:b9164b348919 14 The above copyright notice and this permission notice shall be included in
MrBedfordVan 0:b9164b348919 15 all copies or substantial portions of the Software.
MrBedfordVan 0:b9164b348919 16
MrBedfordVan 0:b9164b348919 17 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
MrBedfordVan 0:b9164b348919 18 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
MrBedfordVan 0:b9164b348919 19 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
MrBedfordVan 0:b9164b348919 20 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
MrBedfordVan 0:b9164b348919 21 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
MrBedfordVan 0:b9164b348919 22 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
MrBedfordVan 0:b9164b348919 23 DEALINGS IN THE SOFTWARE.
MrBedfordVan 0:b9164b348919 24 */
MrBedfordVan 0:b9164b348919 25
MrBedfordVan 0:b9164b348919 26 #ifndef MICROBIT_MESSAGE_BUS_H
MrBedfordVan 0:b9164b348919 27 #define MICROBIT_MESSAGE_BUS_H
MrBedfordVan 0:b9164b348919 28
MrBedfordVan 0:b9164b348919 29 #include "mbed.h"
MrBedfordVan 0:b9164b348919 30 #include "MicroBitConfig.h"
MrBedfordVan 0:b9164b348919 31 #include "MicroBitComponent.h"
MrBedfordVan 0:b9164b348919 32 #include "MicroBitEvent.h"
MrBedfordVan 0:b9164b348919 33 #include "MicroBitListener.h"
MrBedfordVan 0:b9164b348919 34 #include "EventModel.h"
MrBedfordVan 0:b9164b348919 35
MrBedfordVan 0:b9164b348919 36 /**
MrBedfordVan 0:b9164b348919 37 * Class definition for the MicroBitMessageBus.
MrBedfordVan 0:b9164b348919 38 *
MrBedfordVan 0:b9164b348919 39 * The MicroBitMessageBus is the common mechanism to deliver asynchronous events on the
MrBedfordVan 0:b9164b348919 40 * MicroBit platform. It serves a number of purposes:
MrBedfordVan 0:b9164b348919 41 *
MrBedfordVan 0:b9164b348919 42 * 1) It provides an eventing abstraction that is independent of the underlying substrate.
MrBedfordVan 0:b9164b348919 43 *
MrBedfordVan 0:b9164b348919 44 * 2) It provides a mechanism to decouple user code from trusted system code
MrBedfordVan 0:b9164b348919 45 * i.e. the basis of a message passing nano kernel.
MrBedfordVan 0:b9164b348919 46 *
MrBedfordVan 0:b9164b348919 47 * 3) It allows a common high level eventing abstraction across a range of hardware types.e.g. buttons, BLE...
MrBedfordVan 0:b9164b348919 48 *
MrBedfordVan 0:b9164b348919 49 * 4) It provides a mechanim for extensibility - new devices added via I/O pins can have OO based
MrBedfordVan 0:b9164b348919 50 * drivers and communicate via the message bus with minima impact on user level languages.
MrBedfordVan 0:b9164b348919 51 *
MrBedfordVan 0:b9164b348919 52 * 5) It allows for the possiblility of event / data aggregation, which in turn can save energy.
MrBedfordVan 0:b9164b348919 53 *
MrBedfordVan 0:b9164b348919 54 * It has the following design principles:
MrBedfordVan 0:b9164b348919 55 *
MrBedfordVan 0:b9164b348919 56 * 1) Maintain a low RAM footprint where possible
MrBedfordVan 0:b9164b348919 57 *
MrBedfordVan 0:b9164b348919 58 * 2) Make few assumptions about the underlying platform, but allow optimizations where possible.
MrBedfordVan 0:b9164b348919 59 */
MrBedfordVan 0:b9164b348919 60 class MicroBitMessageBus : public EventModel, public MicroBitComponent
MrBedfordVan 0:b9164b348919 61 {
MrBedfordVan 0:b9164b348919 62 public:
MrBedfordVan 0:b9164b348919 63
MrBedfordVan 0:b9164b348919 64 /**
MrBedfordVan 0:b9164b348919 65 * Default constructor.
MrBedfordVan 0:b9164b348919 66 *
MrBedfordVan 0:b9164b348919 67 * Adds itself as a fiber component, and also configures itself to be the
MrBedfordVan 0:b9164b348919 68 * default EventModel if defaultEventBus is NULL.
MrBedfordVan 0:b9164b348919 69 */
MrBedfordVan 0:b9164b348919 70 MicroBitMessageBus();
MrBedfordVan 0:b9164b348919 71
MrBedfordVan 0:b9164b348919 72 /**
MrBedfordVan 0:b9164b348919 73 * Queues the given event to be sent to all registered recipients.
MrBedfordVan 0:b9164b348919 74 *
MrBedfordVan 0:b9164b348919 75 * @param evt The event to send.
MrBedfordVan 0:b9164b348919 76 *
MrBedfordVan 0:b9164b348919 77 * @code
MrBedfordVan 0:b9164b348919 78 * MicroBitMessageBus bus;
MrBedfordVan 0:b9164b348919 79 *
MrBedfordVan 0:b9164b348919 80 * // Creates and sends the MicroBitEvent using bus.
MrBedfordVan 0:b9164b348919 81 * MicrobitEvent evt(MICROBIT_ID_BUTTON_A, MICROBIT_BUTTON_EVT_CLICK);
MrBedfordVan 0:b9164b348919 82 *
MrBedfordVan 0:b9164b348919 83 * // Creates the MicrobitEvent, but delays the sending of that event.
MrBedfordVan 0:b9164b348919 84 * MicrobitEvent evt1(MICROBIT_ID_BUTTON_A, MICROBIT_BUTTON_EVT_CLICK, CREATE_ONLY);
MrBedfordVan 0:b9164b348919 85 *
MrBedfordVan 0:b9164b348919 86 * bus.send(evt1);
MrBedfordVan 0:b9164b348919 87 *
MrBedfordVan 0:b9164b348919 88 * // This has the same effect!
MrBedfordVan 0:b9164b348919 89 * evt1.fire()
MrBedfordVan 0:b9164b348919 90 * @endcode
MrBedfordVan 0:b9164b348919 91 */
MrBedfordVan 0:b9164b348919 92 virtual int send(MicroBitEvent evt);
MrBedfordVan 0:b9164b348919 93
MrBedfordVan 0:b9164b348919 94 /**
MrBedfordVan 0:b9164b348919 95 * Internal function, used to deliver the given event to all relevant recipients.
MrBedfordVan 0:b9164b348919 96 * Normally, this is called once an event has been removed from the event queue.
MrBedfordVan 0:b9164b348919 97 *
MrBedfordVan 0:b9164b348919 98 * @param evt The event to send.
MrBedfordVan 0:b9164b348919 99 *
MrBedfordVan 0:b9164b348919 100 * @param urgent The type of listeners to process (optional). If set to true, only listeners defined as urgent and non-blocking will be processed
MrBedfordVan 0:b9164b348919 101 * otherwise, all other (standard) listeners will be processed. Defaults to false.
MrBedfordVan 0:b9164b348919 102 *
MrBedfordVan 0:b9164b348919 103 * @return 1 if all matching listeners were processed, 0 if further processing is required.
MrBedfordVan 0:b9164b348919 104 *
MrBedfordVan 0:b9164b348919 105 * @note It is recommended that all external code uses the send() function instead of this function,
MrBedfordVan 0:b9164b348919 106 * or the constructors provided by MicrobitEvent.
MrBedfordVan 0:b9164b348919 107 */
MrBedfordVan 0:b9164b348919 108 int process(MicroBitEvent &evt, bool urgent = false);
MrBedfordVan 0:b9164b348919 109
MrBedfordVan 0:b9164b348919 110 /**
MrBedfordVan 0:b9164b348919 111 * Returns the microBitListener with the given position in our list.
MrBedfordVan 0:b9164b348919 112 *
MrBedfordVan 0:b9164b348919 113 * @param n The position in the list to return.
MrBedfordVan 0:b9164b348919 114 *
MrBedfordVan 0:b9164b348919 115 * @return the MicroBitListener at postion n in the list, or NULL if the position is invalid.
MrBedfordVan 0:b9164b348919 116 */
MrBedfordVan 0:b9164b348919 117 virtual MicroBitListener *elementAt(int n);
MrBedfordVan 0:b9164b348919 118
MrBedfordVan 0:b9164b348919 119 /**
MrBedfordVan 0:b9164b348919 120 * Destructor for MicroBitMessageBus, where we deregister this instance from the array of fiber components.
MrBedfordVan 0:b9164b348919 121 */
MrBedfordVan 0:b9164b348919 122 ~MicroBitMessageBus();
MrBedfordVan 0:b9164b348919 123
MrBedfordVan 0:b9164b348919 124 /**
MrBedfordVan 0:b9164b348919 125 * Add the given MicroBitListener to the list of event handlers, unconditionally.
MrBedfordVan 0:b9164b348919 126 *
MrBedfordVan 0:b9164b348919 127 * @param listener The MicroBitListener to add.
MrBedfordVan 0:b9164b348919 128 *
MrBedfordVan 0:b9164b348919 129 * @return MICROBIT_OK if the listener is valid, MICROBIT_INVALID_PARAMETER otherwise.
MrBedfordVan 0:b9164b348919 130 */
MrBedfordVan 0:b9164b348919 131 virtual int add(MicroBitListener *newListener);
MrBedfordVan 0:b9164b348919 132
MrBedfordVan 0:b9164b348919 133 /**
MrBedfordVan 0:b9164b348919 134 * Remove the given MicroBitListener from the list of event handlers.
MrBedfordVan 0:b9164b348919 135 *
MrBedfordVan 0:b9164b348919 136 * @param listener The MicroBitListener to remove.
MrBedfordVan 0:b9164b348919 137 *
MrBedfordVan 0:b9164b348919 138 * @return MICROBIT_OK if the listener is valid, MICROBIT_INVALID_PARAMETER otherwise.
MrBedfordVan 0:b9164b348919 139 */
MrBedfordVan 0:b9164b348919 140 virtual int remove(MicroBitListener *newListener);
MrBedfordVan 0:b9164b348919 141
MrBedfordVan 0:b9164b348919 142 private:
MrBedfordVan 0:b9164b348919 143
MrBedfordVan 0:b9164b348919 144 MicroBitListener *listeners; // Chain of active listeners.
MrBedfordVan 0:b9164b348919 145 MicroBitEventQueueItem *evt_queue_head; // Head of queued events to be processed.
MrBedfordVan 0:b9164b348919 146 MicroBitEventQueueItem *evt_queue_tail; // Tail of queued events to be processed.
MrBedfordVan 0:b9164b348919 147 uint16_t nonce_val; // The last nonce issued.
MrBedfordVan 0:b9164b348919 148 uint16_t queueLength; // The number of events currently waiting to be processed.
MrBedfordVan 0:b9164b348919 149
MrBedfordVan 0:b9164b348919 150 /**
MrBedfordVan 0:b9164b348919 151 * Cleanup any MicroBitListeners marked for deletion from the list.
MrBedfordVan 0:b9164b348919 152 *
MrBedfordVan 0:b9164b348919 153 * @return The number of listeners removed from the list.
MrBedfordVan 0:b9164b348919 154 */
MrBedfordVan 0:b9164b348919 155 int deleteMarkedListeners();
MrBedfordVan 0:b9164b348919 156
MrBedfordVan 0:b9164b348919 157 /**
MrBedfordVan 0:b9164b348919 158 * Queue the given event for processing at a later time.
MrBedfordVan 0:b9164b348919 159 * Add the given event at the tail of our queue.
MrBedfordVan 0:b9164b348919 160 *
MrBedfordVan 0:b9164b348919 161 * @param The event to queue.
MrBedfordVan 0:b9164b348919 162 */
MrBedfordVan 0:b9164b348919 163 void queueEvent(MicroBitEvent &evt);
MrBedfordVan 0:b9164b348919 164
MrBedfordVan 0:b9164b348919 165 /**
MrBedfordVan 0:b9164b348919 166 * Extract the next event from the front of the event queue (if present).
MrBedfordVan 0:b9164b348919 167 *
MrBedfordVan 0:b9164b348919 168 * @return a pointer to the MicroBitEventQueueItem that is at the head of the list.
MrBedfordVan 0:b9164b348919 169 */
MrBedfordVan 0:b9164b348919 170 MicroBitEventQueueItem* dequeueEvent();
MrBedfordVan 0:b9164b348919 171
MrBedfordVan 0:b9164b348919 172 /**
MrBedfordVan 0:b9164b348919 173 * Periodic callback from MicroBit.
MrBedfordVan 0:b9164b348919 174 *
MrBedfordVan 0:b9164b348919 175 * Process at least one event from the event queue, if it is not empty.
MrBedfordVan 0:b9164b348919 176 * We then continue processing events until something appears on the runqueue.
MrBedfordVan 0:b9164b348919 177 */
MrBedfordVan 0:b9164b348919 178 virtual void idleTick();
MrBedfordVan 0:b9164b348919 179 };
MrBedfordVan 0:b9164b348919 180
MrBedfordVan 0:b9164b348919 181 #endif