# HG changeset patch # User Peter D. Barnes, Jr. # Date 1418944355 28800 # Node ID 6a448ac28669db16da57c8b0109d830832c78ad4 # Parent 3f9a0f5f0be65ac0497974fa30115a879ab96053 [Doxygen] Various in src/core diff -r 3f9a0f5f0be6 -r 6a448ac28669 src/core/model/attribute-accessor-helper.h --- 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 MakeAccessor 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" diff -r 3f9a0f5f0be6 -r 6a448ac28669 src/core/model/command-line.cc --- 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 { diff -r 3f9a0f5f0be6 -r 6a448ac28669 src/core/model/command-line.h --- 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 { diff -r 3f9a0f5f0be6 -r 6a448ac28669 src/core/model/event-id.cc --- 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 { diff -r 3f9a0f5f0be6 -r 6a448ac28669 src/core/model/hash-function.h --- 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 { diff -r 3f9a0f5f0be6 -r 6a448ac28669 src/core/model/int-to-type.h --- 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 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 diff -r 3f9a0f5f0be6 -r 6a448ac28669 src/core/model/make-event.cc --- 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 { diff -r 3f9a0f5f0be6 -r 6a448ac28669 src/core/model/make-event.h --- 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. diff -r 3f9a0f5f0be6 -r 6a448ac28669 src/core/model/object-base.cc --- 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 { diff -r 3f9a0f5f0be6 -r 6a448ac28669 src/core/model/object-map.h --- 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 diff -r 3f9a0f5f0be6 -r 6a448ac28669 src/core/model/object-vector.h --- 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 diff -r 3f9a0f5f0be6 -r 6a448ac28669 src/core/model/object.cc --- 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 { diff -r 3f9a0f5f0be6 -r 6a448ac28669 src/core/model/ptr.h --- 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 Ptr const_pointer_cast (Ptr const&p); +// Duplicate of struct CallbackTraits as defined in callback.h template 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 struct CallbackTraits > @@ -474,6 +475,7 @@ } }; +// Duplicate of struct EventMemberImplObjTraits as defined in make-event.h template struct EventMemberImplObjTraits; diff -r 3f9a0f5f0be6 -r 6a448ac28669 src/core/model/realtime-simulator-impl.cc --- 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 +/** + * \file + * \ingroup realtime + * ns3::RealTimeSimulatorImpl implementation. + */ + namespace ns3 { // Note: Logging in this file is largely avoided due to the diff -r 3f9a0f5f0be6 -r 6a448ac28669 src/core/model/scheduler.cc --- 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"); diff -r 3f9a0f5f0be6 -r 6a448ac28669 src/core/model/simulation-singleton.h --- 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); }; diff -r 3f9a0f5f0be6 -r 6a448ac28669 src/core/model/simulator-impl.h --- 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); diff -r 3f9a0f5f0be6 -r 6a448ac28669 src/core/model/simulator.cc --- 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 #include +/** + * \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 diff -r 3f9a0f5f0be6 -r 6a448ac28669 src/core/model/simulator.h --- 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 #include +/** + * \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 diff -r 3f9a0f5f0be6 -r 6a448ac28669 src/core/model/synchronizer.cc --- 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); } diff -r 3f9a0f5f0be6 -r 6a448ac28669 src/core/model/synchronizer.h --- 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); }; diff -r 3f9a0f5f0be6 -r 6a448ac28669 src/core/model/system-path.cc --- 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 { diff -r 3f9a0f5f0be6 -r 6a448ac28669 src/core/model/timer-impl.h --- 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 diff -r 3f9a0f5f0be6 -r 6a448ac28669 src/core/model/timer.cc --- 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 { diff -r 3f9a0f5f0be6 -r 6a448ac28669 src/core/model/timer.h --- 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" diff -r 3f9a0f5f0be6 -r 6a448ac28669 src/core/model/trace-source-accessor.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 { diff -r 3f9a0f5f0be6 -r 6a448ac28669 src/core/model/traced-callback.h --- 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 { diff -r 3f9a0f5f0be6 -r 6a448ac28669 src/core/model/unix-fd-reader.cc --- 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 #include -#include +#include // close() #include #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"); diff -r 3f9a0f5f0be6 -r 6a448ac28669 src/core/model/unix-fd-reader.h --- 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 { diff -r 3f9a0f5f0be6 -r 6a448ac28669 src/core/model/wall-clock-synchronizer.cc --- 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 // for clock_getres -#include + +#include // clock_t +#include // 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 () + ; + 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); } diff -r 3f9a0f5f0be6 -r 6a448ac28669 src/core/model/wall-clock-synchronizer.h --- 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 struct timeval 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; }; diff -r 3f9a0f5f0be6 -r 6a448ac28669 src/core/model/watchdog.cc --- 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"); diff -r 3f9a0f5f0be6 -r 6a448ac28669 src/core/model/watchdog.h --- 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"