le_timer.h

    1 /**
    2  * @page c_timer Timer API
    3  *
    4  * @subpage le_timer.h "API Reference"
    5  *
    6  * <HR>
    7  *
    8  * This module provides an API for managing and using timers.
    9  *
   10  * @note
   11  * This is an initial version of the API that only provides support for relative timers (e.g., expires
   12  * in 10 seconds).  Absolute timers allow a specific time/date to be used, and will be supported in a
   13  * future version of this API.
   14  *
   15  *
   16  * @section timer_objects Creating/Deleting Timer Objects
   17  *
   18  * Timers are created using le_timer_Create(). The timer name is used for diagnostic purposes only.
   19  *
   20  * The following attributes of the timer can be set:
   21  *  - le_timer_SetHandler()
   22  *  - le_timer_SetInterval() (or le_timer_SetMsInterval())
   23  *  - le_timer_SetRepeat()
   24  *  - le_timer_SetContextPtr()
   25  *
   26  * The following attributes of the timer can be retrieved:
   27  *  - le_timer_GetInterval() (or le_timer_GetMsInterval())
   28  *  - le_timer_GetContextPtr()
   29  *
   30  * The repeat count defaults to 1, so that the timer is initially a one-shot timer. All the other
   31  * attributes must be explicitly set.  At a minimum, the interval must be set before the timer can be
   32  * used.  Note that these attributes can only be set if the timer is not currently running; otherwise,
   33  * an error will be returned.
   34  *
   35  * Timers must be explicitly deleted using le_timer_Delete(). If the timer is currently running,
   36  * it'll be stopped before being deleted. If a timer uses le_timer_SetContextPtr(), and the
   37  * context pointer is allocated memory, then the context pointer must be freed when deleting the timer.
   38  * The following function can be used for this:
   39  * @code
   40  * static void DeleteTimerAndFreePtr(le_timer_Ref_t t)
   41  * {
   42  *     le_timer_Stop( t );
   43  *     free( le_timer_GetContextPtr( t ) );
   44  *     le_timer_Delete( t );  // timer ref is now invalid
   45  * }
   46  * @endcode
   47  * You can call this function anywhere, including in the timer handler.
   48  *
   49  * @section timer_usage Using Timers
   50  *
   51  * A timer is started using le_timer_Start(). If it's already running, then it won't be
   52  * modified; instead an error will be returned. To restart a currently running timer, use
   53  * le_timer_Restart().
   54  *
   55  * A timer is stopped using le_timer_Stop().  If it's not currently running, an error
   56  * will be returned, and nothing more will be done.
   57  *
   58  * To determine if the timer is currently running, use le_timer_IsRunning().
   59  *
   60  * To find out how much time is remaining before the next expiry, call either
   61  * le_timer_GetTimeRemaining() or le_timer_GetMsTimeRemaining().
   62  *
   63  * When a timer expires, if the timer expiry handler is set by le_timer_SetHandler(), the
   64  * handler will be called with a reference to the expired timer. If additional data is required in the
   65  * handler, le_timer_SetContextPtr() can be used to set the appropriate context before starting the
   66  * timer, and le_timer_GetContextPtr() can be used to retrieve the context while in the handler.
   67  * In addition, a suspended system will also wake up by default if the timer expires. If this behaviour
   68  * is not desired, user can disable the wake up by passing false into le_timer_SetWakeup().
   69  *
   70  * The number of times that a timer has expired can be retrieved by le_timer_GetExpiryCount(). This
   71  * count is independent of whether there is an expiry handler for the timer.
   72  *
   73  * @section le_timer_thread Thread Support
   74  *
   75  * A timer should only be used by the thread that created it. It's not safe for a thread to use
   76  * or manipulate a timer that belongs to another thread. The timer expiry handler is called by the
   77  * event loop of the thread that starts the timer.
   78  *
   79  * The call to the timer expiry handler may not occur immediately after the timer expires, depending
   80  * on which other functions are called from the event loop. The amount of delay is entirely
   81  * dependent on other work done in the event loop. For a repeating timer, if this delay is longer
   82  * than the timer period, one or more timer expiries may be dropped. To reduce the likelihood of
   83  * dropped expiries, the combined execution time of all handlers called from the event loop should
   84  *  ideally be less than the timer period.
   85  *
   86  * See @ref c_eventLoop for details on running the event loop of a thread.
   87  *
   88  * @section le_timer_suspend Suspend Support
   89  *
   90  * The timer runs even when system is suspended. <br>
   91  * If the timer expires while the system is suspended, it will wake up the system.
   92  *
   93  * @section timer_errors Fatal Errors
   94  *
   95  * The process will exit under any of the following conditions:
   96  *  - If an invalid timer object is given to:
   97  *     - le_timer_Delete()
   98  *     - le_timer_SetHandler()
   99  *     - le_timer_SetInterval()
  100  *     - le_timer_GetInterval()
  101  *     - le_timer_SetMsInterval()
  102  *     - le_timer_GetMsInterval()
  103  *     - le_timer_SetRepeat()
  104  *     - le_timer_Start()
  105  *     - le_timer_Stop()
  106  *     - le_timer_Restart()
  107  *     - le_timer_SetContextPtr()
  108  *     - le_timer_GetContextPtr()
  109  *     - le_timer_GetExpiryCount()
  110  *     - le_timer_GetTimeRemaining()
  111  *     - le_timer_GetMsTimeRemaining()
  112  *     - le_timer_SetWakeup()
  113  *
  114  * @section timer_troubleshooting Troubleshooting
  115  *
  116  * Timers can be traced by enabling the log trace keyword "timers" in the "framework" component.
  117  *
  118  * See @ref c_log_controlling for more information.
  119  *
  120  * <HR>
  121  *
  122  * Copyright (C) Sierra Wireless Inc.
  123  *
  124  */
  125 
  126 //--------------------------------------------------------------------------------------------------
  127 /**
  128  * @file le_timer.h
  129  *
  130  * Legato @ref c_timer include file.
  131  *
  132  * Copyright (C) Sierra Wireless Inc.
  133  *
  134  */
  135 //--------------------------------------------------------------------------------------------------
  136 
  137 #ifndef LEGATO_TIMER_INCLUDE_GUARD
  138 #define LEGATO_TIMER_INCLUDE_GUARD
  139 
  140 
  141 //--------------------------------------------------------------------------------------------------
  142 /**
  143  * Timer object.  Created by le_timer_Create().
  144  */
  145 //--------------------------------------------------------------------------------------------------
  146 typedef struct le_timer* le_timer_Ref_t;
  147 
  148 
  149 //--------------------------------------------------------------------------------------------------
  150 /**
  151  * Prototype for timer expiry handler function.
  152  *
  153  * @param
  154  *      timerRef Timer that has expired
  155  */
  156 //--------------------------------------------------------------------------------------------------
  157 typedef void (*le_timer_ExpiryHandler_t)
  158 (
  159     le_timer_Ref_t timerRef
  160 );
  161 
  162 
  163 #if LE_CONFIG_TIMER_NAMES_ENABLED
  164 //--------------------------------------------------------------------------------------------------
  165 /**
  166  * Create the timer object.
  167  *
  168  *  @param[in]  nameStr Name of the timer.
  169  *
  170  *  @return
  171  *      A reference to the timer object.
  172  */
  173 //--------------------------------------------------------------------------------------------------
  174 le_timer_Ref_t le_timer_Create
  175 (
  176     const char *nameStr
  177 );
  178 #else /* if not LE_CONFIG_TIMER_NAMES_ENABLED */
  179 /// @cond HIDDEN_IN_USER_DOCS
  180 //--------------------------------------------------------------------------------------------------
  181 /**
  182  * Internal function used to implement le_timer_Create().
  183  */
  184 //--------------------------------------------------------------------------------------------------
  185 le_timer_Ref_t _le_timer_Create(void);
  186 /// @endcond
  187 //--------------------------------------------------------------------------------------------------
  188 /**
  189  * Create the timer object.
  190  *
  191  *  @param[in]  nameStr Name of the timer.
  192  *
  193  *  @return
  194  *      A reference to the timer object.
  195  */
  196 //--------------------------------------------------------------------------------------------------
  197 LE_DECLARE_INLINE le_timer_Ref_t le_timer_Create
  198 (
  199     const char *nameStr
  200 )
  201 {
  202     return _le_timer_Create();
  203 }
  204 #endif /* end LE_CONFIG_TIMER_NAMES_ENABLED */
  205 
  206 
  207 //--------------------------------------------------------------------------------------------------
  208 /**
  209  * Delete the timer object.
  210  *
  211  * @note
  212  *      If an invalid timer object is given, the process exits.
  213  */
  214 //--------------------------------------------------------------------------------------------------
  215 void le_timer_Delete
  216 (
  217     le_timer_Ref_t timerRef                 ///< [IN] Delete this timer object
  218 );
  219 
  220 
  221 //--------------------------------------------------------------------------------------------------
  222 /**
  223  * Set the timer expiry handler function.
  224  *
  225  * If the handler is NULL, then the previous handler will be removed.
  226  *
  227  * @return
  228  *      - LE_OK on success
  229  *      - LE_BUSY if the timer is currently running
  230  *
  231  * @note
  232  *      If an invalid timer object is given, the process exits.
  233  */
  234 //--------------------------------------------------------------------------------------------------
  235 le_result_t le_timer_SetHandler
  236 (
  237     le_timer_Ref_t timerRef,                ///< [IN] Set expiry handler for this timer object.
  238     le_timer_ExpiryHandler_t handlerFunc    ///< [IN] Handler function to call on expiry.
  239 );
  240 
  241 
  242 //--------------------------------------------------------------------------------------------------
  243 /**
  244  * Set the timer interval.
  245  *
  246  * Timer will expire after the interval has elapsed since it was last started or restarted.
  247  *
  248  * If the timer is running when the interval is changed and the new interval is shorter than the
  249  * period of time since the timer last (re)started, the timer will expire immediately.
  250  *
  251  * @return
  252  *      - LE_OK on success
  253  *
  254  * @note
  255  *      If an invalid timer object is given, the process exits.
  256  */
  257 //--------------------------------------------------------------------------------------------------
  258 le_result_t le_timer_SetInterval
  259 (
  260     le_timer_Ref_t timerRef,     ///< [IN] Set interval for this timer object.
  261     le_clk_Time_t interval       ///< [IN] Timer interval.
  262 );
  263 
  264 
  265 //--------------------------------------------------------------------------------------------------
  266 /**
  267  * Get the timer interval.
  268  *
  269  * @return
  270  *      The timer interval.  If it hasn't been set yet, {0, 0} will be returned.
  271  *
  272  * @note
  273  *      If an invalid timer object is given, the process exits.
  274  */
  275 //--------------------------------------------------------------------------------------------------
  276 le_clk_Time_t le_timer_GetInterval
  277 (
  278     le_timer_Ref_t timerRef      ///< [IN] Timer object.
  279 );
  280 
  281 
  282 //--------------------------------------------------------------------------------------------------
  283 /**
  284  * Set the timer interval using milliseconds.
  285  *
  286  * Timer will expire after the interval has elapsed since it was last started or restarted.
  287  *
  288  * If the timer is running when the interval is changed and the new interval is shorter than the
  289  * period of time since the timer last (re)started, the timer will expire immediately.
  290  *
  291  * @return
  292  *      - LE_OK on success
  293  *
  294  * @note
  295  *      If an invalid timer object is given, the process exits.
  296  */
  297 //--------------------------------------------------------------------------------------------------
  298 le_result_t le_timer_SetMsInterval
  299 (
  300     le_timer_Ref_t timerRef,     ///< [IN] Set interval for this timer object.
  301     uint32_t interval            ///< [IN] Timer interval in milliseconds.
  302 );
  303 
  304 
  305 //--------------------------------------------------------------------------------------------------
  306 /**
  307  * Get the timer interval in milliseconds.
  308  *
  309  * @return
  310  *      The timer interval (ms).  If it hasn't been set yet, 0 will be returned.
  311  *
  312  * @note
  313  *      If an invalid timer object is given, the process exits.
  314  */
  315 //--------------------------------------------------------------------------------------------------
  316 uint32_t le_timer_GetMsInterval
  317 (
  318     le_timer_Ref_t timerRef      ///< [IN] Timer object.
  319 );
  320 
  321 
  322 //--------------------------------------------------------------------------------------------------
  323 /**
  324  * Set how many times the timer will repeat.
  325  *
  326  * Timer will repeat the given number of times.  A value of 0 means repeat indefinitely.
  327  * The default is 1, so that a one-shot timer is the default.
  328  *
  329  * @return
  330  *      - LE_OK on success
  331  *      - LE_BUSY if the timer is currently running
  332  *
  333  * @note
  334  *      If an invalid timer object is given, the process exits.
  335  */
  336 //--------------------------------------------------------------------------------------------------
  337 le_result_t le_timer_SetRepeat
  338 (
  339     le_timer_Ref_t timerRef,     ///< [IN] Set repeat count for this timer object
  340     uint32_t repeatCount         ///< [IN] Number of times the timer will repeat (0 = forever).
  341 );
  342 
  343 
  344 //--------------------------------------------------------------------------------------------------
  345 /**
  346  * Configure if timer expiry will wake up a suspended system.
  347  *
  348  * @return
  349  *      - LE_OK on success
  350  *      - LE_BUSY if the timer is currently running
  351  *
  352  * @note
  353  *      The default timer expiry behaviour will wake up the system.
  354  *      If an invalid timer object is given, the process exits.
  355  */
  356 //--------------------------------------------------------------------------------------------------
  357 le_result_t le_timer_SetWakeup
  358 (
  359     le_timer_Ref_t timerRef,     ///< [IN] Disable system wake up for this timer object
  360     bool wakeupEnabled           ///< [IN] Flag to determine timer will wakeup or not
  361 );
  362 
  363 
  364 //--------------------------------------------------------------------------------------------------
  365 /**
  366  * Set context pointer for the timer.
  367  *
  368  * This can be used to pass data to the timer when it expires.
  369  *
  370  * @return
  371  *      - LE_OK on success
  372  *      - LE_BUSY if the timer is currently running
  373  *
  374  * @note
  375  *      If an invalid timer object is given, the process exits.
  376  */
  377 //--------------------------------------------------------------------------------------------------
  378 le_result_t le_timer_SetContextPtr
  379 (
  380     le_timer_Ref_t timerRef,     ///< [IN] Set context pointer for this timer object
  381     void* contextPtr             ///< [IN] Context Pointer.
  382 );
  383 
  384 
  385 //--------------------------------------------------------------------------------------------------
  386 /**
  387  * Get context pointer for the timer.
  388  *
  389  * This can be used when the timer expires to retrieve data that was previously set.
  390  *
  391  * @return
  392  *      Context pointer, which could be NULL if it was not set.
  393  *
  394  * @note
  395  *      If an invalid timer object is given, the process exits.
  396  */
  397 //--------------------------------------------------------------------------------------------------
  398 void* le_timer_GetContextPtr
  399 (
  400     le_timer_Ref_t timerRef      ///< [IN] Get context pointer for this timer object
  401 );
  402 
  403 
  404 //--------------------------------------------------------------------------------------------------
  405 /**
  406  * Get the expiry count of a timer.
  407  *
  408  * The count is returned for  currently running and idle timers.  The expiry count
  409  * is reset every time the timer is (re)started.
  410  *
  411  * @return
  412  *      Expiry count, or zero if the timer has never expired.
  413  *
  414  * @note
  415  *      If an invalid timer object is given, the process exits.
  416  */
  417 //--------------------------------------------------------------------------------------------------
  418 uint32_t le_timer_GetExpiryCount
  419 (
  420     le_timer_Ref_t timerRef      ///< [IN] Get expiry count for this timer object
  421 );
  422 
  423 
  424 //--------------------------------------------------------------------------------------------------
  425 /**
  426  * Get the time remaining until the next scheduled expiry.
  427  *
  428  * @return
  429  *      Time remaining.
  430  *      {0, 0} if the timer is stopped or if it has reached its expiry time.
  431  *
  432  * @note
  433  *      If an invalid timer object is given, the process exits.
  434  */
  435 //--------------------------------------------------------------------------------------------------
  436 le_clk_Time_t le_timer_GetTimeRemaining
  437 (
  438     le_timer_Ref_t timerRef      ///< [IN] Get expiry count for this timer object
  439 );
  440 
  441 
  442 //--------------------------------------------------------------------------------------------------
  443 /**
  444  * Get the time remaining (in milliseconds) until the next scheduled expiry.
  445  *
  446  * @return
  447  *      Time remaining (in milliseconds).
  448  *      0 if the timer is stopped or if it has reached its expiry time.
  449  *
  450  * @note
  451  *      If an invalid timer object is given, the process exits.
  452  */
  453 //--------------------------------------------------------------------------------------------------
  454 uint32_t le_timer_GetMsTimeRemaining
  455 (
  456     le_timer_Ref_t timerRef      ///< [IN] Get expiry count for this timer object
  457 );
  458 
  459 
  460 //--------------------------------------------------------------------------------------------------
  461 /**
  462  * Start the timer.
  463  *
  464  * Start the given timer. The timer must not be currently running.
  465  *
  466  * @return
  467  *      - LE_OK on success
  468  *      - LE_BUSY if the timer is already running
  469  *
  470  * @note
  471  *      If an invalid timer object is given, the process exits.
  472  */
  473 //--------------------------------------------------------------------------------------------------
  474 le_result_t le_timer_Start
  475 (
  476     le_timer_Ref_t timerRef      ///< [IN] Start this timer object.
  477 );
  478 
  479 
  480 //--------------------------------------------------------------------------------------------------
  481 /**
  482  * Stop the timer.
  483  *
  484  * Stop the given timer. The timer must be running.
  485  *
  486  * @return
  487  *      - LE_OK on success
  488  *      - LE_FAULT if the timer is not currently running
  489  *
  490  * @note
  491  *      If an invalid timer object is given, the process exits.
  492  */
  493 //--------------------------------------------------------------------------------------------------
  494 le_result_t le_timer_Stop
  495 (
  496     le_timer_Ref_t timerRef      ///< [IN] Stop this timer object.
  497 );
  498 
  499 
  500 //--------------------------------------------------------------------------------------------------
  501 /**
  502  * Re-start the timer.
  503  *
  504  * Start the given timer. If the timer is currently running, it will be stopped and then started.
  505  * If the timer is not currently running, it will be started.
  506  *
  507  * @note
  508  *      If an invalid timer object is given, the process exits.
  509  */
  510 //--------------------------------------------------------------------------------------------------
  511 void le_timer_Restart
  512 (
  513     le_timer_Ref_t timerRef      ///< [IN] (Re)start this timer object.
  514 );
  515 
  516 
  517 //--------------------------------------------------------------------------------------------------
  518 /**
  519  * Is the timer currently running?
  520  *
  521  * @note
  522  *      If an invalid timer object is given, the process exits.
  523  */
  524 //--------------------------------------------------------------------------------------------------
  525 bool le_timer_IsRunning
  526 (
  527     le_timer_Ref_t timerRef      ///< [IN] Is this timer object currently running?
  528 );
  529 
  530 
  531 #endif // LEGATO_TIMER_INCLUDE_GUARD
  532 
