SunnyQjm/ns-3-dev
1
0 Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

[Doxygen] Timer, TimerImpl and Watchdog.

Browse Source
This commit is contained in:
Peter D. Barnes, Jr. committed 2014-12-09 14:37:02 -08:00
1 parent 345c8a94ac
commit f71a5e0b5c
5 files changed
+386 -30
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

src/core/model/timer-impl.h
+249 -1
View File
@@ -26,76 +26,228 @@
#include "fatal-error.h"
#include "int-to-type.h"
/**
* \file
* \ingroup timer
* \ingroup timerimpl
* ns3::TimerImpl declaration and implementation.
*/
namespace ns3 {
/**
* \ingroup timer
* The timer implementation underlying Timer and Watchdog.
*/
class TimerImpl
{
public:
/** Destructor. */
virtual ~TimerImpl ()
{
}
/**
* Set the arguments to be used when invoking the expire function.
*/
/**@{*/
/**
* \tparam T1 Type of the first argument.
* \param a1 The first argument
*/
template <typename T1>
void SetArgs (T1 a1);
/**
* \tparam T1 Type of the first argument.
* \tparam T2 Type of the second argument.
* \param a1 the first argument
* \param a2 the second argument
*/
template <typename T1, typename T2>
void SetArgs (T1 a1, T2 a2);
/**
* \tparam T1 Type of the first argument.
* \tparam T2 Type of the second argument.
* \tparam T3 Type of the third argument.
* \param a1 the first argument
* \param a2 the second argument
* \param a3 the third argument
*/
template <typename T1, typename T2, typename T3>
void SetArgs (T1 a1, T2 a2, T3 a3);
/**
* \tparam T1 Type of the first argument.
* \tparam T2 Type of the second argument.
* \tparam T3 Type of the third argument.
* \tparam T4 Type of the fourth argument.
* \param a1 the first argument
* \param a2 the second argument
* \param a3 the third argument
* \param a4 the fourth argument
*/
template <typename T1, typename T2, typename T3,
typename T4>
void SetArgs (T1 a1, T2 a2, T3 a3, T4 a4);
/**
* \tparam T1 Type of the first argument.
* \tparam T2 Type of the second argument.
* \tparam T3 Type of the third argument.
* \tparam T4 Type of the fourth argument.
* \tparam T5 Type of the fifth argument.
* \param a1 the first argument
* \param a2 the second argument
* \param a3 the third argument
* \param a4 the fourth argument
* \param a5 the fifth argument
*/
template <typename T1, typename T2, typename T3,
typename T4, typename T5>
void SetArgs (T1 a1, T2 a2, T3 a3, T4 a4, T5 a5);
/**
* \tparam T1 Type of the first argument.
* \tparam T2 Type of the second argument.
* \tparam T3 Type of the third argument.
* \tparam T4 Type of the fourth argument.
* \tparam T5 Type of the fifth argument.
* \tparam T6 Type of the sixth argument.
* \param a1 the first argument
* \param a2 the second argument
* \param a3 the third argument
* \param a4 the fourth argument
* \param a5 the fifth argument
* \param a6 the sixth argument
*/
template <typename T1, typename T2, typename T3,
typename T4, typename T5, typename T6>
void SetArgs (T1 a1, T2 a2, T3 a3, T4 a4, T5 a5, T6 a6);
/**@}*/
/**
* Schedule the callback for a future time.
*
* \param delay The amount of time until the timer expires.
* \returns The scheduled EventId.
*/
virtual EventId Schedule (const Time &delay) = 0;
/** Invoke the expire function. */
virtual void Invoke (void) = 0;
};
} // namespace ns3
/********************************************************************
Implementation of TimerImpl implementation functions.
********************************************************************/
namespace ns3 {
/**
* \ingroup timer
* \defgroup timerimpl TimerImpl implementation details.
* @{
*/
/** TimerImpl specialization class for varying numbers of arguments. */
template <typename T1>
struct TimerImplOne : public TimerImpl
{
/**
* Bind the arguments to be used when the callback function is invoked.
*
* \param a1 The first argument.
*/
virtual void SetArguments (T1 a1) = 0;
};
/** TimerImpl specialization class for varying numbers of arguments. */
template <typename T1, typename T2>
struct TimerImplTwo : public TimerImpl
{
/**
* Bind the arguments to be used when the callback function is invoked.
*
* \param a1 The first argument.
* \param a2 The second argument.
*/
virtual void SetArguments (T1 a1,T2 a2) = 0;
};
/** TimerImpl specialization class for varying numbers of arguments. */
template <typename T1, typename T2, typename T3>
struct TimerImplThree : public TimerImpl
{
/**
* Bind the arguments to be used when the callback function is invoked.
*
* \param a1 The first argument.
* \param a2 The second argument.
* \param a3 The third argument.
*/
virtual void SetArguments (T1 a1,T2 a2,T3 a3) = 0;
};
/** TimerImpl specialization class for varying numbers of arguments. */
template <typename T1, typename T2, typename T3, typename T4>
struct TimerImplFour : public TimerImpl
{
/**
* Bind the arguments to be used when the callback function is invoked.
*
* \param a1 The first argument.
* \param a2 The second argument.
* \param a3 The third argument.
* \param a4 The fourth argument.
*/
virtual void SetArguments (T1 a1,T2 a2,T3 a3, T4 a4) = 0;
};
/** TimerImpl specialization class for varying numbers of arguments. */
template <typename T1, typename T2, typename T3, typename T4, typename T5>
struct TimerImplFive : public TimerImpl
{
/**
* Bind the arguments to be used when the callback function is invoked.
*
* \param a1 The first argument.
* \param a2 The second argument.
* \param a3 The third argument.
* \param a4 The fourth argument.
* \param a5 The fifth argument.
*/
virtual void SetArguments (T1 a1,T2 a2,T3 a3, T4 a4, T5 a5) = 0;
};
/** TimerImpl specialization class for varying numbers of arguments. */
template <typename T1, typename T2, typename T3, typename T4, typename T5, typename T6>
struct TimerImplSix : public TimerImpl
{
/**
* Bind the arguments to be used when the callback function is invoked.
*
* \param a1 The first argument.
* \param a2 The second argument.
* \param a3 The third argument.
* \param a4 The fourth argument.
* \param a5 The fifth argument.
* \param a6 The sixth argument.
*/
virtual void SetArguments (T1 a1,T2 a2,T3 a3, T4 a4, T5 a5, T6 a6) = 0;
};
/** Type and reference traits for TimerImpl arguments. */
template <typename T>
struct TimerTraits
{
/** Storage type for an argument. */
typedef typename TypeTraits<typename TypeTraits<T>::ReferencedType>::NonConstType StoredType;
/** Parameter type for an argument. */
typedef const StoredType &ParameterType;
};
/**
* Make a TimerImpl from a function pointer taking varying numbers of arguments.
*
* \tparam FN Function signature type of the callback function.
* \param fn The function pointer to invoke when the timer expires.
* \returns The TimerImpl.
*/
template <typename FN>
TimerImpl *
MakeTimerImpl (FN fn)
@@ -104,6 +256,10 @@ MakeTimerImpl (FN fn)
return MakeTimerImpl (IntToType<TypeTraits<FN>::FunctionPointerTraits::nArgs> (), fn);
}
/**
* Make a TimerImpl from a function pointer taking zero arguments.
* \copydetails MakeTimerImpl(FN)
*/
template <typename FN>
TimerImpl *
MakeTimerImpl (IntToType<0>, FN fn)
@@ -127,6 +283,10 @@ MakeTimerImpl (IntToType<0>, FN fn)
return function;
}
/**
* Make a TimerImpl from a function pointer taking one argument.
* \copydetails MakeTimerImpl(FN)
*/
template <typename FN>
TimerImpl *
MakeTimerImpl (IntToType<1>, FN fn)
@@ -159,6 +319,10 @@ MakeTimerImpl (IntToType<1>, FN fn)
return function;
}
/**
* Make a TimerImpl from a function pointer taking two arguments.
* \copydetails MakeTimerImpl(FN)
*/
template <typename FN>
TimerImpl *
MakeTimerImpl (IntToType<2>, FN fn)
@@ -196,6 +360,10 @@ MakeTimerImpl (IntToType<2>, FN fn)
return function;
}
/**
* Make a TimerImpl from a function pointer taking three arguments.
* \copydetails MakeTimerImpl(FN)
*/
template <typename FN>
TimerImpl *
MakeTimerImpl (IntToType<3>, FN fn)
@@ -238,6 +406,10 @@ MakeTimerImpl (IntToType<3>, FN fn)
return function;
}
/**
* Make a TimerImpl from a function pointer taking four arguments.
* \copydetails MakeTimerImpl(FN)
*/
template <typename FN>
TimerImpl *
MakeTimerImpl (IntToType<4>, FN fn)
@@ -285,6 +457,10 @@ MakeTimerImpl (IntToType<4>, FN fn)
return function;
}
/**
* Make a TimerImpl from a function pointer taking five arguments.
* \copydetails MakeTimerImpl(FN)
*/
template <typename FN>
TimerImpl *
MakeTimerImpl (IntToType<5>, FN fn)
@@ -337,6 +513,10 @@ MakeTimerImpl (IntToType<5>, FN fn)
return function;
}
/**
* Make a TimerImpl from a function pointer taking six arguments.
* \copydetails MakeTimerImpl(FN)
*/
template <typename FN>
TimerImpl *
MakeTimerImpl (IntToType<6>, FN fn)
@@ -395,19 +575,53 @@ MakeTimerImpl (IntToType<6>, FN fn)
}
/**
* Helper for the MakeTimerImpl functions which take a class method.
*
* This helper converts a pointer to a reference.
*
* This is the generic template declaration (with empty body).
*
* \tparam T The object type.
*/
template <typename T>
struct TimerImplMemberTraits;
/**
* Helper for the MakeTimerImpl functions which take a class method.
*
* This helper converts a pointer to a reference.
*
* This is the specialization for pointer to \c T.
*
* \tparam T The object type.
*/
template <typename T>
struct TimerImplMemberTraits<T *>
{
/**
* Convert a pointer type to a reference.
*
* \param p The pointer.
* \returns A reference to the object pointed to by \c p.
*/
static T &GetReference (T *p)
{
return *p;
}
};
/**
* Make a TimerImpl from a class method pointer taking
* a varying number of arguments.
*
* \tparam MEM_PTR Class method function signature type.
* \tparam OBJ_PTR Class type.
* \param memPtr Class method to invoke when the timer expires.
* \param objPtr Object instance pointer.
* \returns The TimerImpl.
*/
template <typename MEM_PTR, typename OBJ_PTR>
TimerImpl *
MakeTimerImpl (MEM_PTR memPtr, OBJ_PTR objPtr)
@@ -416,6 +630,10 @@ MakeTimerImpl (MEM_PTR memPtr, OBJ_PTR objPtr)
return MakeTimerImpl (IntToType<TypeTraits<MEM_PTR>::PointerToMemberTraits::nArgs> (), memPtr, objPtr);
}
/**
* Make a TimerImpl from a function pointer taking zero arguments.
* \copydetails MakeTimerImpl(MEM_PTR,OBJ_PTR)
*/
template <typename MEM_PTR, typename OBJ_PTR>
TimerImpl *
MakeTimerImpl (IntToType<0>, MEM_PTR memPtr, OBJ_PTR objPtr)
@@ -441,6 +659,10 @@ MakeTimerImpl (IntToType<0>, MEM_PTR memPtr, OBJ_PTR objPtr)
return function;
}
/**
* Make a TimerImpl from a function pointer taking one argument.
* \copydetails MakeTimerImpl(MEM_PTR,OBJ_PTR)
*/
template <typename MEM_PTR, typename OBJ_PTR>
TimerImpl *
MakeTimerImpl (IntToType<1>, MEM_PTR memPtr, OBJ_PTR objPtr)
@@ -475,6 +697,10 @@ MakeTimerImpl (IntToType<1>, MEM_PTR memPtr, OBJ_PTR objPtr)
return function;
}
/**
* Make a TimerImpl from a function pointer taking two arguments.
* \copydetails MakeTimerImpl(MEM_PTR,OBJ_PTR)
*/
template <typename MEM_PTR, typename OBJ_PTR>
TimerImpl *
MakeTimerImpl (IntToType<2>, MEM_PTR memPtr, OBJ_PTR objPtr)
@@ -514,6 +740,10 @@ MakeTimerImpl (IntToType<2>, MEM_PTR memPtr, OBJ_PTR objPtr)
return function;
}
/**
* Make a TimerImpl from a function pointer taking three arguments.
* \copydetails MakeTimerImpl(MEM_PTR,OBJ_PTR)
*/
template <typename MEM_PTR, typename OBJ_PTR>
TimerImpl *
MakeTimerImpl (IntToType<3>, MEM_PTR memPtr, OBJ_PTR objPtr)
@@ -558,6 +788,10 @@ MakeTimerImpl (IntToType<3>, MEM_PTR memPtr, OBJ_PTR objPtr)
return function;
}
/**
* Make a TimerImpl from a function pointer taking four arguments.
* \copydetails MakeTimerImpl(MEM_PTR,OBJ_PTR)
*/
template <typename MEM_PTR, typename OBJ_PTR>
TimerImpl *
MakeTimerImpl (IntToType<4>, MEM_PTR memPtr, OBJ_PTR objPtr)
@@ -607,6 +841,10 @@ MakeTimerImpl (IntToType<4>, MEM_PTR memPtr, OBJ_PTR objPtr)
return function;
}
/**
* Make a TimerImpl from a function pointer taking five arguments.
* \copydetails MakeTimerImpl(MEM_PTR,OBJ_PTR)
*/
template <typename MEM_PTR, typename OBJ_PTR>
TimerImpl *
MakeTimerImpl (IntToType<5>, MEM_PTR memPtr, OBJ_PTR objPtr)
@@ -661,6 +899,10 @@ MakeTimerImpl (IntToType<5>, MEM_PTR memPtr, OBJ_PTR objPtr)
return function;
}
/**
* Make a TimerImpl from a function pointer taking six arguments.
* \copydetails MakeTimerImpl(MEM_PTR,OBJ_PTR)
*/
template <typename MEM_PTR, typename OBJ_PTR>
TimerImpl *
MakeTimerImpl (IntToType<6>, MEM_PTR memPtr, OBJ_PTR objPtr)
@@ -720,7 +962,13 @@ MakeTimerImpl (IntToType<6>, MEM_PTR memPtr, OBJ_PTR objPtr)
return function;
}
/**@}*/ // \ingroup timer
/********************************************************************
Implementation of TimerImpl itself.
********************************************************************/
template <typename T1>
void
TimerImpl::SetArgs (T1 a1)
src/core/model/timer.cc
+1
View File
@@ -22,6 +22,7 @@
#include "simulation-singleton.h"
#include "log.h"
namespace ns3 {
NS_LOG_COMPONENT_DEFINE ("Timer");
src/core/model/timer.h
+61 -10
View File
@@ -25,28 +25,56 @@
#include "event-id.h"
#include "int-to-type.h"
/**
* \file
* \ingroup timer
* ns3::Timer class declaration.
*/
namespace ns3 {
/**
* \ingroup core
* \defgroup timer Virtual Time Timer and Watchdog
*
* The Timer and Watchdog objects both facilitate scheduling functions
* to execute a specified virtual time in the future.
*
* A Watchdog timer cannot be paused or cancelled once it has been started,
* however it can be lengthened (delayed). A Watchdog takes no action
* when it is destroyed.
*
* A Timer can be suspended, resumed, cancelled and queried for time left,
* but it can't be extended (except by suspending and resuming).
* In addition, it can be configured to take different actions when the
* Timer is destroyed.
*/
class TimerImpl;
/**
* \ingroup core
*
* \brief a simple Timer class
* \ingroup timer
* \brief A simple Timer class
*
* A 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 Watchdog for a simpler interface for a watchdog timer.
*/
class Timer
{
public:
/**
* The policy to use to manager the internal timer when and
* The policy to use to manager the internal timer when an
* instance of the Timer class is destroyed.
*/
enum DestroyPolicy
@@ -67,14 +95,15 @@ public:
*/
CHECK_ON_DESTROY = (1 << 5)
};
/** The possible states of the Timer. */
enum State
{
RUNNING,
EXPIRED,
SUSPENDED,
RUNNING, /** Timer is currently running. */
EXPIRED, /** Timer has already expired. */
SUSPENDED, /** Timer is suspended. */
};
/**
* create a timer with a default event lifetime management policy:
* Create a timer with a default event lifetime management policy:
* - CHECK_ON_DESTROY
*/
Timer ();
@@ -230,20 +259,42 @@ public:
void Resume (void);
private:
enum
/** Internal bit marking the suspended state. */
enum InternalSuspended
{
TIMER_SUSPENDED = (1 << 7)
TIMER_SUSPENDED = (1 << 7) /** Timer suspended. */
};
/**
* 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.
*/
int m_flags;
/** The delay configured for this Timer. */
Time m_delay;
/** The future event scheduled to expire the timer. */
EventId m_event;
/**
* The timer implementation, which contains the bound callback
* function and arguments.
*/
TimerImpl *m_impl;
/** The amount of time left on the Timer while it is suspended. */
Time m_delayLeft;
};
} // namespace ns3
/********************************************************************
Implementation of templates defined above
********************************************************************/
#include "timer-impl.h"
namespace ns3 {
src/core/model/watchdog.cc
+1
View File
@@ -20,6 +20,7 @@
#include "watchdog.h"
#include "log.h"
namespace ns3 {
NS_LOG_COMPONENT_DEFINE ("Watchdog");
src/core/model/watchdog.h
+74 -19
View File
@@ -23,25 +23,48 @@
#include "nstime.h"
#include "event-id.h"
/**
* \file
* \ingroup timer
* ns3::Watchdog timer class declaration.
*/
namespace ns3 {
class TimerImpl;
/**
* \ingroup core
* \brief a very simple watchdog
* \ingroup timer
* \brief A very simple watchdog operating in virtual time.
*
* The watchdog timer is started by calling Ping with a delay value.
* Once started the timer cannot be suspended, cancelled or shortened.
* It _can_ be lengthened (delayed) by calling Ping again: if the new
* expire time (current simulation time plus the new delay)
* is greater than the old expire time the timer will be extended
* to the new expire time.
*
* Typical usage would be to periodically Ping the Watchdog, extending
* it's execution time. If the owning process fails to Ping before
* the Watchdog expires, the registered function will be invoked.
*
* If you don't ping the watchdog sufficiently often, it triggers its
* listening function.
*
* \see Timer for a more sophisticated general purpose timer.
*/
class Watchdog
{
public:
/** Constructor. */
Watchdog ();
/** Destructor. */
~Watchdog ();
/**
* \param delay the watchdog delay
* Delay the timer.
*
* \param delay The watchdog delay
*
* After a call to this method, the watchdog will not be triggered
* until the delay specified has been expired. This operation is
@@ -50,7 +73,9 @@ public:
void Ping (Time delay);
/**
* \param fn the function
* Set the function to execute when the timer expires.
*
* \param fn The function
*
* Store this function in this Timer for later use by Timer::Schedule.
*/
@@ -58,8 +83,12 @@ public:
void SetFunction (FN fn);
/**
* \param memPtr the member function pointer
* \param objPtr the pointer to object
* Set the function to execute when the timer expires.
*
* \tparam MEM_PTR Class method function type.
* \tparam OBJ_PTR Class type containing the function.
* \param memPtr The member function pointer
* \param objPtr The pointer to object
*
* Store this function and object in this Timer for later use by Timer::Schedule.
*/
@@ -68,72 +97,98 @@ public:
/**
* \param a1 the first argument
*
* Store this argument in this Timer for later use by Timer::Schedule.
* Set the arguments to be used when invoking the expire function.
*/
/**@{*/
/**
* \tparam T1 Type of the first argument.
* \param a1 The first argument
*/
template <typename T1>
void SetArguments (T1 a1);
/**
* \tparam T1 Type of the first argument.
* \tparam T2 Type of the second argument.
* \param a1 the first argument
* \param a2 the second argument
*
* Store these arguments in this Timer for later use by Timer::Schedule.
*/
template <typename T1, typename T2>
void SetArguments (T1 a1, T2 a2);
/**
* \tparam T1 Type of the first argument.
* \tparam T2 Type of the second argument.
* \tparam T3 Type of the third argument.
* \param a1 the first argument
* \param a2 the second argument
* \param a3 the third argument
*
* Store these arguments in this Timer for later use by Timer::Schedule.
*/
template <typename T1, typename T2, typename T3>
void SetArguments (T1 a1, T2 a2, T3 a3);
/**
* \tparam T1 Type of the first argument.
* \tparam T2 Type of the second argument.
* \tparam T3 Type of the third argument.
* \tparam T4 Type of the fourth argument.
* \param a1 the first argument
* \param a2 the second argument
* \param a3 the third argument
* \param a4 the fourth argument
*
* Store these arguments in this Timer for later use by Timer::Schedule.
*/
template <typename T1, typename T2, typename T3, typename T4>
void SetArguments (T1 a1, T2 a2, T3 a3, T4 a4);
/**
* \tparam T1 Type of the first argument.
* \tparam T2 Type of the second argument.
* \tparam T3 Type of the third argument.
* \tparam T4 Type of the fourth argument.
* \tparam T5 Type of the fifth argument.
* \param a1 the first argument
* \param a2 the second argument
* \param a3 the third argument
* \param a4 the fourth argument
* \param a5 the fifth argument
*
* Store these arguments in this Timer for later use by Timer::Schedule.
*/
template <typename T1, typename T2, typename T3, typename T4, typename T5>
void SetArguments (T1 a1, T2 a2, T3 a3, T4 a4, T5 a5);
/**
* \tparam T1 Type of the first argument.
* \tparam T2 Type of the second argument.
* \tparam T3 Type of the third argument.
* \tparam T4 Type of the fourth argument.
* \tparam T5 Type of the fifth argument.
* \tparam T6 Type of the sixth argument.
* \param a1 the first argument
* \param a2 the second argument
* \param a3 the third argument
* \param a4 the fourth argument
* \param a5 the fifth argument
* \param a6 the sixth argument
*
* Store these arguments in this Timer for later use by Timer::Schedule.
*/
template <typename T1, typename T2, typename T3, typename T4, typename T5, typename T6>
void SetArguments (T1 a1, T2 a2, T3 a3, T4 a4, T5 a5, T6 a6);
/**@}*/
private:
/** Internal callback invoked when the timer expires. */
void Expire (void);
/**
* The timer implementation, which contains the bound callback
* function and arguments.
*/
TimerImpl *m_impl;
/** The future event scheduled to expire the timer. */
EventId m_event;
/** The absolute time when the timer will expire. */
Time m_end;
};
} // namespace ns3
/********************************************************************
Implementation of templates defined above
********************************************************************/
#include "timer-impl.h"
namespace ns3 {