A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
trickle-timer.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2020 Universita' di Firenze, Italy
3 *
4 * SPDX-License-Identifier: GPL-2.0-only
5 *
6 * Author: Tommaso Pecorella <tommaso.pecorella@unifi.it>
7 */
8
9#ifndef TRICKLE_TIMER_H
10#define TRICKLE_TIMER_H
11
12#include "event-id.h"
13#include "nstime.h"
15
16/**
17 * \file
18 * \ingroup timer
19 * ns3::TrickleTimer timer class declaration.
20 */
21
22namespace ns3
23{
24
25namespace internal
26{
27
28class TimerImpl;
29
30} // namespace internal
31
32/**
33 * \ingroup timer
34 * \brief A Trickle Timer following \RFC{6206}.
35 *
36 * A Trickle Timer is a timer that varies its frequency between a minimum
37 * and a maximum, depending on events. It is typically used to exchange
38 * information in a highly robust, energy efficient, simple, and scalable manner.
39 *
40 * The Trickle Timer has three parameters:
41 * - minInterval Minimum interval.
42 * - doublings Number of doublings to reach the maximum interval.
43 * - redundancy Redundancy constant.
44 *
45 * The timer *period* is variable. It starts at minInterval, and it doubles
46 * the period length up to maxInterval = std::exp2 (doublings) * minInterval.
47 *
48 * The period is reset to minInterval when an *inconsistent* event is detected
49 * (see `TrickleTimer::InconsistentEvent`).
50 *
51 * The actual function fired by the timer is *not* called when a period expires.
52 * Rather, it is called in random moment between half of the actual period,
53 * and the end of actual the period.
54 * Moreover, the function is *not* fired if the timer did detect in the actual
55 * period a number of *consistent* events (see `TrickleTimer::ConsistentEvent`)
56 * greater than the redundancy constant. Setting the redundancy constant to zero
57 * disables this feature.
58 *
59 * The Trickle Timer is mainly used to self-regulate the transmission of periodic
60 * information (e.g., Router Advertisements) in wireless networks - and
61 * particularly in LLNs. In these contexts the frequency of the timer is adjusted
62 * according to, e.g., RS multicast messages. Moreover, the redundancy constant
63 * can be used to avoid congestion in high density networks.
64 *
65 * Please refer to \RFC{6206} for a full description and discussion of the Trickle Timer.
66 */
68{
69 public:
70 /** Constructor. */
72
73 /**
74 * Constructor.
75 *
76 * The maximum interval is set to std::exp2 (doublings) * minInterval.
77 *
78 * \param minInterval Minimum interval.
79 * \param doublings Number of doublings to reach the maximum interval.
80 * \param redundancy Redundancy constant.
81 *
82 * A zero value in the redundancy constant means that the suppression
83 * algorithm is disabled.
84 *
85 */
86 TrickleTimer(Time minInterval, uint8_t doublings, uint16_t redundancy);
87
88 /** Destructor. */
90
91 /**
92 * Assigns the stream number for the uniform random number generator to use
93 *
94 * \param streamNum first stream index to use
95 * \return the number of stream indices assigned by this helper
96 */
97 int64_t AssignStreams(int64_t streamNum);
98
99 /**
100 * \brief Set the timer parameters.
101 *
102 * The maximum interval is set to std::exp2 (doublings) * minInterval.
103 *
104 * \param minInterval Minimum interval.
105 * \param doublings Number of doublings to reach the maximum interval.
106 * \param redundancy Redundancy constant.
107 *
108 * A zero value in the redundancy constant means that the suppression
109 * algorithm is disabled.
110 *
111 */
112 void SetParameters(Time minInterval, uint8_t doublings, uint16_t redundancy);
113
114 /**
115 * \brief Get the MinInterval of the timer.
116 * \return The MinInterval
117 */
118 Time GetMinInterval() const;
119
120 /**
121 * \brief Get the MaxInterval of the timer.
122 *
123 * The timer MaxInterval is always std::exp2 (doublings) * minInterval
124 * \return The MaxInterval
125 */
126 Time GetMaxInterval() const;
127
128 /**
129 * \brief Get the doublings of the timer.
130 * \return The doublings
131 */
132 uint8_t GetDoublings() const;
133
134 /**
135 * \brief Get the Redundancy constant of the timer.
136 * \return The Redundancy
137 */
138 uint16_t GetRedundancy() const;
139
140 /**
141 * \returns The amount of time left until this timer expires.
142 *
143 * This method returns zero if the timer has never been started.
144 */
145 Time GetDelayLeft() const;
146
147 /**
148 * \returns The amount of time left until this timer interval expires.
149 *
150 * This method returns zero if the timer has never been started.
151 */
152 Time GetIntervalLeft() const;
153
154 /**
155 * \brief Enable the timer.
156 */
157 void Enable();
158
159 /**
160 * \brief Records a consistent event.
161 */
162 void ConsistentEvent();
163
164 /**
165 * \brief Records an inconsistent event.
166 */
167 void InconsistentEvent();
168
169 /**
170 * \brief Reset the timer.
171 */
172 void Reset();
173
174 /**
175 * \brief Stop the timer.
176 *
177 * This will reset the timer and cancel all the pending events.
178 */
179 void Stop();
180
181 /**
182 * Set the function to execute when the timer expires.
183 *
184 * \tparam FN \deduced The type of the function.
185 * \param [in] fn The function
186 *
187 * Store this function in this Timer for later use by Timer::Schedule.
188 */
189 template <typename FN>
190 void SetFunction(FN fn);
191
192 /**
193 * Set the function to execute when the timer expires.
194 *
195 * \tparam MEM_PTR \deduced Class method function type.
196 * \tparam OBJ_PTR \deduced Class type containing the function.
197 * \param [in] memPtr The member function pointer
198 * \param [in] objPtr The pointer to object
199 *
200 * Store this function and object in this Timer for later use by Timer::Schedule.
201 */
202 template <typename MEM_PTR, typename OBJ_PTR>
203 void SetFunction(MEM_PTR memPtr, OBJ_PTR objPtr);
204
205 /**
206 * Set the arguments to be used when invoking the expire function.
207 */
208 /**@{*/
209 /**
210 * \tparam Ts \deduced Argument types.
211 * \param [in] args arguments
212 */
213 template <typename... Ts>
214 void SetArguments(Ts&&... args);
215 /**@}*/
216
217 private:
218 /** Internal callback invoked when the timer expires. */
219 void TimerExpire();
220 /** Internal callback invoked when the interval expires. */
221 void IntervalExpire();
222
223 /**
224 * The timer implementation, which contains the bound callback
225 * function and arguments.
226 */
228
229 /** The future event scheduled to expire the timer. */
231
232 /** The future event scheduled to expire the interval. */
234
235 Time m_minInterval; //!< Minimum interval
236 Time m_maxInterval; //!< Maximum interval
237 uint16_t m_redundancy; //!< Redundancy constant.
238
239 uint64_t m_ticks; //!< Interval span (i.e., exp2(doublings)).
240 Time m_currentInterval; //!< Current interval.
241 uint16_t m_counter; //!< Event counter.
242
243 Ptr<UniformRandomVariable> m_uniRand; //!< Object to generate uniform random numbers
244};
245
246} // namespace ns3
247
248/********************************************************************
249 * Implementation of the templates declared above.
250 ********************************************************************/
251
252#include "timer-impl.h"
253
254namespace ns3
255{
256
257template <typename FN>
258void
260{
261 delete m_impl;
263}
264
265template <typename MEM_PTR, typename OBJ_PTR>
266void
267TrickleTimer::SetFunction(MEM_PTR memPtr, OBJ_PTR objPtr)
268{
269 delete m_impl;
270 m_impl = internal::MakeTimerImpl(memPtr, objPtr);
271}
272
273template <typename... Ts>
274void
276{
277 if (m_impl == nullptr)
278 {
280 "You cannot set the arguments of a TrickleTimer before setting its function.");
281 return;
282 }
283 m_impl->SetArgs(std::forward<Ts>(args)...);
284}
285
286} // namespace ns3
287
288#endif /* TRICKLE_TIMER_H */
An identifier for simulation events.
Definition event-id.h:45
Smart pointer class similar to boost::intrusive_ptr.
Simulation virtual time values and global simulation resolution.
Definition nstime.h:94
A Trickle Timer following RFC 6206 .
int64_t AssignStreams(int64_t streamNum)
Assigns the stream number for the uniform random number generator to use.
uint8_t GetDoublings() const
Get the doublings of the timer.
Time m_minInterval
Minimum interval.
EventId m_timerExpiration
The future event scheduled to expire the timer.
void Stop()
Stop the timer.
Time m_currentInterval
Current interval.
Time m_maxInterval
Maximum interval.
void SetParameters(Time minInterval, uint8_t doublings, uint16_t redundancy)
Set the timer parameters.
internal::TimerImpl * m_impl
The timer implementation, which contains the bound callback function and arguments.
uint64_t m_ticks
Interval span (i.e., exp2(doublings)).
Time GetMinInterval() const
Get the MinInterval of the timer.
void InconsistentEvent()
Records an inconsistent event.
void Reset()
Reset the timer.
void TimerExpire()
Internal callback invoked when the timer expires.
EventId m_intervalExpiration
The future event scheduled to expire the interval.
Time GetDelayLeft() const
uint16_t GetRedundancy() const
Get the Redundancy constant of the timer.
void SetFunction(FN fn)
Set the function to execute when the timer expires.
void Enable()
Enable the timer.
Time GetMaxInterval() const
Get the MaxInterval of the timer.
Ptr< UniformRandomVariable > m_uniRand
Object to generate uniform random numbers.
~TrickleTimer()
Destructor.
void ConsistentEvent()
Records a consistent event.
void SetArguments(Ts &&... args)
Set the arguments to be used when invoking the expire function.
Time GetIntervalLeft() const
TrickleTimer()
Constructor.
uint16_t m_counter
Event counter.
void IntervalExpire()
Internal callback invoked when the interval expires.
uint16_t m_redundancy
Redundancy constant.
The timer implementation underlying Timer and Watchdog.
Definition timer-impl.h:35
void SetArgs(Args... args)
Set the arguments to be used when invoking the expire function.
Definition timer-impl.h:182
ns3::EventId declarations.
#define NS_FATAL_ERROR(msg)
Report a fatal error with a message and terminate.
TimerImpl * MakeTimerImpl(U(fn)(Ts...))
Make a TimerImpl from a function pointer taking varying numbers of arguments.
Definition timer-impl.h:92
Every class exported by the ns3 library is enclosed in the ns3 namespace.
Declaration of classes ns3::Time and ns3::TimeWithUnit, and the TimeValue implementation classes.
ns3::RandomVariableStream declaration, and related classes.
ns3::TimerImpl declaration and implementation.