From 7c28f1cf7b9172baa9de770c60f6f3f4270df27b Mon Sep 17 00:00:00 2001 From: Mathieu Lacage Date: Fri, 3 Nov 2006 10:22:45 +0100 Subject: [PATCH] add doxygen dox for Time classes --- src/simulator/nstime.h | 191 ++++++++++++++++++++++++++++++++++++++++- 1 file changed, 188 insertions(+), 3 deletions(-) diff --git a/src/simulator/nstime.h b/src/simulator/nstime.h index 43a6b70b2..32b390981 100644 --- a/src/simulator/nstime.h +++ b/src/simulator/nstime.h @@ -27,6 +27,51 @@ namespace ns3 { +/** + * \brief keep track of time unit. + * + * This template class is used to keep track of the value + * of a specific time unit: the type TimeUnit<1> is used to + * keep track of seconds, the type TimeUnit<2> is used to keep + * track of seconds squared, the type TimeUnit<-1> is used to + * keep track of 1/seconds, etc. + * + * This base class defines all the functionality shared by all + * these time unit objects: it defines all the classic arithmetic + * operators +, -, *, /, and all the classic comparison operators: + * ==, !=, <, >, <=, >=. It is thus easy to add, substract, or + * multiply multiple TimeUnit objects. The return type of any such + * arithmetic expression is always a TimeUnit object. + * + * The ns3::Scalar, ns3::Time, ns3::TimeSquare, and ns3::TimeInvert classes + * are aliases for the TimeUnit<0>, TimeUnit<1>, TimeUnit<2> and TimeUnit<-1> + * types respectively. + * + * For example: + * \code + * Time<1> t1 = Seconds (10.0); + * Time<1> t2 = Seconds (10.0); + * Time<2> t3 = t1 * t2; + * Time<0> t4 = t1 / t2; + * Time<3> t5 = t3 * t1; + * Time<-2> t6 = t1 / t5; + * TimeSquare t7 = t3; + * Scalar s = t4; + * \endcode + * + * If you try to assign the result of an expression which does not + * match the type of the variable it is assigned to, you will get a + * compiler error. For example, the following will not compile: + * \code + * Time<1> = Seconds (10.0) * Seconds (1.5); + * \endcode + * + * You can also use the following non-member functions to manipulate + * any of these ns3::TimeUnit object: + * - \ref ns3-Time-Abs ns3::Abs + * - \ref ns3-Time-Max ns3::Max + * - \ref ns3-Time-Min ns3::Min + */ template class TimeUnit { @@ -35,12 +80,32 @@ public: TimeUnit (TimeUnit const &o); TimeUnit operator = (TimeUnit const &o); TimeUnit (HighPrecision data); + + /** + * \return the ns3::HighPrecision object which holds the value + * stored in this Time type. + */ HighPrecision GetHighPrecision (void) const; + /** + * \return true if the time is zero, false otherwise. + */ bool IsZero (void) const; + /** + * \return true if the time is negative or zero, false otherwise. + */ bool IsNegative (void) const; + /** + * \return true if the time is positive or zero, false otherwise. + */ bool IsPositive (void) const; + /** + * \return true if the time is strictly negative, false otherwise. + */ bool IsStrictlyNegative (void) const; + /** + * \return true if the time is strictly positive, false otherwise. + */ bool IsStrictlyPositive (void) const; private: @@ -167,11 +232,24 @@ TimeUnit operator / (TimeUnit const &lhs, TimeUnit const &rhs) return TimeUnit (retval); } +/** + * \anchor ns3-Time-Abs + * \relates ns3::TimeUnit + * \param time the input value + * \returns the absolute value of the input value. + */ template TimeUnit Abs (TimeUnit const &time) { return TimeUnit (Abs (time.GetHighPrecision ())); } +/** + * \anchor ns3-Time-Max + * \relates ns3::TimeUnit + * \param ta the first value + * \param tb the seconds value + * \returns the max of the two input values. + */ template TimeUnit Max (TimeUnit const &ta, TimeUnit const &tb) { @@ -179,6 +257,13 @@ TimeUnit Max (TimeUnit const &ta, TimeUnit const &tb) HighPrecision b = tb.GetHighPrecision (); return TimeUnit (Max (a, b)); } +/** + * \anchor ns3-Time-Min + * \relates ns3::TimeUnit + * \param ta the first value + * \param tb the seconds value + * \returns the min of the two input values. + */ template TimeUnit Min (TimeUnit const &ta, TimeUnit const &tb) { @@ -187,20 +272,68 @@ TimeUnit Min (TimeUnit const &ta, TimeUnit const &tb) return TimeUnit (Max (a, b)); } - +/** + * \brief keep track of seconds. + * + * This is an instance of type ns3::TimeUnit<1>: it is + * the return value of the ns3::Simulator::Now method + * and is needed for the Simulator::Schedule methods + * + * Time instances can be created through any of the following classes: + * - ns3::Seconds + * - ns3::MilliSeconds + * - ns3::MicroSeconds + * - ns3::NanoSeconds + * - ns3::Now + * + * Time instances can be added, substracted, multipled and divided using + * the standard C++ operators (if you make sure to obey the rules + * of the ns3::TimeUnit class template) + * To scale a Time instance, you can multiply it with an instance of + * the ns3::Scalar class. + * Time instances can also be manipulated through the following non-member + * functions: + * - \ref ns3-Time-Abs ns3::Abs + * - \ref ns3-Time-Max ns3::Max + * - \ref ns3-Time-Min ns3::Min + */ class Time : public TimeUnit<1> { public: Time (); Time (TimeUnit<1> time); + /** + * \returns an approximation in seconds of the time stored in this + * instance. + */ double ApproximateToSeconds (void) const; + /** + * \returns an approximation in milliseconds of the time stored in this + * instance. + */ int32_t ApproximateToMilliSeconds (void) const; + /** + * \returns an approximation in microseconds of the time stored in this + * instance. + */ int64_t ApproximateToMicroSeconds (void) const; + /** + * \returns an approximation in nanoseconds of the time stored in this + * instance. + */ int64_t ApproximateToNanoSeconds (void) const; }; - +/** + * \brief create ns3::Time instances in units of seconds. + * + * For example: + * \code + * Time t = Seconds (2.0); + * Simulator::Schedule (Now () + NanoSeconds (5.0), ...); + * \endcode + */ class Seconds : public TimeUnit<1> { public: @@ -208,18 +341,45 @@ public: Seconds (double seconds); }; +/** + * \brief create ns3::Time instances in units of milliseconds. + * + * For example: + * \code + * Time t = MilliSeconds (2); + * Simulator::Schedule (Now () + MilliSeconds (5), ...); + * \endcode + */ class MilliSeconds : public TimeUnit<1> { public: MilliSeconds (); MilliSeconds (uint32_t ms); }; +/** + * \brief create ns3::Time instances in units of microseconds. + * + * For example: + * \code + * Time t = MicroSeconds (2); + * Simulator::Schedule (Now () + MicroSeconds (5), ...); + * \endcode + */ class MicroSeconds : public TimeUnit<1> { public: MicroSeconds (); MicroSeconds (uint32_t ms); }; +/** + * \brief create ns3::Time instances in units of nanoseconds. + * + * For example: + * \code + * Time t = NanoSeconds (2); + * Simulator::Schedule (Now () + NanoSeconds (5), ...); + * \endcode + */ class NanoSeconds : public TimeUnit<1> { public: @@ -227,13 +387,38 @@ public: NanoSeconds (uint32_t ms); }; +/** + * \brief create an ns3::Time instance which contains the + * current simulation time. + * + * This is really a shortcut for the ns3::Simulator::Now method. + * It is typically used as shown below to schedule an event + * which expires in 2 seconds from now: + * \code + * Simulator::Schedule (Now () + Seconds (2.0), &my_function); + * \endcode + */ class Now : public Time { public: Now (); }; - +/** + * \brief hold scalar values + * + * This class is used both to construct scalar values to multiply + * ns3::Time instances and to hold the return value of + * an expression which returns a scalar. For example, the + * following code will output on your terminal 1.5: + * \code + * Scalar s0 = Scalar (1.5); + * Time t1 = Seconds (10.0) * s0; + * Time t2 = Seconds (10.0) * Scalar (2.5); + * Scalar s1 = Seconds (15.0) / Seconds (10.0); + * std::cout << s1.GetDouble () << std::endl; + * \endcode + */ class Scalar : public TimeUnit<0> { public: