Contiki-NG
etimer.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2004, Swedish Institute of Computer Science.
3  * All rights reserved.
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions
7  * are met:
8  * 1. Redistributions of source code must retain the above copyright
9  * notice, this list of conditions and the following disclaimer.
10  * 2. Redistributions in binary form must reproduce the above copyright
11  * notice, this list of conditions and the following disclaimer in the
12  * documentation and/or other materials provided with the distribution.
13  * 3. Neither the name of the Institute nor the names of its contributors
14  * may be used to endorse or promote products derived from this software
15  * without specific prior written permission.
16  *
17  * THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
18  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
20  * ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
21  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
22  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
23  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
24  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
25  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
26  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
27  * SUCH DAMAGE.
28  *
29  * This file is part of the Contiki operating system.
30  *
31  * Author: Adam Dunkels <adam@sics.se>
32  *
33  */
34 
35 /**
36  * \file
37  * Event timer header file.
38  * \author
39  * Adam Dunkels <adam@sics.se>
40  */
41 
42 /** \addtogroup timers
43  * @{ */
44 
45 /**
46  * \defgroup etimer Event timers
47  *
48  * Event timers provides a way to generate timed events. An event
49  * timer will post an event to the process that set the timer when the
50  * event timer expires.
51  *
52  * An event timer is declared as a \c struct \c etimer and all access
53  * to the event timer is made by a pointer to the declared event
54  * timer.
55  *
56  * \sa \ref timer "Simple timer library"
57  * \sa \ref clock "Clock library" (used by the timer library)
58  *
59  * It is \e not safe to manipulate event timers within an interrupt context.
60  * @{
61  */
62 
63 #ifndef ETIMER_H_
64 #define ETIMER_H_
65 
66 #include "contiki.h"
67 
68 /**
69  * A timer.
70  *
71  * This structure is used for declaring a timer. The timer must be set
72  * with etimer_set() before it can be used.
73  *
74  * \hideinitializer
75  */
76 struct etimer {
77  struct timer timer;
78  struct etimer *next;
79  struct process *p;
80 };
81 
82 /**
83  * \name Functions called from application programs
84  * @{
85  */
86 
87 /**
88  * \brief Set an event timer.
89  * \param et A pointer to the event timer
90  * \param interval The interval before the timer expires.
91  *
92  * This function is used to set an event timer for a time
93  * sometime in the future. When the event timer expires,
94  * the event PROCESS_EVENT_TIMER will be posted to the
95  * process that called the etimer_set() function.
96  *
97  */
98 void etimer_set(struct etimer *et, clock_time_t interval);
99 
100 /**
101  * \brief Reset an event timer with the same interval as was
102  * previously set.
103  * \param et A pointer to the event timer.
104  *
105  * This function resets the event timer with the same
106  * interval that was given to the event timer with the
107  * etimer_set() function. The start point of the interval
108  * is the exact time that the event timer last
109  * expired. Therefore, this function will cause the timer
110  * to be stable over time, unlike the etimer_restart()
111  * function. If this is executed before the timer expired,
112  * this function has no effect.
113  *
114  * \sa etimer_restart()
115  */
116 void etimer_reset(struct etimer *et);
117 
118 /**
119  * \brief Reset an event timer with a new interval.
120  * \param et A pointer to the event timer.
121  * \param interval The interval before the timer expires.
122  *
123  * This function very similar to etimer_reset. Opposed to
124  * etimer_reset it is possible to change the timout.
125  * This allows accurate, non-periodic timers without drift.
126  *
127  * \sa etimer_reset()
128  */
129 void etimer_reset_with_new_interval(struct etimer *et, clock_time_t interval);
130 
131 /**
132  * \brief Restart an event timer from the current point in time
133  * \param et A pointer to the event timer.
134  *
135  * This function restarts the event timer with the same
136  * interval that was given to the etimer_set()
137  * function. The event timer will start at the current
138  * time.
139  *
140  * \note A periodic timer will drift if this function is
141  * used to reset it. For periodic timers, use the
142  * etimer_reset() function instead.
143  *
144  * \sa etimer_reset()
145  */
146 void etimer_restart(struct etimer *et);
147 
148 /**
149  * \brief Adjust the expiration time for an event timer
150  * \param et A pointer to the event timer.
151  * \param td The time difference to adjust the expiration time with.
152  *
153  * This function is used to adjust the time the event
154  * timer will expire. It can be used to synchronize
155  * periodic timers without the need to restart the timer
156  * or change the timer interval.
157  *
158  * \note This function should only be used for small
159  * adjustments. For large adjustments use etimer_set()
160  * instead.
161  *
162  * \note A periodic timer will drift unless the
163  * etimer_reset() function is used.
164  *
165  * \sa etimer_set()
166  * \sa etimer_reset()
167  */
168 void etimer_adjust(struct etimer *et, int td);
169 
170 /**
171  * \brief Get the expiration time for the event timer.
172  * \param et A pointer to the event timer
173  * \return The expiration time for the event timer.
174  *
175  * This function returns the expiration time for an event timer.
176  */
177 clock_time_t etimer_expiration_time(struct etimer *et);
178 
179 /**
180  * \brief Get the start time for the event timer.
181  * \param et A pointer to the event timer
182  * \return The start time for the event timer.
183  *
184  * This function returns the start time (when the timer
185  * was last set) for an event timer.
186  */
187 clock_time_t etimer_start_time(struct etimer *et);
188 
189 /**
190  * \brief Check if an event timer has expired.
191  * \param et A pointer to the event timer
192  * \return Non-zero if the timer has expired, zero otherwise.
193  *
194  * This function tests if an event timer has expired and
195  * returns true or false depending on its status.
196  */
197 int etimer_expired(struct etimer *et);
198 
199 /**
200  * \brief Stop a pending event timer.
201  * \param et A pointer to the pending event timer.
202  *
203  * This function stops an event timer that has previously
204  * been set with etimer_set() or etimer_reset(). After
205  * this function has been called, the event timer will not
206  * emit any event when it expires.
207  *
208  */
209 void etimer_stop(struct etimer *et);
210 
211 /** @} */
212 
213 /**
214  * \name Functions called from timer interrupts, by the system
215  * @{
216  */
217 
218 /**
219  * \brief Make the event timer aware that the clock has changed
220  *
221  * This function is used to inform the event timer module
222  * that the system clock has been updated. Typically, this
223  * function would be called from the timer interrupt
224  * handler when the clock has ticked.
225  */
226 void etimer_request_poll(void);
227 
228 /**
229  * \brief Check if there are any non-expired event timers.
230  * \return True if there are active event timers, false if there are
231  * no active timers.
232  *
233  * This function checks if there are any active event
234  * timers that have not expired.
235  */
236 int etimer_pending(void);
237 
238 /**
239  * \brief Get next event timer expiration time.
240  * \return Next expiration time of all pending event timers.
241  * If there are no pending event timers this function
242  * returns 0.
243  *
244  * This functions returns next expiration time of all
245  * pending event timers.
246  */
247 clock_time_t etimer_next_expiration_time(void);
248 
249 
250 /** @} */
251 
252 PROCESS_NAME(etimer_process);
253 #endif /* ETIMER_H_ */
254 /** @} */
255 /** @} */
void etimer_stop(struct etimer *et)
Stop a pending event timer.
Definition: etimer.c:243
void etimer_restart(struct etimer *et)
Restart an event timer from the current point in time.
Definition: etimer.c:199
void etimer_request_poll(void)
Make the event timer aware that the clock has changed.
Definition: etimer.c:145
clock_time_t etimer_start_time(struct etimer *et)
Get the start time for the event timer.
Definition: etimer.c:225
A timer.
Definition: timer.h:82
clock_time_t etimer_next_expiration_time(void)
Get next event timer expiration time.
Definition: etimer.c:237
void etimer_reset_with_new_interval(struct etimer *et, clock_time_t interval)
Reset an event timer with a new interval.
Definition: etimer.c:184
int etimer_pending(void)
Check if there are any non-expired event timers.
Definition: etimer.c:231
#define PROCESS_NAME(name)
Declare the name of a process.
Definition: process.h:286
int etimer_expired(struct etimer *et)
Check if an event timer has expired.
Definition: etimer.c:213
void etimer_adjust(struct etimer *et, int timediff)
Adjust the expiration time for an event timer.
Definition: etimer.c:206
A timer.
Definition: etimer.h:76
void etimer_reset(struct etimer *et)
Reset an event timer with the same interval as was previously set.
Definition: etimer.c:192
void etimer_set(struct etimer *et, clock_time_t interval)
Set an event timer.
Definition: etimer.c:177
clock_time_t etimer_expiration_time(struct etimer *et)
Get the expiration time for the event timer.
Definition: etimer.c:219