diff --git a/src/core/model/callback.h b/src/core/model/callback.h index 2b9583d57..7b039100c 100644 --- a/src/core/model/callback.h +++ b/src/core/model/callback.h @@ -32,6 +32,9 @@ namespace ns3 { +// Define the doxygen subgroups all at once, +// since the implementations are interleaved. + /** * \ingroup core * \defgroup callback Callbacks @@ -42,19 +45,68 @@ namespace ns3 { */ /** * \ingroup callback + * \defgroup callbackimpl Callback Implementation + * Callback implementation classes */ -/**@{*/ /** + * \ingroup callback + * \defgroup makecallbackmemptr MakeCallback from member function pointer + * + * Build Callbacks for class method members which take varying numbers + * of arguments and potentially returning a value. + * + * Generally the \c MakeCallback functions are invoked with the + * method function address first, followed by the \c this pointer: + * \code + * MakeCallback ( & MyClass::Handler, this); + * \endcode + * + * There is not a version with bound arguments. You may be able to + * get the same result by using \c MakeBoundCallback with a \c static + * member function, as in: + * \code + * MakeBoundCallback ( & MyClass::StaticHandler, this); + * \endcode + * This still leaves two argument slots available for binding. + */ +/** + * \ingroup callback + * \defgroup makecallbackfnptr MakeCallback from function pointers + * + * Build Callbacks for functions which take varying numbers of arguments + * and potentially returning a value. + */ +/** + * \ingroup callback + * \defgroup makenullcallback MakeCallback with no arguments + * + * Define empty (Null) callbacks as placeholders for unset callback variables. + */ +/** + * \ingroup callback + * \defgroup makeboundcallback MakeBoundCallback from functions bound with up to three arguments. + * + * Build bound Callbacks which take varying numbers of arguments, + * and potentially returning a value. + * + * \internal + * + * The following is experimental code. It works but we have + * not yet determined whether or not it is really useful and whether + * or not we really want to use it. + */ + + +/** + * \ingroup makecallbackmemptr + * * Trait class to convert a pointer into a reference, * used by MemPtrCallBackImpl + * @{ */ template struct CallbackTraits; -/** - * Trait class to convert a pointer into a reference, - * used by MemPtrCallBackImpl - */ template struct CallbackTraits { @@ -69,11 +121,6 @@ struct CallbackTraits }; /**@}*/ -/** - * \ingroup callback - * \defgroup callbackimpl Callback Implementation - * Callback implementation classes - */ /** * \ingroup callbackimpl * Abstract base class for CallbackImpl @@ -103,8 +150,9 @@ class CallbackImpl; /** * \ingroup callbackimpl * CallbackImpl classes with varying numbers of argument types + * + * @{ */ -/**@{*/ /** CallbackImpl class with no arguments. */ template class CallbackImpl : public CallbackImplBase { @@ -179,7 +227,7 @@ public: /** - * \ingroup callback + * \ingroup callbackimpl * CallbackImpl with functors */ template @@ -325,7 +373,7 @@ private: }; /** - * \ingroup callback + * \ingroup makecallbackmemptr * CallbackImpl for pointer to member functions */ template @@ -474,7 +522,7 @@ private: }; /** - * \ingroup callback + * \ingroup callbackimpl * CallbackImpl for functors with first argument bound at construction */ template @@ -608,7 +656,7 @@ private: }; /** - * \ingroup callback + * \ingroup callbackimpl * CallbackImpl for functors with first two arguments bound at construction */ template @@ -730,7 +778,7 @@ private: }; /** - * \ingroup callback + * \ingroup callbackimpl * CallbackImpl for functors with first three arguments bound at construction */ template @@ -841,7 +889,7 @@ private: }; /** - * \ingroup callback + * \ingroup callbackimpl * Base class for Callback class. * Provides pimpl abstraction. */ @@ -1219,13 +1267,6 @@ bool operator != (Callback a, Callback MakeCallback (R (T::*memPtr)(T1,T2,T3,T4, } /**@}*/ -/** - * \ingroup callback - * \defgroup makecallbackfnptr MakeCallback from function pointers - * - * Build Callbacks for functions which take varying numbers of arguments - * and potentially returning a value. - */ /** * \ingroup makecallbackfnptr * @{ @@ -1380,10 +1414,6 @@ Callback MakeCallback (R (*fnPtr)(T1,T2,T3,T4,T5,T } /**@}*/ -/** - * \ingroup callback - * \defgroup makenullcallback MakeCallback with no arguments - */ /** * \ingroup makenullcallback * @{ @@ -1438,27 +1468,10 @@ Callback MakeNullCallback (void) { /**@}*/ -/** - * \ingroup callback - * \defgroup makeboundcallback MakeBoundCallback from functions bound with up to three arguments. - */ - /** * \ingroup makeboundcallback - * - * Build bound Callbacks which take varying numbers of arguments, - * and potentially returning a value. - * - * \internal - * - * The following is experimental code. It works but we have - * not yet determined whether or not it is really useful and whether - * or not we really want to use it. - * - * @{ - */ -/** * @{ + * Make Callbacks with one bound argument. * \param fnPtr function pointer * \param a1 first bound argument * \return a bound Callback @@ -1528,11 +1541,13 @@ Callback MakeBoundCallback (R (*fnPtr)(TX,T1,T2,T3,T4 /**@}*/ /** + * \ingroup makeboundcallback + * @{ + * Make Callbacks with two bound arguments. * \param fnPtr function pointer * \param a1 first bound argument * \param a2 second bound argument * \return a bound Callback - * @{ */ template Callback MakeBoundCallback (R (*fnPtr)(TX1,TX2), ARG1 a1, ARG2 a2) { @@ -1592,12 +1607,14 @@ Callback MakeBoundCallback (R (*fnPtr)(TX1,TX2,T1,T2,T3, /**@}*/ /** + * \ingroup makeboundcallback + * @{ + * Make Callbacks with three bound arguments. * \param a1 first bound argument * \param a2 second bound argument * \param a3 third bound argument * \param fnPtr function pointer * \return a bound Callback - * @{ */ template Callback MakeBoundCallback (R (*fnPtr)(TX1,TX2,TX3), ARG1 a1, ARG2 a2, ARG3 a3) { @@ -1649,7 +1666,6 @@ Callback MakeBoundCallback (R (*fnPtr)(TX1,TX2,TX3,T1,T2,T3 } /**@}*/ -/**@}*/ } // namespace ns3 diff --git a/src/core/model/nstime.h b/src/core/model/nstime.h index 6ac5979d6..213c38c3f 100644 --- a/src/core/model/nstime.h +++ b/src/core/model/nstime.h @@ -37,6 +37,22 @@ class TimeWithUnit; /** * \ingroup core + * \defgroup time Virtual Time + * \brief Management of virtual time in real world units. + * + * The underlying simulator is unit agnostic, just dealing with + * dimensionless virtual time. Models usually need to handle + * time in real world units, such as seconds, and conversions/scaling + * between different units, between minutes and seconds, for example. + * + * The convenience constructors in the \ref timecivil "Standard Units" module + * make it easy to create Times in specific units. + * + * The Time::SetResolution() function allows a one-time change of the + * base resolution, before Simulator::Run(). + */ +/** + * \ingroup time * \brief Simulation virtual time values and global simulation resolution. * * This class defines all the classic C++ addition/subtraction @@ -97,11 +113,17 @@ public: LAST = 10 }; + /** + * Assignment operator + * \param [in] o Time to assign. + * \return the Time. + */ inline Time & operator = (const Time & o) { m_data = o.m_data; return *this; } + /** Default constructor, with value 0. */ inline Time () : m_data () { @@ -110,6 +132,11 @@ public: Mark (this); } } + /** + * Copy constructor + * + * \param [in] o Time to copy + */ inline Time(const Time & o) : m_data (o.m_data) { @@ -118,6 +145,13 @@ public: Mark (this); } } + /** + * Construct from a numeric value. + * + * The current time resolution will be assumed as the unit. + * \param [in] v The value. + * @{ + */ explicit inline Time (double v) : m_data (lround (v)) { @@ -174,6 +208,16 @@ public: Mark (this); } } + explicit inline Time (const int64x64_t & v) + : m_data (v.GetHigh ()) + { + if (g_markingTimes) + { + Mark (this); + } + } + /**@}*/ + /** * \brief Construct Time object from common time expressions like "1ms" * @@ -196,24 +240,18 @@ public: */ explicit Time (const std::string & s); - /** - * \brief Minimum representable Time - */ + /** Minimum representable Time */ static Time Min () { return Time (std::numeric_limits::min ()); } - /** - * \brief Maximum representable Time - */ + /** Maximum representable Time */ static Time Max () { return Time (std::numeric_limits::max ()); } - /** - * Destructor - */ + /** Destructor */ ~Time () { if (g_markingTimes) @@ -222,42 +260,35 @@ public: } } - /** - * \return true if the time is zero, false otherwise. - */ + /** \return true if the time is zero, false otherwise. */ inline bool IsZero (void) const { return m_data == 0; } - /** - * \return true if the time is negative or zero, false otherwise. - */ + /** \return true if the time is negative or zero, false otherwise. */ inline bool IsNegative (void) const { return m_data <= 0; } - /** - * \return true if the time is positive or zero, false otherwise. - */ + /** \return true if the time is positive or zero, false otherwise. */ inline bool IsPositive (void) const { return m_data >= 0; } - /** - * \return true if the time is strictly negative, false otherwise. - */ + /** \return true if the time is strictly negative, false otherwise. */ inline bool IsStrictlyNegative (void) const { return m_data < 0; } - /** - * \return true if the time is strictly positive, false otherwise. - */ + /** \return true if the time is strictly positive, false otherwise. */ inline bool IsStrictlyPositive (void) const { return m_data > 0; } /** + * Compare \p this to another Time + * + * \param [in] o The other Time * \return -1,0,+1 if `this < o`, `this == o`, or `this > o` */ inline int Compare (const Time & o) const @@ -266,90 +297,57 @@ public: } /** - * \returns an approximation in seconds of the time stored in this - * instance. - */ - inline double GetSeconds (void) const - { - return ToDouble (Time::S); - } - - /** - * \returns an approximation in milliseconds of the time stored in this - * instance. - */ - inline int64_t GetMilliSeconds (void) const - { - return ToInteger (Time::MS); - } - /** - * \returns an approximation in microseconds of the time stored in this - * instance. - */ - inline int64_t GetMicroSeconds (void) const - { - return ToInteger (Time::US); - } - /** - * \returns an approximation in nanoseconds of the time stored in this - * instance. - */ - inline int64_t GetNanoSeconds (void) const - { - return ToInteger (Time::NS); - } - /** - * \returns an approximation in picoseconds of the time stored in this - * instance. - */ - inline int64_t GetPicoSeconds (void) const - { - return ToInteger (Time::PS); - } - /** - * \returns an approximation in femtoseconds of the time stored in this - * instance. - */ - inline int64_t GetFemtoSeconds (void) const - { - return ToInteger (Time::FS); - } - - /** - * \returns an approximation in minutes of the time stored in this - * instance. - */ - inline double GetMinutes (void) const - { - return ToDouble (Time::MIN); - } - /** - * \returns an approximation in hours of the time stored in this - * instance. - */ - inline double GetHours (void) const - { - return ToDouble (Time::H); - } - /** - * \returns an approximation in days of the time stored in this - * instance. - */ - inline double GetDays (void) const - { - return ToDouble (Time::D); - } - /** - * \returns an approximation in years of the time stored in this - * instance. + * Get an approximation of the time stored in this instance + * in the indicated unit. + * + * \return An approximate value in the indicated unit. + * @{ */ inline double GetYears (void) const { return ToDouble (Time::Y); } + inline double GetDays (void) const + { + return ToDouble (Time::D); + } + inline double GetHours (void) const + { + return ToDouble (Time::H); + } + inline double GetMinutes (void) const + { + return ToDouble (Time::MIN); + } + inline double GetSeconds (void) const + { + return ToDouble (Time::S); + } + inline int64_t GetMilliSeconds (void) const + { + return ToInteger (Time::MS); + } + inline int64_t GetMicroSeconds (void) const + { + return ToInteger (Time::US); + } + inline int64_t GetNanoSeconds (void) const + { + return ToInteger (Time::NS); + } + inline int64_t GetPicoSeconds (void) const + { + return ToInteger (Time::PS); + } + inline int64_t GetFemtoSeconds (void) const + { + return ToInteger (Time::FS); + } + /**@}*/ /** - * \returns the raw time value, in the current units + * \returns the raw time value, in the current unit + * @{ */ inline int64_t GetTimeStep (void) const { @@ -363,6 +361,7 @@ public: { return GetTimeStep (); } + /**@}*/ /** @@ -377,19 +376,29 @@ public: * \returns the current global resolution. */ static enum Unit GetResolution (void); + + /** - * \param value to convert into a Time object - * \param timeUnit the unit of the value to convert - * \return a new Time object + * Create a Time in the current unit. * - * This method interprets the input value according to the input - * unit and constructs a matching Time object. - * - * \sa FromDouble, ToDouble, ToInteger + * \param [in] value The value of the new Time. + * \return A Time with \p value in the current time unit. */ - inline static Time FromInteger (uint64_t value, enum Unit timeUnit) + inline static Time From (const int64x64_t & value) { - struct Information *info = PeekInformation (timeUnit); + return Time (value); + } + /** + * Create a Time equal to \p value in unit \c unit + * + * \param [in] value The new Time value, expressed in \c unit + * \param [in] unit The unit of \p value + * \return The Time representing \p value in \c unit + * @{ + */ + inline static Time FromInteger (uint64_t value, enum Unit unit) + { + struct Information *info = PeekInformation (unit); if (info->fromMul) { value *= info->factor; @@ -400,16 +409,39 @@ public: } return Time (value); } - /** - * \param timeUnit the unit of the value to return - * \return int64_t time value - * - * Convert the input time into an integer value according to the requested - * time unit. - */ - inline int64_t ToInteger (enum Unit timeUnit) const + inline static Time FromDouble (double value, enum Unit unit) { - struct Information *info = PeekInformation (timeUnit); + return From (int64x64_t (value), unit); + } + inline static Time From (const int64x64_t & value, enum Unit unit) + { + struct Information *info = PeekInformation (unit); + // DO NOT REMOVE this temporary variable. It's here + // to work around a compiler bug in gcc 3.4 + int64x64_t retval = value; + if (info->fromMul) + { + retval *= info->timeFrom; + } + else + { + retval.MulByInvert (info->timeFrom); + } + return Time (retval); + } + /**@}*/ + + + /** + * Get the Time value expressed in a particular unit. + * + * \param [in] unit The desired unit + * \return The Time expressed in \p unit + * @{ + */ + inline int64_t ToInteger (enum Unit unit) const + { + struct Information *info = PeekInformation (unit); int64_t v = m_data; if (info->toMul) { @@ -421,47 +453,13 @@ public: } return v; } - /** - * \param value to convert into a Time object - * \param timeUnit the unit of the value to convert - * \return a new Time object - * - * \sa FromInteger, ToInteger, ToDouble - */ - inline static Time FromDouble (double value, enum Unit timeUnit) + inline double ToDouble (enum Unit unit) const { - return From (int64x64_t (value), timeUnit); + return To (unit).GetDouble (); } - /** - * \param timeUnit the unit of the value to return - * \return double time value - * - * Convert the input time into a floating point value according to the requested - * time unit. - */ - inline double ToDouble (enum Unit timeUnit) const + inline int64x64_t To (enum Unit unit) const { - return To (timeUnit).GetDouble (); - } - static inline Time From (const int64x64_t & from, enum Unit timeUnit) - { - struct Information *info = PeekInformation (timeUnit); - // DO NOT REMOVE this temporary variable. It's here - // to work around a compiler bug in gcc 3.4 - int64x64_t retval = from; - if (info->fromMul) - { - retval *= info->timeFrom; - } - else - { - retval.MulByInvert (info->timeFrom); - } - return Time (retval); - } - inline int64x64_t To (enum Unit timeUnit) const - { - struct Information *info = PeekInformation (timeUnit); + struct Information *info = PeekInformation (unit); int64x64_t retval = int64x64_t (m_data); if (info->toMul) { @@ -473,23 +471,16 @@ public: } return retval; } + /**@}*/ + + + /** Cast to int64x64_t */ inline operator int64x64_t () const { return int64x64_t (m_data); } - explicit inline Time (const int64x64_t & value) - : m_data (value.GetHigh ()) - { - if (g_markingTimes) - { - Mark (this); - } - } - inline static Time From (const int64x64_t & value) - { - return Time (value); - } + /** * Attach a unit to a Time, to facilitate output in a specific unit. * @@ -501,13 +492,12 @@ public: * will print ``+3140.0ms`` * * \param unit [in] The unit to use. + * \return The Time with embedded unit. */ TimeWithUnit As (const enum Unit unit) const; private: - /** - * How to convert between other units and the current unit - */ + /** How to convert between other units and the current unit. */ struct Information { bool toMul; //!< Multiply when converting To, otherwise divide @@ -516,26 +506,47 @@ private: int64x64_t timeTo; //!< Multiplier to convert to this unit int64x64_t timeFrom; //!< Multiplier to convert from this unit }; - /** - * Current time unit, and conversion info. - */ + /** Current time unit, and conversion info. */ struct Resolution { struct Information info[LAST]; //!< Conversion info from current unit enum Time::Unit unit; //!< Current time unit }; + /** + * Get the current Resolution + * + * \return A pointer to the current Resolution + */ static inline struct Resolution *PeekResolution (void) { static struct Time::Resolution resolution = SetDefaultNsResolution (); return & resolution; } + /** + * Get the Information record for \p timeUnit for the current Resolution + * + * \param [in] timeUnit The Unit to get Information for + * \return the Information for \p timeUnit + */ static inline struct Information *PeekInformation (enum Unit timeUnit) { return & (PeekResolution ()->info[timeUnit]); } + /** + * Set the default resolution + * + * \return The Resolution object for the default resolution. + */ static struct Resolution SetDefaultNsResolution (void); + /** + * Set the current Resolution. + * + * \param [in] unit The unit to use as the new resolution. + * \param [in,out] resolution The Resolution record to update. + * \param [in] convert Whether to convert existing Time objects to the new resolution. + */ static void SetResolution (enum Unit unit, struct Resolution *resolution, const bool convert = true); @@ -576,7 +587,9 @@ private: static MarkedTimes * g_markingTimes; public: /** - * Function to force static initialization of Time + * Function to force static initialization of Time. + * + * \return true on the first call */ static bool StaticInit (); private: @@ -593,18 +606,28 @@ private: */ static void ClearMarkedTimes (); /** - * Record a Time instance with the MarkedTimes + * Record a Time instance with the MarkedTimes. + * \param [in] time The Time instance to record. */ static void Mark (Time * const time); /** - * Remove a Time instance from the MarkedTimes, called by ~Time() + * Remove a Time instance from the MarkedTimes, called by ~Time(). + * \param [in] time The Time instance to remove. */ static void Clear (Time * const time); /** * Convert existing Times to the new unit. + * \param [in] unit The Unit to convert existing Times to. */ static void ConvertTimes (const enum Unit unit); + /** + * @{ + * Arithmetic operator. + * \param [in] lhs Left hand argument + * \param [in] rhs Righ hand argument + * \return The result of the operator. + */ friend bool operator == (const Time & lhs, const Time & rhs); friend bool operator != (const Time & lhs, const Time & rhs); friend bool operator <= (const Time & lhs, const Time & rhs); @@ -619,12 +642,30 @@ private: friend Time operator / (const Time & lhs, const int64_t & rhs); friend Time & operator += (Time & lhs, const Time & rhs); friend Time & operator -= (Time & lhs, const Time & rhs); + /**@}*/ + + /** + * Absolute value function for Time + * \param time the input value + * \returns the absolute value of the input value. + */ friend Time Abs (const Time & time); + /** + * Max function for Time. + * \param ta the first value + * \param tb the seconds value + * \returns the max of the two input values. + */ friend Time Max (const Time & ta, const Time & tb); + /** + * Min function for Time. + * \param ta the first value + * \param tb the seconds value + * \returns the min of the two input values. + */ friend Time Min (const Time & ta, const Time & tb); - - int64_t m_data; //!< Virtual time value, in the current unit. + int64_t m_data; //!< Virtual time value, in the current unit. }; // class Time @@ -708,38 +749,22 @@ inline Time & operator -= (Time & lhs, const Time & rhs) return lhs; } -/** - * Max function for Time. - * \param ta the first value - * \param tb the seconds value - * \returns the max of the two input values. - */ + +inline Time Abs (const Time & time) +{ + return Time ((time.m_data < 0) ? -time.m_data : time.m_data); +} inline Time Max (const Time & ta, const Time & tb) { return Time ((ta.m_data < tb.m_data) ? tb : ta); } -/** - * Min function for Time. - * \param ta the first value - * \param tb the seconds value - * \returns the min of the two input values. - */ inline Time Min (const Time & ta, const Time & tb) { return Time ((ta.m_data > tb.m_data) ? tb : ta); } /** - * Absolute value function for Time - * \param time the input value - * \returns the absolute value of the input value. - */ -inline Time Abs (const Time & time) -{ - return Time ((time.m_data < 0) ? -time.m_data : time.m_data); -} - -/** + * \ingroup time * \brief Time output streamer. * * Generates output such as "3.96ns". Times are printed with the @@ -749,274 +774,163 @@ inline Time Abs (const Time & time) * - `left` * The stream `width` and `precision` are ignored; Time output always * includes ".0". - * \relates Time + * + * \param [in] os The output stream. + * \param [in] time The Time to put on the stream. + * \return The stream. */ -std::ostream & operator<< (std::ostream & os, const Time & time); +std::ostream & operator << (std::ostream & os, const Time & time); /** + * \ingroup time * \brief Time input streamer * * Uses the Time::Time (const std::string &) constructor - * \relates Time + * + * \param [in] is The input stream. + * \param [out] time The Time variable to set from the stream data. + * \return The stream. */ -std::istream & operator>> (std::istream & is, Time & time); +std::istream & operator >> (std::istream & is, Time & time); /** - * \brief create ns3::Time instances in units of seconds. + * \ingroup time + * \defgroup timecivil Standard time units. + * \brief Convenience constructors in standard units. * * For example: * \code - * Time t = Seconds (2.0); - * Simulator::Schedule (Seconds (5.0), ...); + * Time t = Seconds (2.0); + * Simulator::Schedule (Seconds (5.0), ...); * \endcode - * \param seconds seconds value - * \relates Time */ -inline Time Seconds (double seconds) +/** + * \ingroup timecivil + * Construct a Time in the indicated unit. + * \param value The value + * \return The Time + * @{ + */ +inline Time Years (double value) { - return Time::FromDouble (seconds, Time::S); + return Time::FromDouble (value, Time::Y); } +inline Time Years (int64x64_t value) +{ + return Time::From (value, Time::Y); +} +inline Time Days (double value) +{ + return Time::FromDouble (value, Time::D); +} +inline Time Days (int64x64_t value) +{ + return Time::From (value, Time::D); +} +inline Time Hours (double value) +{ + return Time::FromDouble (value, Time::H); +} +inline Time Hours (int64x64_t value) +{ + return Time::From (value, Time::H); +} +inline Time Minutes (double value) +{ + return Time::FromDouble (value, Time::MIN); +} +inline Time Minutes (int64x64_t value) +{ + return Time::From (value, Time::MIN); +} +inline Time Seconds (double value) +{ + return Time::FromDouble (value, Time::S); +} +inline Time Seconds (int64x64_t value) +{ + return Time::From (value, Time::S); +} +inline Time MilliSeconds (uint64_t value) +{ + return Time::FromInteger (value, Time::MS); +} +inline Time MilliSeconds (int64x64_t value) +{ + return Time::From (value, Time::MS); +} +inline Time MicroSeconds (uint64_t value) +{ + return Time::FromInteger (value, Time::US); +} +inline Time MicroSeconds (int64x64_t value) +{ + return Time::From (value, Time::US); +} +inline Time NanoSeconds (uint64_t value) +{ + return Time::FromInteger (value, Time::NS); +} +inline Time NanoSeconds (int64x64_t value) +{ + return Time::From (value, Time::NS); +} +inline Time PicoSeconds (uint64_t value) +{ + return Time::FromInteger (value, Time::PS); +} +inline Time PicoSeconds (int64x64_t value) +{ + return Time::From (value, Time::PS); +} +inline Time FemtoSeconds (uint64_t value) +{ + return Time::FromInteger (value, Time::FS); +} +inline Time FemtoSeconds (int64x64_t value) +{ + return Time::From (value, Time::FS); +} +/**@}*/ + /** - * \brief create ns3::Time instances in units of milliseconds. - * - * For example: - * \code - * Time t = MilliSeconds (2); - * Simulator::Schedule (MilliSeconds (5), ...); - * \endcode - * \param ms milliseconds value - * \relates Time + * \ingroup time + * \internal Scheduler interface + * \param [in] ts The time value, in the current unit. + * \return A Time. */ -inline Time MilliSeconds (uint64_t ms) -{ - return Time::FromInteger (ms, Time::MS); -} -/** - * \brief create ns3::Time instances in units of microseconds. - * - * For example: - * \code - * Time t = MicroSeconds (2); - * Simulator::Schedule (MicroSeconds (5), ...); - * \endcode - * \param us microseconds value - * \relates Time - */ -inline Time MicroSeconds (uint64_t us) -{ - return Time::FromInteger (us, Time::US); -} -/** - * \brief create ns3::Time instances in units of nanoseconds. - * - * For example: - * \code - * Time t = NanoSeconds (2); - * Simulator::Schedule (NanoSeconds (5), ...); - * \endcode - * \param ns nanoseconds value - * \relates Time - */ -inline Time NanoSeconds (uint64_t ns) -{ - return Time::FromInteger (ns, Time::NS); -} -/** - * \brief create ns3::Time instances in units of picoseconds. - * - * For example: - * \code - * Time t = PicoSeconds (2); - * Simulator::Schedule (PicoSeconds (5), ...); - * \endcode - * \param ps picoseconds value - * \relates Time - */ -inline Time PicoSeconds (uint64_t ps) -{ - return Time::FromInteger (ps, Time::PS); -} -/** - * \brief create ns3::Time instances in units of femtoseconds. - * - * For example: - * \code - * Time t = FemtoSeconds (2); - * Simulator::Schedule (FemtoSeconds (5), ...); - * \endcode - * \param fs femtoseconds value - * \relates Time - */ -inline Time FemtoSeconds (uint64_t fs) -{ - return Time::FromInteger (fs, Time::FS); -} -/** - * \brief create ns3::Time instances in units of minutes (equal to 60 seconds). - * - * For example: - * \code - * Time t = Minutes (2.0); - * Simulator::Schedule (Minutes (5.0), ...); - * \endcode - * \param minutes mintues value - * \relates Time - */ -inline Time Minutes (double minutes) -{ - return Time::FromDouble (minutes, Time::MIN); -} -/** - * \brief create ns3::Time instances in units of hours (equal to 60 minutes). - * - * For example: - * \code - * Time t = Hours (2.0); - * Simulator::Schedule (Hours (5.0), ...); - * \endcode - * \param hours hours value - * \relates Time - */ -inline Time Hours (double hours) -{ - return Time::FromDouble (hours, Time::H); -} -/** - * \brief create ns3::Time instances in units of days (equal to 24 hours). - * - * For example: - * \code - * Time t = Days (2.0); - * Simulator::Schedule (Days (5.0), ...); - * \endcode - * \param days days value - * \relates Time - */ -inline Time Days (double days) -{ - return Time::FromDouble (days, Time::D); -} -/** - * \brief create ns3::Time instances in units of years (equal to 365 days). - * - * For example: - * \code - * Time t = Years (2.0); - * Simulator::Schedule (Years (5.0), ...); - * \endcode - * \param years years value - * \relates Time - */ -inline Time Years (double years) -{ - return Time::FromDouble (years, Time::Y); -} - -/** - * \see Seconds(double) - * \relates Time - */ -inline Time Seconds (int64x64_t seconds) -{ - return Time::From (seconds, Time::S); -} -/** - * \see MilliSeconds(uint64_t) - * \relates Time - */ -inline Time MilliSeconds (int64x64_t ms) -{ - return Time::From (ms, Time::MS); -} -/** - * \see MicroSeconds(uint64_t) - * \relates Time - */ -inline Time MicroSeconds (int64x64_t us) -{ - return Time::From (us, Time::US); -} -/** - * \see NanoSeconds(uint64_t) - * \relates Time - */ -inline Time NanoSeconds (int64x64_t ns) -{ - return Time::From (ns, Time::NS); -} -/** - * \see PicoSeconds(uint64_t) - * \relates Time - */ -inline Time PicoSeconds (int64x64_t ps) -{ - return Time::From (ps, Time::PS); -} -/** - * \see FemtoSeconds(uint64_t) - * \relates Time - */ -inline Time FemtoSeconds (int64x64_t fs) -{ - return Time::From (fs, Time::FS); -} -/** - * \see Minutes(uint64_t) - * \relates Time - */ -inline Time Minutes (int64x64_t minutes) -{ - return Time::From (minutes, Time::MIN); -} -/** - * \see Minutes(uint64_t) - * \relates Time - */ -inline Time Hours (int64x64_t hours) -{ - return Time::From (hours, Time::H); -} -/** - * \see Minutes(uint64_t) - * \relates Time - */ -inline Time Days (int64x64_t days) -{ - return Time::From (days, Time::D); -} -/** - * \see Minutes(uint64_t) - * \relates Time - */ -inline Time Years (int64x64_t years) -{ - return Time::From (years, Time::Y); -} - -// internal function not publicly documented inline Time TimeStep (uint64_t ts) { return Time (ts); } /** + * \ingroup time * \class ns3::TimeValue - * \brief hold objects of type ns3::Time + * \brief Attribute for objects of type ns3::Time */ - - ATTRIBUTE_VALUE_DEFINE (Time); -ATTRIBUTE_ACCESSOR_DEFINE (Time); /** - * \brief Helper to make a Time checker with bounded range. - * Both limits are inclusive + * Attribute accessor function for Time + * @{ + */ +ATTRIBUTE_ACCESSOR_DEFINE (Time); +/**@}*/ + +/** + * \ingroup time + * \brief Helper to make a Time checker with bounded range. + * Both limits are inclusive * - * \return the AttributeChecker + * \param [in] min Minimum allowed value. + * \param [in] max Maximum allowed value. + * \return the AttributeChecker */ Ptr MakeTimeChecker (const Time min, const Time max); /** + * \ingroup time * \brief Helper to make an unbounded Time checker. * * \return the AttributeChecker @@ -1028,8 +942,10 @@ Ptr MakeTimeChecker (void) } /** + * \ingroup time * \brief Helper to make a Time checker with a lower bound. * + * \param [in] min Minimum allowed value. * \return the AttributeChecker */ inline @@ -1060,8 +976,13 @@ private: Time m_time; //!< The time Time::Unit m_unit; //!< The unit to use in output - /// Output streamer - friend std::ostream & operator << (std::ostream & os, const TimeWithUnit & time); + /** + * Output streamer + * \param [in] os The stream. + * \param [in] timeU The Time with desired unit + * \returns The stream. + */ + friend std::ostream & operator << (std::ostream & os, const TimeWithUnit & timeU); }; // class TimeWithUnit diff --git a/src/core/model/time.cc b/src/core/model/time.cc index 027106bf9..4e050aab0 100644 --- a/src/core/model/time.cc +++ b/src/core/model/time.cc @@ -44,6 +44,8 @@ Time::MarkedTimes * Time::g_markingTimes = 0; * \internal * Get mutex for critical sections around modification of Time::g_markingTimes * + * \returns The static mutex to control access to Time::g_markingTimes. + * * \relates Time */ SystemMutex & @@ -387,8 +389,8 @@ Time::As (const enum Unit unit) const } -std::ostream& -operator<< (std::ostream& os, const Time & time) +std::ostream & +operator << (std::ostream & os, const Time & time) { os << time.As (Time::GetResolution ()); return os; @@ -427,7 +429,8 @@ operator << (std::ostream & os, const TimeWithUnit & timeU) } -std::istream& operator>> (std::istream& is, Time & time) +std::istream & +operator >> (std::istream & is, Time & time) { std::string value; is >> value; diff --git a/src/flow-monitor/model/histogram.h b/src/flow-monitor/model/histogram.h index 13f915d09..fe3d57d56 100644 --- a/src/flow-monitor/model/histogram.h +++ b/src/flow-monitor/model/histogram.h @@ -38,7 +38,7 @@ namespace ns3 { * * \todo Add support for negative data. * - * \todo Add method(s) to estimate \f$N\f$, \f$\mu\f$, and \f$s^2\f$ from the histogram, + * \todo Add method(s) to estimate parameters from the histogram, * see http://www.dspguide.com/ch2/4.htm * */ diff --git a/src/internet/model/ripng.h b/src/internet/model/ripng.h index 3f95e685f..5f581791c 100644 --- a/src/internet/model/ripng.h +++ b/src/internet/model/ripng.h @@ -36,7 +36,7 @@ namespace ns3 { /** * \defgroup ripng RIPng * - * The RIPng protocol (\rfc{2080}) is a unicast-only IPv6 IGP (Interior Gateway Protocol). + * The RIPng protocol (\RFC{2080}) is a unicast-only IPv6 IGP (Interior Gateway Protocol). * Its convergence time is rather long. As a consequence, it is suggested to * carefully check the network topology and the route status before sending * data flows. @@ -168,7 +168,7 @@ std::ostream& operator<< (std::ostream& os, RipNgRoutingTableEntry const& route) /** * \ingroup ripng * - * \brief RIPng Routing Protocol, defined in \rfc{2080}. + * \brief RIPng Routing Protocol, defined in \RFC{2080}. */ class RipNg : public Ipv6RoutingProtocol {