RtosTimer.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2006-2019 ARM Limited
00003  *
00004  * Permission is hereby granted, free of charge, to any person obtaining a copy
00005  * of this software and associated documentation files (the "Software"), to deal
00006  * in the Software without restriction, including without limitation the rights
00007  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
00008  * copies of the Software, and to permit persons to whom the Software is
00009  * furnished to do so, subject to the following conditions:
00010  *
00011  * The above copyright notice and this permission notice shall be included in
00012  * all copies or substantial portions of the Software.
00013  *
00014  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
00015  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
00016  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
00017  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
00018  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
00019  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
00020  * SOFTWARE.
00021  */
00022 #ifndef RTOS_TIMER_H
00023 #define RTOS_TIMER_H
00024 
00025 #include <stdint.h>
00026 #include "rtos/mbed_rtos_types.h"
00027 #include "rtos/mbed_rtos_storage.h"
00028 #include "platform/Callback.h"
00029 #include "platform/NonCopyable.h"
00030 #include "platform/mbed_toolchain.h"
00031 #include "rtos/mbed_rtos1_types.h"
00032 
00033 #if MBED_CONF_RTOS_PRESENT || defined(DOXYGEN_ONLY)
00034 
00035 namespace rtos {
00036 /** \addtogroup rtos-public-api */
00037 /** @{*/
00038 
00039 /**
00040  * \defgroup rtos_RtosTimer RtosTimer class
00041  * @{
00042  */
00043 
00044 /** The RtosTimer class allow creating and and controlling of timer functions in the system.
00045  A timer function is called when a time period expires whereby both on-shot and
00046  periodic timers are possible. A timer can be started, restarted, or stopped.
00047 
00048  Timers are handled in the thread osTimerThread.
00049  Callback functions run under control of this thread and may use CMSIS-RTOS API calls.
00050 
00051  @deprecated
00052  The RtosTimer has been superseded by the EventQueue. The RtosTimer and EventQueue duplicate
00053  the functionality of timing events outside of interrupt context, however the EventQueue
00054  has additional features to handle deferring other events to multiple contexts.
00055 
00056  For an example, the following code shows a simple use of the RtosTimer:
00057  @code
00058  DigitalOut led(LED1);
00059  void blink() {
00060      led = !led;
00061  }
00062 
00063  RtosTimer timer(&blink);
00064  int main() {
00065      timer.start(1000); // call blink every 1s
00066      ThisThread::sleep_for(5000);
00067      timer.stop(); // stop after 5s
00068  }
00069  @endcode
00070 
00071  This is the above example rewritten to use the EventQueue:
00072  @code
00073  DigitalOut led(LED1);
00074  void blink() {
00075      led = !led;
00076  }
00077 
00078  EventQueue queue(4*EVENTS_EVENT_SIZE);
00079  int main() {
00080     int blink_id = queue.call_every(1000, &blink); // call blink every 1s
00081     queue.dispatch(5000);
00082     queue.cancel(blink_id); // stop after 5s
00083  }
00084  @endcode
00085 
00086  @note
00087  Memory considerations: The timer control structures will be created on current thread's stack, both for the mbed OS
00088  and underlying RTOS objects (static or dynamic RTOS memory pools are not being used).
00089 */
00090 class RtosTimer : private mbed::NonCopyable<RtosTimer> {
00091 public:
00092     /** Create timer.
00093       @param   func      function to be executed by this timer.
00094       @param   type      osTimerOnce for one-shot or osTimerPeriodic for periodic behavior. (default: osTimerPeriodic)
00095       @param   argument  argument to the timer call back function. (default: nullptr)
00096       @deprecated Replaced with RtosTimer(Callback<void()>, os_timer_type)
00097       @deprecated
00098           The RtosTimer has been superseded by the EventQueue. See RtosTimer.h for more details
00099 
00100       @note You cannot call this function from ISR context.
00101      */
00102     MBED_DEPRECATED_SINCE("mbed-os-5.1",
00103                           "Replaced with RtosTimer(Callback<void()>, os_timer_type)")
00104     MBED_DEPRECATED_SINCE("mbed-os-5.2",
00105                           "The RtosTimer has been superseded by the EventQueue. See RtosTimer.h for more details")
00106     RtosTimer(void (*func)(void const *argument), os_timer_type type = osTimerPeriodic, void *argument = nullptr)
00107     {
00108         constructor(mbed::callback((void (*)(void *))func, argument), type);
00109     }
00110 
00111     /** Create timer.
00112       @param   func      function to be executed by this timer.
00113       @param   type      osTimerOnce for one-shot or osTimerPeriodic for periodic behavior. (default: osTimerPeriodic)
00114       @deprecated
00115           The RtosTimer has been superseded by the EventQueue. See RtosTimer.h for more details
00116 
00117       @note You cannot call this function from ISR context.
00118     */
00119     MBED_DEPRECATED_SINCE("mbed-os-5.2",
00120                           "The RtosTimer has been superseded by the EventQueue. See RtosTimer.h for more details")
00121     RtosTimer(mbed::Callback<void()> func, os_timer_type type = osTimerPeriodic)
00122     {
00123         constructor(func, type);
00124     }
00125 
00126     /** Create timer.
00127       @param   obj       pointer to the object to call the member function on.
00128       @param   method    member function to be executed by this timer.
00129       @param   type      osTimerOnce for one-shot or osTimerPeriodic for periodic behavior. (default: osTimerPeriodic)
00130       @deprecated
00131           The RtosTimer constructor does not support cv-qualifiers. Replaced by
00132           RtosTimer(callback(obj, method), os_timer_type).
00133       @deprecated
00134           The RtosTimer has been superseded by the EventQueue. See RtosTimer.h for more details
00135 
00136       @note You cannot call this function from ISR context.
00137     */
00138     template <typename T, typename M>
00139     MBED_DEPRECATED_SINCE("mbed-os-5.1",
00140                           "The RtosTimer constructor does not support cv-qualifiers. Replaced by "
00141                           "RtosTimer(callback(obj, method), os_timer_type).")
00142     MBED_DEPRECATED_SINCE("mbed-os-5.2",
00143                           "The RtosTimer has been superseded by the EventQueue. See RtosTimer.h for more details")
00144     RtosTimer(T *obj, M method, os_timer_type type = osTimerPeriodic)
00145     {
00146         constructor(mbed::callback(obj, method), type);
00147     }
00148 
00149     /** Stop the timer.
00150       @return  status code that indicates the execution status of the function:
00151           @a osOK the timer has been stopped.
00152           @a osErrorISR @a stop cannot be called from interrupt service routines.
00153           @a osErrorParameter internal error.
00154           @a osErrorResource the timer is not running.
00155 
00156       @note You cannot call this function from ISR context.
00157     */
00158     osStatus stop(void);
00159 
00160     /** Start or restart the timer.
00161       @param   millisec  non-zero value of the timer.
00162       @return  status code that indicates the execution status of the function:
00163           @a osOK the timer has been started or restarted.
00164           @a osErrorISR @a start cannot be called from interrupt service routines.
00165           @a osErrorParameter internal error or incorrect parameter value.
00166           @a osErrorResource internal error (the timer is in an invalid timer state).
00167 
00168       @note You cannot call this function from ISR context.
00169     */
00170     osStatus start(uint32_t millisec);
00171 
00172     /** RtosTimer destructor
00173      *
00174      * @note You cannot call this function from ISR context.
00175      */
00176     ~RtosTimer();
00177 
00178 private:
00179     // Required to share definitions without
00180     // delegated constructors
00181     void constructor(mbed::Callback<void()> func, os_timer_type type);
00182 
00183     osTimerId_t _id;
00184     mbed_rtos_storage_timer_t _obj_mem;
00185     mbed::Callback<void()> _function;
00186 };
00187 /** @}*/
00188 /** @}*/
00189 
00190 }
00191 
00192 #endif
00193 
00194 #endif