fsdfds
Dependencies: BLE_API mbed-dev-bin nRF51822
Fork of microbit-dal by
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
Generated on Wed Jul 13 2022 00:58:03 by 1.7.2