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