CallChain.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2006-2013 ARM Limited
00003  *
00004  * Licensed under the Apache License, Version 2.0 (the "License");
00005  * you may not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 #ifndef MBED_CALLCHAIN_H
00017 #define MBED_CALLCHAIN_H
00018 
00019 #include "Callback.h"
00020 #include "toolchain.h"
00021 #include <string.h>
00022 
00023 namespace mbed {
00024 
00025 /** Group one or more functions in an instance of a CallChain, then call them in
00026  * sequence using CallChain::call(). Used mostly by the interrupt chaining code,
00027  * but can be used for other purposes.
00028  *
00029  * @Note Synchronization level: Not protected
00030  *
00031  * Example:
00032  * @code
00033  * #include "mbed.h"
00034  *
00035  * CallChain chain;
00036  *
00037  * void first(void) {
00038  *     printf("'first' function.\n");
00039  * }
00040  *
00041  * void second(void) {
00042  *     printf("'second' function.\n");
00043  * }
00044  *
00045  * class Test {
00046  * public:
00047  *     void f(void) {
00048  *         printf("A::f (class member).\n");
00049  *     }
00050  * };
00051  *
00052  * int main() {
00053  *     Test test;
00054  *
00055  *     chain.add(second);
00056  *     chain.add_front(first);
00057  *     chain.add(&test, &Test::f);
00058  *     chain.call();
00059  * }
00060  * @endcode
00061  */
00062 
00063 typedef Callback<void()> *pFunctionPointer_t;
00064 class CallChainLink;
00065 
00066 class CallChain {
00067 public:
00068     /** Create an empty chain
00069      *
00070      *  @param size (optional) Initial size of the chain
00071      */
00072     CallChain(int size = 4);
00073     virtual ~CallChain();
00074 
00075     /** Add a function at the end of the chain
00076      *
00077      *  @param func A pointer to a void function
00078      *
00079      *  @returns
00080      *  The function object created for 'func'
00081      */
00082     pFunctionPointer_t add(Callback<void()> func);
00083 
00084     /** Add a function at the end of the chain
00085      *
00086      *  @param obj pointer to the object to call the member function on
00087      *  @param method pointer to the member function to be called
00088      *
00089      *  @returns
00090      *  The function object created for 'obj' and 'method'
00091      *
00092      *  @deprecated
00093      *  The add function does not support cv-qualifiers. Replaced by
00094      *  add(callback(obj, method)).
00095      */
00096     template<typename T, typename M>
00097     MBED_DEPRECATED_SINCE("mbed-os-5.1",
00098         "The add function does not support cv-qualifiers. Replaced by "
00099         "add(callback(obj, method)).")
00100     pFunctionPointer_t add(T *obj, M method) {
00101         return add(callback(obj, method));
00102     }
00103 
00104     /** Add a function at the beginning of the chain
00105      *
00106      *  @param func A pointer to a void function
00107      *
00108      *  @returns
00109      *  The function object created for 'func'
00110      */
00111     pFunctionPointer_t add_front(Callback<void()> func);
00112 
00113     /** Add a function at the beginning of the chain
00114      *
00115      *  @param tptr pointer to the object to call the member function on
00116      *  @param mptr pointer to the member function to be called
00117      *
00118      *  @returns
00119      *  The function object created for 'tptr' and 'mptr'
00120      *
00121      *  @deprecated
00122      *  The add_front function does not support cv-qualifiers. Replaced by
00123      *  add_front(callback(obj, method)).
00124      */
00125     template<typename T, typename M>
00126     MBED_DEPRECATED_SINCE("mbed-os-5.1",
00127         "The add_front function does not support cv-qualifiers. Replaced by "
00128         "add_front(callback(obj, method)).")
00129     pFunctionPointer_t add_front(T *obj, M method) {
00130         return add_front(callback(obj, method));
00131     }
00132 
00133     /** Get the number of functions in the chain
00134      */
00135     int size() const;
00136 
00137     /** Get a function object from the chain
00138      *
00139      *  @param i function object index
00140      *
00141      *  @returns
00142      *  The function object at position 'i' in the chain
00143      */
00144     pFunctionPointer_t get(int i) const;
00145 
00146     /** Look for a function object in the call chain
00147      *
00148      *  @param f the function object to search
00149      *
00150      *  @returns
00151      *  The index of the function object if found, -1 otherwise.
00152      */
00153     int find(pFunctionPointer_t f) const;
00154 
00155     /** Clear the call chain (remove all functions in the chain).
00156      */
00157     void clear();
00158 
00159     /** Remove a function object from the chain
00160      *
00161      *  @arg f the function object to remove
00162      *
00163      *  @returns
00164      *  true if the function object was found and removed, false otherwise.
00165      */
00166     bool remove(pFunctionPointer_t f);
00167 
00168     /** Call all the functions in the chain in sequence
00169      */
00170     void call();
00171 
00172     void operator ()(void) {
00173         call();
00174     }
00175     pFunctionPointer_t operator [](int i) const {
00176         return get(i);
00177     }
00178 
00179     /* disallow copy constructor and assignment operators */
00180 private:
00181     CallChain(const CallChain&);
00182     CallChain & operator = (const CallChain&);
00183     CallChainLink *_chain;
00184 };
00185 
00186 } // namespace mbed
00187 
00188 #endif