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 "platform/NonCopyable.h"
00022 #include <string.h>
00023 
00024 namespace mbed {
00025 /** \addtogroup platform */
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  * @ingroup platform
00064  */
00065 
00066 typedef Callback<void()> *pFunctionPointer_t;
00067 class CallChainLink;
00068 
00069 class CallChain : private NonCopyable<CallChain> {
00070 public:
00071     /** Create an empty chain
00072      *
00073      *  @param size (optional) Initial size of the chain
00074      */
00075     CallChain(int size = 4);
00076     virtual ~CallChain();
00077 
00078     /** Add a function at the end of the chain
00079      *
00080      *  @param func A pointer to a void function
00081      *
00082      *  @returns
00083      *  The function object created for 'func'
00084      */
00085     pFunctionPointer_t add(Callback<void()> func);
00086 
00087     /** Add a function at the end of the chain
00088      *
00089      *  @param obj pointer to the object to call the member function on
00090      *  @param method pointer to the member function to be called
00091      *
00092      *  @returns
00093      *  The function object created for 'obj' and 'method'
00094      *
00095      *  @deprecated
00096      *  The add function does not support cv-qualifiers. Replaced by
00097      *  add(callback(obj, method)).
00098      */
00099     template<typename T, typename M>
00100     MBED_DEPRECATED_SINCE("mbed-os-5.1",
00101         "The add function does not support cv-qualifiers. Replaced by "
00102         "add(callback(obj, method)).")
00103     pFunctionPointer_t add(T *obj, M method) {
00104         return add(callback(obj, method));
00105     }
00106 
00107     /** Add a function at the beginning of the chain
00108      *
00109      *  @param func A pointer to a void function
00110      *
00111      *  @returns
00112      *  The function object created for 'func'
00113      */
00114     pFunctionPointer_t add_front(Callback<void()> func);
00115 
00116     /** Add a function at the beginning of the chain
00117      *
00118      *  @param obj pointer to the object to call the member function on
00119      *  @param method pointer to the member function to be called
00120      *
00121      *  @returns
00122      *  The function object created for 'tptr' and 'mptr'
00123      *
00124      *  @deprecated
00125      *  The add_front function does not support cv-qualifiers. Replaced by
00126      *  add_front(callback(obj, method)).
00127      */
00128     template<typename T, typename M>
00129     MBED_DEPRECATED_SINCE("mbed-os-5.1",
00130         "The add_front function does not support cv-qualifiers. Replaced by "
00131         "add_front(callback(obj, method)).")
00132     pFunctionPointer_t add_front(T *obj, M method) {
00133         return add_front(callback(obj, method));
00134     }
00135 
00136     /** Get the number of functions in the chain
00137      */
00138     int size() const;
00139 
00140     /** Get a function object from the chain
00141      *
00142      *  @param i function object index
00143      *
00144      *  @returns
00145      *  The function object at position 'i' in the chain
00146      */
00147     pFunctionPointer_t get(int i) const;
00148 
00149     /** Look for a function object in the call chain
00150      *
00151      *  @param f the function object to search
00152      *
00153      *  @returns
00154      *  The index of the function object if found, -1 otherwise.
00155      */
00156     int find(pFunctionPointer_t f) const;
00157 
00158     /** Clear the call chain (remove all functions in the chain).
00159      */
00160     void clear();
00161 
00162     /** Remove a function object from the chain
00163      *
00164      *  @arg f the function object to remove
00165      *
00166      *  @returns
00167      *  true if the function object was found and removed, false otherwise.
00168      */
00169     bool remove(pFunctionPointer_t f);
00170 
00171     /** Call all the functions in the chain in sequence
00172      */
00173     void call();
00174 
00175     void operator ()(void) {
00176         call();
00177     }
00178     pFunctionPointer_t operator [](int i) const {
00179         return get(i);
00180     }
00181 
00182 private:
00183     CallChainLink *_chain;
00184 };
00185 
00186 } // namespace mbed
00187 
00188 #endif
00189