ns-3.24: comparison src/core/model/synchronizer.h

equal deleted inserted replaced

-:3f9a0f5f0be6
+:6a448ac28669
 #include <stdint.h>
 #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.
 *
 * The real-time clock is maintained as a 64-bit integer count of nanoseconds.
 * feedback loop.
 */
 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.
+* realtime clock.
-* @returns True if locked with realtime, false if not.
+*
-*/
+* 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).
+* @returns The normalized wall clock time (in Time resolution units).
-* @see TimeStepPrecision::Get
+* @see SetOrigin
-* @see Synchronizer::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
+* virtual method to do the actual real-time-clock-specific work
-* correspondence mentioned above.
+* of making the correspondence mentioned above.
 *
-* @param ts The simulation time we should use as the origin (in simulator
+* @param ts The simulation time we should use as the origin (in
-* timestep units).
+*     Time resolution units).
-* @see TimeStepPrecision::Get
+* @see DoSetOrigin
-* @see TimeStepPrecision::DoSetOrigin
+*/
-*/
 void SetOrigin (uint64_t ts);
 /**
 * @brief Retrieve the value of the origin of the simulation time in
-* simulator timestep units.
+* Time.resolution units.
 *
-* @returns The simulation time used as the origin (in simulator timestep
+* @returns The simulation time used as the origin (in Time resolution units).
-* units).
+* @see SetOrigin
-* @see TimeStepPrecision::Get
+*/
-* @see Synchronizer::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
+* synchronize the simulation and the simulation time (in
-* units).
+* Time resolution units).
 *
