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  * @{
60  */
61 
62 #ifndef ETIMER_H_
63 #define ETIMER_H_
64 
65 #include "contiki.h"
66 
67 /**
68  * A timer.
69  *
70  * This structure is used for declaring a timer. The timer must be set
71  * with etimer_set() before it can be used.
72  *
73  * \hideinitializer
74  */
75 struct etimer {
76  struct timer timer;
77  struct etimer *next;
78  struct process *p;
79 };
80 
81 /**
82  * \name Functions called from application programs
83  * @{
84  */
85 
86 /**
87  * \brief Set an event timer.
88  * \param et A pointer to the event timer
89  * \param interval The interval before the timer expires.
90  *
91  * This function is used to set an event timer for a time
92  * sometime in the future. When the event timer expires,
93  * the event PROCESS_EVENT_TIMER will be posted to the
94  * process that called the etimer_set() function.
95  *
96  */
97 void etimer_set(struct etimer *et, clock_time_t interval);
98 
99 /**
100  * \brief Reset an event timer with the same interval as was
101  * previously set.
102  * \param et A pointer to the event timer.
103  *
104  * This function resets the event timer with the same
105  * interval that was given to the event timer with the
106  * etimer_set() function. The start point of the interval
107  * is the exact time that the event timer last
108  * expired. Therefore, this function will cause the timer
109  * to be stable over time, unlike the etimer_restart()
110  * function.
111  *
112  * \sa etimer_restart()
113  */
114 void etimer_reset(struct etimer *et);
115 
116 /**
117  * \brief Reset an event timer with a new interval.
118  * \param et A pointer to the event timer.
119  * \param interval The interval before the timer expires.
120  *
121  * This function very similar to etimer_reset. Opposed to
122  * etimer_reset it is possible to change the timout.
123  * This allows accurate, non-periodic timers without drift.
124  *
125  * \sa etimer_reset()
126  */
127 void etimer_reset_with_new_interval(struct etimer *et, clock_time_t interval);
128 
129 /**
130  * \brief Restart an event timer from the current point in time
131  * \param et A pointer to the event timer.
132  *
133  * This function restarts the event timer with the same
134  * interval that was given to the etimer_set()
135  * function. The event timer will start at the current
136  * time.
137  *
138  * \note A periodic timer will drift if this function is
139  * used to reset it. For periodic timers, use the
140  * etimer_reset() function instead.
141  *
142  * \sa etimer_reset()
143  */
144 void etimer_restart(struct etimer *et);
145 
146 /**
147  * \brief Adjust the expiration time for an event timer
148  * \param et A pointer to the event timer.
149  * \param td The time difference to adjust the expiration time with.
150  *
151  * This function is used to adjust the time the event
152  * timer will expire. It can be used to synchronize
153  * periodic timers without the need to restart the timer
154  * or change the timer interval.
155  *
156  * \note This function should only be used for small
157  * adjustments. For large adjustments use etimer_set()
158  * instead.
159  *
160  * \note A periodic timer will drift unless the
161  * etimer_reset() function is used.
162  *
163  * \sa etimer_set()
164  * \sa etimer_reset()
165  */
166 void etimer_adjust(struct etimer *et, int td);
167 
168 /**
169  * \brief Get the expiration time for the event timer.
170  * \param et A pointer to the event timer
171  * \return The expiration time for the event timer.
172  *
173  * This function returns the expiration time for an event timer.
174  */
175 clock_time_t etimer_expiration_time(struct etimer *et);
176 
177 /**
178  * \brief Get the start time for the event timer.
179  * \param et A pointer to the event timer
180  * \return The start time for the event timer.
181  *
182  * This function returns the start time (when the timer
183  * was last set) for an event timer.
184  */
185 clock_time_t etimer_start_time(struct etimer *et);
186 
187 /**
188  * \brief Check if an event timer has expired.
189  * \param et A pointer to the event timer
190  * \return Non-zero if the timer has expired, zero otherwise.
191  *
192  * This function tests if an event timer has expired and
193  * returns true or false depending on its status.
194  */
195 int etimer_expired(struct etimer *et);
196 
197 /**
198  * \brief Stop a pending event timer.
199  * \param et A pointer to the pending event timer.
200  *
201  * This function stops an event timer that has previously
202  * been set with etimer_set() or etimer_reset(). After
203  * this function has been called, the event timer will not
204  * emit any event when it expires.
205  *
206  */
207 void etimer_stop(struct etimer *et);
208 
209 /** @} */
210 
211 /**
212  * \name Functions called from timer interrupts, by the system
213  * @{
214  */
215 
216 /**
217  * \brief Make the event timer aware that the clock has changed
218  *
219  * This function is used to inform the event timer module
220  * that the system clock has been updated. Typically, this
221  * function would be called from the timer interrupt
222  * handler when the clock has ticked.
223  */
224 void etimer_request_poll(void);
225 
226 /**
227  * \brief Check if there are any non-expired event timers.
228  * \return True if there are active event timers, false if there are
229  * no active timers.
230  *
231  * This function checks if there are any active event
232  * timers that have not expired.
233  */
234 int etimer_pending(void);
235 
236 /**
237  * \brief Get next event timer expiration time.
238  * \return Next expiration time of all pending event timers.
239  * If there are no pending event timers this function
240  * returns 0.
241  *
242  * This functions returns next expiration time of all
243  * pending event timers.
244  */
245 clock_time_t etimer_next_expiration_time(void);
246 
247 
248 /** @} */
249 
250 PROCESS_NAME(etimer_process);
251 #endif /* ETIMER_H_ */
252 /** @} */
253 /** @} */
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:75
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