A Discrete-Event Network Simulator
API
ns3::Timer Class Reference

A simple virtual Timer class. More...

#include "timer.h"

+ Collaboration diagram for ns3::Timer:

Public Types

enum  DestroyPolicy { CANCEL_ON_DESTROY = (1 << 3), REMOVE_ON_DESTROY = (1 << 4), CHECK_ON_DESTROY = (1 << 5) }
 The policy to use to manager the internal timer when an instance of the Timer class is destroyed or suspended. More...
 
enum  State { RUNNING, EXPIRED, SUSPENDED }
 The possible states of the Timer. More...
 

Public Member Functions

 Timer ()
 Create a timer with a default event lifetime management policy: More...
 
 Timer (enum DestroyPolicy destroyPolicy)
 
 ~Timer ()
 
void Cancel (void)
 Cancel the currently-running event if there is one. More...
 
Time GetDelay (void) const
 
Time GetDelayLeft (void) const
 
enum Timer::State GetState (void) const
 
bool IsExpired (void) const
 
bool IsRunning (void) const
 
bool IsSuspended (void) const
 
void Remove (void)
 Remove from the simulation event-list the currently-running event if there is one. More...
 
void Resume (void)
 Restart the timer to expire within the amount of time left saved during Suspend. More...
 
void Schedule (Time delay)
 
void Schedule (void)
 Schedule a new event using the currently-configured delay, function, and arguments. More...
 
template<typename... Ts>
void SetArguments (Ts... args)
 
void SetDelay (const Time &delay)
 
template<typename FN >
void SetFunction (FN fn)
 
template<typename MEM_PTR , typename OBJ_PTR >
void SetFunction (MEM_PTR memPtr, OBJ_PTR objPtr)
 
void Suspend (void)
 Pause the timer and save the amount of time left until it was set to expire. More...
 

Private Types

enum  InternalSuspended { TIMER_SUSPENDED = (1 << 7) }
 Internal bit marking the suspended state. More...
 

Private Attributes

Time m_delay
 The delay configured for this Timer. More...
 
Time m_delayLeft
 The amount of time left on the Timer while it is suspended. More...
 
EventId m_event
 The future event scheduled to expire the timer. More...
 
int m_flags
 Bitfield for Timer State, DestroyPolicy and InternalSuspended. More...
 
TimerImplm_impl
 The timer implementation, which contains the bound callback function and arguments. More...
 

Detailed Description

A simple virtual Timer class.

A (virtual time) timer is used to hold together a delay, a function to invoke when the delay expires, and a set of arguments to pass to the function when the delay expires.

A Timer can be suspended, resumed, cancelled and queried for the time left, but it can't be extended (except by suspending and resuming).

A timer can also be used to enforce a set of predefined event lifetime management policies. These policies are specified at construction time and cannot be changed after.

See also
Watchdog for a simpler interface for a watchdog Virtual Time Timer and Watchdog.

Definition at line 73 of file timer.h.

Member Enumeration Documentation

◆ DestroyPolicy

The policy to use to manager the internal timer when an instance of the Timer class is destroyed or suspended.

In the case of suspension, only CANCEL_ON_DESTROY and REMOVE_ON_DESTROY apply.

These symbols have "Destroy" in their names for historical reasons.

Enumerator
CANCEL_ON_DESTROY 

This policy cancels the event from the destructor of the Timer or from Suspend().

This is typically faster than REMOVE_ON_DESTROY but uses more memory.

REMOVE_ON_DESTROY 

This policy removes the event from the simulation event list when the destructor of the Timer is invoked, or the Timer is suspended.

This is typically slower than Cancel, but frees memory.

CHECK_ON_DESTROY 

This policy enforces a check from the destructor of the Timer to verify that the timer has already expired.

Definition at line 86 of file timer.h.

◆ InternalSuspended

Internal bit marking the suspended state.

Enumerator
TIMER_SUSPENDED 

Definition at line 236 of file timer.h.

◆ State

The possible states of the Timer.

Enumerator
RUNNING 

Timer is currently running.

EXPIRED 

Timer has already expired.

SUSPENDED 

