le_timer.h

Go to the documentation of this file.
    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 @ref le_timer_Create. The timer name is used for logging purposes only.
   19  *
   20  * The following attributes of the timer can be set:
   21  *  - @ref le_timer_SetHandler
   22  *  - @ref le_timer_SetInterval
   23  *  - @ref le_timer_SetRepeat
   24  *  - @ref le_timer_SetContextPtr
   25  *
   26  * The repeat count defaults to 1, so that the timer is initially a one-shot timer. All the other
   27  * attributes must be explicitly set.  At a minimum, the interval must be set before the timer can be
   28  * used.  Note that these attributes can only be set if the timer is not currently running; otherwise,
   29  * an error will be returned.
   30  *
   31  * Timers must be explicitly deleted using @ref le_timer_Delete. If the timer is currently running,
   32  * it'll be stopped before being deleted. If a timer uses @ref le_timer_SetContextPtr, and the
   33  * context pointer is allocated memory, then the context pointer must be freed when deleting the timer.
   34  * The following function can be used for this:
   35  * @code
   36  * static void DeleteTimerAndFreePtr(le_timer_Ref_t t)
   37  * {
   38  *     le_timer_Stop( t );
   39  *     free( le_timer_GetContextPtr( t ) );
   40  *     le_timer_Delete( t );  // timer ref is now invalid
   41  * }
   42  * @endcode
   43  * You can call this function anywhere, including in the timer handler.
   44  *
   45  * @section timer_usage Using Timers
   46  *
   47  * A timer is started using @ref le_timer_Start. If it's already running, then it won't be
   48  * modified; instead an error will be returned. To restart a currently running timer, use @ref
   49  * le_timer_Restart.
   50  *
   51  * A timer is stopped using @ref le_timer_Stop.  If it's not currently running, an error
   52  * will be returned, and nothing more will be done.
   53  *
   54  * To determine if the timer is currently running, use @ref le_timer_IsRunning.
   55  *
   56  * When a timer expires, if the timer expiry handler is set by @ref le_timer_SetHandler, the
   57  * handler will be called with a reference to the expired timer. If additional data is required in the
   58  * handler, @ref le_timer_SetContextPtr can be used to set the appropriate context before starting the
   59  * timer, and @ref le_timer_GetContextPtr can be used to retrieve the context while in the handler.
   60  * In addition, a suspended system will also wake up by default if the timer expires. If this behaviour
   61  * is not desired, user can disable the wake up by passing false into @ref le_timer_SetWakeup.
   62  *
   63  * The number of times that a timer has expired can be retrieved by @ref le_timer_GetExpiryCount. This
   64  * count is independent of whether there is an expiry handler for the timer.
   65  *
   66  * @section le_timer_thread Thread Support
   67  *
   68  * A timer should only be used by the thread that created it. It's not safe for a thread to use
   69  * or manipulate a timer that belongs to another thread. The timer expiry handler is called by the
   70  * event loop of the thread that starts the timer.
   71  *
   72  * The call to the timer expiry handler may not occur immediately after the timer expires, depending
   73  * on which other functions are called from the event loop. The amount of delay is entirely
   74  * dependent on other work done in the event loop. For a repeating timer, if this delay is longer
   75  * than the timer period, one or more timer expiries may be dropped. To reduce the likelihood of
   76  * dropped expiries, the combined execution time of all handlers called from the event loop should
   77  *  ideally be less than the timer period.
   78  *
   79  * See @ref c_eventLoop for details on running the event loop of a thread.
   80  *
   81  * @section le_timer_suspend Suspend Support
   82  *
   83  * The timer runs even when system is suspended. <br>
   84  * If the timer expires while the system is suspended, it will wake up the system.
   85  *
   86  * @section timer_errors Fatal Errors
   87  *
   88  * The process will exit under any of the following conditions:
   89  *  - If an invalid timer object is given to:
   90  *     - @ref le_timer_Delete
   91  *     - @ref le_timer_SetHandler
   92  *     - @ref le_timer_SetInterval
   93  *     - @ref le_timer_SetRepeat
   94  *     - @ref le_timer_Start
   95  *     - @ref le_timer_Stop
   96  *     - @ref le_timer_Restart
   97  *     - @ref le_timer_SetContextPtr
   98  *     - @ref le_timer_GetContextPtr
   99  *     - @ref le_timer_GetExpiryCount
  100  *     - @ref le_timer_SetWakeup
  101  *
  102  * @section timer_troubleshooting Troubleshooting
  103  *
  104  * Timers can be traced by enabling the log trace keyword "timers" in the "framework" component.
  105  *
  106  * See @ref c_log_controlling for more information.
  107  *
  108  * <HR>
  109  *
  110  * Copyright (C) Sierra Wireless Inc.
  111  *
  112  */
  113 
  114 //--------------------------------------------------------------------------------------------------
  115 /**
  116  * @file le_timer.h
  117  *
  118  * Legato @ref c_timer include file.
  119  *
  120  * Copyright (C) Sierra Wireless Inc.
  121  *
  122  */
  123 //--------------------------------------------------------------------------------------------------
  124 
  125 #ifndef LEGATO_TIMER_INCLUDE_GUARD
  126 #define LEGATO_TIMER_INCLUDE_GUARD
  127 
  128 
  129 //--------------------------------------------------------------------------------------------------
  130 /**
  131  * Timer object.  Created by le_timer_Create().
  132  */
  133 //--------------------------------------------------------------------------------------------------
  134 typedef struct le_timer* le_timer_Ref_t;
  135 
  136 
  137 //--------------------------------------------------------------------------------------------------
  138 /**
  139  * Prototype for timer expiry handler function.
  140  *
  141  * @param
  142  *      timerRef Timer that has expired
  143  */
  144 //--------------------------------------------------------------------------------------------------
  145 typedef void (*le_timer_ExpiryHandler_t)
  146 (
  147     le_timer_Ref_t timerRef
  148 );
  149 
  150 
  151 //--------------------------------------------------------------------------------------------------
  152 /**
  153  * Create the timer object.
  154  *
  155  * @return
  156  *      A reference to the timer object.
  157  */
  158 //--------------------------------------------------------------------------------------------------
  159 le_timer_Ref_t le_timer_Create
  160 (
  161     const char* nameStr                 ///< [IN]  Name of the timer.
  162 );
  163 
  164 
  165 //--------------------------------------------------------------------------------------------------
  166 /**
  167  * Delete the timer object.
  168  *
  169  * @note
  170  *      If an invalid timer object is given, the process exits.
  171  */
  172 //--------------------------------------------------------------------------------------------------
  173 void le_timer_Delete
  174 (
  175     le_timer_Ref_t timerRef                 ///< [IN] Delete this timer object
  176 );
  177 
  178 
  179 //--------------------------------------------------------------------------------------------------
  180 /**
  181  * Set the timer expiry handler function.
  182  *
  183  * If the handler is NULL, then the previous handler will be removed.
  184  *
  185  * @return
  186  *      - LE_OK on success
  187  *      - LE_BUSY if the timer is currently running
  188  *
  189  * @note
  190  *      If an invalid timer object is given, the process exits.
  191  */
  192 //--------------------------------------------------------------------------------------------------
  193 le_result_t le_timer_SetHandler
  194 (
  195     le_timer_Ref_t timerRef,                ///< [IN] Set expiry handler for this timer object.
  196     le_timer_ExpiryHandler_t handlerFunc    ///< [IN] Handler function to call on expiry.
  197 );
  198 
  199 
  200 //--------------------------------------------------------------------------------------------------
  201 /**
  202  * Set the timer interval.
  203  *
  204  * Timer will expire after the interval has elapsed.
  205  *
  206  * @return
  207  *      - LE_OK on success
  208  *      - LE_BUSY if the timer is currently running
  209  *
  210  * @note
  211  *      If an invalid timer object is given, the process exits.
  212  */
  213 //--------------------------------------------------------------------------------------------------
  214 le_result_t le_timer_SetInterval
  215 (
  216     le_timer_Ref_t timerRef,     ///< [IN] Set interval for this timer object.
  217     le_clk_Time_t interval       ///< [IN] Timer interval.
  218 );
  219 
  220 
  221 //--------------------------------------------------------------------------------------------------
  222 /**
  223  * Set the timer interval using milliseconds.
  224  *
  225  * Timer will expire after the interval has elapsed.
  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_SetMsInterval
  236 (
  237     le_timer_Ref_t timerRef,     ///< [IN] Set interval for this timer object.
  238     uint32_t interval            ///< [IN] Timer interval in milliseconds.
  239 );
  240 
  241 
  242 //--------------------------------------------------------------------------------------------------
  243 /**
  244  * Set how many times the timer will repeat.
  245  *
  246  * Timer will repeat the given number of times.  A value of 0 means repeat indefinitely.
  247  * The default is 1, so that a one-shot timer is the default.
  248  *
  249  * @return
  250  *      - LE_OK on success
  251  *      - LE_BUSY if the timer is currently running
  252  *
  253  * @note
  254  *      If an invalid timer object is given, the process exits.
  255  */
  256 //--------------------------------------------------------------------------------------------------
  257 le_result_t le_timer_SetRepeat
  258 (
  259     le_timer_Ref_t timerRef,     ///< [IN] Set repeat count for this timer object
  260     uint32_t repeatCount         ///< [IN] Number of times the timer will repeat (0 = forever).
  261 );
  262 
  263 
  264 //--------------------------------------------------------------------------------------------------
  265 /**
  266  * Configure if timer expiry will wake up a suspended system.
  267  *
  268  * @return
  269  *      - LE_OK on success
  270  *      - LE_BUSY if the timer is currently running
  271  *
  272  * @note
  273  *      The default timer expiry behaviour will wake up the system.
  274  *      If an invalid timer object is given, the process exits.
  275  */
  276 //--------------------------------------------------------------------------------------------------
  277 le_result_t le_timer_SetWakeup
  278 (
  279     le_timer_Ref_t timerRef,     ///< [IN] Disable system wake up for this timer object
  280     bool wakeupEnabled           ///< [IN] Flag to determine timer will wakeup or not
  281 );
  282 
  283 
  284 //--------------------------------------------------------------------------------------------------
  285 /**
  286  * Set context pointer for the timer.
  287  *
  288  * This can be used to pass data to the timer when it expires.
  289  *
  290  * @return
  291  *      - LE_OK on success
  292  *      - LE_BUSY if the timer is currently running
  293  *
  294  * @note
  295  *      If an invalid timer object is given, the process exits.
  296  */
  297 //--------------------------------------------------------------------------------------------------
  298 le_result_t le_timer_SetContextPtr
  299 (
  300     le_timer_Ref_t timerRef,     ///< [IN] Set context pointer for this timer object
  301     void* contextPtr             ///< [IN] Context Pointer.
  302 );
  303 
  304 
  305 //--------------------------------------------------------------------------------------------------
  306 /**
  307  * Get context pointer for the timer.
  308  *
  309  * This can be used when the timer expires to retrieve data that was previously set.
  310  *
  311  * @return
  312  *      Context pointer, which could be NULL if it was not set.
  313  *
  314  * @note
  315  *      If an invalid timer object is given, the process exits.
  316  */
  317 //--------------------------------------------------------------------------------------------------
  318 void* le_timer_GetContextPtr
  319 (
  320     le_timer_Ref_t timerRef      ///< [IN] Get context pointer for this timer object
  321 );
  322 
  323 
  324 //--------------------------------------------------------------------------------------------------
  325 /**
  326  * Get the expiry count of a timer.
  327  *
  328  * The count is returned for  currently running and idle timers.  The expiry count
  329  * is reset every time the timer is (re)started.
  330  *
  331  * @return
  332  *      Expiry count, or zero if the timer has never expired.
  333  *
  334  * @note
  335  *      If an invalid timer object is given, the process exits.
  336  */
  337 //--------------------------------------------------------------------------------------------------
  338 uint32_t le_timer_GetExpiryCount
  339 (
  340     le_timer_Ref_t timerRef      ///< [IN] Get expiry count for this timer object
  341 );
  342 
  343 
  344 //--------------------------------------------------------------------------------------------------
  345 /**
  346  * Start the timer.
  347  *
  348  * Start the given timer. The timer must not be currently running.
  349  *
  350  * @return
  351  *      - LE_OK on success
  352  *      - LE_BUSY if the timer is already running
  353  *
  354  * @note
  355  *      If an invalid timer object is given, the process exits.
  356  */
  357 //--------------------------------------------------------------------------------------------------
  358 le_result_t le_timer_Start
  359 (
  360     le_timer_Ref_t timerRef      ///< [IN] Start this timer object.
  361 );
  362 
  363 
  364 //--------------------------------------------------------------------------------------------------
  365 /**
  366  * Stop the timer.
  367  *
  368  * Stop the given timer. The timer must be running.
  369  *
  370  * @return
  371  *      - LE_OK on success
  372  *      - LE_FAULT if the timer is not currently running
  373  *
  374  * @note
  375  *      If an invalid timer object is given, the process exits.
  376  */
  377 //--------------------------------------------------------------------------------------------------
  378 le_result_t le_timer_Stop
  379 (
  380     le_timer_Ref_t timerRef      ///< [IN] Stop this timer object.
  381 );
  382 
  383 
  384 //--------------------------------------------------------------------------------------------------
  385 /**
  386  * Re-start the timer.
  387  *
  388  * Start the given timer. If the timer is currently running, it will be stopped and then started.
  389  * If the timer is not currently running, it will be started.
  390  *
  391  * @note
  392  *      If an invalid timer object is given, the process exits.
  393  */
  394 //--------------------------------------------------------------------------------------------------
  395 void le_timer_Restart
  396 (
  397     le_timer_Ref_t timerRef      ///< [IN] (Re)start this timer object.
  398 );
  399 
  400 
  401 //--------------------------------------------------------------------------------------------------
  402 /**
  403  * Is the timer currently running?
  404  *
  405  * @note
  406  *      If an invalid timer object is given, the process exits.
  407  */
  408 //--------------------------------------------------------------------------------------------------
  409 bool le_timer_IsRunning
  410 (
  411     le_timer_Ref_t timerRef      ///< [IN] Is this timer object currently running?
  412 );
  413 
  414 
  415 #endif // LEGATO_TIMER_INCLUDE_GUARD
  416 
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:134


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_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_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:146