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