CallChainOfFunctionPointersWithContext.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_OF_FUNCTION_POINTERS_WITH_CONTEXT_H
00017 #define MBED_CALLCHAIN_OF_FUNCTION_POINTERS_WITH_CONTEXT_H
00018 
00019 #include <string.h>
00020 #include "FunctionPointerWithContext.h"
00021 
00022 
00023 /** Group one or more functions in an instance of a CallChainOfFunctionPointersWithContext, then call them in
00024  * sequence using CallChainOfFunctionPointersWithContext::call(). Used mostly by the interrupt chaining code,
00025  * but can be used for other purposes.
00026  *
00027  * Example:
00028  * @code
00029  *
00030  * CallChainOfFunctionPointersWithContext<void *> chain;
00031  *
00032  * void first(void *context) {
00033  *     printf("'first' function.\n");
00034  * }
00035  *
00036  * void second(void *context) {
00037  *     printf("'second' function.\n");
00038  * }
00039  *
00040  * class Test {
00041  * public:
00042  *     void f(void *context) {
00043  *         printf("A::f (class member).\n");
00044  *     }
00045  * };
00046  *
00047  * int main() {
00048  *     Test test;
00049  *
00050  *     chain.add(second);
00051  *     chain.add_front(first);
00052  *     chain.add(&test, &Test::f);
00053  *     chain.call();
00054  * }
00055  * @endcode
00056  */
00057 
00058 template <typename ContextType>
00059 class CallChainOfFunctionPointersWithContext {
00060 public:
00061     typedef FunctionPointerWithContext<ContextType> *pFunctionPointerWithContext_t;
00062 
00063 public:
00064     /** Create an empty chain
00065      *
00066      *  @param size (optional) Initial size of the chain
00067      */
00068     CallChainOfFunctionPointersWithContext() : chainHead(NULL) {
00069         /* empty */
00070     }
00071 
00072     virtual ~CallChainOfFunctionPointersWithContext() {
00073         clear();
00074     }
00075 
00076     /** Add a function at the front of the chain
00077      *
00078      *  @param function A pointer to a void function
00079      *
00080      *  @returns
00081      *  The function object created for 'function'
00082      */
00083     pFunctionPointerWithContext_t  add(void (*function)(ContextType context)) {
00084         return common_add(new FunctionPointerWithContext<ContextType>(function));
00085     }
00086 
00087     /** Add a function at the front of the chain
00088      *
00089      *  @param tptr pointer to the object to call the member function on
00090      *  @param mptr pointer to the member function to be called
00091      *
00092      *  @returns
00093      *  The function object created for 'tptr' and 'mptr'
00094      */
00095     template<typename T>
00096     pFunctionPointerWithContext_t  add(T *tptr, void (T::*mptr)(ContextType context)) {
00097         return common_add(new FunctionPointerWithContext<ContextType>(tptr, mptr));
00098     }
00099 
00100     /** Clear the call chain (remove all functions in the chain).
00101      */
00102     void clear(void) {
00103         pFunctionPointerWithContext_t  fptr = chainHead;
00104         while (fptr) {
00105             pFunctionPointerWithContext_t  deadPtr = fptr;
00106             fptr = deadPtr->getNext();
00107             delete deadPtr;
00108         }
00109 
00110         chainHead = NULL;
00111     }
00112 
00113     bool hasCallbacksAttached(void) const {
00114         return (chainHead != NULL);
00115     }
00116 
00117     /** Call all the functions in the chain in sequence
00118      * @Note: the stack frames of all the callbacks within the chained
00119      *        FunctionPointers will stack up. Hopefully there won't be too many
00120      *        chained FunctionPointers.
00121      */
00122     void call(ContextType context) {
00123         if (chainHead) {
00124             chainHead->call(context);
00125         }
00126     }
00127 
00128 private:
00129     pFunctionPointerWithContext_t common_add(pFunctionPointerWithContext_t pf) {
00130         if (chainHead == NULL) {
00131             chainHead = pf;
00132         } else {
00133             pf->chainAsNext(chainHead);
00134             chainHead = pf;
00135         }
00136 
00137         return chainHead;
00138     }
00139 
00140 private:
00141     pFunctionPointerWithContext_t chainHead;
00142 
00143     /* disallow copy constructor and assignment operators */
00144 private:
00145     CallChainOfFunctionPointersWithContext(const CallChainOfFunctionPointersWithContext &);
00146     CallChainOfFunctionPointersWithContext & operator = (const CallChainOfFunctionPointersWithContext &);
00147 };
00148 
00149 #endif