Timer is suspended.

Definition at line 107 of file timer.h.

Constructor & Destructor Documentation

◆ Timer() [1/2]

ns3::Timer::Timer ( )

Create a timer with a default event lifetime management policy:

  • CHECK_ON_DESTROY

Definition at line 35 of file timer.cc.

References NS_LOG_FUNCTION.

◆ Timer() [2/2]

ns3::Timer::Timer ( enum DestroyPolicy  destroyPolicy)
Parameters
[in]destroyPolicythe event lifetime management policies to use for destroy events

Definition at line 44 of file timer.cc.

References NS_LOG_FUNCTION.

◆ ~Timer()

ns3::Timer::~Timer ( )

Member Function Documentation

◆ Cancel()

◆ GetDelay()

Time ns3::Timer::GetDelay ( void  ) const
Returns
The currently-configured delay for the next Schedule.

Definition at line 81 of file timer.cc.

References m_delay, and NS_LOG_FUNCTION.

◆ GetDelayLeft()

Time ns3::Timer::GetDelayLeft ( void  ) const
Returns
The amount of time left until this timer expires.

This method returns zero if the timer is in EXPIRED state.

Definition at line 87 of file timer.cc.

References EXPIRED, ns3::Simulator::GetDelayLeft(), GetState(), m_delayLeft, m_event, NS_ASSERT, NS_LOG_FUNCTION, RUNNING, and SUSPENDED.

Referenced by ns3::dsdv::RoutingProtocol::RecvDsdv(), ns3::TcpSocketBase::SendPendingData(), ns3::aodv::RoutingProtocol::SendRequest(), ns3::aodv::RoutingProtocol::SendRerrMessage(), and ns3::aodv::RoutingProtocol::SendRerrWhenNoRouteToForward().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ GetState()

enum Timer::State ns3::Timer::GetState ( void  ) const
Returns
The current state of the timer.

Definition at line 133 of file timer.cc.

Referenced by TimerStateTestCase::DoRun(), and GetDelayLeft().

+ Here is the caller graph for this function:

◆ IsExpired()

bool ns3::Timer::IsExpired ( void  ) const
Returns
true if there is no currently-running event, false otherwise.

Definition at line 121 of file timer.cc.

References ns3::EventId::IsExpired(), IsSuspended(), m_event, and NS_LOG_FUNCTION.

Referenced by TimerStateTestCase::DoRun(), ns3::TcpSocketBase::SendDataPacket(), and ns3::TcpSocketBase::SendPendingData().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ IsRunning()

bool ns3::Timer::IsRunning ( void  ) const

◆ IsSuspended()

bool ns3::Timer::IsSuspended ( void  ) const
Returns
true if this timer was suspended and not yet resumed, false otherwise.

Definition at line 133 of file timer.cc.

References m_flags, NS_LOG_FUNCTION, and TIMER_SUSPENDED.

Referenced by ns3::dsr::DsrRouting::CheckSendBuffer(), TimerStateTestCase::DoRun(), IsExpired(), and IsRunning().

+ Here is the caller graph for this function:

◆ Remove()

void ns3::Timer::Remove ( void  )

Remove from the simulation event-list the currently-running event if there is one.

Do nothing otherwise.

Definition at line 115 of file timer.cc.

References m_event, NS_LOG_FUNCTION, and ns3::EventId::Remove().

+ Here is the call graph for this function:

◆ Resume()

void ns3::Timer::Resume ( void  )

Restart the timer to expire within the amount of time left saved during Suspend.

Calling Resume without a prior call to Suspend is an error.

Definition at line 194 of file timer.cc.

References m_delayLeft, m_event, m_flags, m_impl, NS_ASSERT, NS_LOG_FUNCTION, ns3::TimerImpl::Schedule(), and TIMER_SUSPENDED.

Referenced by ns3::dsr::DsrRouting::CheckSendBuffer(), and TimerStateTestCase::DoRun().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ Schedule() [1/2]

void ns3::Timer::Schedule ( Time  delay)
Parameters
[in]delaythe delay to use

Schedule a new event using the specified delay (ignore the delay set by Timer::SetDelay), function, and arguments.