le_timer_SetRepeat
le_result_t le_timer_SetRepeat(le_timer_Ref_t timerRef, uint32_t repeatCount)
le_timer_SetWakeup
le_result_t le_timer_SetWakeup(le_timer_Ref_t timerRef, bool wakeupEnabled)
le_result_t
le_result_t
Definition: le_basics.h:35
le_clk_Time_t
Definition: le_clock.h:98
le_timer_Start
le_result_t le_timer_Start(le_timer_Ref_t timerRef)
le_timer_Delete
void le_timer_Delete(le_timer_Ref_t timerRef)
le_timer_Create
le_timer_Ref_t le_timer_Create(const char *nameStr)
le_timer_Ref_t
struct le_timer * le_timer_Ref_t
Definition: le_timer.h:146
le_timer_SetMsInterval
le_result_t le_timer_SetMsInterval(le_timer_Ref_t timerRef, uint32_t interval)
le_timer_GetMsTimeRemaining
uint32_t le_timer_GetMsTimeRemaining(le_timer_Ref_t timerRef)
le_timer_GetTimeRemaining
le_clk_Time_t le_timer_GetTimeRemaining(le_timer_Ref_t timerRef)
le_timer_GetInterval
le_clk_Time_t le_timer_GetInterval(le_timer_Ref_t timerRef)
le_timer_GetContextPtr
void * le_timer_GetContextPtr(le_timer_Ref_t timerRef)
le_timer_SetInterval
le_result_t le_timer_SetInterval(le_timer_Ref_t timerRef, le_clk_Time_t interval)
le_timer_SetHandler
le_result_t le_timer_SetHandler(le_timer_Ref_t timerRef, le_timer_ExpiryHandler_t handlerFunc)
le_timer_Stop
le_result_t le_timer_Stop(le_timer_Ref_t timerRef)
le_timer_IsRunning
bool le_timer_IsRunning(le_timer_Ref_t timerRef)
le_timer_Restart
void le_timer_Restart(le_timer_Ref_t timerRef)
le_timer_GetMsInterval
uint32_t le_timer_GetMsInterval(le_timer_Ref_t timerRef)
le_timer_SetContextPtr
le_result_t le_timer_SetContextPtr(le_timer_Ref_t timerRef, void *contextPtr)
le_timer_GetExpiryCount
uint32_t le_timer_GetExpiryCount(le_timer_Ref_t timerRef)
le_timer_ExpiryHandler_t
void(* le_timer_ExpiryHandler_t)(le_timer_Ref_t timerRef)
Definition: le_timer.h:158
LE_DECLARE_INLINE
#define LE_DECLARE_INLINE
Definition: le_basics.h:274