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 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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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_result_t le_timer_SetRepeat(le_timer_Ref_t timerRef, uint32_t repeatCount)
le_result_t le_timer_SetWakeup(le_timer_Ref_t timerRef, bool wakeupEnabled)
le_result_t
Definition: le_basics.h:35
le_result_t le_timer_Start(le_timer_Ref_t timerRef)
void le_timer_Delete(le_timer_Ref_t timerRef)
le_timer_Ref_t le_timer_Create(const char *nameStr)
struct le_timer * le_timer_Ref_t
Definition: le_timer.h:146
Definition: le_clock.h:98
le_result_t le_timer_SetMsInterval(le_timer_Ref_t timerRef, uint32_t interval)
uint32_t le_timer_GetMsTimeRemaining(le_timer_Ref_t timerRef)
le_clk_Time_t le_timer_GetTimeRemaining(le_timer_Ref_t timerRef)
le_clk_Time_t le_timer_GetInterval(le_timer_Ref_t timerRef)
void * le_timer_GetContextPtr(le_timer_Ref_t timerRef)
le_result_t le_timer_SetInterval(le_timer_Ref_t timerRef, le_clk_Time_t interval)
le_result_t le_timer_SetHandler(le_timer_Ref_t timerRef, le_timer_ExpiryHandler_t handlerFunc)
le_result_t le_timer_Stop(le_timer_Ref_t timerRef)
bool le_timer_IsRunning(le_timer_Ref_t timerRef)
void le_timer_Restart(le_timer_Ref_t timerRef)
uint32_t le_timer_GetMsInterval(le_timer_Ref_t timerRef)
le_result_t le_timer_SetContextPtr(le_timer_Ref_t timerRef, void *contextPtr)
uint32_t le_timer_GetExpiryCount(le_timer_Ref_t timerRef)
void(* le_timer_ExpiryHandler_t)(le_timer_Ref_t timerRef)
Definition: le_timer.h:158