Lee Kai Xuan / mbed-os

mbed-os

Fork of mbed-os by erkin yucel

platform/CallChain.h@0:f269e3021894, 2016-10-23 (annotated)

Committer:
elessair
Date:
Sun Oct 23 15:10:02 2016 +0000
Revision:
0:f269e3021894
Initial commit

Who changed what in which revision?

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