CallChain.h

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