CallChain.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2006-2013 ARM Limited
00003  * SPDX-License-Identifier: Apache-2.0
00004  *
00005  * Licensed under the Apache License, Version 2.0 (the "License");
00006  * you may not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  *     http://www.apache.org/licenses/LICENSE-2.0
00010  *
00011  * Unless required by applicable law or agreed to in writing, software
00012  * distributed under the License is distributed on an "AS IS" BASIS,
00013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00014  * See the License for the specific language governing permissions and
00015  * limitations under the License.
00016  */
00017 #ifndef MBED_CALLCHAIN_H
00018 #define MBED_CALLCHAIN_H
00019 
00020 #include "platform/Callback.h"
00021 #include "platform/mbed_toolchain.h"
00022 #include "platform/NonCopyable.h"
00023 #include <string.h>
00024 
00025 namespace mbed {
00026 
00027 
00028 typedef Callback<void()> *pFunctionPointer_t;
00029 class CallChainLink;
00030 
00031 /** \addtogroup platform */
00032 /** @{*/
00033 /**
00034  * \defgroup platform_CallChain CallChain class
00035  * @{
00036  */
00037 
00038 /** Group one or more functions in an instance of a CallChain, then call them in
00039  * sequence using CallChain::call(). Used mostly by the interrupt chaining code,
00040  * but can be used for other purposes.
00041  *
00042  * @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.
00043  * @note Synchronization level: Not protected
00044  *
00045  * Example:
00046  * @code
00047  * #include "mbed.h"
00048  *
00049  * CallChain chain;
00050  *
00051  * void first(void) {
00052  *     printf("'first' function.\n");
00053  * }
00054  *
00055  * void second(void) {
00056  *     printf("'second' function.\n");
00057  * }
00058  *
00059  * class Test {
00060  * public:
00061  *     void f(void) {
00062  *         printf("A::f (class member).\n");
00063  *     }
00064  * };
00065  *
00066  * int main() {
00067  *     Test test;
00068  *
00069  *     chain.add(second);
00070  *     chain.add_front(first);
00071  *     chain.add(&test, &Test::f);
00072  *     chain.call();
00073  * }
00074  * @endcode
00075  */
00076 class CallChain : private NonCopyable<CallChain> {
00077 public:
00078     /** Create an empty chain
00079      *  @deprecated
00080      *  Do not use this function, this class is not part of the public API of mbed-os and is being removed in the future.
00081      *
00082      *  @param size (optional) Initial size of the chain
00083      */
00084     MBED_DEPRECATED_SINCE("mbed-os-5.6", "This class is not part of the "
00085                           "public API of mbed-os and is being removed in the future.")
00086     CallChain(int size = 4);
00087 
00088     /** Create an empty chain
00089      *  @deprecated
00090      *  Do not use this function, this class is not part of the public API of mbed-os and is being removed in the future.
00091      */
00092     MBED_DEPRECATED_SINCE("mbed-os-5.6", "This class is not part of the "
00093                           "public API of mbed-os and is being removed in the future.")
00094     virtual ~CallChain();
00095 
00096     /** Add a function at the end of the chain
00097      *
00098      *  @deprecated
00099      *  Do not use this function, this class is not part of the public API of mbed-os and is being removed in the future.
00100      *
00101      *  @param func A pointer to a void function
00102      *
00103      *  @returns
00104      *  The function object created for 'func'
00105      */
00106     MBED_DEPRECATED_SINCE("mbed-os-5.6", "This class is not part of the "
00107                           "public API of mbed-os and is being removed in the future.")
00108     pFunctionPointer_t add(Callback<void()> func);
00109 
00110     /** Add a function at the end of the chain
00111      *
00112      *  @param obj pointer to the object to call the member function on
00113      *  @param method pointer to the member function to be called
00114      *
00115      *  @returns
00116      *  The function object created for 'obj' and 'method'
00117      *
00118      *  @deprecated
00119      *  The add function does not support cv-qualifiers. Replaced by
00120      *  add(callback(obj, method)).
00121      */
00122     template<typename T, typename M>
00123     MBED_DEPRECATED_SINCE("mbed-os-5.1",
00124                           "The add function does not support cv-qualifiers. Replaced by "
00125                           "add(callback(obj, method)).")
00126     pFunctionPointer_t add(T *obj, M method)
00127     {
00128         return add(callback(obj, method));
00129     }
00130 
00131     /** Add a function at the beginning of the chain
00132      *  @deprecated
00133      *  Do not use this function, this class is not part of the public API of mbed-os and is being removed in the future.
00134      *
00135      *
00136      *  @param func A pointer to a void function
00137      *
00138      *  @returns
00139      *  The function object created for 'func'
00140      */
00141     MBED_DEPRECATED_SINCE("mbed-os-5.6", "This class is not part of the "
00142                           "public API of mbed-os and is being removed in the future.")
00143     pFunctionPointer_t add_front(Callback<void()> func);
00144 
00145     /** Add a function at the beginning of the chain
00146      *
00147      *  @param obj pointer to the object to call the member function on
00148      *  @param method pointer to the member function to be called
00149      *
00150      *  @returns
00151      *  The function object created for the object and method pointers
00152      *
00153      *  @deprecated
00154      *  The add_front function does not support cv-qualifiers. Replaced by
00155      *  add_front(callback(obj, method)).
00156      */
00157     template<typename T, typename M>
00158     MBED_DEPRECATED_SINCE("mbed-os-5.1",
00159                           "The add_front function does not support cv-qualifiers. Replaced by "
00160                           "add_front(callback(obj, method)).")
00161     pFunctionPointer_t add_front(T *obj, M method)
00162     {
00163         return add_front(callback(obj, method));
00164     }
00165 
00166     /** Get the number of functions in the chain
00167      *  @deprecated
00168      *  Do not use this function, this class is not part of the public API of mbed-os and is being removed in the future.
00169      *
00170      */
00171     MBED_DEPRECATED_SINCE("mbed-os-5.6", "This class is not part of the "
00172                           "public API of mbed-os and is being removed in the future.")
00173     int size() const;
00174 
00175     /** Get a function object from the chain
00176      *  @deprecated
00177      *  Do not use this function, this class is not part of the public API of mbed-os and is being removed in the future.
00178      *
00179      *  @param i function object index
00180      *
00181      *  @returns
00182      *  The function object at position 'i' in the chain
00183      */
00184     MBED_DEPRECATED_SINCE("mbed-os-5.6", "This class is not part of the "
00185                           "public API of mbed-os and is being removed in the future.")
00186     pFunctionPointer_t get(int i) const;
00187 
00188     /** Look for a function object in the call chain
00189      *  @deprecated
00190      *  Do not use this function, this class is not part of the public API of mbed-os and is being removed in the future.
00191      *
00192      *  @param f the function object to search
00193      *
00194      *  @returns
00195      *  The index of the function object if found, -1 otherwise.
00196      */
00197     MBED_DEPRECATED_SINCE("mbed-os-5.6", "This class is not part of the "
00198                           "public API of mbed-os and is being removed in the future.")
00199     int find(pFunctionPointer_t f) const;
00200 
00201     /** Clear the call chain (remove all functions in the chain).
00202      *  @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.
00203      */
00204     MBED_DEPRECATED_SINCE("mbed-os-5.6", "This class is not part of the "
00205                           "public API of mbed-os and is being removed in the future.")
00206     void clear();
00207 
00208     /** Remove a function object from the chain
00209      *  @deprecated
00210      *  Do not use this function, this class is not part of the public API of mbed-os and is being removed in the future.
00211      *
00212      *  @arg f the function object to remove
00213      *
00214      *  @returns
00215      *  true if the function object was found and removed, false otherwise.
00216      */
00217     MBED_DEPRECATED_SINCE("mbed-os-5.6", "This class is not part of the "
00218                           "public API of mbed-os and is being removed in the future.")
00219     bool remove(pFunctionPointer_t f);
00220 
00221     /** Call all the functions in the chain in sequence
00222      *  @deprecated
00223      *  Do not use this function, this class is not part of the public API of mbed-os and is being removed in the future.
00224      *
00225      */
00226     MBED_DEPRECATED_SINCE("mbed-os-5.6", "This class is not part of the "
00227                           "public API of mbed-os and is being removed in the future.")
00228     void call();
00229 
00230     /**
00231      *  @deprecated
00232      *  Do not use this function, this class is not part of the public API of mbed-os and is being removed in the future.
00233      *
00234      */
00235     MBED_DEPRECATED_SINCE("mbed-os-5.6", "This class is not part of the "
00236                           "public API of mbed-os and is being removed in the future.")
00237     void operator()(void)
00238     {
00239         call();
00240     }
00241 
00242     /**
00243      *  @deprecated
00244      *  Do not use this function, this class is not part of the public API of mbed-os and is being removed in the future.
00245      *
00246      */
00247     MBED_DEPRECATED_SINCE("mbed-os-5.6", "This class is not part of the "
00248                           "public API of mbed-os and is being removed in the future.")
00249     pFunctionPointer_t operator [](int i) const
00250     {
00251         return get(i);
00252     }
00253 
00254 private:
00255     CallChainLink *_chain;
00256 };
00257 
00258 /**@}*/
00259 
00260 /**@}*/
00261 
00262 } // namespace mbed
00263 
00264 #endif
00265