--- a/src/core/model/attribute-accessor-helper.h Wed Dec 17 12:17:11 2014 -0800
+++ b/src/core/model/attribute-accessor-helper.h Thu Dec 18 15:12:35 2014 -0800
@@ -48,7 +48,7 @@
* specific AttributeValue type \p V which holds the value
* (or the type implied by the name \c Make<V>Accessor of this function.)
* In the case of a \p setter returning \p bool, the return value
- * should be true if the value could be set successfully.
+ * should be \c true if the value could be set successfully.
*
* \tparam V (If present) The specific AttributeValue type to use to represent
* the Attribute. (If not present, the type \p V is implicit
@@ -115,7 +115,7 @@
/***************************************************************
- * The implementation of the above functions.
+ * Implementation of the templates declared above.
***************************************************************/
#include "type-traits.h"
--- a/src/core/model/command-line.cc Wed Dec 17 12:17:11 2014 -0800
+++ b/src/core/model/command-line.cc Thu Dec 18 15:12:35 2014 -0800
@@ -37,7 +37,7 @@
/**
* \file
* \ingroup commandline
- * CommandLine class definitions.
+ * CommandLine class implementation.
*/
namespace ns3 {
--- a/src/core/model/command-line.h Wed Dec 17 12:17:11 2014 -0800
+++ b/src/core/model/command-line.h Thu Dec 18 15:12:35 2014 -0800
@@ -436,7 +436,7 @@
/** \ingroup commandline
- * \defgroup commandlinehelper Helpers to specialize on bool
+ * \defgroup commandlinehelper Helpers to Specialize on \c bool
*/
/**
* \ingroup commandlinehelper
@@ -446,7 +446,7 @@
/**
* \ingroup commandlinehelper
- * \brief Helper to specialize UserItem::Parse on bool
+ * \brief Helpers to specialize CommandLine::UserItem::Parse() on bool
*
* \param value the argument name
* \param val the argument location
@@ -461,7 +461,7 @@
/**
* \ingroup commandlinehelper
- * \brief Helper to specialize UserItem::GetDefault on bool
+ * \brief Helper to specialize CommandLine::UserItem::GetDefault() on bool
*
* \param val the argument value
* \return the string representation of value
@@ -481,7 +481,7 @@
/********************************************************************
- * Implementation of templates defined above
+ * Implementation of the templates declared above.
********************************************************************/
namespace ns3 {
--- a/src/core/model/event-id.cc Wed Dec 17 12:17:11 2014 -0800
+++ b/src/core/model/event-id.cc Thu Dec 18 15:12:35 2014 -0800
@@ -25,7 +25,7 @@
/**
* \file
* \ingroup events
- * ns3::EventId definitions.
+ * ns3::EventId implementation.
*/
namespace ns3 {
--- a/src/core/model/hash-function.h Wed Dec 17 12:17:11 2014 -0800
+++ b/src/core/model/hash-function.h Thu Dec 18 15:12:35 2014 -0800
@@ -96,9 +96,9 @@
*
* \ingroup hash
*
- * \brief Basic hash function typedefs.
+ * \brief Function pointer signatures for basic hash functions.
*
- * See Hash32Implementation<> or Hash64Implementation<>
+ * See Hash::Function::Hash32 or Hash::Function::Hash64
* @{
*/
typedef uint32_t (*Hash32Function_ptr) (const char *, const size_t);
@@ -114,7 +114,8 @@
/**
* \ingroup hash
*
- * \brief Template for Hashfunctions from 32-bit hash functions.
+ * \brief Template for creating a Hash::Implementation from
+ * a 32-bit hash function.
*/
class Hash32 : public Implementation
{
@@ -137,7 +138,8 @@
/**
* \ingroup hash
*
- * \brief Template for Hashfunctions from 64-bit hash functions
+ * \brief Template for creating a Hash::Implemetation from
+ * a 64-bit hash function.
*/
class Hash64 : public Implementation
{
--- a/src/core/model/int-to-type.h Wed Dec 17 12:17:11 2014 -0800
+++ b/src/core/model/int-to-type.h Thu Dec 18 15:12:35 2014 -0800
@@ -20,17 +20,32 @@
#ifndef INT_TO_TYPE_H
#define INT_TO_TYPE_H
+/**
+ * \file
+ * ns3::IntToType template class.
+ */
+
namespace ns3 {
/**
+ * Convert an integer into a type.
+ *
* This trivial template is extremely useful, as explained in
- * "Modern C++ Design", p29, section 2.4,
- * "Mapping Integral Constants to Types"
+ * "Modern C++ Design", p 29, section 2.4,
+ * "Mapping Integral Constants to Types".
+ *
+ * For an example, see timer-impl.h
+ *
+ * \tparam v The integral constant value distinguishing this type
+ * from other values.
*/
template <int v>
struct IntToType
{
- enum v_e { value = v};
+ /** Enumeration holding the type-specific value. */
+ enum v_e {
+ value = v /**< The integer value distinguishing this type. */
+ };
};
} // namespace ns3
--- a/src/core/model/make-event.cc Wed Dec 17 12:17:11 2014 -0800
+++ b/src/core/model/make-event.cc Thu Dec 18 15:12:35 2014 -0800
@@ -23,7 +23,7 @@
/**
* \file
* \ingroup events
- * ns3::MakeEvent(void(*f)(void)) definition.
+ * ns3::MakeEvent(void(*f)(void)) implementation.
*/
namespace ns3 {
--- a/src/core/model/make-event.h Wed Dec 17 12:17:11 2014 -0800
+++ b/src/core/model/make-event.h Thu Dec 18 15:12:35 2014 -0800
@@ -23,7 +23,7 @@
/**
* \file
* \ingroup events
- * ns3::MakeEvent function declarations and template definitions.
+ * ns3::MakeEvent function declarations and template implementation.
*/
namespace ns3 {
@@ -32,7 +32,7 @@
/**
* \ingroup events
- * \defgroup makeeventmemptr MakeEvent from member function pointer.
+ * \defgroup makeeventmemptr MakeEvent from Member Function Pointer.
*
* Create EventImpl instances from class member functions which take
* varying numbers of arguments.
@@ -148,13 +148,11 @@
/**
* \ingroup events
- * \defgroup makeeventfnptr MakeEvent from function pointers.
+ * \defgroup makeeventfnptr MakeEvent from Function Pointers.
*
* Create EventImpl instances from function pointers which take
* varying numbers of arguments.
- */
-/**
- * \ingroup makeeventfnptr
+ *
* @{
*/
/**
@@ -260,7 +258,7 @@
} // namespace ns3
/********************************************************************
- Implementation of templates defined above
+ * Implementation of the templates declared above.
********************************************************************/
#include "event-impl.h"
@@ -272,6 +270,8 @@
* \ingroup makeeventmemptr
* Helper for the MakeEvent 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 class type.
@@ -283,6 +283,8 @@
* \ingroup makeeventmemptr
* Helper for the MakeEvent functions which take a class method.
*
+ * This helper converts a pointer to a reference.
+ *
* This is the specialization for pointer types.
*
* \tparam T The class type.
--- a/src/core/model/object-base.cc Wed Dec 17 12:17:11 2014 -0800
+++ b/src/core/model/object-base.cc Thu Dec 18 15:12:35 2014 -0800
@@ -30,7 +30,7 @@
/**
* \file
* \ingroup object
- * ns3::ObjectBase class definition.
+ * ns3::ObjectBase class implementation.
*/
namespace ns3 {
--- a/src/core/model/object-map.h Wed Dec 17 12:17:11 2014 -0800
+++ b/src/core/model/object-map.h Thu Dec 18 15:12:35 2014 -0800
@@ -66,7 +66,7 @@
/***************************************************************
- * The implementation of the above functions.
+ * Implementation of the templates declared above.
***************************************************************/
template <typename T, typename U>
--- a/src/core/model/object-vector.h Wed Dec 17 12:17:11 2014 -0800
+++ b/src/core/model/object-vector.h Thu Dec 18 15:12:35 2014 -0800
@@ -67,7 +67,7 @@
/***************************************************************
- * The implementation of the above functions.
+ * Implementation of the templates declared above.
***************************************************************/
template <typename T, typename U>
--- a/src/core/model/object.cc Wed Dec 17 12:17:11 2014 -0800
+++ b/src/core/model/object.cc Thu Dec 18 15:12:35 2014 -0800
@@ -34,7 +34,7 @@
/**
* \file
* \ingroup object
- * ns3::Object class definition.
+ * ns3::Object class implementation.
*/
namespace ns3 {
--- a/src/core/model/ptr.h Wed Dec 17 12:17:11 2014 -0800
+++ b/src/core/model/ptr.h Thu Dec 18 15:12:35 2014 -0800
@@ -448,18 +448,19 @@
template <typename T1, typename T2>
Ptr<T1> const_pointer_cast (Ptr<T2> const&p);
+// Duplicate of struct CallbackTraits<T> as defined in callback.h
template <typename T>
struct CallbackTraits;
/**
- * \ingroup makecallbackmemptr
+ * \ingroup callbackimpl
*
* Trait class to convert a pointer into a reference,
* used by MemPtrCallBackImpl.
*
* This is the specialization for Ptr types.
*
- * \tparam The base object type.
+ * \tparam T The base object type.
*/
template <typename T>
struct CallbackTraits<Ptr<T> >
@@ -474,6 +475,7 @@
}
};
+// Duplicate of struct EventMemberImplObjTraits<T> as defined in make-event.h
template <typename T>
struct EventMemberImplObjTraits;
--- a/src/core/model/realtime-simulator-impl.cc Wed Dec 17 12:17:11 2014 -0800
+++ b/src/core/model/realtime-simulator-impl.cc Thu Dec 18 15:12:35 2014 -0800
@@ -36,6 +36,12 @@
#include <cmath>
+/**
+ * \file
+ * \ingroup realtime
+ * ns3::RealTimeSimulatorImpl implementation.
+ */
+
namespace ns3 {
// Note: Logging in this file is largely avoided due to the
--- a/src/core/model/scheduler.cc Wed Dec 17 12:17:11 2014 -0800
+++ b/src/core/model/scheduler.cc Thu Dec 18 15:12:35 2014 -0800
@@ -22,6 +22,12 @@
#include "assert.h"
#include "log.h"
+/**
+ * \file
+ * \ingroup scheduler
+ * ns3::Scheduler implementation.
+ */
+
namespace ns3 {
NS_LOG_COMPONENT_DEFINE ("Scheduler");
--- a/src/core/model/simulation-singleton.h Wed Dec 17 12:17:11 2014 -0800
+++ b/src/core/model/simulation-singleton.h Thu Dec 18 15:12:35 2014 -0800
@@ -34,14 +34,24 @@
{
public:
/**
- * \returns the instance underlying this singleton.
+ * \returns The instance underlying this singleton.
*
* This instance will be automatically deleted when the
* user calls ns3::Simulator::Destroy.
*/
static T *Get (void);
private:
+ /**
+ * Get the singleton object, creating a new one if it doesn't exist yet.
+ *
+ * \internal
+ * When a new object is created, this method schedules it's own
+ * destruction using Simulator::ScheduleDestroy().
+ *
+ * \returns The address of the pointer holding the static instance.
+ */
static T **GetObject (void);
+ /** Delete the underlying object. */
static void DeleteObject (void);
};
--- a/src/core/model/simulator-impl.h Wed Dec 17 12:17:11 2014 -0800
+++ b/src/core/model/simulator-impl.h Thu Dec 18 15:12:35 2014 -0800
@@ -44,8 +44,8 @@
public:
/**
- * Register this type.
- * \return The object TypeId.
+ * Get the registered TypeId for this class.
+ * \return The object TypeId.
*/
static TypeId GetTypeId (void);
--- a/src/core/model/simulator.cc Wed Dec 17 12:17:11 2014 -0800
+++ b/src/core/model/simulator.cc Thu Dec 18 15:12:35 2014 -0800
@@ -37,6 +37,14 @@
#include <vector>
#include <iostream>
+/**
+ * \file
+ * \ingroup simulator
+ * ns3::Simulator implementation, as well as implementation pointer,
+ * global scheduler implementation, and default ns3::NodePrinter
+ * and ns3::TimePrinter.
+ */
+
namespace ns3 {
// Note: Logging in this file is largely avoided due to the
--- a/src/core/model/simulator.h Wed Dec 17 12:17:11 2014 -0800
+++ b/src/core/model/simulator.h Thu Dec 18 15:12:35 2014 -0800
@@ -31,6 +31,12 @@
#include <stdint.h>
#include <string>
+/**
+ * \file
+ * \ingroup simulator
+ * ns3::Simulator declaration.
+ */
+
namespace ns3 {
class SimulatorImpl;
@@ -786,6 +792,7 @@
};
/**
+ * \ingroup simulator
* \brief create an ns3::Time instance which contains the
* current simulation time.
*
@@ -801,6 +808,11 @@
} // namespace ns3
+
+/********************************************************************
+ * Implementation of the templates declared above.
+ ********************************************************************/
+
namespace ns3 {
template <typename MEM, typename OBJ>
--- a/src/core/model/synchronizer.cc Wed Dec 17 12:17:11 2014 -0800
+++ b/src/core/model/synchronizer.cc Thu Dec 18 15:12:35 2014 -0800
@@ -19,6 +19,12 @@
#include "synchronizer.h"
#include "log.h"
+/**
+ * \file
+ * \ingroup realtime
+ * ns3::Synchronizer implementation.
+ */
+
namespace ns3 {
NS_LOG_COMPONENT_DEFINE ("Synchronizer");
@@ -35,7 +41,8 @@
}
Synchronizer::Synchronizer ()
- : m_realtimeOriginNano (0), m_simOriginNano (0)
+ : m_realtimeOriginNano (0),
+ m_simOriginNano (0)
{
NS_LOG_FUNCTION (this);
}
--- a/src/core/model/synchronizer.h Wed Dec 17 12:17:11 2014 -0800
+++ b/src/core/model/synchronizer.h Thu Dec 18 15:12:35 2014 -0800
@@ -23,14 +23,21 @@
#include "nstime.h"
#include "object.h"
+/**
+ * \file
+ * \ingroup realtime
+ * ns3::Synchronizer declaration.
+ */
+
namespace ns3 {
/**
+ * @ingroup realtime
* @brief Base class used for synchronizing the simulation events to some
* real time "wall clock."
*
* The simulation clock is maintained as a 64-bit integer in a unit specified
- * by the user through the TimeStepPrecision::Set function. This means that
+ * by the user through the Time::SetResolution function. This means that
* it is not possible to specify event expiration times with anything better
* than this user-specified accuracy. We use this clock for the simulation
* time.
@@ -44,274 +51,287 @@
class Synchronizer : public Object
{
public:
+ /**
+ * Get the registered TypeId for this class.
+ * \returns The TypeId.
+ */
static TypeId GetTypeId (void);
+ /** Constructor. */
Synchronizer ();
+ /** Destructor. */
virtual ~Synchronizer ();
-/**
- * @brief Return true if this synchronizer is actually synchronizing to a
- * realtime clock. The simulator sometimes needs to know this.
- * @returns True if locked with realtime, false if not.
- */
+ /**
+ * @brief Return true if this synchronizer is actually synchronizing to a
+ * realtime clock.
+ *
+ * The simulator sometimes needs to know this.
+ *
+ * @returns \c true if locked with realtime, \c false if not.
+ */
bool Realtime (void);
-/**
- * @brief Retrieve the value of the origin of the underlying normalized wall
- * clock time in simulator timestep units.
- *
- * @returns The normalized wall clock time (in simulator timestep units).
- * @see TimeStepPrecision::Get
- * @see Synchronizer::SetOrigin
- */
+ /**
+ * @brief Retrieve the value of the origin of the underlying normalized wall
+ * clock time in simulator timestep units.
+ *
+ * @returns The normalized wall clock time (in Time resolution units).
+ * @see SetOrigin
+ */
uint64_t GetCurrentRealtime (void);
-/**
- * @brief Establish a correspondence between a simulation time and the
- * synchronizer real time.
- *
- * This method is expected to be called at the "instant" before simulation
- * begins. At this point, simulation time = 0, and a
- * set = 0 in this method. We then associate this time with the current
- * value of the real time clock that will be used to actually perform the
- * synchronization.
- *
- * Subclasses are expected to implement the corresponding DoSetOrigin pure
- * virtual method to do the actual real-time-clock-specific work of making the
- * correspondence mentioned above.
- *
- * @param ts The simulation time we should use as the origin (in simulator
- * timestep units).
- * @see TimeStepPrecision::Get
- * @see TimeStepPrecision::DoSetOrigin
- */
+ /**
+ * @brief Establish a correspondence between a simulation time and the
+ * synchronizer real time.
+ *
+ * This method is expected to be called at the "instant" before simulation
+ * begins. At this point, simulation time = 0, and a
+ * set = 0 in this method. We then associate this time with the current
+ * value of the real time clock that will be used to actually perform the
+ * synchronization.
+ *
+ * Subclasses are expected to implement the corresponding DoSetOrigin pure
+ * virtual method to do the actual real-time-clock-specific work
+ * of making the correspondence mentioned above.
+ *
+ * @param ts The simulation time we should use as the origin (in
+ * Time resolution units).
+ * @see DoSetOrigin
+ */
void SetOrigin (uint64_t ts);
-/**
- * @brief Retrieve the value of the origin of the simulation time in
- * simulator timestep units.
- *
- * @returns The simulation time used as the origin (in simulator timestep
- * units).
- * @see TimeStepPrecision::Get
- * @see Synchronizer::SetOrigin
- */
+ /**
+ * @brief Retrieve the value of the origin of the simulation time in
+ * Time.resolution units.
+ *
+ * @returns The simulation time used as the origin (in Time resolution units).
+ * @see SetOrigin
+ */
uint64_t GetOrigin (void);
-/**
- * @brief Retrieve the difference between the real time clock used to
- * synchronize the simulation and the simulation time (in simulator timestep
- * units).
- *
- * @param ts Simulation timestep from the simulator interpreted as current time
- * in the simulator.
- * @returns Simulation timestep (in simulator timestep units) minus origin
- * time (stored internally in nanosecond units).
- * @see TimeStepPrecision::Get
- * @see Synchronizer::SetOrigin
- * @see Synchronizer::DoGetDrift
- */
+ /**
+ * @brief Retrieve the difference between the real time clock used to
+ * synchronize the simulation and the simulation time (in
+ * Time resolution units).
+ *
+ * @param ts Simulation time in Time resolution units.
+ * @returns Simulation Time (in Time resolution units)
+ * minus the origin time (stored internally in nanosecond units).
+ * @see SetOrigin
+ * @see DoGetDrift
+ */
int64_t GetDrift (uint64_t ts);
-/**
- * @brief Wait until the real time is in sync with the specified simulation
- * time or until the synchronizer is Sigalled.
- *
- * This is where the real work of synchronization is done. The Time passed
- * in as a parameter is the simulation time. The job of Synchronize is to
- * translate from simulation time to synchronizer time (in a perfect world
- * this is the same time) and then figure out how long in real-time it needs
- * to wait until that synchronizer / simulation time comes around.
- *
- * Subclasses are expected to implement the corresponding DoSynchronize pure
- * virtual method to do the actual real-time-clock-specific work of waiting
- * (either busy-waiting or sleeping, or some combination thereof) until the
- * requested simulation time.
- *
- * @param tsCurrent The current simulation time (in simulator timestep units).
- * @param tsDelay The simulation time we need to wait for (in simulator
- * timestep units).
- * @returns True if the function ran to completion, false if it was interrupted
- * by a Signal.
- * @see TimeStepPrecision::Get
- * @see Synchronizer::DoSynchronize
- * @see Synchronizer::Signal
- */
+ /**
+ * @brief Wait until the real time is in sync with the specified simulation
+ * time or until the synchronizer is Sigalled.
+ *
+ * This is where the real work of synchronization is done. The \c tsCurrent
+ * argument is the simulation time. The job of Synchronize is to
+ * translate from simulation time to synchronizer time (in a perfect world
+ * this is the same time) and then figure out how long in real-time it needs
+ * to wait until that synchronizer / simulation time comes around.
+ *
+ * Subclasses are expected to implement the corresponding DoSynchronize pure
+ * virtual method to do the actual real-time-clock-specific work of waiting
+ * (either busy-waiting or sleeping, or some combination thereof) until the
+ * requested simulation time.
+ *
+ * @param tsCurrent The current simulation time (in Time resolution units).
+ * @param tsDelay The simulation time we need to wait for (in Time
+ * resolution units).
+ * @returns \c true if the function ran to completion,
+ * \c false if it was interrupted by a Signal.
+ * @see DoSynchronize
+ * @see Signal
+ */
bool Synchronize (uint64_t tsCurrent, uint64_t tsDelay);
-/**
- * @brief Tell a possible simulator thread waiting in the Synchronize method
- * that an event has happened which demands a reevaluation of the wait time.
- * This will cause the thread to wake and return to the simulator proper
- * where it can get its bearings.
- *
- * @see Synchronizer::Synchronize
- * @see Synchronizer::DoSignal
- */
+ /**
+ * @brief Tell a possible simulator thread waiting in the Synchronize method
+ * that an event has happened which demands a reevaluation of the wait time.
+ *
+ * This will cause the thread to wake and return to the simulator proper
+ * where it can get its bearings.
+ *
+ * @see Synchronize
+ * @see DoSignal
+ */
void Signal (void);
-/**
- * @brief Set the condition variable that tells a possible simulator thread
- * waiting in the Synchronize method that an event has happened which demands
- * a reevaluation of the wait time.
- *
- * @see Synchronizer::Signal
- */
+ /**
+ * @brief Set the condition variable that tells a possible simulator thread
+ * waiting in the Synchronize method that an event has happened which demands
+ * a reevaluation of the wait time.
+ *
+ * @see Signal
+ */
void SetCondition (bool);
-/**
- * @brief Ask the synchronizer to remember what time it is. Typically used
- * with EventEnd to determine the real execution time of a simulation event.
- *
- * @see Synchronizer::EventEnd
- * @see TimeStepPrecision::Get
- */
+ /**
+ * @brief Ask the synchronizer to remember what time it is.
+ *
+ * Typically used with EventEnd to determine the real execution time
+ * of a simulation event.
+ *
+ * @see EventEnd
+ */
void EventStart (void);
-/**
- * @brief Ask the synchronizer to return the time step between the instant
- * remembered during EventStart and now. Used in conjunction with EventStart
- * to determine the real execution time of a simulation event.
- *
- * @see Synchronizer::EventStart
- * @see TimeStepPrecision::Get
- */
+ /**
+ * @brief Ask the synchronizer to return the time step between the instant
+ * remembered during EventStart and now.
+ *
+ * Used in conjunction with EventStart to determine the real execution time
+ * of a simulation event.
+ *
+ * @returns The elapsed real time, in ns.
+ * @see EventStart
+ */
uint64_t EventEnd (void);
protected:
-/**
- * @brief Establish a correspondence between a simulation time and a
- * wall-clock (real) time.
- *
- * There are three timelines involved here: the simulation time, the
- * (absolute) wall-clock time and the (relative) synchronizer real time.
- * Calling this method makes a correspondence between the origin of the
- * synchronizer time and the current wall-clock time.
- *
- * This method is expected to be called at the "instant" before simulation
- * begins. At this point, simulation time = 0, and synchronizer time is
- * set = 0 in this method. We then associate this time with the current
- * value of the real time clock that will be used to actually perform the
- * synchronization.
- *
- * Subclasses are expected to implement this method to do the actual
- * real-time-clock-specific work of making the correspondence mentioned above.
- * for example, this is where the differences between Time parameters and
- * parameters to clock_nanosleep would be dealt with.
- *
- * @param ns The simulation time we need to use as the origin (normalized to
- * nanosecond units).
- * @see Synchronizer::SetOrigin
- * @see TimeStepPrecision::Get
- */
+ /**
+ * @brief Establish a correspondence between a simulation time and a
+ * wall-clock (real) time.
+ *
+ * There are three timelines involved here: the simulation (virtual) time,
+ * the (absolute) wall-clock time and the (relative) synchronizer real time.
+ * Calling this method makes a correspondence between the origin of the
+ * synchronizer time and the current wall-clock time.
+ *
+ * This method is expected to be called at the "instant" before simulation
+ * begins. At this point, simulation time = 0, and synchronizer time is
+ * set = 0 in this method. We then associate this time with the current
+ * value of the real time clock that will be used to actually perform the
+ * synchronization.
+ *
+ * Subclasses are expected to implement this method to do the actual
+ * real-time-clock-specific work of making the correspondence mentioned above.
+ * for example, this is where the differences between Time parameters and
+ * parameters to clock_nanosleep would be dealt with.
+ *
+ * @param ns The simulation time we need to use as the origin (normalized to
+ * nanosecond units).
+ * @see SetOrigin
+ */
virtual void DoSetOrigin (uint64_t ns) = 0;
-/**
- * @brief Return true if this synchronizer is actually synchronizing to a
- * realtime clock. The simulator sometimes needs to know this.
- *
- * Subclasses are expected to implement this method to tell the outside world
- * whether or not they are synchronizing to a realtime clock.
- *
- * @returns True if locked with realtime, false if not.
- */
+ /**
+ * @brief Return \c true if this synchronizer is actually synchronizing to a
+ * realtime clock.
+ *
+ * The simulator sometimes needs to know this.
+ *
+ * Subclasses are expected to implement this method to tell the outside world
+ * whether or not they are synchronizing to a realtime clock.
+ *
+ * @returns \c true if locked with realtime, \c false if not.
+ */
virtual bool DoRealtime (void) = 0;
-/**
- * @brief Retrieve the value of the origin of the underlying normalized wall
- * clock time in simulator timestep units.
- *
- * Subclasses are expected to implement this method to do the actual
- * real-time-clock-specific work of getting the current time.
- *
- * @returns The normalized wall clock time (in nanosecond units).
- * @see TimeStepPrecision::Get
- * @see Synchronizer::SetOrigin
- */
+ /**
+ * @brief Retrieve the value of the origin of the underlying normalized wall
+ * clock time in Time resolution units.
+ *
+ * Subclasses are expected to implement this method to do the actual
+ * real-time-clock-specific work of getting the current time.
+ *
+ * @returns The normalized wall clock time (in nanosecond units).
+ * @see SetOrigin
+ */
virtual uint64_t DoGetCurrentRealtime (void) = 0;
-/**
- * @brief Wait until the real time is in sync with the specified simulation
- * time.
- *
- * This is where the real work of synchronization is done. The Time passed
- * in as a parameter is the simulation time. The job of Synchronize is to
- * translate from simulation time to synchronizer time (in a perfect world
- * this is the same time) and then figure out how long in real-time it needs
- * to wait until that synchronizer / simulation time comes around.
- *
- * Subclasses are expected to implement this method to do the actual
- * real-time-clock-specific work of waiting (either busy-waiting or sleeping,
- * or some combination) until the requested simulation time.
- *
- * @param nsCurrent The current simulation time (normalized to nanosecond
- * units).
- * @param nsDelay The simulation time we need to wait for (normalized to
- * nanosecond units).
- * @returns True if the function ran to completion, false if it was interrupted
- * by a Signal.
- * @see Synchronizer::Synchronize
- * @see TimeStepPrecision::Get
- * @see Synchronizer::Signal
- */
+ /**
+ * @brief Wait until the real time is in sync with the specified simulation
+ * time.
+ *
+ * This is where the real work of synchronization is done. The
+ * \c nsCurrent argument is the simulation time (in ns). The job of
+ * DoSynchronize is to translate from simulation time to synchronizer time
+ * (in a perfect world these are the same time) and then figure out
+ * how long in real-time it needs to wait until that
+ * synchronizer / simulation time comes around.
+ *
+ * Subclasses are expected to implement this method to do the actual
+ * real-time-clock-specific work of waiting (either busy-waiting or sleeping,
+ * or some combination) until the requested simulation time.
+ *
+ * @param nsCurrent The current simulation time (in nanosecond units).
+ * @param nsDelay The simulation time we need to wait for (normalized to
+ * nanosecond units).
+ * @returns \c true if the function ran to completion,
+ * \c false if it was interrupted by a Signal.
+ * @see Synchronize
+ * @see Signal
+ */
virtual bool DoSynchronize (uint64_t nsCurrent, uint64_t nsDelay) = 0;
-/**
- * @brief Declaration of the method used to tell a possible simulator thread
- * waiting in the DoSynchronize method that an event has happened which
- * demands a reevaluation of the wait time.
- *
- * @see Synchronizer::Signal
- */
+ /**
+ * @brief Tell a possible simulator thread waiting in the
+ * DoSynchronize method that an event has happened which
+ * demands a reevaluation of the wait time.
+ *
+ * @see Signal
+ */
virtual void DoSignal (void) = 0;
-/**
- * @brief Declaration of the method used to set the condition variable that
- * tells a possible simulator thread waiting in the Synchronize method that an
- * event has happened which demands a reevaluation of the wait time.
- *
- * @see Synchronizer::SetCondition
- */
+ /**
+ * @brief Set the condition variable to tell a possible simulator thread
+ * waiting in the Synchronize method that an event has happened which
+ * demands a reevaluation of the wait time.
+ *
+ * @see SetCondition
+ */
virtual void DoSetCondition (bool) = 0;
-/**
- * @brief Declaration of method used to retrieve drift between the real time
- * clock used to synchronize the simulation and the current simulation time.
- *
- * @param ns Simulation timestep from the simulator normalized to nanosecond
- * steps.
- * @returns Drift in nanosecond units.
- * @see TimeStepPrecision::Get
- * @see Synchronizer::SetOrigin
- * @see Synchronizer::GetDrift
- */
+ /**
+ * @brief Get the drift between the real time clock used to synchronize
+ * the simulation and the current simulation time.
+ *
+ * @param ns Simulation time in ns.
+ * @returns Drift in ns units.
+ * @see SetOrigin
+ * @see GetDrift
+ */
virtual int64_t DoGetDrift (uint64_t ns) = 0;
+ /**
+ * @brief Record the normalized real time at which the current
+ * event is starting execution.
+ */
virtual void DoEventStart (void) = 0;
+ /**
+ * @brief Return the amount of real time elapsed since the last call
+ * to EventStart.
+ *
+ * @returns The elapsed real time, in ns.
+ */
virtual uint64_t DoEventEnd (void) = 0;
+ /** The real time, in ns, when SetOrigin was called. */
uint64_t m_realtimeOriginNano;
+ /** The simulation time, in ns, when SetOrigin was called. */
uint64_t m_simOriginNano;
private:
-/**
- * @brief Convert a simulator time step (which can be steps of time in a
- * user-specified unit) to a normalized time step in nanosecond units.
- *
- * @param ts The simulation time step to be normalized.
- * @returns The simulation time step normalized to nanosecond units.
- * @see TimeStepPrecision::Get
- */
+ /**
+ * @brief Convert a simulator time step (in Time resolution units)
+ * to a normalized time step in nanosecond units.
+ *
+ * @param ts The simulation time step to be normalized.
+ * @returns The simulation time step normalized to nanosecond units.
+ */
uint64_t TimeStepToNanosecond (uint64_t ts);
-/**
- * @brief Convert a normalized nanosecond count into a simulator time step
- * (which can be steps of time in a user-specified unit).
- *
- * @param ns The nanosecond count step to be converted
- * @returns The simulation time step to be interpreted in appropriate units.
- * @see TimeStepPrecision::Get
- */
+ /**
+ * @brief Convert a normalized nanosecond time step into a
+ * simulator time step (in Time resolution units).
+ *
+ * @param ns The nanosecond count step to be converted
+ * @returns The simulation time step to be interpreted in appropriate units.
+ */
uint64_t NanosecondToTimeStep (uint64_t ns);
};
--- a/src/core/model/system-path.cc Wed Dec 17 12:17:11 2014 -0800
+++ b/src/core/model/system-path.cc Thu Dec 18 15:12:35 2014 -0800
@@ -66,7 +66,7 @@
/**
* \file
* \ingroup systempath
- * System-independent file and directory function definitions.
+ * System-independent file and directory functions implementation.
*/
namespace ns3 {
--- a/src/core/model/timer-impl.h Wed Dec 17 12:17:11 2014 -0800
+++ b/src/core/model/timer-impl.h Thu Dec 18 15:12:35 2014 -0800
@@ -137,14 +137,14 @@
/********************************************************************
- Implementation of TimerImpl implementation functions.
+ * Implementation of TimerImpl implementation functions.
********************************************************************/
namespace ns3 {
/**
* \ingroup timer
- * \defgroup timerimpl TimerImpl implementation details.
+ * \defgroup timerimpl TimerImpl Implementation
* @{
*/
@@ -966,7 +966,7 @@
/********************************************************************
- Implementation of TimerImpl itself.
+ * Implementation of TimerImpl itself.
********************************************************************/
template <typename T1>
--- a/src/core/model/timer.cc Wed Dec 17 12:17:11 2014 -0800
+++ b/src/core/model/timer.cc Thu Dec 18 15:12:35 2014 -0800
@@ -22,6 +22,11 @@
#include "simulation-singleton.h"
#include "log.h"
+/**
+ * \file
+ * \ingroup timer
+ * ns3::Timer implementation.
+ */
namespace ns3 {
--- a/src/core/model/timer.h Wed Dec 17 12:17:11 2014 -0800
+++ b/src/core/model/timer.h Thu Dec 18 15:12:35 2014 -0800
@@ -292,7 +292,7 @@
/********************************************************************
- Implementation of templates defined above
+ * Implementation of the templates declared above.
********************************************************************/
#include "timer-impl.h"
--- a/src/core/model/trace-source-accessor.h Wed Dec 17 12:17:11 2014 -0800
+++ b/src/core/model/trace-source-accessor.h Thu Dec 18 15:12:35 2014 -0800
@@ -119,7 +119,7 @@
/********************************************************************
- Implementation of MakeTraceSourceAccessor
+ * Implementation of the templates declared above.
********************************************************************/
namespace ns3 {
--- a/src/core/model/traced-callback.h Wed Dec 17 12:17:11 2014 -0800
+++ b/src/core/model/traced-callback.h Thu Dec 18 15:12:35 2014 -0800
@@ -243,7 +243,7 @@
/********************************************************************
- Implementation of TimerImpl implementation functions.
+ * Implementation of the templates declared above.
********************************************************************/
namespace ns3 {
--- a/src/core/model/unix-fd-reader.cc Wed Dec 17 12:17:11 2014 -0800
+++ b/src/core/model/unix-fd-reader.cc Thu Dec 18 15:12:35 2014 -0800
@@ -21,7 +21,7 @@
#include <cerrno>
#include <cstring>
-#include <unistd.h>
+#include <unistd.h> // close()
#include <fcntl.h>
#include "log.h"
@@ -32,6 +32,12 @@
#include "unix-fd-reader.h"
+/**
+ * \file
+ * \ingroup system
+ * ns3::FdReader implementation.
+ */
+
namespace ns3 {
NS_LOG_COMPONENT_DEFINE ("FdReader");
--- a/src/core/model/unix-fd-reader.h Wed Dec 17 12:17:11 2014 -0800
+++ b/src/core/model/unix-fd-reader.h Thu Dec 18 15:12:35 2014 -0800
@@ -28,9 +28,9 @@
#include "event-id.h"
/**
+ * \file
* \ingroup system
- * \file
- * Asynchronous reads from a file descriptor, which trigger a Callback.
+ * ns3::FdReader declaration.
*/
namespace ns3 {
--- a/src/core/model/wall-clock-synchronizer.cc Wed Dec 17 12:17:11 2014 -0800
+++ b/src/core/model/wall-clock-synchronizer.cc Thu Dec 18 15:12:35 2014 -0800
@@ -16,18 +16,37 @@
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*/
-#include <ctime> // for clock_getres
-#include <sys/time.h>
+
+#include <ctime> // clock_t
+#include <sys/time.h> // gettimeofday
+ // clock_getres: glibc < 2.17, link with librt
#include "log.h"
#include "system-condition.h"
#include "wall-clock-synchronizer.h"
+/**
+ * \file
+ * \ingroup realtime
+ * ns3::WallClockSynchronizer implementation.
+ */
+
namespace ns3 {
NS_LOG_COMPONENT_DEFINE ("WallClockSynchronizer");
+NS_OBJECT_ENSURE_REGISTERED (WallClockSynchronizer);
+
+TypeId
+WallClockSynchronizer::GetTypeId (void)
+{
+ static TypeId tid = TypeId ("ns3::WallClockSynchronizer")
+ .SetParent<Synchronizer> ()
+ ;
+ return tid;
+}
+
WallClockSynchronizer::WallClockSynchronizer ()
{
NS_LOG_FUNCTION (this);
@@ -295,15 +314,8 @@
WallClockSynchronizer::SpinWait (uint64_t ns)
{
NS_LOG_FUNCTION (this << ns);
-//
-// Do a busy-wait until the normalized realtime equals the value passed in
-// or the condition variable becomes true. The condition becomes true if
-// an outside entity (a network device receives a packet, sets the condition
-// and signals the scheduler it needs to re-evaluate).
-//
// We just sit here and spin, wasting CPU cycles until we get to the right
// time or are told to leave.
-//
for (;;)
{
if (GetNormalizedRealtime () >= ns)
@@ -323,25 +335,6 @@
WallClockSynchronizer::SleepWait (uint64_t ns)
{
NS_LOG_FUNCTION (this << ns);
-//
-// Put our process to sleep for some number of nanoseconds. Typically this
-// will be some time equal to an integral number of jiffies. We will usually
-// follow a call to SleepWait with a call to SpinWait to get the kind of
-// accuracy we want.
-//
-// We have to have some mechanism to wake up this sleep in case an external
-// event happens that causes a schedule event in the simulator. This newly
-// scheduled event might be before the time we are waiting until, so we have
-// to break out of both the SleepWait and the following SpinWait to go back
-// and reschedule/resynchronize taking the new event into account. The
-// SystemCondition we have saved in m_condition takes care of this for us.
-//
-// This call will return if the timeout expires OR if the condition is
-// set true by a call to WallClockSynchronizer::SetCondition (true) followed
-// by a call to WallClockSynchronizer::Signal(). In either case, we are done
-// waiting. If the timeout happened, we TimedWait returns true; if a Signal
-// happened, false.
-//
return m_condition.TimedWait (ns);
}
--- a/src/core/model/wall-clock-synchronizer.h Wed Dec 17 12:17:11 2014 -0800
+++ b/src/core/model/wall-clock-synchronizer.h Thu Dec 18 15:12:35 2014 -0800
@@ -22,164 +22,165 @@
#include "system-condition.h"
#include "synchronizer.h"
+/**
+ * \file
+ * \ingroup realtime
+ * ns3::WallClockSynchronizer declaration.
+ */
+
namespace ns3 {
/**
+ * @ingroup realtime
* @brief Class used for synchronizing the simulation events to a real-time
- * "wall clock" using Posix Clock functions.
+ * "wall clock" using Posix clock functions.
*
* Enable this synchronizer using:
*
+ * \code
* DefaultValue::Bind ("Synchronizer", "WallClockSynchronizer");
+ * \endcode
*
* before calling any simulator functions.
*
- * The simulation clock is maintained as a 64-bit integer in a unit specified
- * by the user through the TimeStepPrecision::Set function. This means that
- * it is not possible to specify event expiration times with anything better
- * than this user-specified accuracy.
- *
* There are a couple of more issues at this level. Posix clocks provide
* access to several clocks we could use as a wall clock. We don't care about
- * time in the sense of 0430 CEST, we care about some piece of hardware that
+ * time in the sense of 04:30 CEST, we care about some piece of hardware that
* ticks at some regular period. The most accurate posix clock in this
- * respect is the CLOCK_PROCESS_CPUTIME_ID clock. This is a high-resolution
+ * respect is the \c CLOCK_PROCESS_CPUTIME_ID clock. This is a high-resolution
* register in the CPU. For example, on Intel machines this corresponds to
* the timestamp counter (TSC) register. The resolution of this counter will
* be on the order of nanoseconds.
*
* Now, just because we can measure time in nanoseconds doesn't mean we can
* put our process to sleep to nanosecond resolution. We are eventually going
- * to use the function clock_nanosleep () to sleep until a simulation Time
+ * to use the function \c clock_nanosleep() to sleep until a simulation Time
* specified by the caller.
*
- * MORE ON JIFFIES, SLEEP, PROCESSES, etc., as required
+ * \todo Add more on jiffies, sleep, processes, etc.
*
- * Nanosleep takes a struct timespec as an input so we have to deal with
- * conversion between Time and struct timespec here. They are both
- * interpreted as elapsed times.
+ * \internal
+ * Nanosleep takes a <tt>struct timeval</tt> as an input so we have to
+ * deal with conversion between Time and \c timeval here.
+ * They are both interpreted as elapsed times.
*/
class WallClockSynchronizer : public Synchronizer
{
public:
+ /**
+ * Get the registered TypeId for this class.
+ * \returns The TypeId.
+ */
+ static TypeId GetTypeId (void);
+
+ /** Constructor. */
WallClockSynchronizer ();
+ /** Destructor. */
virtual ~WallClockSynchronizer ();
+ /** Conversion constant between μs and ns. */
static const uint64_t US_PER_NS = (uint64_t)1000;
+ /** Conversion constant between μs and seconds. */
static const uint64_t US_PER_SEC = (uint64_t)1000000;
- /// Conversion from ns to s.
+ /** Conversion constant between ns and s. */
static const uint64_t NS_PER_SEC = (uint64_t)1000000000;
protected:
-/**
- * @brief Return true if this synchronizer is actually synchronizing to a
- * realtime clock. The simulator sometimes needs to know this.
- *
- * Subclasses are expected to implement this method to tell the outside world
- * whether or not they are synchronizing to a realtime clock.
- *
- * @returns True if locked with realtime, false if not.
- */
- virtual bool DoRealtime (void);
-
-/**
- * @brief Retrieve the value of the origin of the underlying normalized wall
- * clock time in nanosecond units.
- *
- * Subclasses are expected to implement this method to do the actual
- * real-time-clock-specific work of getting the current time.
- *
- * @returns The normalized wall clock time (in nanosecond units).
- * @see TimeStepPrecision::Get
- * @see Synchronizer::SetOrigin
- */
- virtual uint64_t DoGetCurrentRealtime (void);
+ /**
+ * @brief Do a busy-wait until the normalized realtime equals the argument
+ * or the condition variable becomes \c true.
+
+ * The condition becomes \c true if an outside entity (a network device
+ * receives a packet), sets the condition and signals the scheduler
+ * it needs to re-evaluate.
+ *
+ * @param ns The target normalized real time we should wait for.
+ * @returns \c true if we reached the target time,
+ * \c false if we retured because the condition was set.
+ */
+ bool SpinWait (uint64_t ns);
+ /**
+ * Put our process to sleep for some number of nanoseconds.
+ *
+ * Typically this will be some time equal to an integral number of jiffies.
+ * We will usually follow a call to SleepWait with a call to SpinWait
+ * to get the kind of accuracy we want.
+ *
+ * We have to have some mechanism to wake up this sleep in case an external
+ * event happens that causes a Schedule event in the simulator. This newly
+ * scheduled event might be before the time we are waiting until, so we have
+ * to break out of both the SleepWait and the following SpinWait to go back
+ * and reschedule/resynchronize taking the new event into account. The
+ * SystemCondition we have saved in m_condition takes care of this for us.
+ *
+ * This call will return if the timeout expires OR if the condition is
+ * set \c true by a call to SetCondition (true) followed by a call to
+ * Signal(). In either case, we are done waiting. If the timeout happened,
+ * we return \c true; if a Signal happened we return \c false.
+ *
+ * @param ns The target normalized real time we should wait for.
+ * @returns \c true if we reached the target time,
+ * \c false if we retured because the condition was set.
+ */
+ bool SleepWait (uint64_t ns);
-/**
- * @brief Establish a correspondence between a simulation time and a
- * wall-clock (real) time.
- *
- * There are three timelines involved here: the simulation time, the
- * (absolute) wall-clock time and the (relative) synchronizer real time.
- * Calling this method makes a correspondence between the origin of the
- * synchronizer time and the current wall-clock time.
- *
- * This method is expected to be called at the "instant" before simulation
- * begins. At this point, simulation time = 0, and synchronizer time is
- * set = 0 in this method. We then associate this time with the current
- * value of the real time clock that will be used to actually perform the
- * synchronization.
- *
- * Subclasses are expected to implement this method to do the actual
- * real-time-clock-specific work of making the correspondence mentioned above.
- * for example, this is where the differences between Time parameters and
- * parameters to clock_nanosleep would be dealt with.
- *
- * @param ns The simulation time we need to use as the origin (normalized to
- * nanosecond units).
- */
- virtual void DoSetOrigin (uint64_t ns);
-
-/**
- * @brief Declaration of method used to retrieve drift between the real time
- * clock used to synchronize the simulation and the current simulation time.
- *
- * @param ns Simulation timestep from the simulator normalized to nanosecond
- * steps.
- * @returns Drift in nanosecond units.
- * @see TimeStepPrecision::Get
- * @see Synchronizer::SetOrigin
- * @see Synchronizer::GetDrift
- */
- virtual int64_t DoGetDrift (uint64_t ns);
-
-/**
- * @brief Wait until the real time is in sync with the specified simulation
- * time.
- *
- * This is where the real work of synchronization is done. The Time passed
- * in as a parameter is the simulation time. The job of Synchronize is to
- * translate from simulation time to synchronizer time (in a perfect world
- * this is the same time) and then figure out how long in real-time it needs
- * to wait until that synchronizer / simulation time comes around.
- *
- * Subclasses are expected to implement this method to do the actual
- * real-time-clock-specific work of waiting (either busy-waiting or sleeping,
- * or some combination) until the requested simulation time.
- *
- * @param nsCurrent The current simulation time.
- * @param nsDelay The simulation time of the next event (in nanosecond units).
- *
- * @see TimeStepPrecision::Get
- */
- virtual bool DoSynchronize (uint64_t nsCurrent, uint64_t nsDelay);
- virtual void DoSignal (void);
- virtual void DoSetCondition (bool cond);
-
- virtual void DoEventStart (void);
- virtual uint64_t DoEventEnd (void);
-
- bool SpinWait (uint64_t);
- bool SleepWait (uint64_t);
-
+ /**
+ * @brief Compute a correction to the nominal delay to account for
+ * realtime drift since the last DoSynchronize.
+ *
+ * @param nsNow The current simulation time (in nanosecond units).
+ * @param nsDelay The simulation time we need to wait for (normalized to
+ * nanosecond units).
+ * @returns The corrected delay.
+ */
uint64_t DriftCorrect (uint64_t nsNow, uint64_t nsDelay);
+ /**
+ * @brief Get the current absolute real time (in ns since the epoch).
+ *
+ * @returns The current real time, in ns.
+ */
uint64_t GetRealtime (void);
+ /**
+ * @brief Get the current normalized real time, in ns.
+ *
+ * @returns The current normalized real time, in ns.
+ */
uint64_t GetNormalizedRealtime (void);
+ /**
+ * @brief Convert an absolute time in ns to a \c timeval
+ *
+ * @param ns Absolute time in ns.
+ * @param tv Converted \c timeval.
+ */
void NsToTimeval (int64_t ns, struct timeval *tv);
+ /**
+ * @brief Convert a \c timeval to absolute time, in ns.
+ *
+ * @param tv The input \c timeval.
+ * @returns The absolute time, in ns.
+ */
uint64_t TimevalToNs (struct timeval *tv);
+ /**
+ * @brief Add two \c timeval.
+ *
+ * @param tv1 The first \c timeval.
+ * @param tv2 The second \c timeval.
+ * @param result The sum of \c tv1 and \c tv2.
+ */
void TimevalAdd (
struct timeval *tv1,
struct timeval *tv2,
struct timeval *result);
- uint64_t m_cpuTick;
- uint64_t m_realtimeTick;
+ /** Size of the system clock tick, as reported by \c clock_getres, in ns. */
uint64_t m_jiffy;
+ /** Time recorded by DoEventStart. */
uint64_t m_nsEventStart;
+ /** Thread synchronizer. */
SystemCondition m_condition;
};
--- a/src/core/model/watchdog.cc Wed Dec 17 12:17:11 2014 -0800
+++ b/src/core/model/watchdog.cc Thu Dec 18 15:12:35 2014 -0800
@@ -21,6 +21,12 @@
#include "log.h"
+/**
+ * \file
+ * \ingroup timer
+ * ns3::Watchdog timer class implementation.
+ */
+
namespace ns3 {
NS_LOG_COMPONENT_DEFINE ("Watchdog");
--- a/src/core/model/watchdog.h Wed Dec 17 12:17:11 2014 -0800
+++ b/src/core/model/watchdog.h Thu Dec 18 15:12:35 2014 -0800
@@ -186,7 +186,7 @@
/********************************************************************
- Implementation of templates defined above
+ * Implementation of the templates declared above.
********************************************************************/
#include "timer-impl.h"