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  *
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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_result_t le_timer_SetRepeat(le_timer_Ref_t timerRef, uint32_t repeatCount)
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:131
Definition: le_clock.h:92
le_result_t le_timer_SetMsInterval(le_timer_Ref_t timerRef, uint32_t interval)
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)
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:143