le_timer.h

    1 /**
    2  * @page c_timer Timer API
    3  *
    4  * @ref 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 //--------------------------------------------------------------------------------------------------
  164 /**
  165  * Create the timer object.
  166  *
  167  * @return
  168  *      A reference to the timer object.
  169  */
  170 //--------------------------------------------------------------------------------------------------
  171 le_timer_Ref_t le_timer_Create
  172 (
  173     const char* nameStr                 ///< [IN]  Name of the timer.
  174 );
  175 
  176 
  177 //--------------------------------------------------------------------------------------------------
  178 /**
  179  * Delete the timer object.
  180  *
  181  * @note
  182  *      If an invalid timer object is given, the process exits.
  183  */
  184 //--------------------------------------------------------------------------------------------------
  185 void le_timer_Delete
  186 (
  187     le_timer_Ref_t timerRef                 ///< [IN] Delete this timer object
  188 );
  189 
  190 
  191 //--------------------------------------------------------------------------------------------------
  192 /**
  193  * Set the timer expiry handler function.
  194  *
  195  * If the handler is NULL, then the previous handler will be removed.
  196  *
  197  * @return
  198  *      - LE_OK on success
  199  *      - LE_BUSY if the timer is currently running
  200  *
  201  * @note
  202  *      If an invalid timer object is given, the process exits.
  203  */
  204 //--------------------------------------------------------------------------------------------------
  205 le_result_t le_timer_SetHandler
  206 (
  207     le_timer_Ref_t timerRef,                ///< [IN] Set expiry handler for this timer object.
  208     le_timer_ExpiryHandler_t handlerFunc    ///< [IN] Handler function to call on expiry.
  209 );
  210 
  211 
  212 //--------------------------------------------------------------------------------------------------
  213 /**
  214  * Set the timer interval.
  215  *
  216  * Timer will expire after the interval has elapsed since it was last started or restarted.
  217  *
  218  * If the timer is running when the interval is changed and the new interval is shorter than the
  219  * period of time since the timer last (re)started, the timer will expire immediately.
  220  *
  221  * @return
  222  *      - LE_OK on success
  223  *
  224  * @note
  225  *      If an invalid timer object is given, the process exits.
  226  */
  227 //--------------------------------------------------------------------------------------------------
  228 le_result_t le_timer_SetInterval
  229 (
  230     le_timer_Ref_t timerRef,     ///< [IN] Set interval for this timer object.
  231     le_clk_Time_t interval       ///< [IN] Timer interval.
  232 );
  233 
  234 
  235 //--------------------------------------------------------------------------------------------------
  236 /**
  237  * Get the timer interval.
  238  *
  239  * @return
  240  *      The timer interval.  If it hasn't been set yet, {0, 0} will be returned.
  241  *
  242  * @note
  243  *      If an invalid timer object is given, the process exits.
  244  */
  245 //--------------------------------------------------------------------------------------------------
  246 le_clk_Time_t le_timer_GetInterval
  247 (
  248     le_timer_Ref_t timerRef      ///< [IN] Timer object.
  249 );
  250 
  251 
  252 //--------------------------------------------------------------------------------------------------
  253 /**
  254  * Set the timer interval using milliseconds.
  255  *
  256  * Timer will expire after the interval has elapsed since it was last started or restarted.
  257  *
  258  * If the timer is running when the interval is changed and the new interval is shorter than the
  259  * period of time since the timer last (re)started, the timer will expire immediately.
  260  *
  261  * @return
  262  *      - LE_OK on success
  263  *
  264  * @note
  265  *      If an invalid timer object is given, the process exits.
  266  */
  267 //--------------------------------------------------------------------------------------------------
  268 le_result_t le_timer_SetMsInterval
  269 (
  270     le_timer_Ref_t timerRef,     ///< [IN] Set interval for this timer object.
  271     uint32_t interval            ///< [IN] Timer interval in milliseconds.
  272 );
  273 
  274 
  275 //--------------------------------------------------------------------------------------------------
  276 /**
  277  * Get the timer interval in milliseconds.
  278  *
  279  * @return
  280  *      The timer interval (ms).  If it hasn't been set yet, 0 will be returned.
  281  *
  282  * @note
  283  *      If an invalid timer object is given, the process exits.
  284  */
  285 //--------------------------------------------------------------------------------------------------
  286 uint32_t le_timer_GetMsInterval
  287 (
  288     le_timer_Ref_t timerRef      ///< [IN] Timer object.
  289 );
  290 
  291 
  292 //--------------------------------------------------------------------------------------------------
  293 /**
  294  * Set how many times the timer will repeat.
  295  *
  296  * Timer will repeat the given number of times.  A value of 0 means repeat indefinitely.
  297  * The default is 1, so that a one-shot timer is the default.
  298  *
  299  * @return
  300  *      - LE_OK on success
  301  *      - LE_BUSY if the timer is currently running
  302  *
  303  * @note
  304  *      If an invalid timer object is given, the process exits.
  305  */
  306 //--------------------------------------------------------------------------------------------------
  307 le_result_t le_timer_SetRepeat
  308 (
  309     le_timer_Ref_t timerRef,     ///< [IN] Set repeat count for this timer object
  310     uint32_t repeatCount         ///< [IN] Number of times the timer will repeat (0 = forever).
  311 );
  312 
  313 
  314 //--------------------------------------------------------------------------------------------------
  315 /**
  316  * Configure if timer expiry will wake up a suspended system.
  317  *
  318  * @return
  319  *      - LE_OK on success
  320  *      - LE_BUSY if the timer is currently running
  321  *
  322  * @note
  323  *      The default timer expiry behaviour will wake up the system.
  324  *      If an invalid timer object is given, the process exits.
  325  */
  326 //--------------------------------------------------------------------------------------------------
  327 le_result_t le_timer_SetWakeup
  328 (
  329     le_timer_Ref_t timerRef,     ///< [IN] Disable system wake up for this timer object
  330     bool wakeupEnabled           ///< [IN] Flag to determine timer will wakeup or not
  331 );
  332 
  333 
  334 //--------------------------------------------------------------------------------------------------
  335 /**
  336  * Set context pointer for the timer.
  337  *
  338  * This can be used to pass data to the timer when it expires.
  339  *
  340  * @return
  341  *      - LE_OK on success
  342  *      - LE_BUSY if the timer is currently running
  343  *
  344  * @note
  345  *      If an invalid timer object is given, the process exits.
  346  */
  347 //--------------------------------------------------------------------------------------------------
  348 le_result_t le_timer_SetContextPtr
  349 (
  350     le_timer_Ref_t timerRef,     ///< [IN] Set context pointer for this timer object
  351     void* contextPtr             ///< [IN] Context Pointer.
  352 );
  353 
  354 
  355 //--------------------------------------------------------------------------------------------------
  356 /**
  357  * Get context pointer for the timer.
  358  *
  359  * This can be used when the timer expires to retrieve data that was previously set.
  360  *
  361  * @return
  362  *      Context pointer, which could be NULL if it was not set.
  363  *
  364  * @note
  365  *      If an invalid timer object is given, the process exits.
  366  */
  367 //--------------------------------------------------------------------------------------------------
  368 void* le_timer_GetContextPtr
  369 (
  370     le_timer_Ref_t timerRef      ///< [IN] Get context pointer for this timer object
  371 );
  372 
  373 
  374 //--------------------------------------------------------------------------------------------------
  375 /**
  376  * Get the expiry count of a timer.
  377  *
  378  * The count is returned for  currently running and idle timers.  The expiry count
  379  * is reset every time the timer is (re)started.
  380  *
  381  * @return
  382  *      Expiry count, or zero if the timer has never expired.
  383  *
  384  * @note
  385  *      If an invalid timer object is given, the process exits.
  386  */
  387 //--------------------------------------------------------------------------------------------------
  388 uint32_t le_timer_GetExpiryCount
  389 (
  390     le_timer_Ref_t timerRef      ///< [IN] Get expiry count for this timer object
  391 );
  392 
  393 
  394 //--------------------------------------------------------------------------------------------------
  395 /**
  396  * Get the time remaining until the next scheduled expiry.
  397  *
  398  * @return
  399  *      Time remaining.
  400  *      {0, 0} if the timer is stopped or if it has reached its expiry time.
  401  *
  402  * @note
  403  *      If an invalid timer object is given, the process exits.
  404  */
  405 //--------------------------------------------------------------------------------------------------
  406 le_clk_Time_t le_timer_GetTimeRemaining
  407 (
  408     le_timer_Ref_t timerRef      ///< [IN] Get expiry count for this timer object
  409 );
  410 
  411 
  412 //--------------------------------------------------------------------------------------------------
  413 /**
  414  * Get the time remaining (in milliseconds) until the next scheduled expiry.
  415  *
  416  * @return
  417  *      Time remaining (in milliseconds).
  418  *      0 if the timer is stopped or if it has reached its expiry time.
  419  *
  420  * @note
  421  *      If an invalid timer object is given, the process exits.
  422  */
  423 //--------------------------------------------------------------------------------------------------
  424 uint32_t le_timer_GetMsTimeRemaining
  425 (
  426     le_timer_Ref_t timerRef      ///< [IN] Get expiry count for this timer object
  427 );
  428 
  429 
  430 //--------------------------------------------------------------------------------------------------
  431 /**
  432  * Start the timer.
  433  *
  434  * Start the given timer. The timer must not be currently running.
  435  *
  436  * @return
  437  *      - LE_OK on success
  438  *      - LE_BUSY if the timer is already running
  439  *
  440  * @note
  441  *      If an invalid timer object is given, the process exits.
  442  */
  443 //--------------------------------------------------------------------------------------------------
  444 le_result_t le_timer_Start
  445 (
  446     le_timer_Ref_t timerRef      ///< [IN] Start this timer object.
  447 );
  448 
  449 
  450 //--------------------------------------------------------------------------------------------------
  451 /**
  452  * Stop the timer.
  453  *
  454  * Stop the given timer. The timer must be running.
  455  *
  456  * @return
  457  *      - LE_OK on success
  458  *      - LE_FAULT if the timer is not currently running
  459  *
  460  * @note
  461  *      If an invalid timer object is given, the process exits.
  462  */
  463 //--------------------------------------------------------------------------------------------------
  464 le_result_t le_timer_Stop
  465 (
  466     le_timer_Ref_t timerRef      ///< [IN] Stop this timer object.
  467 );
  468 
  469 
  470 //--------------------------------------------------------------------------------------------------
  471 /**
  472  * Re-start the timer.
  473  *
  474  * Start the given timer. If the timer is currently running, it will be stopped and then started.
  475  * If the timer is not currently running, it will be started.
  476  *
  477  * @note
  478  *      If an invalid timer object is given, the process exits.
  479  */
  480 //--------------------------------------------------------------------------------------------------
  481 void le_timer_Restart
  482 (
  483     le_timer_Ref_t timerRef      ///< [IN] (Re)start this timer object.
  484 );
  485 
  486 
  487 //--------------------------------------------------------------------------------------------------
  488 /**
  489  * Is the timer currently running?
  490  *
  491  * @note
  492  *      If an invalid timer object is given, the process exits.
  493  */
  494 //--------------------------------------------------------------------------------------------------
  495 bool le_timer_IsRunning
  496 (
  497     le_timer_Ref_t timerRef      ///< [IN] Is this timer object currently running?
  498 );
  499 
  500 
  501 #endif // LEGATO_TIMER_INCLUDE_GUARD
  502 
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_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_clk_Time_t
Definition: le_clock.h:98
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