-* @param ts Simulation timestep from the simulator interpreted as current time
+* @param ts Simulation time in Time resolution units.
-* in the simulator.
+* @returns Simulation Time (in Time resolution units)
-* @returns Simulation timestep (in simulator timestep units) minus origin
+*     minus the origin time (stored internally in nanosecond units).
-* time (stored internally in nanosecond units).
+* @see SetOrigin
-* @see TimeStepPrecision::Get
+* @see DoGetDrift
-* @see Synchronizer::SetOrigin
+*/
-* @see Synchronizer::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
+* This is where the real work of synchronization is done.  The \c tsCurrent
-* in as a parameter is the simulation time.  The job of Synchronize is to
+* 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 simulator timestep units).
+* @param tsCurrent The current simulation time (in Time resolution units).
-* @param tsDelay The simulation time we need to wait for (in simulator
+* @param tsDelay The simulation time we need to wait for (in Time
-* timestep units).
+*     resolution units).
-* @returns True if the function ran to completion, false if it was interrupted
+* @returns \c true if the function ran to completion,
-* by a Signal.
+*          \c false if it was interrupted by a Signal.
-* @see TimeStepPrecision::Get
+* @see DoSynchronize
-* @see Synchronizer::DoSynchronize
+* @see Signal
-* @see Synchronizer::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.
+* 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
+* @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
+* @see Signal
 */
 void SetCondition (bool);
 /**
-* @brief Ask the synchronizer to remember what time it is.  Typically used
+* @brief Ask the synchronizer to remember what time it is.
-* with EventEnd to determine the real execution time of a simulation event.
+*
-*
+* Typically used with EventEnd to determine the real execution time
-* @see Synchronizer::EventEnd
+* of a simulation event.
-* @see TimeStepPrecision::Get
+*
-*/
+* @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
+* remembered during EventStart and now.
-* to determine the real execution time of a simulation event.
+*
-*
+* Used in conjunction with EventStart to determine the real execution time
-* @see Synchronizer::EventStart
+* of a simulation event.
-* @see TimeStepPrecision::Get
+*
-*/
+* @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
+* There are three timelines involved here:  the simulation (virtual) time,
-* (absolute) wall-clock time and the (relative) synchronizer real 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).
+*    nanosecond units).
-* @see Synchronizer::SetOrigin
+* @see SetOrigin
-* @see TimeStepPrecision::Get
+*/
-*/
 virtual void DoSetOrigin (uint64_t ns) = 0;
 /**
-* @brief Return true if this synchronizer is actually synchronizing to a
+* @brief Return \c true if this synchronizer is actually synchronizing to a
-* realtime clock.  The simulator sometimes needs to know this.
+* realtime clock.
 *
-* Subclasses are expected to implement this method to tell the outside world
+* The simulator sometimes needs to know this.
-* whether or not they are synchronizing to a realtime clock.
+*
-*
+* Subclasses are expected to implement this method to tell the outside world
-* @returns True if locked with realtime, false if not.
+* 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.
+* 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 TimeStepPrecision::Get
+* @see SetOrigin
-* @see Synchronizer::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
+* This is where the real work of synchronization is done.  The
-* in as a parameter is the simulation time.  The job of Synchronize is to
+* \c nsCurrent argument is the simulation time (in ns).  The job of
-* translate from simulation time to synchronizer time (in a perfect world
+* DoSynchronize is to translate from simulation time to synchronizer time
-* this is the same time) and then figure out how long in real-time it needs
+* (in a perfect world these are the same time) and then figure out
-* to wait until that synchronizer / simulation time comes around.
+* 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,
+* Subclasses are expected to implement this method to do the actual
-* or some combination) until the requested simulation time.
+* 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 nsCurrent The current simulation time (in 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
+* @returns \c true if the function ran to completion,
-* by a Signal.
+*          \c false if it was interrupted by a Signal.
-* @see Synchronizer::Synchronize
+* @see Synchronize
-* @see TimeStepPrecision::Get
+* @see Signal
-* @see Synchronizer::Signal
+*/
-*/
 virtual bool DoSynchronize (uint64_t nsCurrent, uint64_t nsDelay) = 0;
 /**
-* @brief Declaration of the method used to tell a possible simulator thread
+* @brief Tell a possible simulator thread waiting in the
-* waiting in the DoSynchronize method that an event has happened which
+* DoSynchronize method that an event has happened which
 * demands a reevaluation of the wait time.
 *
-* @see Synchronizer::Signal
+* @see Signal
 */
 virtual void DoSignal (void) = 0;
 /**
-* @brief Declaration of the method used to set the condition variable that
+* @brief Set the condition variable to tell a possible simulator thread
-* tells a possible simulator thread waiting in the Synchronize method that an
+* waiting in the Synchronize method that an event has happened which
-* event has happened which demands a reevaluation of the wait time.
+* demands a reevaluation of the wait time.
 *
-* @see Synchronizer::SetCondition
+* @see SetCondition
 */
 virtual void DoSetCondition (bool) = 0;
 /**
-* @brief Declaration of method used to retrieve drift between the real time
+* @brief Get the drift between the real time clock used to synchronize
-* clock used to synchronize the simulation and the current simulation time.
+* the simulation and the current simulation time.
 *
-* @param ns Simulation timestep from the simulator normalized to nanosecond
+* @param ns Simulation time in ns.
-* steps.
+* @returns Drift in ns units.
-* @returns Drift in nanosecond units.
+* @see SetOrigin
-* @see TimeStepPrecision::Get
+* @see GetDrift
-* @see Synchronizer::SetOrigin
+*/
-* @see Synchronizer::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
+* @brief Convert a simulator time step (in Time resolution units)
-* user-specified unit) to a normalized time step in nanosecond 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.
-* @see TimeStepPrecision::Get
+*/
-*/
 uint64_t TimeStepToNanosecond (uint64_t ts);
 /**
-* @brief Convert a normalized nanosecond count into a simulator time step
+* @brief Convert a normalized nanosecond time step into a
-* (which can be steps of time in a user-specified unit).
+* 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.
-* @see TimeStepPrecision::Get
+*/
-*/
 uint64_t NanosecondToTimeStep (uint64_t ns);
 };
 } // namespace ns3

changeset 11131	6a448ac28669
parent 11045	6024c150e4c8
child 11531	5d6b3f94ebf3