A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
timer.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2007 INRIA
3 *
4 * SPDX-License-Identifier: GPL-2.0-only
5 *
6 * Author: Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
7 */
8#ifndef TIMER_H
9#define TIMER_H
10
11#include "event-id.h"
12#include "fatal-error.h"
13#include "nstime.h"
14
15/**
16 * @file
17 * @ingroup timer
18 * ns3::Timer class declaration.
19 */
20
21namespace ns3
22{
23
24/**
25 * @ingroup core
26 * @defgroup timer Virtual Time Timer and Watchdog
27 *
28 * The Timer and Watchdog objects both facilitate scheduling functions
29 * to execute a specified virtual time in the future.
30 *
31 * A Watchdog timer cannot be paused or cancelled once it has been started,
32 * however it can be lengthened (delayed). A Watchdog takes no action
33 * when it is destroyed.
34 *
35 * A Timer can be suspended, resumed, cancelled and queried for time left,
36 * but it can't be extended (except by suspending and resuming).
37 * In addition, it can be configured to take different actions when the
38 * Timer is destroyed.
39 */
40
41namespace internal
42{
43
44class TimerImpl;
45
46} // namespace internal
47
48/**
49 * @ingroup timer
50 * @brief A simple virtual Timer class
51 *
52 * A (virtual time) timer is used to hold together a delay, a function to invoke
53 * when the delay expires, and a set of arguments to pass to the function
54 * when the delay expires.
55 *
56 * A Timer can be suspended, resumed, cancelled and queried for the
57 * time left, but it can't be extended (except by suspending and
58 * resuming).
59 *
60 * A timer can also be used to enforce a set of predefined event lifetime
61 * management policies. These policies are specified at construction time
62 * and cannot be changed after.
63 *
64 * @see Watchdog for a simpler interface for a watchdog timer.
65 */
66class Timer
67{
68 public:
69 /**
70 * The policy to use to manager the internal timer when an
71 * instance of the Timer class is destroyed or suspended.
72 *
73 * In the case of suspension, only `CANCEL_ON_DESTROY` and
74 * `REMOVE_ON_DESTROY` apply.
75 *
76 * These symbols have "Destroy" in their names
77 * for historical reasons.
78 */
80 {
81 /**
82 * This policy cancels the event from the destructor of the Timer
83 * or from Suspend(). This is typically faster than `REMOVE_ON_DESTROY`
84 * but uses more memory.
85 */
87 /**
88 * This policy removes the event from the simulation event list
89 * when the destructor of the Timer is invoked, or the Timer is
90 * suspended. This is typically slower than Cancel, but frees memory.
91 */
93 /**
94 * This policy enforces a check from the destructor of the Timer
95 * to verify that the timer has already expired.
96 */
97 CHECK_ON_DESTROY = (1 << 5)
98 };
99
100 /** The possible states of the Timer. */
101 enum State
102 {
103 RUNNING, /**< Timer is currently running. */
104 EXPIRED, /**< Timer has already expired. */
105 SUSPENDED, /**< Timer is suspended. */
106 };
107
108 /**
109 * Create a timer with a default event lifetime management policy:
110 * - CHECK_ON_DESTROY
111 */
112 Timer();
113 /**
114 * @param [in] destroyPolicy the event lifetime management policies
115 * to use for destroy events
116 */
117 Timer(DestroyPolicy destroyPolicy);
118 ~Timer();
119
120 /**
121 * @tparam FN \deduced The type of the function.
122 * @param [in] fn the function
123 *
124 * Store this function in this Timer for later use by Timer::Schedule.
125 */
126 template <typename FN>
127 void SetFunction(FN fn);
128
129 /**
130 * @tparam MEM_PTR \deduced The type of the class member function.
131 * @tparam OBJ_PTR \deduced The type of the class instance pointer.
132 * @param [in] memPtr the member function pointer
133 * @param [in] objPtr the pointer to object
134 *
135 * Store this function and object in this Timer for later use by
136 * Timer::Schedule.
137 */
138 template <typename MEM_PTR, typename OBJ_PTR>
139 void SetFunction(MEM_PTR memPtr, OBJ_PTR objPtr);
140
141 /**
142 * @tparam Ts \deduced Argument types
143 * @param [in] args arguments
144 *
145 * Store these arguments in this Timer for later use by Timer::Schedule.
146 */
147 template <typename... Ts>
148 void SetArguments(Ts... args);
149
150 /**
151 * @param [in] delay The delay
152 *
153 * The next call to Schedule will schedule the timer with this delay.
154 */
155 void SetDelay(const Time& delay);
156 /**
157 * @returns The currently-configured delay for the next Schedule.
158 */
159 Time GetDelay() const;
160 /**
161 * @returns The amount of time left until this timer expires.
162 *
163 * This method returns zero if the timer is in EXPIRED state.
164 */
165 Time GetDelayLeft() const;
166 /**
167 * Cancel the currently-running event if there is one. Do nothing
168 * otherwise.
169 */
170 void Cancel();
171 /**
172 * Remove from the simulation event-list the currently-running event
173 * if there is one. Do nothing otherwise.
174 */
175 void Remove();
176 /**
177 * @return \c true if there is no currently-running event,
178 * \c false otherwise.
179 */
180 bool IsExpired() const;
181 /**
182 * @return \c true if there is a currently-running event,
183 * \c false otherwise.
184 */
185 bool IsRunning() const;
186 /**
187 * @returns \c true if this timer was suspended and not yet resumed,
188 * \c false otherwise.
189 */
190 bool IsSuspended() const;
191 /**
192 * @returns The current state of the timer.
193 */
194 Timer::State GetState() const;
195 /**
196 * Schedule a new event using the currently-configured delay, function,
197 * and arguments.
198 */
199 void Schedule();
200 /**
201 * @param [in] delay the delay to use
202 *
203 * Schedule a new event using the specified delay (ignore the delay set by
204 * Timer::SetDelay), function, and arguments.
205 */
206 void Schedule(Time delay);
207
208 /**
209 * Pause the timer and save the amount of time left until it was
210 * set to expire.
211 *
212 * Subsequently calling Resume() will restart the Timer with the
213 * remaining time.
214 *
215 * The DestroyPolicy set at construction determines
216 * whether the underlying Simulator::Event is cancelled or removed.
217 *
218 * Calling Suspend on a non-running timer is an error.
219 */
220 void Suspend();
221 /**
222 * Restart the timer to expire within the amount of time left saved
223 * during Suspend.
224 * Calling Resume without a prior call to Suspend is an error.
225 */
226 void Resume();
227
228 private:
229 /** Internal bit marking the suspended timer state */
230 static constexpr auto TIMER_SUSPENDED{1 << 7};
231
232 /**
233 * Bitfield for Timer State, DestroyPolicy and InternalSuspended.
234 *
235 * @internal
236 * The DestroyPolicy, State and InternalSuspended state are stored
237 * in this single bitfield. The State uses the low-order bits,
238 * so the other users of the bitfield have to be careful in defining
239 * their bits to avoid the State.
240 */
242 /** The delay configured for this Timer. */
244 /** The future event scheduled to expire the timer. */
246 /**
247 * The timer implementation, which contains the bound callback
248 * function and arguments.
249 */
251 /** The amount of time left on the Timer while it is suspended. */
253};
254
255} // namespace ns3
256
257/********************************************************************
258 * Implementation of the templates declared above.
259 ********************************************************************/
260
261#include "timer-impl.h"
262
263namespace ns3
264{
265
266template <typename FN>
267void
269{
270 delete m_impl;
272}
273
274template <typename MEM_PTR, typename OBJ_PTR>
275void
276Timer::SetFunction(MEM_PTR memPtr, OBJ_PTR objPtr)
277{
278 delete m_impl;
279 m_impl = internal::MakeTimerImpl(memPtr, objPtr);
280}
281
282template <typename... Ts>
283void
285{
286 if (m_impl == nullptr)
287 {
288 NS_FATAL_ERROR("You cannot set the arguments of a Timer before setting its function.");
289 return;
290 }
291 m_impl->SetArgs(args...);
292}
293
294} // namespace ns3
295
296#endif /* TIMER_H */
An identifier for simulation events.
Definition event-id.h:45
Simulation virtual time values and global simulation resolution.
Definition nstime.h:94
A simple virtual Timer class.
Definition timer.h:67
void SetDelay(const Time &delay)
Definition timer.cc:65
void SetFunction(FN fn)
Definition timer.h:268
internal::TimerImpl * m_impl
The timer implementation, which contains the bound callback function and arguments.
Definition timer.h:250
bool IsExpired() const
Definition timer.cc:111
Timer()
Create a timer with a default event lifetime management policy:
Definition timer.cc:25
EventId m_event
The future event scheduled to expire the timer.
Definition timer.h:245
Time GetDelayLeft() const
Definition timer.cc:79
Timer::State GetState() const
Definition timer.cc:132
void SetArguments(Ts... args)
Definition timer.h:284
int m_flags
Bitfield for Timer State, DestroyPolicy and InternalSuspended.
Definition timer.h:241
DestroyPolicy
The policy to use to manager the internal timer when an instance of the Timer class is destroyed or s...
Definition timer.h:80
@ CANCEL_ON_DESTROY
This policy cancels the event from the destructor of the Timer or from Suspend().
Definition timer.h:86
@ CHECK_ON_DESTROY
This policy enforces a check from the destructor of the Timer to verify that the timer has already ex...
Definition timer.h:97
@ REMOVE_ON_DESTROY
This policy removes the event from the simulation event list when the destructor of the Timer is invo...
Definition timer.h:92
State
The possible states of the Timer.
Definition timer.h:102
@ RUNNING
Timer is currently running.
Definition timer.h:103
@ EXPIRED
Timer has already expired.
Definition timer.h:104
@ SUSPENDED
Timer is suspended.
Definition timer.h:105
static constexpr auto TIMER_SUSPENDED
Internal bit marking the suspended timer state.
Definition timer.h:230
void Cancel()
Cancel the currently-running event if there is one.
Definition timer.cc:97
Time GetDelay() const
Definition timer.cc:72
bool IsSuspended() const
Definition timer.cc:125
Time m_delay
The delay configured for this Timer.
Definition timer.h:243
void Remove()
Remove from the simulation event-list the currently-running event if there is one.
Definition timer.cc:104
void Schedule()
Schedule a new event using the currently-configured delay, function, and arguments.
Definition timer.cc:151
Time m_delayLeft
The amount of time left on the Timer while it is suspended.
Definition timer.h:252
void Resume()
Restart the timer to expire within the amount of time left saved during Suspend.
Definition timer.cc:187
bool IsRunning() const
Definition timer.cc:118
void Suspend()
Pause the timer and save the amount of time left until it was set to expire.
Definition timer.cc:170
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.
NS_FATAL_x macro definitions.
#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::TimerImpl declaration and implementation.