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         return add(callback(obj, method));
00127     }
00128 
00129     /** Add a function at the beginning of the chain
00130      *  @deprecated 
00131      *  Do not use this function, this class is not part of the public API of mbed-os and is being removed in the future.
00132      *
00133      *
00134      *  @param func A pointer to a void function
00135      *
00136      *  @returns
00137      *  The function object created for 'func'
00138      */
00139     MBED_DEPRECATED_SINCE("mbed-os-5.6", "This class is not part of the "
00140         "public API of mbed-os and is being removed in the future.")
00141     pFunctionPointer_t add_front(Callback<void()> func);
00142 
00143     /** Add a function at the beginning of the chain
00144      *
00145      *  @param obj pointer to the object to call the member function on
00146      *  @param method pointer to the member function to be called
00147      *
00148      *  @returns
00149      *  The function object created for 'tptr' and 'mptr'
00150      *
00151      *  @deprecated
00152      *  The add_front function does not support cv-qualifiers. Replaced by
00153      *  add_front(callback(obj, method)).
00154      */
00155     template<typename T, typename M>
00156     MBED_DEPRECATED_SINCE("mbed-os-5.1",
00157         "The add_front function does not support cv-qualifiers. Replaced by "
00158         "add_front(callback(obj, method)).")
00159     pFunctionPointer_t add_front(T *obj, M method) {
00160         return add_front(callback(obj, method));
00161     }
00162 
00163     /** Get the number of functions in the chain
00164      *  @deprecated 
00165      *  Do not use this function, this class is not part of the public API of mbed-os and is being removed in the future.
00166      *
00167      */
00168     MBED_DEPRECATED_SINCE("mbed-os-5.6", "This class is not part of the "
00169         "public API of mbed-os and is being removed in the future.")
00170     int size() const;
00171 
00172     /** Get a function object from the chain
00173      *  @deprecated 
00174      *  Do not use this function, this class is not part of the public API of mbed-os and is being removed in the future.
00175      *
00176      *  @param i function object index
00177      *
00178      *  @returns
00179      *  The function object at position 'i' in the chain
00180      */
00181     MBED_DEPRECATED_SINCE("mbed-os-5.6", "This class is not part of the "
00182         "public API of mbed-os and is being removed in the future.")
00183     pFunctionPointer_t get(int i) const;
00184 
00185     /** Look for a function object in the call chain
00186      *  @deprecated 
00187      *  Do not use this function, this class is not part of the public API of mbed-os and is being removed in the future.
00188      *
00189      *  @param f the function object to search
00190      *
00191      *  @returns
00192      *  The index of the function object if found, -1 otherwise.
00193      */
00194     MBED_DEPRECATED_SINCE("mbed-os-5.6", "This class is not part of the "
00195         "public API of mbed-os and is being removed in the future.")
00196     int find(pFunctionPointer_t f) const;
00197 
00198     /** Clear the call chain (remove all functions in the chain).
00199      *  @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.
00200      */
00201     MBED_DEPRECATED_SINCE("mbed-os-5.6", "This class is not part of the "
00202         "public API of mbed-os and is being removed in the future.")
00203     void clear();
00204 
00205     /** Remove a function object from the chain
00206      *  @deprecated 
00207      *  Do not use this function, this class is not part of the public API of mbed-os and is being removed in the future.
00208      *
00209      *  @arg f the function object to remove
00210      *
00211      *  @returns
00212      *  true if the function object was found and removed, false otherwise.
00213      */
00214     MBED_DEPRECATED_SINCE("mbed-os-5.6", "This class is not part of the "
00215         "public API of mbed-os and is being removed in the future.")
00216     bool remove(pFunctionPointer_t f);
00217 
00218     /** Call all the functions in the chain in sequence
00219      *  @deprecated 
00220      *  Do not use this function, this class is not part of the public API of mbed-os and is being removed in the future.
00221      *
00222      */
00223     MBED_DEPRECATED_SINCE("mbed-os-5.6", "This class is not part of the "
00224         "public API of mbed-os and is being removed in the future.")
00225     void call();
00226 
00227     /** 
00228      *  @deprecated 
00229      *  Do not use this function, this class is not part of the public API of mbed-os and is being removed in the future.
00230      *
00231      */
00232     MBED_DEPRECATED_SINCE("mbed-os-5.6", "This class is not part of the "
00233         "public API of mbed-os and is being removed in the future.")
00234     void operator ()(void) {
00235         call();
00236     }
00237 
00238     /** 
00239      *  @deprecated 
00240      *  Do not use this function, this class is not part of the public API of mbed-os and is being removed in the future.
00241      *
00242      */
00243     MBED_DEPRECATED_SINCE("mbed-os-5.6", "This class is not part of the "
00244         "public API of mbed-os and is being removed in the future.")
00245     pFunctionPointer_t operator [](int i) const {
00246         return get(i);
00247     }
00248 
00249 private:
00250     CallChainLink *_chain;
00251 };
00252 
00253 /**@}*/
00254 
00255 /**@}*/
00256 
00257 } // namespace mbed
00258 
00259 #endif
00260