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 "platform/Callback.h"
00020 #include "platform/mbed_toolchain.h"
00021 #include <string.h>
00022 
00023 namespace mbed {
00024 /** \addtogroup platform */
00025 /** @{*/
00026 
00027 /** Group one or more functions in an instance of a CallChain, then call them in
00028  * sequence using CallChain::call(). Used mostly by the interrupt chaining code,
00029  * but can be used for other purposes.
00030  *
00031  * @Note Synchronization level: Not protected
00032  *
00033  * Example:
00034  * @code
00035  * #include "mbed.h"
00036  *
00037  * CallChain chain;
00038  *
00039  * void first(void) {
00040  *     printf("'first' function.\n");
00041  * }
00042  *
00043  * void second(void) {
00044  *     printf("'second' function.\n");
00045  * }
00046  *
00047  * class Test {
00048  * public:
00049  *     void f(void) {
00050  *         printf("A::f (class member).\n");
00051  *     }
00052  * };
00053  *
00054  * int main() {
00055  *     Test test;
00056  *
00057  *     chain.add(second);
00058  *     chain.add_front(first);
00059  *     chain.add(&test, &Test::f);
00060  *     chain.call();
00061  * }
00062  * @endcode
00063  */
00064 
00065 typedef Callback<void()> *pFunctionPointer_t;
00066 class CallChainLink;
00067 
00068 class CallChain {
00069 public:
00070     /** Create an empty chain
00071      *
00072      *  @param size (optional) Initial size of the chain
00073      */
00074     CallChain(int size = 4);
00075     virtual ~CallChain();
00076 
00077     /** Add a function at the end of the chain
00078      *
00079      *  @param func A pointer to a void function
00080      *
00081      *  @returns
00082      *  The function object created for 'func'
00083      */
00084     pFunctionPointer_t add(Callback<void()> func);
00085 
00086     /** Add a function at the end of the chain
00087      *
00088      *  @param obj pointer to the object to call the member function on
00089      *  @param method pointer to the member function to be called
00090      *
00091      *  @returns
00092      *  The function object created for 'obj' and 'method'
00093      *
00094      *  @deprecated
00095      *  The add function does not support cv-qualifiers. Replaced by
00096      *  add(callback(obj, method)).
00097      */
00098     template<typename T, typename M>
00099     MBED_DEPRECATED_SINCE("mbed-os-5.1",
00100         "The add function does not support cv-qualifiers. Replaced by "
00101         "add(callback(obj, method)).")
00102     pFunctionPointer_t add(T *obj, M method) {
00103         return add(callback(obj, method));
00104     }
00105 
00106     /** Add a function at the beginning of the chain
00107      *
00108      *  @param func A pointer to a void function
00109      *
00110      *  @returns
00111      *  The function object created for 'func'
00112      */
00113     pFunctionPointer_t add_front(Callback<void()> func);
00114 
00115     /** Add a function at the beginning of the chain
00116      *
00117      *  @param tptr pointer to the object to call the member function on
00118      *  @param mptr pointer to the member function to be called
00119      *
00120      *  @returns
00121      *  The function object created for 'tptr' and 'mptr'
00122      *
00123      *  @deprecated
00124      *  The add_front function does not support cv-qualifiers. Replaced by
00125      *  add_front(callback(obj, method)).
00126      */
00127     template<typename T, typename M>
00128     MBED_DEPRECATED_SINCE("mbed-os-5.1",
00129         "The add_front function does not support cv-qualifiers. Replaced by "
00130         "add_front(callback(obj, method)).")
00131     pFunctionPointer_t add_front(T *obj, M method) {
00132         return add_front(callback(obj, method));
00133     }
00134 
00135     /** Get the number of functions in the chain
00136      */
00137     int size() const;
00138 
00139     /** Get a function object from the chain
00140      *
00141      *  @param i function object index
00142      *
00143      *  @returns
00144      *  The function object at position 'i' in the chain
00145      */
00146     pFunctionPointer_t get(int i) const;
00147 
00148     /** Look for a function object in the call chain
00149      *
00150      *  @param f the function object to search
00151      *
00152      *  @returns
00153      *  The index of the function object if found, -1 otherwise.
00154      */
00155     int find(pFunctionPointer_t f) const;
00156 
00157     /** Clear the call chain (remove all functions in the chain).
00158      */
00159     void clear();
00160 
00161     /** Remove a function object from the chain
00162      *
00163      *  @arg f the function object to remove
00164      *
00165      *  @returns
00166      *  true if the function object was found and removed, false otherwise.
00167      */
00168     bool remove(pFunctionPointer_t f);
00169 
00170     /** Call all the functions in the chain in sequence
00171      */
00172     void call();
00173 
00174     void operator ()(void) {
00175         call();
00176     }
00177     pFunctionPointer_t operator [](int i) const {
00178         return get(i);
00179     }
00180 
00181     /* disallow copy constructor and assignment operators */
00182 private:
00183     CallChain(const CallChain&);
00184     CallChain & operator = (const CallChain&);
00185     CallChainLink *_chain;
00186 };
00187 
00188 } // namespace mbed
00189 
00190 #endif
00191 
00192 /** @}*/