Definition at line 165 of file timer.cc.

References ns3::EventId::IsRunning(), m_event, m_impl, NS_ASSERT, NS_FATAL_ERROR, NS_LOG_FUNCTION, and ns3::TimerImpl::Schedule().

+ Here is the call graph for this function:

◆ Schedule() [2/2]

◆ SetArguments()

template<typename... Ts>
void ns3::Timer::SetArguments ( Ts...  args)
Template Parameters
Ts[deduced] Argument types
Parameters
[in]argsarguments

Store these arguments in this Timer for later use by Timer::Schedule.

Definition at line 293 of file timer.h.

References m_impl, NS_FATAL_ERROR, and ns3::TimerImpl::SetArgs().

Referenced by TimerStateTestCase::DoRun(), TimerTemplateTestCase::DoRun(), and ns3::aodv::RoutingProtocol::SendReplyByIntermediateNode().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ SetDelay()

void ns3::Timer::SetDelay ( const Time delay)

◆ SetFunction() [1/2]

template<typename FN >
void ns3::Timer::SetFunction ( FN  fn)

◆ SetFunction() [2/2]

template<typename MEM_PTR , typename OBJ_PTR >
void ns3::Timer::SetFunction ( MEM_PTR  memPtr,
OBJ_PTR  objPtr 
)
Template Parameters
MEM_PTR[deduced] The type of the class member function.
OBJ_PTR[deduced] The type of the class instance pointer.
Parameters
[in]memPtrthe member function pointer
[in]objPtrthe pointer to object

Store this function and object in this Timer for later use by Timer::Schedule.

Definition at line 285 of file timer.h.

References m_impl, and ns3::MakeTimerImpl().

+ Here is the call graph for this function:

◆ Suspend()

void ns3::Timer::Suspend ( void  )

Pause the timer and save the amount of time left until it was set to expire.

Subsequently calling Resume() will restart the Timer with the remaining time.

The DestroyPolicy set at construction determines whether the underlying Simulator::Event is cancelled or removed.

Calling Suspend on a non-running timer is an error.

Definition at line 177 of file timer.cc.

References ns3::EventId::Cancel(), CANCEL_ON_DESTROY, ns3::Simulator::GetDelayLeft(), IsRunning(), m_delayLeft, m_event, m_flags, NS_ASSERT, NS_LOG_FUNCTION, ns3::EventId::Remove(), REMOVE_ON_DESTROY, and TIMER_SUSPENDED.

Referenced by ns3::dsr::DsrRouting::CheckSendBuffer(), and TimerStateTestCase::DoRun().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

Member Data Documentation

◆ m_delay

Time ns3::Timer::m_delay
private

The delay configured for this Timer.

Definition at line 252 of file timer.h.

Referenced by GetDelay(), Schedule(), and SetDelay().

◆ m_delayLeft

Time ns3::Timer::m_delayLeft
private

The amount of time left on the Timer while it is suspended.

Definition at line 261 of file timer.h.

Referenced by GetDelayLeft(), Resume(), and Suspend().

◆ m_event

EventId ns3::Timer::m_event
private

The future event scheduled to expire the timer.

Definition at line 254 of file timer.h.

Referenced by ~Timer(), Cancel(), GetDelayLeft(), IsExpired(), IsRunning(), Remove(), Resume(), Schedule(), and Suspend().

◆ m_flags

int ns3::Timer::m_flags
private

Bitfield for Timer State, DestroyPolicy and InternalSuspended.

Internal:
The DestroyPolicy, State and InternalSuspended state are stored in this single bitfield. The State uses the low-order bits, so the other users of the bitfield have to be careful in defining their bits to avoid the State.

Definition at line 250 of file timer.h.

Referenced by ~Timer(), IsSuspended(), Resume(), and Suspend().

◆ m_impl

TimerImpl* ns3::Timer::m_impl
private

The timer implementation, which contains the bound callback function and arguments.

Definition at line 259 of file timer.h.

Referenced by ~Timer(), Resume(), Schedule(), SetArguments(), and SetFunction().


The documentation for this class was generated from the following files: