Simon Cooksey / mbed-os

Pinned to some recent date

platform/CallChain.h@0:fb7af294d5d9, 2016-11-17 (annotated)

Committer:
Simon Cooksey
Date:
Thu Nov 17 16:43:53 2016 +0000
Revision:
0:fb7af294d5d9
Initial commit

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Simon Cooksey 0:fb7af294d5d9 1 /* mbed Microcontroller Library
Simon Cooksey 0:fb7af294d5d9 2 * Copyright (c) 2006-2013 ARM Limited
Simon Cooksey 0:fb7af294d5d9 3 *
Simon Cooksey 0:fb7af294d5d9 4 * Licensed under the Apache License, Version 2.0 (the "License");
Simon Cooksey 0:fb7af294d5d9 5 * you may not use this file except in compliance with the License.
Simon Cooksey 0:fb7af294d5d9 6 * You may obtain a copy of the License at
Simon Cooksey 0:fb7af294d5d9 7 *
Simon Cooksey 0:fb7af294d5d9 8 * http://www.apache.org/licenses/LICENSE-2.0
Simon Cooksey 0:fb7af294d5d9 9 *
Simon Cooksey 0:fb7af294d5d9 10 * Unless required by applicable law or agreed to in writing, software
Simon Cooksey 0:fb7af294d5d9 11 * distributed under the License is distributed on an "AS IS" BASIS,
Simon Cooksey 0:fb7af294d5d9 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
Simon Cooksey 0:fb7af294d5d9 13 * See the License for the specific language governing permissions and
Simon Cooksey 0:fb7af294d5d9 14 * limitations under the License.
Simon Cooksey 0:fb7af294d5d9 15 */
Simon Cooksey 0:fb7af294d5d9 16 #ifndef MBED_CALLCHAIN_H
Simon Cooksey 0:fb7af294d5d9 17 #define MBED_CALLCHAIN_H
Simon Cooksey 0:fb7af294d5d9 18
Simon Cooksey 0:fb7af294d5d9 19 #include "platform/Callback.h"
Simon Cooksey 0:fb7af294d5d9 20 #include "platform/toolchain.h"
Simon Cooksey 0:fb7af294d5d9 21 #include <string.h>
Simon Cooksey 0:fb7af294d5d9 22
Simon Cooksey 0:fb7af294d5d9 23 namespace mbed {
Simon Cooksey 0:fb7af294d5d9 24 /** \addtogroup platform */
Simon Cooksey 0:fb7af294d5d9 25 /** @{*/
Simon Cooksey 0:fb7af294d5d9 26
Simon Cooksey 0:fb7af294d5d9 27 /** Group one or more functions in an instance of a CallChain, then call them in
Simon Cooksey 0:fb7af294d5d9 28 * sequence using CallChain::call(). Used mostly by the interrupt chaining code,
Simon Cooksey 0:fb7af294d5d9 29 * but can be used for other purposes.
Simon Cooksey 0:fb7af294d5d9 30 *
Simon Cooksey 0:fb7af294d5d9 31 * @Note Synchronization level: Not protected
Simon Cooksey 0:fb7af294d5d9 32 *
Simon Cooksey 0:fb7af294d5d9 33 * Example:
Simon Cooksey 0:fb7af294d5d9 34 * @code
Simon Cooksey 0:fb7af294d5d9 35 * #include "mbed.h"
Simon Cooksey 0:fb7af294d5d9 36 *
Simon Cooksey 0:fb7af294d5d9 37 * CallChain chain;
Simon Cooksey 0:fb7af294d5d9 38 *
Simon Cooksey 0:fb7af294d5d9 39 * void first(void) {
Simon Cooksey 0:fb7af294d5d9 40 * printf("'first' function.\n");
Simon Cooksey 0:fb7af294d5d9 41 * }
Simon Cooksey 0:fb7af294d5d9 42 *
Simon Cooksey 0:fb7af294d5d9 43 * void second(void) {
Simon Cooksey 0:fb7af294d5d9 44 * printf("'second' function.\n");
Simon Cooksey 0:fb7af294d5d9 45 * }
Simon Cooksey 0:fb7af294d5d9 46 *
Simon Cooksey 0:fb7af294d5d9 47 * class Test {
Simon Cooksey 0:fb7af294d5d9 48 * public:
Simon Cooksey 0:fb7af294d5d9 49 * void f(void) {
Simon Cooksey 0:fb7af294d5d9 50 * printf("A::f (class member).\n");
Simon Cooksey 0:fb7af294d5d9 51 * }
Simon Cooksey 0:fb7af294d5d9 52 * };
Simon Cooksey 0:fb7af294d5d9 53 *
Simon Cooksey 0:fb7af294d5d9 54 * int main() {
Simon Cooksey 0:fb7af294d5d9 55 * Test test;
Simon Cooksey 0:fb7af294d5d9 56 *
Simon Cooksey 0:fb7af294d5d9 57 * chain.add(second);
Simon Cooksey 0:fb7af294d5d9 58 * chain.add_front(first);
Simon Cooksey 0:fb7af294d5d9 59 * chain.add(&test, &Test::f);
Simon Cooksey 0:fb7af294d5d9 60 * chain.call();
Simon Cooksey 0:fb7af294d5d9 61 * }
Simon Cooksey 0:fb7af294d5d9 62 * @endcode
Simon Cooksey 0:fb7af294d5d9 63 */
Simon Cooksey 0:fb7af294d5d9 64
Simon Cooksey 0:fb7af294d5d9 65 typedef Callback<void()> *pFunctionPointer_t;
Simon Cooksey 0:fb7af294d5d9 66 class CallChainLink;
Simon Cooksey 0:fb7af294d5d9 67
Simon Cooksey 0:fb7af294d5d9 68 class CallChain {
Simon Cooksey 0:fb7af294d5d9 69 public:
Simon Cooksey 0:fb7af294d5d9 70 /** Create an empty chain
Simon Cooksey 0:fb7af294d5d9 71 *
Simon Cooksey 0:fb7af294d5d9 72 * @param size (optional) Initial size of the chain
Simon Cooksey 0:fb7af294d5d9 73 */
Simon Cooksey 0:fb7af294d5d9 74 CallChain(int size = 4);
Simon Cooksey 0:fb7af294d5d9 75 virtual ~CallChain();
Simon Cooksey 0:fb7af294d5d9 76
Simon Cooksey 0:fb7af294d5d9 77 /** Add a function at the end of the chain
Simon Cooksey 0:fb7af294d5d9 78 *
Simon Cooksey 0:fb7af294d5d9 79 * @param func A pointer to a void function
Simon Cooksey 0:fb7af294d5d9 80 *
Simon Cooksey 0:fb7af294d5d9 81 * @returns
Simon Cooksey 0:fb7af294d5d9 82 * The function object created for 'func'
Simon Cooksey 0:fb7af294d5d9 83 */
Simon Cooksey 0:fb7af294d5d9 84 pFunctionPointer_t add(Callback<void()> func);
Simon Cooksey 0:fb7af294d5d9 85
Simon Cooksey 0:fb7af294d5d9 86 /** Add a function at the end of the chain
Simon Cooksey 0:fb7af294d5d9 87 *
Simon Cooksey 0:fb7af294d5d9 88 * @param obj pointer to the object to call the member function on
Simon Cooksey 0:fb7af294d5d9 89 * @param method pointer to the member function to be called
Simon Cooksey 0:fb7af294d5d9 90 *
Simon Cooksey 0:fb7af294d5d9 91 * @returns
Simon Cooksey 0:fb7af294d5d9 92 * The function object created for 'obj' and 'method'
Simon Cooksey 0:fb7af294d5d9 93 *
Simon Cooksey 0:fb7af294d5d9 94 * @deprecated
Simon Cooksey 0:fb7af294d5d9 95 * The add function does not support cv-qualifiers. Replaced by
Simon Cooksey 0:fb7af294d5d9 96 * add(callback(obj, method)).
Simon Cooksey 0:fb7af294d5d9 97 */
Simon Cooksey 0:fb7af294d5d9 98 template<typename T, typename M>
Simon Cooksey 0:fb7af294d5d9 99 MBED_DEPRECATED_SINCE("mbed-os-5.1",
Simon Cooksey 0:fb7af294d5d9 100 "The add function does not support cv-qualifiers. Replaced by "
Simon Cooksey 0:fb7af294d5d9 101 "add(callback(obj, method)).")
Simon Cooksey 0:fb7af294d5d9 102 pFunctionPointer_t add(T *obj, M method) {
Simon Cooksey 0:fb7af294d5d9 103 return add(callback(obj, method));
Simon Cooksey 0:fb7af294d5d9 104 }
Simon Cooksey 0:fb7af294d5d9 105
Simon Cooksey 0:fb7af294d5d9 106 /** Add a function at the beginning of the chain
Simon Cooksey 0:fb7af294d5d9 107 *
Simon Cooksey 0:fb7af294d5d9 108 * @param func A pointer to a void function
Simon Cooksey 0:fb7af294d5d9 109 *
Simon Cooksey 0:fb7af294d5d9 110 * @returns
Simon Cooksey 0:fb7af294d5d9 111 * The function object created for 'func'
Simon Cooksey 0:fb7af294d5d9 112 */
Simon Cooksey 0:fb7af294d5d9 113 pFunctionPointer_t add_front(Callback<void()> func);
Simon Cooksey 0:fb7af294d5d9 114
Simon Cooksey 0:fb7af294d5d9 115 /** Add a function at the beginning of the chain
Simon Cooksey 0:fb7af294d5d9 116 *
Simon Cooksey 0:fb7af294d5d9 117 * @param tptr pointer to the object to call the member function on
Simon Cooksey 0:fb7af294d5d9 118 * @param mptr pointer to the member function to be called
Simon Cooksey 0:fb7af294d5d9 119 *
Simon Cooksey 0:fb7af294d5d9 120 * @returns
Simon Cooksey 0:fb7af294d5d9 121 * The function object created for 'tptr' and 'mptr'
Simon Cooksey 0:fb7af294d5d9 122 *
Simon Cooksey 0:fb7af294d5d9 123 * @deprecated
Simon Cooksey 0:fb7af294d5d9 124 * The add_front function does not support cv-qualifiers. Replaced by
Simon Cooksey 0:fb7af294d5d9 125 * add_front(callback(obj, method)).
Simon Cooksey 0:fb7af294d5d9 126 */
Simon Cooksey 0:fb7af294d5d9 127 template<typename T, typename M>
Simon Cooksey 0:fb7af294d5d9 128 MBED_DEPRECATED_SINCE("mbed-os-5.1",
Simon Cooksey 0:fb7af294d5d9 129 "The add_front function does not support cv-qualifiers. Replaced by "
Simon Cooksey 0:fb7af294d5d9 130 "add_front(callback(obj, method)).")
Simon Cooksey 0:fb7af294d5d9 131 pFunctionPointer_t add_front(T *obj, M method) {
Simon Cooksey 0:fb7af294d5d9 132 return add_front(callback(obj, method));
Simon Cooksey 0:fb7af294d5d9 133 }
Simon Cooksey 0:fb7af294d5d9 134
Simon Cooksey 0:fb7af294d5d9 135 /** Get the number of functions in the chain
Simon Cooksey 0:fb7af294d5d9 136 */
Simon Cooksey 0:fb7af294d5d9 137 int size() const;
Simon Cooksey 0:fb7af294d5d9 138
Simon Cooksey 0:fb7af294d5d9 139 /** Get a function object from the chain
Simon Cooksey 0:fb7af294d5d9 140 *
Simon Cooksey 0:fb7af294d5d9 141 * @param i function object index
Simon Cooksey 0:fb7af294d5d9 142 *
Simon Cooksey 0:fb7af294d5d9 143 * @returns
Simon Cooksey 0:fb7af294d5d9 144 * The function object at position 'i' in the chain
Simon Cooksey 0:fb7af294d5d9 145 */
Simon Cooksey 0:fb7af294d5d9 146 pFunctionPointer_t get(int i) const;
Simon Cooksey 0:fb7af294d5d9 147
Simon Cooksey 0:fb7af294d5d9 148 /** Look for a function object in the call chain
Simon Cooksey 0:fb7af294d5d9 149 *
Simon Cooksey 0:fb7af294d5d9 150 * @param f the function object to search
Simon Cooksey 0:fb7af294d5d9 151 *
Simon Cooksey 0:fb7af294d5d9 152 * @returns
Simon Cooksey 0:fb7af294d5d9 153 * The index of the function object if found, -1 otherwise.
Simon Cooksey 0:fb7af294d5d9 154 */
Simon Cooksey 0:fb7af294d5d9 155 int find(pFunctionPointer_t f) const;
Simon Cooksey 0:fb7af294d5d9 156
Simon Cooksey 0:fb7af294d5d9 157 /** Clear the call chain (remove all functions in the chain).
Simon Cooksey 0:fb7af294d5d9 158 */
Simon Cooksey 0:fb7af294d5d9 159 void clear();
Simon Cooksey 0:fb7af294d5d9 160
Simon Cooksey 0:fb7af294d5d9 161 /** Remove a function object from the chain
Simon Cooksey 0:fb7af294d5d9 162 *
Simon Cooksey 0:fb7af294d5d9 163 * @arg f the function object to remove
Simon Cooksey 0:fb7af294d5d9 164 *
Simon Cooksey 0:fb7af294d5d9 165 * @returns
Simon Cooksey 0:fb7af294d5d9 166 * true if the function object was found and removed, false otherwise.
Simon Cooksey 0:fb7af294d5d9 167 */
Simon Cooksey 0:fb7af294d5d9 168 bool remove(pFunctionPointer_t f);
Simon Cooksey 0:fb7af294d5d9 169
Simon Cooksey 0:fb7af294d5d9 170 /** Call all the functions in the chain in sequence
Simon Cooksey 0:fb7af294d5d9 171 */
Simon Cooksey 0:fb7af294d5d9 172 void call();
Simon Cooksey 0:fb7af294d5d9 173
Simon Cooksey 0:fb7af294d5d9 174 void operator ()(void) {
Simon Cooksey 0:fb7af294d5d9 175 call();
Simon Cooksey 0:fb7af294d5d9 176 }
Simon Cooksey 0:fb7af294d5d9 177 pFunctionPointer_t operator [](int i) const {
Simon Cooksey 0:fb7af294d5d9 178 return get(i);
Simon Cooksey 0:fb7af294d5d9 179 }
Simon Cooksey 0:fb7af294d5d9 180
Simon Cooksey 0:fb7af294d5d9 181 /* disallow copy constructor and assignment operators */
Simon Cooksey 0:fb7af294d5d9 182 private:
Simon Cooksey 0:fb7af294d5d9 183 CallChain(const CallChain&);
Simon Cooksey 0:fb7af294d5d9 184 CallChain & operator = (const CallChain&);
Simon Cooksey 0:fb7af294d5d9 185 CallChainLink *_chain;
Simon Cooksey 0:fb7af294d5d9 186 };
Simon Cooksey 0:fb7af294d5d9 187
Simon Cooksey 0:fb7af294d5d9 188 } // namespace mbed
Simon Cooksey 0:fb7af294d5d9 189
Simon Cooksey 0:fb7af294d5d9 190 #endif
Simon Cooksey 0:fb7af294d5d9 191
Simon Cooksey 0:fb7af294d5d9 192 /** @}*/