Contiki-NG
Loading...
Searching...
No Matches
ctimer.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2006, 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 */
32
33/**
34 * \file
35 * Header file for the callback timer
36 * \author
37 * Adam Dunkels <adam@sics.se>
38 */
39
40/**
41 * \addtogroup timers
42 * @{
43 */
44
45/**
46 * \defgroup ctimer Callback timer
47 * @{
48 *
49 * The ctimer module provides a timer mechanism that calls a specified
50 * C function when a ctimer expires.
51 *
52 * It is \e not safe to manipulate callback timers within an interrupt context.
53 */
54
55#ifndef CTIMER_H_
56#define CTIMER_H_
57
58#include "contiki.h"
59#include "sys/etimer.h"
60
61#include <stdbool.h>
62
63struct ctimer {
64 struct ctimer *next;
65 struct etimer etimer;
66 struct process *p;
67 void (*f)(void *);
68 void *ptr;
69};
70
71/**
72 * \brief Reset a callback timer with the same interval as was
73 * previously set.
74 * \param c A pointer to the callback timer.
75 *
76 * This function resets the callback timer with the same
77 * interval that was given to the callback timer with the
78 * ctimer_set() function. The start point of the interval
79 * is the exact time that the callback timer last
80 * expired. Therefore, this function will cause the timer
81 * to be stable over time, unlike the ctimer_restart()
82 * function. If this is executed before the timer expired,
83 * this function has no effect.
84 *
85 * \sa ctimer_restart()
86 */
87void ctimer_reset(struct ctimer *c);
88
89/**
90 * \brief Reset a callback timer with a new interval.
91 * \param c A pointer to the callback timer.
92 * \param interval The interval before the timer expires.
93 *
94 * This function very similar to ctimer_reset(). Opposed to
95 * ctimer_reset() it is possible to change the timout.
96 * This allows accurate, non-periodic timers without drift.
97 *
98 * \sa ctimer_reset()
99 */
100void ctimer_reset_with_new_interval(struct ctimer *c, clock_time_t interval);
101
102/**
103 * \brief Restart a callback timer from the current point in time
104 * \param c A pointer to the callback timer.
105 *
106 * This function restarts the callback timer with the same
107 * interval that was given to the ctimer_set()
108 * function. The callback timer will start at the current
109 * time.
110 *
111 * \note A periodic timer will drift if this function is
112 * used to reset it. For periodic timers, use the
113 * ctimer_reset() function instead.
114 *
115 * \sa ctimer_reset()
116 */
117void ctimer_restart(struct ctimer *c);
118
119/**
120 * \brief Set a callback timer.
121 * \param c A pointer to the callback timer.
122 * \param t The interval before the timer expires.
123 * \param f A function to be called when the timer expires.
124 * \param ptr An opaque pointer that will be supplied as an argument to the callback function.
125 * \param p A pointer to the process the timer belongs to
126 *
127 * This function is used to set a callback timer for a time
128 * sometime in the future. When the callback timer expires,
129 * the callback function f will be called with ptr as argument.
130 *
131 */
132void ctimer_set_with_process(struct ctimer *c, clock_time_t t,
133 void (*f)(void *), void *ptr, struct process *p);
134
135/**
136 * \brief Set a callback timer.
137 * \param c A pointer to the callback timer.
138 * \param t The interval before the timer expires.
139 * \param f A function to be called when the timer expires.
140 * \param ptr An opaque pointer that will be supplied as an argument to the callback function.
141 *
142 * This function is used to set a callback timer for a time
143 * sometime in the future. When the callback timer expires,
144 * the callback function f will be called with ptr as argument.
145 *
146 * This essentially does ctimer_set_process(c, t, f, ptr, PROCESS_CURRENT());
147 *
148 */
149static inline void
150ctimer_set(struct ctimer *c, clock_time_t t, void (*f)(void *), void *ptr)
151{
153}
154
155/**
156 * \brief Stop a pending callback timer.
157 * \param c A pointer to the pending callback timer.
158 *
159 * This function stops a callback timer that has previously
160 * been set with ctimer_set(), ctimer_reset(), or ctimer_restart().
161 * After this function has been called, the callback timer will be
162 * expired and will not call the callback function.
163 *
164 */
165void ctimer_stop(struct ctimer *c);
166
167/**
168 * \brief Get the expiration time for the callback timer.
169 * \param c A pointer to the callback timer
170 * \return The expiration time for the callback timer.
171 *
172 * This function returns the expiration time for a callback timer.
173 */
174static inline clock_time_t
175ctimer_expiration_time(struct ctimer *c)
176{
177 return etimer_expiration_time(&c->etimer);
178}
179
180/**
181 * \brief Get the start time for the callback timer.
182 * \param c A pointer to the callback timer
183 * \return The start time for the callback timer.
184 *
185 * This function returns the start time (when the timer
186 * was last set) for a callback timer.
187 */
188static inline clock_time_t
189ctimer_start_time(struct ctimer *c)
190{
191 return etimer_start_time(&c->etimer);
192}
193
194/**
195 * \brief Check if a callback timer has expired.
196 * \param c A pointer to the callback timer
197 * \return True if the timer has expired.
198 *
199 * This function tests if a callback timer has expired and
200 * returns true or false depending on its status.
201 */
202bool ctimer_expired(struct ctimer *c);
203
204/**
205 * \brief Initialize the callback timer library.
206 *
207 * This function initializes the callback timer library and
208 * should be called from the system boot up code.
209 */
210void ctimer_init(void);
211
212#endif /* CTIMER_H_ */
213/** @} */
214/** @} */
Event timer header file.
void ctimer_init(void)
Initialize the callback timer library.
Definition ctimer.c:86
void ctimer_stop(struct ctimer *c)
Stop a pending callback timer.
Definition ctimer.c:150
void ctimer_reset(struct ctimer *c)
Reset a callback timer with the same interval as was previously set.
Definition ctimer.c:112
static clock_time_t ctimer_expiration_time(struct ctimer *c)
Get the expiration time for the callback timer.
Definition ctimer.h:175
bool ctimer_expired(struct ctimer *c)
Check if a callback timer has expired.
Definition ctimer.c:162
static void ctimer_set(struct ctimer *c, clock_time_t t, void(*f)(void *), void *ptr)
Set a callback timer.
Definition ctimer.h:150
void ctimer_reset_with_new_interval(struct ctimer *c, clock_time_t interval)
Reset a callback timer with a new interval.
Definition ctimer.c:124
void ctimer_restart(struct ctimer *c)
Restart a callback timer from the current point in time.
Definition ctimer.c:138
static clock_time_t ctimer_start_time(struct ctimer *c)
Get the start time for the callback timer.
Definition ctimer.h:189
void ctimer_set_with_process(struct ctimer *c, clock_time_t t, void(*f)(void *), void *ptr, struct process *p)
Set a callback timer.
Definition ctimer.c:93
clock_time_t etimer_start_time(struct etimer *et)
Get the start time for the event timer.
Definition etimer.c:219
clock_time_t etimer_expiration_time(struct etimer *et)
Get the expiration time for the event timer.
Definition etimer.c:213
#define PROCESS_CURRENT()
Get a pointer to the currently running process.
Definition process.h:404
A timer.
Definition etimer.h:79