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  * @deprecated Do not use this class. This class is not part of the public API of mbed-os and is being removed in the future.
00042  * @note Synchronization level: Not protected
00043  *
00044  * Example:
00045  * @code
00046  * #include "mbed.h"
00047  *
00048  * CallChain chain;
00049  *
00050  * void first(void) {
00051  *     printf("'first' function.\n");
00052  * }
00053  *
00054  * void second(void) {
00055  *     printf("'second' function.\n");
00056  * }
00057  *
00058  * class Test {
00059  * public:
00060  *     void f(void) {
00061  *         printf("A::f (class member).\n");
00062  *     }
00063  * };
00064  *
00065  * int main() {
00066  *     Test test;
00067  *
00068  *     chain.add(second);
00069  *     chain.add_front(first);
00070  *     chain.add(&test, &Test::f);
00071  *     chain.call();
00072  * }
00073  * @endcode
00074  */
00075 class CallChain : private NonCopyable<CallChain> {
00076 public:
00077     /** Create an empty chain
00078      *  @deprecated
00079      *  Do not use this function, this class is not part of the public API of mbed-os and is being removed in the future.
00080      *
00081      *  @param size (optional) Initial size of the chain
00082      */
00083     MBED_DEPRECATED_SINCE("mbed-os-5.6", "This class is not part of the "
00084                           "public API of mbed-os and is being removed in the future.")
00085     CallChain(int size = 4);
00086 
00087     /** Create an empty chain
00088      *  @deprecated
00089      *  Do not use this function, this class is not part of the public API of mbed-os and is being removed in the future.
00090      */
00091     MBED_DEPRECATED_SINCE("mbed-os-5.6", "This class is not part of the "
00092                           "public API of mbed-os and is being removed in the future.")
00093     virtual ~CallChain();
00094 
00095     /** Add a function at the end of the chain
00096      *
00097      *  @deprecated
00098      *  Do not use this function, this class is not part of the public API of mbed-os and is being removed in the future.
00099      *
00100      *  @param func A pointer to a void function
00101      *
00102      *  @returns
00103      *  The function object created for 'func'
00104      */
00105     MBED_DEPRECATED_SINCE("mbed-os-5.6", "This class is not part of the "
00106                           "public API of mbed-os and is being removed in the future.")
00107     pFunctionPointer_t add(Callback<void()> func);
00108 
00109     /** Add a function at the end of the chain
00110      *
00111      *  @param obj pointer to the object to call the member function on
00112      *  @param method pointer to the member function to be called
00113      *
00114      *  @returns
00115      *  The function object created for 'obj' and 'method'
00116      *
00117      *  @deprecated
00118      *  The add function does not support cv-qualifiers. Replaced by
00119      *  add(callback(obj, method)).
00120      */
00121     template<typename T, typename M>
00122     MBED_DEPRECATED_SINCE("mbed-os-5.1",
00123                           "The add function does not support cv-qualifiers. Replaced by "
00124                           "add(callback(obj, method)).")
00125     pFunctionPointer_t add(T *obj, M method)
00126     {
00127         return add(callback(obj, method));
00128     }
00129 
00130     /** Add a function at the beginning of the chain
00131      *  @deprecated
00132      *  Do not use this function, this class is not part of the public API of mbed-os and is being removed in the future.
00133      *
00134      *
00135      *  @param func A pointer to a void function
00136      *
00137      *  @returns
00138      *  The function object created for 'func'
00139      */
00140     MBED_DEPRECATED_SINCE("mbed-os-5.6", "This class is not part of the "
00141                           "public API of mbed-os and is being removed in the future.")
00142     pFunctionPointer_t add_front(Callback<void()> func);
00143 
00144     /** Add a function at the beginning of the chain
00145      *
00146      *  @param obj pointer to the object to call the member function on
00147      *  @param method pointer to the member function to be called
00148      *
00149      *  @returns
00150      *  The function object created for 'tptr' and 'mptr'
00151      *
00152      *  @deprecated
00153      *  The add_front function does not support cv-qualifiers. Replaced by
00154      *  add_front(callback(obj, method)).
00155      */
00156     template<typename T, typename M>
00157     MBED_DEPRECATED_SINCE("mbed-os-5.1",
00158                           "The add_front function does not support cv-qualifiers. Replaced by "
00159                           "add_front(callback(obj, method)).")
00160     pFunctionPointer_t add_front(T *obj, M method)
00161     {
00162         return add_front(callback(obj, method));
00163     }
00164 
00165     /** Get the number of functions in the chain
00166      *  @deprecated
00167      *  Do not use this function, this class is not part of the public API of mbed-os and is being removed in the future.
00168      *
00169      */
00170     MBED_DEPRECATED_SINCE("mbed-os-5.6", "This class is not part of the "
00171                           "public API of mbed-os and is being removed in the future.")
00172     int size() const;
00173 
00174     /** Get a function object from the chain
00175      *  @deprecated
00176      *  Do not use this function, this class is not part of the public API of mbed-os and is being removed in the future.
00177      *
00178      *  @param i function object index
00179      *
00180      *  @returns
00181      *  The function object at position 'i' in the chain
00182      */
00183     MBED_DEPRECATED_SINCE("mbed-os-5.6", "This class is not part of the "
00184                           "public API of mbed-os and is being removed in the future.")
00185     pFunctionPointer_t get(int i) const;
00186 
00187     /** Look for a function object in the call chain
00188      *  @deprecated
00189      *  Do not use this function, this class is not part of the public API of mbed-os and is being removed in the future.
00190      *
00191      *  @param f the function object to search
00192      *
00193      *  @returns
00194      *  The index of the function object if found, -1 otherwise.
00195      */
00196     MBED_DEPRECATED_SINCE("mbed-os-5.6", "This class is not part of the "
00197                           "public API of mbed-os and is being removed in the future.")
00198     int find(pFunctionPointer_t f) const;
00199 
00200     /** Clear the call chain (remove all functions in the chain).
00201      *  @deprecated Do not use this function. This class is not part of the public API of mbed-os and is being removed in the future.
00202      */
00203     MBED_DEPRECATED_SINCE("mbed-os-5.6", "This class is not part of the "
00204                           "public API of mbed-os and is being removed in the future.")
00205     void clear();
00206 
00207     /** Remove a function object from the chain
00208      *  @deprecated
00209      *  Do not use this function, this class is not part of the public API of mbed-os and is being removed in the future.
00210      *
00211      *  @arg f the function object to remove
00212      *
00213      *  @returns
00214      *  true if the function object was found and removed, false otherwise.
00215      */
00216     MBED_DEPRECATED_SINCE("mbed-os-5.6", "This class is not part of the "
00217                           "public API of mbed-os and is being removed in the future.")
00218     bool remove(pFunctionPointer_t f);
00219 
00220     /** Call all the functions in the chain in sequence
00221      *  @deprecated
00222      *  Do not use this function, this class is not part of the public API of mbed-os and is being removed in the future.
00223      *
00224      */
00225     MBED_DEPRECATED_SINCE("mbed-os-5.6", "This class is not part of the "
00226                           "public API of mbed-os and is being removed in the future.")
00227     void call();
00228 
00229     /**
00230      *  @deprecated
00231      *  Do not use this function, this class is not part of the public API of mbed-os and is being removed in the future.
00232      *
00233      */
00234     MBED_DEPRECATED_SINCE("mbed-os-5.6", "This class is not part of the "
00235                           "public API of mbed-os and is being removed in the future.")
00236     void operator()(void)
00237     {
00238         call();
00239     }
00240 
00241     /**
00242      *  @deprecated
00243      *  Do not use this function, this class is not part of the public API of mbed-os and is being removed in the future.
00244      *
00245      */
00246     MBED_DEPRECATED_SINCE("mbed-os-5.6", "This class is not part of the "
00247                           "public API of mbed-os and is being removed in the future.")
00248     pFunctionPointer_t operator [](int i) const
00249     {
00250         return get(i);
00251     }
00252 
00253 private:
00254     CallChainLink *_chain;
00255 };
00256 
00257 /**@}*/
00258 
00259 /**@}*/
00260 
00261 } // namespace mbed
00262 
00263 #endif
00264