--- a/src/core/examples/sample-simulator.cc Tue Jul 21 12:20:12 2015 -0700
+++ b/src/core/examples/sample-simulator.cc Tue Jul 21 16:20:17 2015 -0700
@@ -33,11 +33,18 @@
using namespace ns3;
+/** Simple model object to illustrate event handling. */
class MyModel
{
public:
+ /** Start model execution by scheduling a HandleEvent. */
void Start (void);
private:
+ /**
+ * Simple event handler.
+ *
+ * \param [in] eventValue Event argument.
+ */
void HandleEvent (double eventValue);
};
@@ -56,6 +63,11 @@
<< "s started at " << value << "s" << std::endl;
}
+/**
+ * Simple function event handler which Starts a MyModel object.
+ *
+ * \param [in] model The MyModel object to start.
+ */
static void
ExampleFunction (MyModel *model)
{
@@ -64,6 +76,9 @@
model->Start ();
}
+/**
+ * Simple function event handler; this function is called randomly.
+ */
static void
RandomFunction (void)
{
@@ -71,6 +86,7 @@
<< Simulator::Now ().GetSeconds () << "s" << std::endl;
}
+/** Simple function event handler; the corresponding event is cancelled. */
static void
CancelledEvent (void)
{
--- a/src/core/examples/sample-simulator.py Tue Jul 21 12:20:12 2015 -0700
+++ b/src/core/examples/sample-simulator.py Tue Jul 21 16:20:17 2015 -0700
@@ -23,11 +23,17 @@
import ns.core
class MyModel(object):
+ """Simple model object to illustrate event handling."""
+ ## \returns None.
def Start(self):
+ """Start model execution by scheduling a HandleEvent."""
ns.core.Simulator.Schedule(ns.core.Seconds(10.0), self.HandleEvent, ns.core.Simulator.Now().GetSeconds())
+ ## \param [in] value Event argument.
+ ## \return None.
def HandleEvent(self, value):
+ """Simple event handler."""
print "Member method received event at", ns.core.Simulator.Now().GetSeconds(), \
"s started at", value, "s"
--- a/src/core/model/calendar-scheduler.h Tue Jul 21 12:20:12 2015 -0700
+++ b/src/core/model/calendar-scheduler.h Tue Jul 21 16:20:17 2015 -0700
@@ -39,58 +39,113 @@
* \ingroup scheduler
* \brief a calendar queue event scheduler
*
- * This event scheduler is a direct implementation of the algorithm known as a calendar queue.
- * first published in 1988 in "Calendar Queues: A Fast O(1) Priority Queue Implementation for
- * the Simulation Event Set Problem" by Randy Brown. There are many refinements published
- * later but this class implements the original algorithm (to the best of my knowledge).
+ * This event scheduler is a direct implementation of the algorithm
+ * known as a calendar queue, first published in 1988 in
+ * "Calendar Queues: A Fast O(1) Priority Queue Implementation for
+ * the Simulation Event Set Problem" by Randy Brown. There are many
+ * refinements published later but this class implements
+ * the original algorithm (to the best of my knowledge).
*
- * Note: This queue is much slower than I expected (much slower than the std::map queue)
- * and this seems to be because the original resizing policy is horribly bad. This is
- * most likely the reason why there have been so many variations published which all
- * slightly tweak the resizing heuristics to obtain a better distribution of events
- * across buckets.
+ * \note
+ * This queue is much slower than I expected (much slower than the
+ * std::map queue) and this seems to be because the original resizing policy
+ * is horribly bad. This is most likely the reason why there have been
+ * so many variations published which all slightly tweak the resizing
+ * heuristics to obtain a better distribution of events across buckets.
*/
class CalendarScheduler : public Scheduler
{
public:
+ /**
+ * Register this type.
+ * \return The object TypeId.
+ */
static TypeId GetTypeId (void);
+ /** Constructor. */
CalendarScheduler ();
+ /** Destructor. */
virtual ~CalendarScheduler ();
- virtual void Insert (const Event &ev);
+ // Inherited
+ virtual void Insert (const Scheduler::Event &ev);
virtual bool IsEmpty (void) const;
- virtual Event PeekNext (void) const;
- virtual Event RemoveNext (void);
- virtual void Remove (const Event &ev);
+ virtual Scheduler::Event PeekNext (void) const;
+ virtual Scheduler::Event RemoveNext (void);
+ virtual void Remove (const Scheduler::Event &ev);
private:
+ /** Double the number of buckets if necessary. */
void ResizeUp (void);
+ /** Halve the number of buckets if necessary. */
void ResizeDown (void);
+ /**
+ * Resize to a new number of buckets, with automatically computed width.
+ *
+ * \param [in] newSize The new number of buckets.
+ */
void Resize (uint32_t newSize);
+ /**
+ * Compute the new bucket size, based on up to the first 25 entries.
+ *
+ * \returns The new width.
+ */
uint32_t CalculateNewWidth (void);
+ /**
+ * Initialize the calendar queue.
+ *
+ * \param [in] nBuckets The number of buckets.
+ * \param [in] width The bucket size, in dimensionless time units.
+ * \param [in] startPrio The starting time.
+ */
void Init (uint32_t nBuckets,
uint64_t width,
uint64_t startPrio);
+ /**
+ * Hash the dimensionless time to a bucket.
+ *
+ * \param [in] key The dimensionless time.
+ * \returns The bucket index.
+ */
inline uint32_t Hash (uint64_t key) const;
+ /** Print the configuration and bucket size distribution. */
void PrintInfo (void);
+ /**
+ * Resize the number of buckets and width.
+ *
+ * \param [in] newSize The number of buckets.
+ * \param [in] newWidth The size of the new buckets.
+ */
void DoResize (uint32_t newSize, uint32_t newWidth);
+ /**
+ * Remove the earliest event.
+ *
+ * \returns The earliest event.
+ */
Scheduler::Event DoRemoveNext (void);
- void DoInsert (const Event &ev);
+ /**
+ * Insert a new event in to the correct bucket.
+ *
+ * \param [in] ev The new Event.
+ */
+ void DoInsert (const Scheduler::Event &ev);
+ /** Calendar bucket type: a list of Events. */
typedef std::list<Scheduler::Event> Bucket;
+
+ /** Array of buckets. */
Bucket *m_buckets;
- // number of buckets in array
+ /** Number of buckets in the array. */
uint32_t m_nBuckets;
- // duration of a bucket
+ /** Duration of a bucket, in dimensionless time units. */
uint64_t m_width;
- // bucket index from which the last event was dequeued
+ /** Bucket index from which the last event was dequeued. */
uint32_t m_lastBucket;
- // priority at the top of the bucket from which last event was dequeued
+ /** Priority at the top of the bucket from which last event was dequeued. */
uint64_t m_bucketTop;
- // the priority of the last event removed
+ /** The priority of the last event removed. */
uint64_t m_lastPrio;
- // number of events in queue
+ /** Number of events in queue. */
uint32_t m_qSize;
};
--- a/src/core/model/command-line.h Tue Jul 21 12:20:12 2015 -0700
+++ b/src/core/model/command-line.h Tue Jul 21 16:20:17 2015 -0700
@@ -293,13 +293,13 @@
* Handler for \c \-\-PrintHelp and \c \-\-help: print Usage(), argument names, and help strings
*
* Alternatively, an overloaded operator << can be used:
- * @code
+ * \code
* CommandLine cmd;
* cmd.Parse (argc, argv);
* ...
*
* std::cerr << cmd;
- * @endcode
+ * \endcode
*
* \param [in,out] os The output stream to print on.
*/
--- a/src/core/model/config.cc Tue Jul 21 12:20:12 2015 -0700
+++ b/src/core/model/config.cc Tue Jul 21 16:20:17 2015 -0700
@@ -148,13 +148,34 @@
} // namespace Config
+
+/** Helper to test if an array entry matches a config path specification. */
class ArrayMatcher
{
public:
+ /**
+ * Construct from a Config path specification.
+ *
+ * \param [in] element The Config path specification.
+ */
ArrayMatcher (std::string element);
+ /**
+ * Test if a specific index matches the Config Path.
+ *
+ * \param [in] i The index.
+ * \returns \c true if the index matches the Config Path.
+ */
bool Matches (uint32_t i) const;
private:
+ /**
+ * Convert a string to an \c uint32_t.
+ *
+ * \param [in] str The string.
+ * \param [in] value The location to store the \c uint32_t.
+ * \returns \c true if the string could be converted.
+ */
bool StringToUint32 (std::string str, uint32_t *value) const;
+ /** The Config path element. */
std::string m_element;
};
@@ -238,22 +259,71 @@
return !iss.bad () && !iss.fail ();
}
-
+/**
+ * Abstract class to parse Config paths into object references.
+ */
class Resolver
{
public:
+ /**
+ * Construct from a base Config path.
+ *
+ * \param [in] path The Config path.
+ */
Resolver (std::string path);
+ /** Destructor. */
virtual ~Resolver ();
+ /**
+ * Parse the stored Config path into an object reference,
+ * beginning at the indicated root object.
+ *
+ * \param [in] root The object corresponding to the current position in
+ * in the Config path.
+ */
void Resolve (Ptr<Object> root);
+
private:
+ /** Ensure the Config path starts and ends with a '/'. */
void Canonicalize (void);
+ /**
+ * Parse the next element in the Config path.
+ *
+ * \param [in] path The remaining portion of the Config path.
+ * \param [in] root The object corresponding to the current positon
+ * in the Config path.
+ */
void DoResolve (std::string path, Ptr<Object> root);
+ /**
+ * Parse an index on the Config path.
+ *
+ * \param [in] path The remaining Config path.
+ * \param [in,out] vector The resulting list of matching objects.
+ */
void DoArrayResolve (std::string path, const ObjectPtrContainerValue &vector);
+ /**
+ * Handle one object found on the path.
+ *
+ * \param [in] object The current object on the Config path.
+ */
void DoResolveOne (Ptr<Object> object);
+ /**
+ * Get the current Config path.
+ *
+ * \returns The current Config path.
+ */
std::string GetResolvedPath (void) const;
+ /**
+ * Handle one found object.
+ *
+ * \param [in] object The found object.
+ * \param [in] path The matching Config path context.
+ */
virtual void DoOne (Ptr<Object> object, std::string path) = 0;
+
+ /** Current list of path tokens. */
std::vector<std::string> m_workStack;
+ /** The Config path. */
std::string m_path;
};
@@ -502,26 +572,47 @@
}
}
-
-class ConfigImpl
+/** Config system implementation class. */
+class ConfigImpl : public Singleton<ConfigImpl>
{
public:
+ /** \copydoc Config::Set() */
void Set (std::string path, const AttributeValue &value);
+ /** \copydoc Config::ConnectWithoutContext() */
void ConnectWithoutContext (std::string path, const CallbackBase &cb);
+ /** \copydoc Config::Connect() */
void Connect (std::string path, const CallbackBase &cb);
+ /** \copydoc Config::DisconnectWithoutContext() */
void DisconnectWithoutContext (std::string path, const CallbackBase &cb);
+ /** \copydoc Config::Disconnect() */
void Disconnect (std::string path, const CallbackBase &cb);
+ /** \copydoc Config::LookupMatches() */
Config::MatchContainer LookupMatches (std::string path);
+ /** \copydoc Config::RegisterRootNamespaceObject() */
void RegisterRootNamespaceObject (Ptr<Object> obj);
+ /** \copydoc Config::UnregisterRootNamespaceObject() */
void UnregisterRootNamespaceObject (Ptr<Object> obj);
+ /** \copydoc Config::GetRootNamespaceObjectN() */
uint32_t GetRootNamespaceObjectN (void) const;
+ /** \copydoc Config::GetRootNamespaceObject() */
Ptr<Object> GetRootNamespaceObject (uint32_t i) const;
private:
+ /**
+ * Break a Config path into the leading path and the last leaf token.
+ * \param [in] path The Config path.
+ * \param [in,out] root The leading part of the \p path,
+ * up to the final slash.
+ * \param [in,out] leaf The trailing part of the \p path.
+ */
void ParsePath (std::string path, std::string *root, std::string *leaf) const;
+
+ /** Container type to hold the root Config path tokens. */
typedef std::vector<Ptr<Object> > Roots;
+
+ /** The list of Config path roots. */
Roots m_roots;
};
@@ -678,7 +769,7 @@
void Set (std::string path, const AttributeValue &value)
{
NS_LOG_FUNCTION (path << &value);
- Singleton<ConfigImpl>::Get ()->Set (path, value);
+ ConfigImpl::Get ()->Set (path, value);
}
void SetDefault (std::string name, const AttributeValue &value)
{
@@ -733,53 +824,53 @@
void ConnectWithoutContext (std::string path, const CallbackBase &cb)
{
NS_LOG_FUNCTION (path << &cb);
- Singleton<ConfigImpl>::Get ()->ConnectWithoutContext (path, cb);
+ ConfigImpl::Get ()->ConnectWithoutContext (path, cb);
}
void DisconnectWithoutContext (std::string path, const CallbackBase &cb)
{
NS_LOG_FUNCTION (path << &cb);
- Singleton<ConfigImpl>::Get ()->DisconnectWithoutContext (path, cb);
+ ConfigImpl::Get ()->DisconnectWithoutContext (path, cb);
}
void
Connect (std::string path, const CallbackBase &cb)
{
NS_LOG_FUNCTION (path << &cb);
- Singleton<ConfigImpl>::Get ()->Connect (path, cb);
+ ConfigImpl::Get ()->Connect (path, cb);
}
void
Disconnect (std::string path, const CallbackBase &cb)
{
NS_LOG_FUNCTION (path << &cb);
- Singleton<ConfigImpl>::Get ()->Disconnect (path, cb);
+ ConfigImpl::Get ()->Disconnect (path, cb);
}
Config::MatchContainer LookupMatches (std::string path)
{
NS_LOG_FUNCTION (path);
- return Singleton<ConfigImpl>::Get ()->LookupMatches (path);
+ return ConfigImpl::Get ()->LookupMatches (path);
}
void RegisterRootNamespaceObject (Ptr<Object> obj)
{
NS_LOG_FUNCTION (obj);
- Singleton<ConfigImpl>::Get ()->RegisterRootNamespaceObject (obj);
+ ConfigImpl::Get ()->RegisterRootNamespaceObject (obj);
}
void UnregisterRootNamespaceObject (Ptr<Object> obj)
{
NS_LOG_FUNCTION (obj);
- Singleton<ConfigImpl>::Get ()->UnregisterRootNamespaceObject (obj);
+ ConfigImpl::Get ()->UnregisterRootNamespaceObject (obj);
}
uint32_t GetRootNamespaceObjectN (void)
{
NS_LOG_FUNCTION_NOARGS ();
- return Singleton<ConfigImpl>::Get ()->GetRootNamespaceObjectN ();
+ return ConfigImpl::Get ()->GetRootNamespaceObjectN ();
}
Ptr<Object> GetRootNamespaceObject (uint32_t i)
{
NS_LOG_FUNCTION (i);
- return Singleton<ConfigImpl>::Get ()->GetRootNamespaceObject (i);
+ return ConfigImpl::Get ()->GetRootNamespaceObject (i);
}
} // namespace Config
--- a/src/core/model/config.h Tue Jul 21 12:20:12 2015 -0700
+++ b/src/core/model/config.h Tue Jul 21 16:20:17 2015 -0700
@@ -97,6 +97,7 @@
* \ingroup config
* \param name the name of the requested GlobalValue.
* \param value the value to set
+ * \return \c true if the GlobalValue could be set.
*
* This method is equivalent to GlobalValue::BindFailSafe
*/
@@ -150,9 +151,16 @@
class MatchContainer
{
public:
+ /** Const iterator over the objects in this container. */
typedef std::vector<Ptr<Object> >::const_iterator Iterator;
MatchContainer ();
- // constructor used only by implementation.
+ /**
+ * Constructor used only by implementation.
+ *
+ * \param [in] objects The vector of objects to store in this container.
+ * \param [in] contexts The corresponding contexts.
+ * \param [in] path The path used for object matching.
+ */
MatchContainer (const std::vector<Ptr<Object> > &objects,
const std::vector<std::string> &contexts,
std::string path);
@@ -232,9 +240,13 @@
* \sa ns3::Config::DisconnectWithoutContext
*/
void DisconnectWithoutContext (std::string name, const CallbackBase &cb);
+
private:
+ /** The list of objects in this container. */
std::vector<Ptr<Object> > m_objects;
+ /** The context for each object. */
std::vector<std::string> m_contexts;
+ /** The path used to perform the object matching. */
std::string m_path;
};
--- a/src/core/model/default-simulator-impl.h Tue Jul 21 12:20:12 2015 -0700
+++ b/src/core/model/default-simulator-impl.h Tue Jul 21 16:20:17 2015 -0700
@@ -47,11 +47,18 @@
class DefaultSimulatorImpl : public SimulatorImpl
{
public:
+ /**
+ * Register this type.
+ * \return The object TypeId.
+ */
static TypeId GetTypeId (void);
+ /** Constructor. */
DefaultSimulatorImpl ();
+ /** Destructor. */
~DefaultSimulatorImpl ();
+ // Inherited
virtual void Destroy ();
virtual bool IsFinished (void) const;
virtual void Stop (void);
@@ -73,32 +80,57 @@
private:
virtual void DoDispose (void);
+
+ /** Process the next event. */
void ProcessOneEvent (void);
+ /** Move events from a different context into the main event queue. */
void ProcessEventsWithContext (void);
+ /** Wrap an event with its execution context. */
struct EventWithContext {
+ /** The event context. */
uint32_t context;
+ /** Event timestamp. */
uint64_t timestamp;
+ /** The event implementation. */
EventImpl *event;
};
+ /** Container type for the events from a different context. */
typedef std::list<struct EventWithContext> EventsWithContext;
+ /** The container of events from a different context. */
EventsWithContext m_eventsWithContext;
+ /**
+ * Flag \c true if all events with context have been moved to the
+ * primary event queue.
+ */
bool m_eventsWithContextEmpty;
+ /** Mutex to control access to the list of events with context. */
SystemMutex m_eventsWithContextMutex;
+ /** Container type for the events to run at Simulator::Destroy() */
typedef std::list<EventId> DestroyEvents;
+ /** The container of events to run at Destroy. */
DestroyEvents m_destroyEvents;
+ /** Flag calling for the end of the simulation. */
bool m_stop;
+ /** The event priority queue. */
Ptr<Scheduler> m_events;
+ /** Next event unique id. */
uint32_t m_uid;
+ /** Unique id of the current event. */
uint32_t m_currentUid;
+ /** Timestamp of the current event. */
uint64_t m_currentTs;
+ /** Execution context of the current event. */
uint32_t m_currentContext;
- // number of events that have been inserted but not yet scheduled,
- // not counting the "destroy" events; this is used for validation
+ /**
+ * Number of events that have been inserted but not yet scheduled,
+ * not counting the Destroy events; this is used for validation
+ */
int m_unscheduledEvents;
+ /** Main execution thread. */
SystemThread::ThreadId m_main;
};
--- a/src/core/model/global-value.h Tue Jul 21 12:20:12 2015 -0700
+++ b/src/core/model/global-value.h Tue Jul 21 16:20:17 2015 -0700
@@ -53,11 +53,15 @@
*/
class GlobalValue
{
+ /** Container type for holding all the GlobalValues. */
typedef std::vector<GlobalValue *> Vector;
+
public:
+ /** Iterator type for the list of all global values. */
typedef Vector::const_iterator Iterator;
/**
+ * Constructor.
* \param name the name of this global value.
* \param help some help text which describes the purpose of this
* global value.
@@ -72,77 +76,89 @@
Ptr<const AttributeChecker> checker);
/**
+ * Get the name.
* \returns the name of this GlobalValue.
*/
std::string GetName (void) const;
/**
+ * Get the help string.
* \returns the help text of this GlobalValue.
*/
std::string GetHelp (void) const;
/**
+ * Get the value.
+ * \param [out] value The AttributeValue to set to the value
+ * of this GlobalValue
* \returns the current value of this GlobalValue.
*/
void GetValue (AttributeValue &value) const;
/**
+ * Get the AttributeChecker.
* \returns the checker associated to this GlobalValue.
*/
Ptr<const AttributeChecker> GetChecker (void) const;
/**
+ * Set the value of this GlobalValue.
* \param value the new value to set in this GlobalValue.
+ * \returns \c true if the Global Value was set successfully.
*/
bool SetValue (const AttributeValue &value);
+ /** Reset to the initial value. */
void ResetInitialValue (void);
/**
+ * Iterate over the set of GlobalValues until a matching name is found
+ * and then set its value with GlobalValue::SetValue.
+ *
* \param name the name of the global value
* \param value the value to set in the requested global value.
*
- * Iterate over the set of GlobalValues until a matching name is found
- * and then set its value with GlobalValue::SetValue.
- *
* This method cannot fail. It will crash if the input is not valid.
*/
static void Bind (std::string name, const AttributeValue &value);
/**
+ * Iterate over the set of GlobalValues until a matching name is found
+ * and then set its value with GlobalValue::SetValue.
+ *
* \param name the name of the global value
* \param value the value to set in the requested global value.
* \returns true if the value could be set successfully, false otherwise.
- *
- * Iterate over the set of GlobalValues until a matching name is found
- * and then set its value with GlobalValue::SetValue.
*/
static bool BindFailSafe (std::string name, const AttributeValue &value);
/**
+ * The Begin iterator.
* \returns an iterator which represents a pointer to the first GlobalValue registered.
*/
static Iterator Begin (void);
/**
+ * The End iterator.
* \returns an iterator which represents a pointer to the last GlobalValue registered.
*/
static Iterator End (void);
/**
- * finds the GlobalValue with the given name and returns its value
+ * Finds the GlobalValue with the given name and returns its value
*
- * @param name the name of the GlobalValue to be found
- * @param value where to store the value of the found GlobalValue
+ * \param name the name of the GlobalValue to be found
+ * \param value where to store the value of the found GlobalValue
*
- * @return true if the GlobalValue was found, false otherwise
+ * \return true if the GlobalValue was found, false otherwise
*/
static bool GetValueByNameFailSafe (std::string name, AttributeValue &value);
/**
- * finds the GlobalValue with the given name and returns its
- * value. This method cannot fail, i.e., it will trigger a
+ * Finds the GlobalValue with the given name and returns its
+ * value.
+ *
+ * This method cannot fail, i.e., it will trigger a
* NS_FATAL_ERROR if the requested GlobalValue is not found.
*
- * @param name the name of the GlobalValue to be found
- * @param value where to store the value of the found GlobalValue
- *
+ * \param name the name of the GlobalValue to be found
+ * \param value where to store the value of the found GlobalValue
*/
static void GetValueByName (std::string name, AttributeValue &value);
@@ -150,12 +166,24 @@
private:
friend class ::GlobalValueTestCase;
+ /**
+ * Get the static vector of all GlobalValues.
+ *
+ * \returns The vector.
+ */
static Vector *GetVector (void);
+ /** Initialize from the \c NS_GLOBAL_VALUE environment variable. */
void InitializeFromEnv (void);
+
+ /** The name of this GlobalValue. */
std::string m_name;
+ /** The help string. */
std::string m_help;
+ /** The initial value. */
Ptr<AttributeValue> m_initialValue;
+ /** The current value. */
Ptr<AttributeValue> m_currentValue;
+ /** The AttributeChecker for this GlobalValue. */
Ptr<const AttributeChecker> m_checker;
};
--- a/src/core/model/heap-scheduler.h Tue Jul 21 12:20:12 2015 -0700
+++ b/src/core/model/heap-scheduler.h Tue Jul 21 16:20:17 2015 -0700
@@ -53,36 +53,114 @@
class HeapScheduler : public Scheduler
{
public:
+ /**
+ * Register this type.
+ * \return The object TypeId.
+ */
static TypeId GetTypeId (void);
+ /** Constructor. */
HeapScheduler ();
+ /** Destructor. */
virtual ~HeapScheduler ();
- virtual void Insert (const Event &ev);
+ // Inherited
+ virtual void Insert (const Scheduler::Event &ev);
virtual bool IsEmpty (void) const;
- virtual Event PeekNext (void) const;
- virtual Event RemoveNext (void);
- virtual void Remove (const Event &ev);
+ virtual Scheduler::Event PeekNext (void) const;
+ virtual Scheduler::Event RemoveNext (void);
+ virtual void Remove (const Scheduler::Event &ev);
private:
- typedef std::vector<Event> BinaryHeap;
+ /** Event list type: vector of Events, managed as a heap. */
+ typedef std::vector<Scheduler::Event> BinaryHeap;
+ /**
+ * Get the parent index of a given entry.
+ *
+ * \param [in] id The child index.
+ * \return The index of the parent of \p id.
+ */
inline uint32_t Parent (uint32_t id) const;
+ /**
+ * Get the next sibling of a given entry.
+ *
+ * \param [in] id The starting index.
+ * \returns The next sibling of \p id.
+ */
uint32_t Sibling (uint32_t id) const;
+ /**
+ * Get the left child of a given entry.
+ *
+ * \param [in] id The parent index.
+ * \returns The index of the left (first) child.
+ */
inline uint32_t LeftChild (uint32_t id) const;
+ /**
+ * Get the right child index of a given entry.
+ *
+ * \param [in] id The parent index.
+ * \returns The index of the right (second) child.
+ */
inline uint32_t RightChild (uint32_t id) const;
+ /**
+ * Get the root index of the heap.
+ *
+ * \returns The root index.
+ */
inline uint32_t Root (void) const;
- /* Return the position in the array of the last element included in it. */
+ /**
+ * Return the index of the last element.
+ * \returns The last index.
+ */
uint32_t Last (void) const;
+ /**
+ * Test if an index is the root.
+ *
+ * \param [in] id The index to test.
+ * \returns \c true if the \p id is the root.
+ */
inline bool IsRoot (uint32_t id) const;
+ /**
+ * Test if an index is at the bottom of the heap.
+ *
+ * \param [in] id The index to test.
+ * \returns \c true if the index is at the bottom.
+ */
inline bool IsBottom (uint32_t id) const;
+ /**
+ * Compare (less than) two items.
+ *
+ * \param [in] a The first item.
+ * \param [in] b The second item.
+ * \returns \c true if \c a < \c b
+ */
inline bool IsLessStrictly (uint32_t a, uint32_t b) const;
+ /**
+ * Minimum of two items.
+ *
+ * \param [in] a The first item.
+ * \param [in] b The second item.
+ * \returns The smaller of the two items.
+ */
inline uint32_t Smallest (uint32_t a, uint32_t b) const;
-
+ /**
+ * Swap two items.
+ *
+ * \param [in] a The first item.
+ * \param [in] b The second item.
+ */
inline void Exch (uint32_t a, uint32_t b);
+ /** Percolate a newly inserted Last item to its proper position. */
void BottomUp (void);
+ /**
+ * Percolate a deletion bubble down the heap.
+ *
+ * \param [in] start Starting entry.
+ */
void TopDown (uint32_t start);
+ /** The event list. */
BinaryHeap m_heap;
};
--- a/src/core/model/int64x64-128.cc Tue Jul 21 12:20:12 2015 -0700
+++ b/src/core/model/int64x64-128.cc Tue Jul 21 16:20:17 2015 -0700
@@ -25,7 +25,7 @@
/**
* \file
* \ingroup highprec
- * Implementation of the ns3::int64x64_t type using a native int128_t type..
+ * Implementation of the ns3::int64x64_t type using a native int128_t type.
*/
namespace ns3 {
--- a/src/core/model/int64x64.cc Tue Jul 21 12:20:12 2015 -0700
+++ b/src/core/model/int64x64.cc Tue Jul 21 16:20:17 2015 -0700
@@ -40,6 +40,20 @@
NS_LOG_COMPONENT_DEFINE ("int64x64");
/**
+ * \ingroup highprec
+ * Print the high and low words of an int64x64 in hex, for debugging.
+ *
+ * \param [in] hi The high (integer) word.
+ * \param [in] lo The low (fractional) work.
+ */
+#define HEXHILOW(hi, lo) \
+ std::hex << std::setfill ('0') << std::right << " (0x" \
+ << std::setw (16) << hi << " " \
+ << std::setw (16) << lo \
+ << std::dec << std::setfill (' ') << std::left << ")"
+
+
+/**
* \internal
* This algorithm is exact to the precision requested, up to the full
* 64 decimal digits required to exactly represent a 64-bit fraction.
@@ -74,13 +88,6 @@
int64x64_t low(0, absVal.GetLow ());
int places = 0; // Number of decimal places printed so far
bool more = true; // Should we print more digits?
-
-#define HEXHILOW(hi, lo) \
- std::hex << std::setfill ('0') << std::right << " (0x" \
- << std::setw (16) << hi << " " \
- << std::setw (16) << lo \
- << std::dec << std::setfill (' ') << std::left << ")"
-
NS_LOG_LOGIC (std::endl
<< (floatfield ? " f" : " ")
--- a/src/core/model/list-scheduler.h Tue Jul 21 12:20:12 2015 -0700
+++ b/src/core/model/list-scheduler.h Tue Jul 21 16:20:17 2015 -0700
@@ -46,20 +46,31 @@
class ListScheduler : public Scheduler
{
public:
+ /**
+ * Register this type.
+ * \return The object TypeId.
+ */
static TypeId GetTypeId (void);
+ /** Constructor. */
ListScheduler ();
+ /** Destructor. */
virtual ~ListScheduler ();
- virtual void Insert (const Event &ev);
+ // Inherited
+ virtual void Insert (const Scheduler::Event &ev);
virtual bool IsEmpty (void) const;
- virtual Event PeekNext (void) const;
- virtual Event RemoveNext (void);
- virtual void Remove (const Event &ev);
+ virtual Scheduler::Event PeekNext (void) const;
+ virtual Scheduler::Event RemoveNext (void);
+ virtual void Remove (const Scheduler::Event &ev);
private:
- typedef std::list<Event> Events;
- typedef std::list<Event>::iterator EventsI;
+ /** Event list type: a simple list of Events. */
+ typedef std::list<Scheduler::Event> Events;
+ /** Events iterator. */
+ typedef std::list<Scheduler::Event>::iterator EventsI;
+
+ /** The event list. */
Events m_events;
};
--- a/src/core/model/map-scheduler.h Tue Jul 21 12:20:12 2015 -0700
+++ b/src/core/model/map-scheduler.h Tue Jul 21 16:20:17 2015 -0700
@@ -44,22 +44,33 @@
class MapScheduler : public Scheduler
{
public:
+ /**
+ * Register this type.
+ * \return The object TypeId.
+ */
static TypeId GetTypeId (void);
+ /** Constructor. */
MapScheduler ();
+ /** Destructor. */
virtual ~MapScheduler ();
- virtual void Insert (const Event &ev);
+ // Inherited
+ virtual void Insert (const Scheduler::Event &ev);
virtual bool IsEmpty (void) const;
- virtual Event PeekNext (void) const;
- virtual Event RemoveNext (void);
- virtual void Remove (const Event &ev);
+ virtual Scheduler::Event PeekNext (void) const;
+ virtual Scheduler::Event RemoveNext (void);
+ virtual void Remove (const Scheduler::Event &ev);
+
private:
+ /** Event list type: a Map from EventKey to EventImpl. */
typedef std::map<Scheduler::EventKey, EventImpl*> EventMap;
+ /** EventMap iterator. */
typedef std::map<Scheduler::EventKey, EventImpl*>::iterator EventMapI;
+ /** EventMap const iterator. */
typedef std::map<Scheduler::EventKey, EventImpl*>::const_iterator EventMapCI;
-
+ /** The event list. */
EventMap m_list;
};
--- a/src/core/model/names.cc Tue Jul 21 12:20:12 2015 -0700
+++ b/src/core/model/names.cc Tue Jul 21 16:20:17 2015 -0700
@@ -22,6 +22,7 @@
#include "assert.h"
#include "abort.h"
#include "names.h"
+#include "singleton.h"
/**
* \file
@@ -34,20 +35,48 @@
NS_LOG_COMPONENT_DEFINE ("Names");
+/**
+ * \ingroup config
+ * Node in the naming tree.
+ */
class NameNode
{
public:
+ /** Default constructor. */
NameNode ();
+ /**
+ * Copy constructor.
+ *
+ * \param [in] nameNode The NameNode to copy from.
+ */
NameNode (const NameNode &nameNode);
+ /**
+ * Constructor.
+ *
+ * \param [in] parent The parent NameNode.
+ * \param [in] name The name of this NameNode
+ * \param [in] object The object corresponding to this NameNode.
+ */
NameNode (NameNode *parent, std::string name, Ptr<Object> object);
+ /**
+ * Assignment operator.
+ *
+ * \param [in] rhs The NameNode to copy from.
+ * \returns The lhs NameNode.
+ */
NameNode &operator = (const NameNode &rhs);
+ /** Destructor. */
~NameNode ();
+ /** The parent NameNode. */
NameNode *m_parent;
+ /** The name of this NameNode. */
std::string m_name;
+ /** The object corresponding to this NameNode. */
Ptr<Object> m_object;
+ /** Children of this NameNode. */
std::map<std::string, NameNode *> m_nameMap;
};
@@ -85,48 +114,91 @@
NS_LOG_FUNCTION (this);
}
-class NamesPriv
+/**
+ * \ingroup config
+ * The singleton root Names object.
+ */
+class NamesPriv : public Singleton<NamesPriv>
{
public:
+ /** Constructor. */
NamesPriv ();
+ /** Destructor. */
~NamesPriv ();
+ /**
+ * \copydoc Names::Add(std::string,Ptr<Object>object)
+ * \return \c true if the object was named successfully.
+ */
bool Add (std::string name, Ptr<Object> object);
+ /**
+ * \copydoc Names::Add(std::string,std::string,Ptr<Object>)
+ * \return \c true if the object was named successfully.
+ */
bool Add (std::string path, std::string name, Ptr<Object> object);
+ /**
+ * \copydoc Names::Add(Ptr<Object>,std::string,Ptr<Object>)
+ * \return \c true if the object was named successfully.
+ */
bool Add (Ptr<Object> context, std::string name, Ptr<Object> object);
+ /**
+ * \copydoc Names::Rename(std::string,std::string)
+ * \return \c true if the object was renamed successfully.
+ */
bool Rename (std::string oldpath, std::string newname);
+ /**
+ * \copydoc Names::Rename(std::string,std::string,std::string)
+ * \return \c true if the object was renamed successfully.
+ */
bool Rename (std::string path, std::string oldname, std::string newname);
+ /**
+ * \copydoc Names::Rename(Ptr<Object>,std::string,std::string)
+ * \return \c true if the object was renamed successfully.
+ */
bool Rename (Ptr<Object> context, std::string oldname, std::string newname);
+ /** \copydoc Names::FindName() */
std::string FindName (Ptr<Object> object);
+ /** \copydoc Names::FindPath() */
std::string FindPath (Ptr<Object> object);
+ /** \copydoc Names::Clear() */
void Clear (void);
- Ptr<Object> Find (std::string name);
+ /** \copydoc Names::Find(std::string) */
+ Ptr<Object> Find (std::string path);
+ /** \copydoc Names::Find(std::string,std::string) */
Ptr<Object> Find (std::string path, std::string name);
+ /** \copydoc Names::Find(Ptr<Object>,std::string) */
Ptr<Object> Find (Ptr<Object> context, std::string name);
private:
friend class Names;
- static NamesPriv *Get (void);
- NameNode *IsNamed (Ptr<Object>);
+ /**
+ * Check if an object has a name.
+ *
+ * \param [in] object The object to check.
+ * \returns The corresponding NameNode, if it exists.
+ */
+ NameNode *IsNamed (Ptr<Object> object);
+ /**
+ * Check if a name already exists as a child of a NameNode.
+ *
+ * \param [in] node The node to search.
+ * \param [in] name The name to search for.
+ * \returns \c true if \c name already exists as a child of \c node.
+ */
bool IsDuplicateName (NameNode *node, std::string name);
+ /** The root NameNode. */
NameNode m_root;
+
+ /** Map from object pointers to their NameNodes. */
std::map<Ptr<Object>, NameNode *> m_objectMap;
};
-NamesPriv *
-NamesPriv::Get (void)
-{
- NS_LOG_FUNCTION_NOARGS ();
- static NamesPriv namesPriv;
- return &namesPriv;
-}
-
NamesPriv::NamesPriv ()
{
NS_LOG_FUNCTION (this);
--- a/src/core/model/names.h Tue Jul 21 12:20:12 2015 -0700
+++ b/src/core/model/names.h Tue Jul 21 16:20:17 2015 -0700
@@ -31,6 +31,7 @@
namespace ns3 {
/**
+ * \ingroup config
* \brief A directory of name and Ptr<Object> associations that allows us to
* give any ns3 Object a name.
*/
@@ -246,7 +247,7 @@
static void Rename (Ptr<Object> context, std::string oldname, std::string newname);
/**
- * Given a pointer to an object, look to see if that object has a name
+ * \brief Given a pointer to an object, look to see if that object has a name
* associated with it and, if so, return the name of the object otherwise
* return an empty string.
*
@@ -265,7 +266,7 @@
static std::string FindName (Ptr<Object> object);
/**
- * Given a pointer to an object, look to see if that object has a name
+ * \brief Given a pointer to an object, look to see if that object has a name
* associated with it and return the fully qualified name path of the
* object otherwise return an empty string.
*
@@ -284,13 +285,13 @@
static std::string FindPath (Ptr<Object> object);
/**
- * Clear the list of objects associated with names.
+ * \brief Clear the list of objects associated with names.
*/
static void Clear (void);
/**
- * Given a name path string, look to see if there's an object in the system
+ * \brief Given a name path string, look to see if there's an object in the system
* with that associated to it. If there is, do a GetObject on the resulting
* object to convert it to the requested typename and return it.
*
@@ -310,7 +311,7 @@
static Ptr<T> Find (std::string path);
/**
- * Given a path to an object and an object name, look through the names defined
+ * \brief Given a path to an object and an object name, look through the names defined
* under the path to see if there's an object there with the given name.
*
* In some cases, it is desirable to break up the path used to describe an item
@@ -334,7 +335,7 @@
static Ptr<T> Find (std::string path, std::string name);
/**
- * Given a path to an object and an object name, look through the names defined
+ * \brief Given a path to an object and an object name, look through the names defined
* under the path to see if there's an object there with the given name.
*
* In some cases, it is desirable to break up the path used to describe an item
@@ -402,14 +403,13 @@
static Ptr<Object> FindInternal (Ptr<Object> context, std::string name);
};
-/**
- * \brief Template definition of corresponding template declaration found in class Names.
- */
+
template <typename T>
+/* static */
Ptr<T>
-Names::Find (std::string name)
+Names::Find (std::string path)
{
- Ptr<Object> obj = FindInternal (name);
+ Ptr<Object> obj = FindInternal (path);
if (obj)
{
return obj->GetObject<T> ();
@@ -420,10 +420,8 @@
}
}
-/**
- * \brief Template definition of corresponding template declaration found in class Names.
- */
template <typename T>
+/* static */
Ptr<T>
Names::Find (std::string path, std::string name)
{
@@ -438,10 +436,8 @@
}
}
-/**
- * \brief Template definition of corresponding template declaration found in class Names.
- */
template <typename T>
+/* static */
Ptr<T>
Names::Find (Ptr<Object> context, std::string name)
{
--- a/src/core/model/nstime.h Tue Jul 21 12:20:12 2015 -0700
+++ b/src/core/model/nstime.h Tue Jul 21 16:20:17 2015 -0700
@@ -77,9 +77,9 @@
*
* You can also use the following non-member functions to manipulate
* any of these ns3::Time object:
- * - \ref Abs()
- * - \ref Max()
- * - \ref Min()
+ * - Abs(Time)
+ * - Max(Time,Time)
+ * - Min(Time,Time)
*
* This class also controls the resolution of the underlying time value.
* The resolution is the smallest representable time interval.
@@ -161,7 +161,6 @@
* 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))
@@ -228,7 +227,6 @@
}
}
/**@}*/
- /**@}*/
/**
* \brief Construct Time object from common time expressions like "1ms"
@@ -309,11 +307,20 @@
}
/**
+ * \name Convert to Number in a Unit.
+ * Convert a Time to number, in indicated units.
+ *
+ * Conversions to seconds and larger will return doubles, with
+ * possible loss of precision. Conversions to units smaller than
+ * seconds will by rounded.
+ *
+ * @{
+ */
+ /**
* 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
{
@@ -358,9 +365,15 @@
/**@}*/
/**
- * \returns the raw time value, in the current unit
+ * \name Convert to Raw Value.
+ * Convert a Time to a number in the current resolution units.
+ *
* @{
*/
+ /**
+ * Get the raw time value, in the current resolution unit.
+ * \returns the raw time value
+ */
inline int64_t GetTimeStep (void) const
{
return m_data;
@@ -401,12 +414,17 @@
return Time (value);
}
/**
+ * \name Create Times from Values and Units.
+ * Create Times from values given in the indicated units.
+ *
+ * @{
+ */
+ /**
* 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)
{
@@ -443,13 +461,18 @@
}
/**@}*/
-
+
+ /**
+ * \name Get Times as Numbers in Specified Units
+ * Get the Time as integers or doubles in the indicated unit.
+ *
+ * @{
+ */
/**
* 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
{
@@ -642,11 +665,15 @@
*/
static void ConvertTimes (const enum Unit unit);
+ /*
+ * \name Arithmetic Operators
+ * Arithmetic operators between Times, and scaling by scalars.
+ */
/**
- * @{
+ * @{
* Arithmetic operator.
* \param [in] lhs Left hand argument
- * \param [in] rhs Righ hand argument
+ * \param [in] rhs Right hand argument
* \return The result of the operator.
*/
friend bool operator == (const Time & lhs, const Time & rhs);
@@ -663,8 +690,8 @@
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
@@ -769,7 +796,7 @@
lhs.m_data -= rhs.m_data;
return lhs;
}
-
+/**@}*/
inline Time Abs (const Time & time)
{
--- a/src/core/model/random-variable-stream.h Tue Jul 21 12:20:12 2015 -0700
+++ b/src/core/model/random-variable-stream.h Tue Jul 21 16:20:17 2015 -0700
@@ -31,6 +31,12 @@
#include "attribute-helper.h"
#include <stdint.h>
+/**
+ * \file
+ * \ingroup randomvariable
+ * Declaration of ns3::RandomVariableStream and derivatives.
+ */
+
namespace ns3 {
/**
@@ -67,13 +73,13 @@
/**
* \ingroup randomvariable
- * \brief The Random Number Generator (RNG) that allows stream numbers to be set deterministically.
+ * \brief The basic uniform Random Number Generator (RNG).
*
- * Note: The underlying random number generation method used
- * by NS-3 is the RngStream code by Pierre L'Ecuyer at
+ * \note The underlying random number generation method used
+ * by ns-3 is the RngStream code by Pierre L'Ecuyer at
* the University of Montreal.
*
- * NS-3 has a rich set of random number generators that allow stream
+ * ns-3 has a rich set of random number generators that allow stream
* numbers to be set deterministically if desired. Class
* RandomVariableStream defines the base class functionalty required
* for all such random number generators.
@@ -83,6 +89,10 @@
* \ref GlobalValueRngSeed "RngSeed" and \ref GlobalValueRngRun
* "RngRun". Also by default, the stream number value for this RNG
* stream is automatically allocated.
+ *
+ * Instances can be configured to return "antithetic" values.
+ * See the documentation for the specific distributions to see
+ * how this modifies the returned values.
*/
class RandomVariableStream : public Object
{
@@ -92,80 +102,106 @@
* \return The object TypeId.
*/
static TypeId GetTypeId (void);
+ /**
+ * \brief Default constructor.
+ */
RandomVariableStream ();
+ /**
+ * \brief Destructor.
+ */
virtual ~RandomVariableStream();
/**
* \brief Specifies the stream number for this RNG stream.
- * \param stream The stream number for this RNG stream. -1 means "allocate a stream number automatically".
- */
+ * \param stream The stream number for this RNG stream.
+ * -1 means "allocate a stream number automatically".
+ */
void SetStream (int64_t stream);
/**
* \brief Returns the stream number for this RNG stream.
- * \return The stream number for this RNG stream. -1 means "allocate a stream number automatically".
+ * \return The stream number for this RNG stream.
+ * -1 means this stream was allocated automatically.
*/
int64_t GetStream(void) const;
/**
- * \brief Specifies whether antithetic values should be generated.
- * \param isAntithetic Set equal to true if antithetic values should
- * be generated by this RNG stream.
+ * \brief Specify whether antithetic values should be generated.
+ * \param isAntithetic If \c true antithetic value will be generated.
*/
void SetAntithetic(bool isAntithetic);
/**
- * \brief Returns true if antithetic values should be generated.
- * \return A bool value that indicates if antithetic values should
- * be generated by this RNG stream.
+ * \brief Check if antithetic values will be generated.
+ * \return \c true if antithetic values will be generated.
*/
bool IsAntithetic(void) const;
/**
- * \brief Returns a random double from the underlying distribution
+ * \brief Get the next random value as a double drawn from the distribution.
* \return A floating point random value.
*/
virtual double GetValue (void) = 0;
/**
- * \brief Returns a random integer integer from the underlying distribution
- * \return Integer cast of RandomVariableStream::GetValue
+ * \brief Get the next random value as an integer drawn from the distribution.
+ * \return An integer random value.
*/
virtual uint32_t GetInteger (void) = 0;
protected:
/**
- * \brief Returns a pointer to the underlying RNG stream.
+ * \brief Get the pointer to the underlying RNG stream.
*/
RngStream *Peek(void) const;
private:
- // you can't copy these objects.
- // Theoretically, it is possible to give them good copy semantics
- // but not enough time to iron out the details.
+ /**
+ * Copy constructor. These objects are not copyable.
+ *
+ * \param o The RandomVariableStream to copy in construction.
+ * \internal
+ * Theoretically, it is possible to give them good copy semantics
+ * but not enough time to iron out the details.
+ */
RandomVariableStream (const RandomVariableStream &o);
+ /**
+ * Assignment operator. These objects can't be copied by assignement.
+ *
+ * \param o The RandomVariableStream to copy.
+ * \return lvalue RandomVariableStream.
+ *
+ * \internal
+ * Theoretically, it is possible to give them good copy semantics
+ * but not enough time to iron out the details.
+ */
RandomVariableStream &operator = (const RandomVariableStream &o);
- /// Pointer to the underlying RNG stream.
+ /** Pointer to the underlying RNG stream. */
RngStream *m_rng;
- /// Indicates if antithetic values should be generated by this RNG stream.
+ /** Indicates if antithetic values should be generated by this RNG stream. */
bool m_isAntithetic;
- /// The stream number for this RNG stream.
+ /** The stream number for this RNG stream. */
int64_t m_stream;
-};
+}; // class RandomVariableStream
+
+
/**
* \ingroup randomvariable
- * \brief The uniform distribution Random Number Generator (RNG) that allows stream numbers to be set deterministically.
+ * \brief The uniform distribution Random Number Generator (RNG).
*
* This class supports the creation of objects that return random numbers
* from a fixed uniform distribution. It also supports the generation of
* single random numbers from various uniform distributions.
*
- * The low end of the range is always included and the high end
- * of the range is always excluded.
+ * The output range is \f$[min, max)\f$ for floating point values,
+ * (\c max <i>excluded</i>), and \f$[min, max]\f$ (\c max <i>included</i>)
+ * for integral values.
+ *
+ * \par Example
*
* Here is an example of how to use this class:
* \code
@@ -183,10 +219,24 @@
* //
* double value = x->GetValue ();
* \endcode
+ *
+ * \par Antithetic Values.
+ *
+ * Normally this RNG returns values \f$x\f$ in the interval \f$[min,max)\f$.
+ * If an instance of this RNG is configured to return antithetic values,
+ * the actual value returned is calculated as follows:
+ *
+ * - Compute the initial random value \f$x\f$ as normal.
+ * - Compute the distance from the maximum, \f$y = max - x\f$
+ * - Return \f$x' = min + y = min + (max - x)\f$:
*/
class UniformRandomVariable : public RandomVariableStream
{
public:
+ /**
+ * \brief Register this type.
+ * \return The object TypeId.
+ */
static TypeId GetTypeId (void);
/**
@@ -195,118 +245,82 @@
UniformRandomVariable ();
/**
- * \brief Returns the lower bound on values that can be returned by this RNG stream.
- * \return The lower bound on values that can be returned by this RNG stream.
+ * \brief Get the lower bound on randoms returned by GetValue(void).
+ * \return The lower bound on values from GetValue(void).
*/
double GetMin (void) const;
/**
- * \brief Returns the upper bound on values that can be returned by this RNG stream.
- * \return The upper bound on values that can be returned by this RNG stream.
+ * \brief Get the upper bound on values returned by GetValue(void).
+ * \return The upper bound on values from GetValue(void).
*/
double GetMax (void) const;
/**
- * \brief Returns a random double from the uniform distribution with the specified range.
- * \param min Low end of the range.
- * \param max High end of the range.
- * \return A floating point random value.
+ * \brief Get the next random value, as a double in the specified range
+ * \f$[min, max)\f$.
*
- * Note that antithetic values are being generated if
- * m_isAntithetic is equal to true. If \f$x\f$ is a value that
- * would be returned normally, then \f$(max - x\f$) is the distance
- * that \f$x\f$ would be from \f$max\f$. The value returned in the
- * antithetic case, \f$x'\f$, is calculated as
+ * \note The upper limit is excluded from the output range.
*
- * \f[
- * x' = min + (max - x) ,
- * \f]
- *
- * which is the lower bound plus the distance \f$x\f$ is from the
- * upper bound.
+ * \param min Low end of the range (included).
+ * \param max High end of the range (excluded).
+ * \return A floating point random value.
*/
double GetValue (double min, double max);
/**
- * \brief Returns a random unsigned integer from a uniform distribution over the interval [min,max] including both ends.
+ * \brief Get the next random value, as an unsigned integer in the
+ * specified range \f$[min, max]/f$.
+ *
+ * \note The upper limit is included in the output range.
+ *
* \param min Low end of the range.
* \param max High end of the range.
* \return A random unsigned integer value.
- *
- * Note that antithetic values are being generated if
- * m_isAntithetic is equal to true. If \f$x\f$ is a value that
- * would be returned normally, then \f$(max - x\f$) is the distance
- * that \f$x\f$ would be from \f$max\f$. The value returned in the
- * antithetic case, \f$x'\f$, is calculated as
- *
- * \f[
- * x' = min + (max - x) ,
- * \f]
- *
- * which is the lower bound plus the distance \f$x\f$ is from the
- * upper bound.
*/
uint32_t GetInteger (uint32_t min, uint32_t max);
+ // Inherited from RandomVariableStream
/**
- * \brief Returns a random double from the uniform distribution with the range [min,max), where min and max are the current lower and upper bounds.
+ * \brief Get the next random value as a double drawn from the distribution.
* \return A floating point random value.
- *
- * Note that antithetic values are being generated if
- * m_isAntithetic is equal to true. If \f$x\f$ is a value that
- * would be returned normally, then \f$(max - x\f$) is the distance
- * that \f$x\f$ would be from \f$max\f$. The value returned in the
- * antithetic case, \f$x'\f$, is calculated as
- *
- * \f[
- * x' = min + (max - x) ,
- * \f]
- *
- * which is the lower bound plus the distance \f$x\f$ is from the
- * upper bound.
- *
- * Note that we have to re-implement this method here because the method is
- * overloaded above for the two-argument variant and the c++ name resolution
- * rules don't work well with overloads split between parent and child
- * classes.
- */
+ * \note The upper limit is excluded from the output range.
+ */
virtual double GetValue (void);
-
/**
- * \brief Returns a random unsigned integer from a uniform distribution over the interval [min,max] including both ends, where min and max are the current lower and upper bounds.
- * \return A random unsigned integer value.
- *
- * Note that antithetic values are being generated if
- * m_isAntithetic is equal to true. If \f$x\f$ is a value that
- * would be returned normally, then \f$(max - x\f$) is the distance
- * that \f$x\f$ would be from \f$max\f$. The value returned in the
- * antithetic case, \f$x'\f$, is calculated as
- *
- * \f[
- * x' = min + (max - x) ,
- * \f]
- *
- * which is the lower bound plus the distance \f$x\f$ is from the
- * upper bound.
+ * \brief Get the next random value as an integer drawn from the distribution.
+ * \return An integer random value.
+ * \note The upper limit is included in the output range.
*/
virtual uint32_t GetInteger (void);
+
private:
- /// The lower bound on values that can be returned by this RNG stream.
+ /** The lower bound on values that can be returned by this RNG stream. */
double m_min;
- /// The upper bound on values that can be returned by this RNG stream.
+ /** The upper bound on values that can be returned by this RNG stream. */
double m_max;
-};
+}; // class UniformRandomVariable
+
+
/**
* \ingroup randomvariable
* \brief The Random Number Generator (RNG) that returns a constant.
*
- * Class ConstantRandomVariable returns the same value for every sample.
+ * This RNG returns the same value for every sample.
+ *
+ * \par Antithetic Values.
+ *
+ * This RNG ignores the antithetic setting.
*/
class ConstantRandomVariable : public RandomVariableStream
{
public:
+ /**
+ * \brief Register this type.
+ * \return The object TypeId.
+ */
static TypeId GetTypeId (void);
/**
@@ -315,147 +329,186 @@
ConstantRandomVariable ();
/**
- * \brief Returns the constant value returned by this RNG stream.
- * \return The constant value returned by this RNG stream.
+ * \brief Get the constant value returned by this RNG stream.
+ * \return The constant value.
*/
double GetConstant (void) const;
/**
- * \brief Returns the value passed in.
- * \return The floating point value passed in.
+ * \brief Get the next random value, as a double equal to the argument.
+ * \param constant The value to return.
+ * \return The floating point argument.
*/
double GetValue (double constant);
/**
- * \brief Returns the value passed in.
- * \return The integer value passed in.
+ * \brief Get the next random value, as an integer equal to the argument.
+ * \param constant The value to return.
+ * \return The integer argument.
*/
uint32_t GetInteger (uint32_t constant);
- /**
- * \brief Returns the constant value returned by this RNG stream.
- * \return The constant value returned by this RNG stream.
- */
+ // Inherited from RandomVariableStream
+ /* \note This RNG always returns the same value. */
virtual double GetValue (void);
-
- /**
- * \brief Returns an integer cast of the constant value returned by this RNG stream.
- * \return Integer cast of the constant value returned by this RNG stream.
- */
+ /* \note This RNG always returns the same value. */
virtual uint32_t GetInteger (void);
private:
- /// The constant value returned by this RNG stream.
+ /** The constant value returned by this RNG stream. */
double m_constant;
-};
+}; // class ConstantRandomVariable
+
+
/**
* \ingroup randomvariable
- * \brief The Random Number Generator (RNG) that returns a sequential
- * list of values
+ * \brief The Random Number Generator (RNG) that returns a pattern of
+ * sequential values.
+ *
+ * This RNG has four configuration attributes:
+ *
+ * - An increment, \c Increment.
+ * - A consecutive repeat numer, \c Consecutive.
+ * - The minimum value, \c Min.
+ * - The maximum value, \c Max.
+ *
+ * The RNG starts at the \c Min value. Each return value is
+ * repeated \c Consecutive times, before advancing by the \c Increment.
+ * When the \c Increment would cause the value to equal or exceed
+ * \c Max it is reset to \c Min first.
*
- * Class SequentialRandomVariable defines a random number generator
- * that returns a sequence of values. The sequence monotonically
- * increases for a period, then wraps around to the low value and
- * begins monotonically increasing again.
+ * For example, if an instance is configured with:
+ *
+ * Attribute | Value
+ * :---------- | -----:
+ * Min | 2
+ * Max | 13
+ * Increment | 4
+ * Consecutive | 3
+ *
+ * The sequence will repeat this pattern: 2 2 2 6 6 6 10 10 10.
+ *
+ * Notice that \c Max will be a strict upper bound on the values:
+ * all values in the sequence will be less than \c Max.
+ *
+ * \par Antithetic Values.
+ *
+ * This RNG ignores the antithetic setting.
*/
class SequentialRandomVariable : public RandomVariableStream
{
public:
+ /**
+ * \brief Register this type.
+ * \return The object TypeId.
+ */
static TypeId GetTypeId (void);
/**
- * \brief Creates a sequential RNG with the default values for the sequence parameters.
+ * \brief Creates a sequential RNG with the default values
+ * for the sequence parameters.
*/
SequentialRandomVariable ();
/**
- * \brief Returns the first value of the sequence.
+ * \brief Get the first value of the sequence.
* \return The first value of the sequence.
*/
double GetMin (void) const;
/**
- * \brief Returns one more than the last value of the sequence.
- * \return One more than the last value of the sequence.
+ * \brief Get the limit of the sequence, which is (at least)
+ * one more than the last value of the sequence.
+ * \return The limit of the sequence.
*/
double GetMax (void) const;
/**
- * \brief Returns the random variable increment for the sequence.
- * \return The random variable increment for the sequence.
+ * \brief Get the increment for the sequence.
+ * \return The increment between distinct values for the sequence.
*/
Ptr<RandomVariableStream> GetIncrement (void) const;
/**
- * \brief Returns the number of times each member of the sequence is repeated.
- * \return The number of times each member of the sequence is repeated.
+ * \brief Get the number of times each distinct value of the sequence
+ * is repeated before incrementing to the next value.
+ * \return The number of times each value is repeated.
*/
uint32_t GetConsecutive (void) const;
- /**
- * \brief Returns the next value in the sequence returned by this RNG stream.
- * \return The next value in the sequence returned by this RNG stream.
- *
- * The following four parameters define the sequence. For example,
- *
- * - m_min = 0 (First value of the sequence)
- * - m_max = 5 (One more than the last value of the sequence)
- * - m_increment = 1 (Random variable increment between sequence values)
- * - m_consecutive = 2 (Number of times each member of the sequence is repeated)
- *
- * creates a RNG that has the sequence 0, 0, 1, 1, 2, 2, 3, 3, 4, 4, 0, 0 ...
- */
+ // Inherited from RandomVariableStream
virtual double GetValue (void);
-
- /**
- * \brief Returns an integer cast of the next value in the sequence returned by this RNG stream.
- * \return Integer cast of the next value in the sequence returned by this RNG stream.
- */
virtual uint32_t GetInteger (void);
private:
- /// The first value of the sequence.
+ /** The first value of the sequence. */
double m_min;
- /// One more than the last value of the sequence.
+ /** Strict upper bound on the sequence. */
double m_max;
- /// The sequence random variable increment.
+ /** Increment between distinct values. */
Ptr<RandomVariableStream> m_increment;
- /// The number of times each member of the sequence is repeated.
+ /** The number of times each distinct value is repeated. */
uint32_t m_consecutive;
- /// The current sequence value.
+ /** The current sequence value. */
double m_current;
- /// The number of times the sequence has been repeated.
+ /** The number of times the current distinct value has been repeated. */
uint32_t m_currentConsecutive;
- /// Indicates if the current sequence value has been set.
+ /** Indicates if the current sequence value has been properly initialized. */
bool m_isCurrentSet;
-};
+}; // class SequentialRandomVariable
+
/**
* \ingroup randomvariable
- * \brief The exponential distribution Random Number Generator (RNG) that allows stream numbers to be set deterministically.
+ * \brief The exponential distribution Random Number Generator (RNG).
*
* This class supports the creation of objects that return random numbers
* from a fixed exponential distribution. It also supports the generation of
* single random numbers from various exponential distributions.
*
* The probability density function of an exponential variable
- * is defined over the interval [0, \f$+\infty\f$) as:
- * \f$ \alpha e^{-\alpha x} \f$
- * where \f$ \alpha = \frac{1}{mean} \f$
+ * is defined as:
+ * \f[
+ * P(x) dx = \alpha e^{-\alpha x} dx, \quad x \in [0, +\infty)
+ * \f]
+ * over the interval \f$[0, +\infty)\f$, where \f$ \alpha = \frac{1}{Mean} \f$
+ * and \c Mean is a configurable attribute.
+ *
+ * The normal RNG value \f$x\f$ is calculated by
+ *
+ * \f[
+ * x = - 1/\alpha \log(u)
+ * \f]
+ *
+ * where \f$u\f$ is a uniform random variable on \f$[0,1)\f$.
+ *
+ * \par Bounded Distribution
*
* Since exponential distributions can theoretically return unbounded
* values, it is sometimes useful to specify a fixed upper limit. The
- * bounded version is defined over the interval [0,b] as: \f$ \alpha
- * e^{-\alpha x} \quad x \in [0,b] \f$. Note that in this case the
- * true mean of the distribution is slightly smaller than the mean
- * value specified: \f$ 1/\alpha - b/(e^{\alpha \, b}-1) \f$.
+ * bounded version is defined over the interval \f$[0,b]\f$ as:
+ *
+ * \f[
+ * P(x; b) dx = \alpha e^{-\alpha x} dx \quad x \in [0,b]
+ * \f]
+ *
+ * where the \c Bound \f$b\f$ is a configurable attribute.
+ *
+ * Note that in this case the true mean of the distribution is smaller
+ * than the nominal mean value:
+ *
+ * \f[
+ * <X: P(x; b)> = 1/\alpha - b/(e^{\alpha \, b} -1)
+ * \f]
+ *
+ * \par Example
*
* Here is an example of how to use this class:
* \code
@@ -470,10 +523,24 @@
* // exponentially distributed random variable is equal to mean.
* double value = x->GetValue ();
* \endcode
+ *
+ * \par Antithetic Values.
+ *
+ * The antithetic value is calculated from
+ *
+ * \f[
+ * x' = - mean * \log(1 - u),
+ * \f]
+ *
+ * where again \f$u\f$ is a uniform random variable on \f$[0,1)\f$.
*/
class ExponentialRandomVariable : public RandomVariableStream
{
public:
+ /**
+ * \brief Register this type.
+ * \return The object TypeId.
+ */
static TypeId GetTypeId (void);
/**
@@ -483,133 +550,55 @@
ExponentialRandomVariable ();
/**
- * \brief Returns the mean value of the random variables returned by this RNG stream.
- * \return The mean value of the random variables returned by this RNG stream.
+ * \brief Get the configured mean value of this RNG.
+ *
+ * \note This will not be the actual mean if the distribution is
+ * truncated by a bound.
+ * \return The configured mean value.
*/
double GetMean (void) const;
/**
- * \brief Returns the upper bound on values that can be returned by this RNG stream.
- * \return The upper bound on values that can be returned by this RNG stream.
+ * \brief Get the configured upper bound of this RNG.
+ * \return The upper bound.
*/
double GetBound (void) const;
/**
- * \brief Returns a random double from an exponential distribution with the specified mean and upper bound.
- * \param mean Mean value of the random variables.
+ * \brief Get the next random value, as a double from
+ * the exponential distribution with the specified mean and upper bound.
+ * \param mean Mean value of the unbounded exponential distribution.
* \param bound Upper bound on values returned.
* \return A floating point random value.
- *
- * Note that antithetic values are being generated if
- * m_isAntithetic is equal to true. If \f$u\f$ is a uniform variable
- * over [0,1] and
- *
- * \f[
- * x = - mean * \log(u)
- * \f]
- *
- * is a value that would be returned normally, then \f$(1 - u\f$) is
- * the distance that \f$u\f$ would be from \f$1\f$. The value
- * returned in the antithetic case, \f$x'\f$, is calculated as
- *
- * \f[
- * x' = - mean * \log(1 - u),
- * \f]
- *
- * which now involves the log of the distance \f$u\f$ is from the 1.
*/
double GetValue (double mean, double bound);
/**
- * \brief Returns a random unsigned integer from an exponential distribution with the specified mean and upper bound.
- * \param mean Mean value of the random variables.
+ * \brief Get the next random value, as an unsigned integer from
+ * the exponential distribution with the specified mean and upper bound.
+ * \param mean Mean value of the unbounded exponential distributuion.
* \param bound Upper bound on values returned.
* \return A random unsigned integer value.
- *
- * Note that antithetic values are being generated if
- * m_isAntithetic is equal to true. If \f$u\f$ is a uniform variable
- * over [0,1] and
- *
- * \f[
- * x = - mean * \log(u)
- * \f]
- *
- * is a value that would be returned normally, then \f$(1 - u\f$) is
- * the distance that \f$u\f$ would be from \f$1\f$. The value
- * returned in the antithetic case, \f$x'\f$, is calculated as
- *
- * \f[
- * x' = - mean * \log(1 - u),
- * \f]
- *
- * which now involves the log of the distance \f$u\f$ is from the 1.
*/
uint32_t GetInteger (uint32_t mean, uint32_t bound);
- /**
- * \brief Returns a random double from an exponential distribution with the current mean and upper bound.
- * \return A floating point random value.
- *
- * Note that antithetic values are being generated if
- * m_isAntithetic is equal to true. If \f$u\f$ is a uniform variable
- * over [0,1] and
- *
- * \f[
- * x = - mean * \log(u)
- * \f]
- *
- * is a value that would be returned normally, then \f$(1 - u\f$) is
- * the distance that \f$u\f$ would be from \f$1\f$. The value
- * returned in the antithetic case, \f$x'\f$, is calculated as
- *
- * \f[
- * x' = - mean * \log(1 - u),
- * \f]
- *
- * which now involves the log of the distance \f$u\f$ is from the 1.
- *
- * Note that we have to re-implement this method here because the method is
- * overloaded above for the two-argument variant and the c++ name resolution
- * rules don't work well with overloads split between parent and child
- * classes.
- */
+ // Inherited from RandomVariableStream
virtual double GetValue (void);
-
- /**
- * \brief Returns a random unsigned integer from an exponential distribution with the current mean and upper bound.
- * \return A random unsigned integer value.
- *
- * Note that antithetic values are being generated if
- * m_isAntithetic is equal to true. If \f$u\f$ is a uniform variable
- * over [0,1] and
- *
- * \f[
- * x = - mean * \log(u)
- * \f]
- *
- * is a value that would be returned normally, then \f$(1 - u\f$) is
- * the distance that \f$u\f$ would be from \f$1\f$. The value
- * returned in the antithetic case, \f$x'\f$, is calculated as
- *
- * \f[
- * x' = - mean * \log(1 - u),
- * \f]
- *
- * which now involves the log of the distance \f$u\f$ is from the 1.
- */
virtual uint32_t GetInteger (void);
private:
- /// The mean value of the random variables returned by this RNG stream.
+ /** The mean value of the unbounded exponential distribution. */
double m_mean;
- /// The upper bound on values that can be returned by this RNG stream.
+ /** The upper bound on values that can be returned by this RNG stream. */
double m_bound;
-};
+}; // class ExponentialRandomVariable
+
+
/**
* \ingroup randomvariable
- * \brief The Pareto distribution Random Number Generator (RNG) that allows stream numbers to be set deterministically.
+ * \brief The Pareto distribution Random Number Generator (RNG).
*
* This class supports the creation of objects that return random numbers
* from a fixed Pareto distribution. It also supports the generation of
@@ -654,6 +643,10 @@
class ParetoRandomVariable : public RandomVariableStream
{
public:
+ /**
+ * \brief Register this type.
+ * \return The object TypeId.
+ */
static TypeId GetTypeId (void);
/**
@@ -812,16 +805,18 @@
virtual uint32_t GetInteger (void);
private:
- /// The mean parameter for the Pareto distribution returned by this RNG stream.
+ /** The mean parameter for the Pareto distribution returned by this RNG stream. */
double m_mean;
- /// The shape parameter for the Pareto distribution returned by this RNG stream.
+ /** The shape parameter for the Pareto distribution returned by this RNG stream. */
double m_shape;
- /// The upper bound on values that can be returned by this RNG stream.
+ /** The upper bound on values that can be returned by this RNG stream. */
double m_bound;
-};
+}; // class ParetoRandomVariable
+
+
/**
* \ingroup randomvariable
* \brief The Weibull distribution Random Number Generator (RNG) that allows stream numbers to be set deterministically.
@@ -878,6 +873,10 @@
class WeibullRandomVariable : public RandomVariableStream
{
public:
+ /**
+ * \brief Register this type.
+ * \return The object TypeId.
+ */
static TypeId GetTypeId (void);
/**
@@ -1012,16 +1011,18 @@
virtual uint32_t GetInteger (void);
private:
- /// The scale parameter for the Weibull distribution returned by this RNG stream.
+ /** The scale parameter for the Weibull distribution returned by this RNG stream. */
double m_scale;
- /// The shape parameter for the Weibull distribution returned by this RNG stream.
+ /** The shape parameter for the Weibull distribution returned by this RNG stream. */
double m_shape;
- /// The upper bound on values that can be returned by this RNG stream.
+ /** The upper bound on values that can be returned by this RNG stream. */
double m_bound;
-};
+}; // class WeibullRandomVariable
+
+
/**
* \ingroup randomvariable
* \brief The normal (Gaussian) distribution Random Number Generator
@@ -1058,8 +1059,13 @@
class NormalRandomVariable : public RandomVariableStream
{
public:
+ /** Large constant to bound the range. */
static const double INFINITE_VALUE;
+ /**
+ * \brief Register this type.
+ * \return The object TypeId.
+ */
static TypeId GetTypeId (void);
/**
@@ -1238,22 +1244,24 @@
virtual uint32_t GetInteger (void);
private:
- /// The mean value for the normal distribution returned by this RNG stream.
+ /** The mean value for the normal distribution returned by this RNG stream. */
double m_mean;
- /// The variance value for the normal distribution returned by this RNG stream.
+ /** The variance value for the normal distribution returned by this RNG stream. */
double m_variance;
- /// The bound on values that can be returned by this RNG stream.
+ /** The bound on values that can be returned by this RNG stream. */
double m_bound;
- /// True if the next value is valid.
+ /** True if the next value is valid. */
bool m_nextValid;
- /// The algorithm produces two values at a time.
+ /** The algorithm produces two values at a time. */
double m_next;
-};
+}; // class NormalRandomVariable
+
+
/**
* \ingroup randomvariable
* \brief The log-normal distribution Random Number Generator
@@ -1300,6 +1308,10 @@
class LogNormalRandomVariable : public RandomVariableStream
{
public:
+ /**
+ * \brief Register this type.
+ * \return The object TypeId.
+ */
static TypeId GetTypeId (void);
/**
@@ -1462,12 +1474,14 @@
virtual uint32_t GetInteger (void);
private:
- /// The mu value for the log-normal distribution returned by this RNG stream.
+ /** The mu value for the log-normal distribution returned by this RNG stream. */
double m_mu;
- /// The sigma value for the log-normal distribution returned by this RNG stream.
+ /** The sigma value for the log-normal distribution returned by this RNG stream. */
double m_sigma;
-};
+
+}; // class LogNormalRandomVariable
+
/**
* \ingroup randomvariable
@@ -1503,6 +1517,10 @@
class GammaRandomVariable : public RandomVariableStream
{
public:
+ /**
+ * \brief Register this type.
+ * \return The object TypeId.
+ */
static TypeId GetTypeId (void);
/**
@@ -1623,19 +1641,20 @@
*/
double GetNormalValue (double mean, double variance, double bound);
- /// The alpha value for the gamma distribution returned by this RNG stream.
+ /** The alpha value for the gamma distribution returned by this RNG stream. */
double m_alpha;
- /// The beta value for the gamma distribution returned by this RNG stream.
+ /** The beta value for the gamma distribution returned by this RNG stream. */
double m_beta;
- /// True if the next normal value is valid.
+ /** True if the next normal value is valid. */
bool m_nextValid;
- /// The algorithm produces two normal values at a time.
+ /** The algorithm produces two normal values at a time. */
double m_next;
-};
+}; // class GammaRandomVariable
+
/**
* \ingroup randomvariable
@@ -1675,6 +1694,10 @@
class ErlangRandomVariable : public RandomVariableStream
{
public:
+ /**
+ * \brief Register this type.
+ * \return The object TypeId.
+ */
static TypeId GetTypeId (void);
/**
@@ -1783,13 +1806,14 @@
*/
double GetExponentialValue (double mean, double bound);
- /// The k value for the Erlang distribution returned by this RNG stream.
+ /** The k value for the Erlang distribution returned by this RNG stream. */
uint32_t m_k;
- /// The lambda value for the Erlang distribution returned by this RNG stream.
+ /** The lambda value for the Erlang distribution returned by this RNG stream. */
double m_lambda;
-};
+}; // class ErlangRandomVariable
+
/**
* \ingroup randomvariable
@@ -1822,6 +1846,10 @@
class TriangularRandomVariable : public RandomVariableStream
{
public:
+ /**
+ * \brief Register this type.
+ * \return The object TypeId.
+ */
static TypeId GetTypeId (void);
/**
@@ -2008,15 +2036,17 @@
virtual uint32_t GetInteger (void);
private:
- /// The mean value for the triangular distribution returned by this RNG stream.
+ /** The mean value for the triangular distribution returned by this RNG stream. */
double m_mean;
- /// The lower bound on values that can be returned by this RNG stream.
+ /** The lower bound on values that can be returned by this RNG stream. */
double m_min;
- /// The upper bound on values that can be returned by this RNG stream.
+ /** The upper bound on values that can be returned by this RNG stream. */
double m_max;
-};
+
+}; // class TriangularRandomVariable
+
/**
* \ingroup randomvariable
@@ -2079,6 +2109,10 @@
class ZipfRandomVariable : public RandomVariableStream
{
public:
+ /**
+ * \brief Register this type.
+ * \return The object TypeId.
+ */
static TypeId GetTypeId (void);
/**
@@ -2161,15 +2195,17 @@
virtual uint32_t GetInteger (void);
private:
- /// The n value for the Zipf distribution returned by this RNG stream.
+ /** The n value for the Zipf distribution returned by this RNG stream. */
uint32_t m_n;
- /// The alpha value for the Zipf distribution returned by this RNG stream.
+ /** The alpha value for the Zipf distribution returned by this RNG stream. */
double m_alpha;
- /// The normalization constant.
+ /** The normalization constant. */
double m_c;
-};
+
+}; // class ZipfRandomVariable
+
/**
* \ingroup randomvariable
@@ -2213,6 +2249,10 @@
class ZetaRandomVariable : public RandomVariableStream
{
public:
+ /**
+ * \brief Register this type.
+ * \return The object TypeId.
+ */
static TypeId GetTypeId (void);
/**
@@ -2287,12 +2327,14 @@
virtual uint32_t GetInteger (void);
private:
- /// The alpha value for the zeta distribution returned by this RNG stream.
+ /** The alpha value for the zeta distribution returned by this RNG stream. */
double m_alpha;
- /// Just for calculus simplifications.
+ /** Just for calculus simplifications. */
double m_b;
-};
+
+}; // class ZetaRandomVariable
+
/**
* \ingroup randomvariable
@@ -2300,7 +2342,7 @@
*
* Defines a random variable that has a specified, predetermined
* sequence. This would be useful when trying to force the RNG to
- * return a known sequence, perhaps to compare NS-3 to some other
+ * return a known sequence, perhaps to compare ns-3 to some other
* simulator
*
* Creates a generator that returns successive elements of the values
@@ -2327,6 +2369,10 @@
class DeterministicRandomVariable : public RandomVariableStream
{
public:
+ /**
+ * \brief Register this type.
+ * \return The object TypeId.
+ */
static TypeId GetTypeId (void);
/**
@@ -2359,15 +2405,17 @@
virtual uint32_t GetInteger (void);
private:
- /// Position in the array of values.
+ /** Position in the array of values. */
uint64_t m_count;
- /// Position of the next value in the array of values.
+ /** Position of the next value in the array of values. */
uint64_t m_next;
- /// Array of values to return in sequence.
+ /** Array of values to return in sequence. */
double* m_data;
-};
+
+}; // class DeterministicRandomVariable
+
/**
* \ingroup randomvariable
@@ -2403,6 +2451,10 @@
class EmpiricalRandomVariable : public RandomVariableStream
{
public:
+ /**
+ * \brief Register this type.
+ * \return The object TypeId.
+ */
static TypeId GetTypeId (void);
/**
@@ -2445,20 +2497,63 @@
virtual uint32_t GetInteger (void);
private:
+ /** Helper to hold one point of the CDF. */
class ValueCDF
{
public:
+ /** Constructor. */
ValueCDF ();
+ /**
+ * Construct from values.
+ *
+ * \param [in] v The argumetn value.
+ * \param [in] c The CDF at the argument value \p v.
+ */
ValueCDF (double v, double c);
+ /**
+ * Copy constructor.
+ *
+ * \param [in] c The other ValueCDF.
+ */
ValueCDF (const ValueCDF& c);
+
+ /** The argument value. */
double value;
+ /** The CDF at \p value. */
double cdf;
};
- virtual void Validate (); // Insure non-decreasing emiprical values
- virtual double Interpolate (double, double, double, double, double);
- bool validated; // True if non-decreasing validated
- std::vector<ValueCDF> emp; // Empicical CDF
-};
+ /**
+ * Check that the CDF is valid.
+ *
+ * A valid CDF has
+ *
+ * - Strictly increasing arguments, and
+ * - Strictly increasing CDF.
+ *
+ * It is a fatal error to fail validation.
+ */
+ virtual void Validate ();
+ /**
+ * Linear nterpolation between two points on the CDF to estimate
+ * the value at \p r.
+ *
+ * \param [in] c1 The first argument value.
+ * \param [in] c2 The secong argument value.
+ * \param [in] v1 The first CDF value.
+ * \param [in] v2 The secong CDF value.
+ * \param [in] r The argument value to interpolate to.
+ * \returns The interpolated CDF at \p r.
+ */
+ virtual double Interpolate (double c1, double c2,
+ double v1, double v2, double r);
+
+ /** \c true once the CDF has been validated. */
+ bool validated;
+ /** The vector of CDF points. */
+ std::vector<ValueCDF> emp;
+
+}; // class EmpiricalRandomVariable
+
} // namespace ns3
--- a/src/core/model/realtime-simulator-impl.h Tue Jul 21 12:20:12 2015 -0700
+++ b/src/core/model/realtime-simulator-impl.h Tue Jul 21 16:20:17 2015 -0700
@@ -108,18 +108,18 @@
virtual uint32_t GetSystemId (void) const;
virtual uint32_t GetContext (void) const;
- /** \copydoc ScheduleWithContext */
+ /** \copydoc ScheduleWithContext(uint32_t,const Time&,EventImpl*) */
void ScheduleRealtimeWithContext (uint32_t context, Time const &delay, EventImpl *event);
- /** \copydoc Schedule */
+ /** \copydoc Schedule(const Time&,EventImpl*) */
void ScheduleRealtime (Time const &delay, EventImpl *event);
/**
- * \copybrief ScheduleNow
+ * \copybrief ScheduleNow(EventImpl*)
*
* \param context Event context.
* \param event The event to schedule.
*/
void ScheduleRealtimeNowWithContext (uint32_t context, EventImpl *event);
- /** \copydoc ScheduleNow */
+ /** \copydoc ScheduleNow(EventImpl*) */
void ScheduleRealtimeNow (EventImpl *event);
/**
* Get the current real time from the synchronizer.
--- a/src/core/model/rng-seed-manager.h Tue Jul 21 12:20:12 2015 -0700
+++ b/src/core/model/rng-seed-manager.h Tue Jul 21 16:20:17 2015 -0700
@@ -22,68 +22,92 @@
#include <stdint.h>
+/**
+ * \file
+ * \ingroup randomvariable
+ * ns3::RngSeedManager declaration.
+ */
+
namespace ns3 {
+/**
+ * \ingroup randomvariable
+ *
+ * Manage the seed number and run number of the underlying
+ * random number generator, and automatic assignment of stream numbers.
+ */
class RngSeedManager
{
public:
/**
- * \brief set the seed
- * it will duplicate the seed value 6 times
+ * \brief Set the seed.
+ *
+ * This sets the global initial seed which will be used all
+ * subsequently instantiated RandomVariableStream objects.
+ *
* \code
- * RngSeedManger::SetSeed(15);
- * UniformVariable x(2,3); //these will give the same output everytime
- * ExponentialVariable y(120); //as long as the seed stays the same
+ * RngSeedManger::SetSeed(15);
+ * UniformVariable x(2,3); // These will give the same output everytime
+ * ExponentialVariable y(120); // as long as the seed stays the same.
* \endcode
- * \param seed
+ * \param seed The seed value to use.
*
- * Note, while the underlying RNG takes six integer values as a seed;
+ * \note While the underlying RNG takes six integer values as a seed;
* it is sufficient to set these all to the same integer, so we provide
* a simpler interface here that just takes one integer.
*/
static void SetSeed (uint32_t seed);
/**
- * \brief Get the seed value
- * \return the seed value
+ * \brief Get the current seed value which will be used by all
+ * subsequently instantiated RandomVariableStream objects.
+ *
+ * \return The seed value.
*
- * Note: returns the first of the six seed values used in the underlying RNG
+ * This returns the current seed value.
*/
static uint32_t GetSeed (void);
/**
- * \brief Set the run number of simulation
+ * \brief Set the run number of simulation.
*
* \code
- * RngSeedManager::SetSeed(12);
- * int N = atol(argv[1]); //read in run number from command line
- * RngSeedManager::SetRun(N);
- * UniformVariable x(0,10);
- * ExponentialVariable y(2902);
+ * RngSeedManager::SetSeed(12);
+ * int N = atol(argv[1]); // Read in run number from command line.
+ * RngSeedManager::SetRun(N);
+ * UniformVariable x(0,10);
+ * ExponentialVariable y(2902);
* \endcode
- * In this example, N could successivly be equal to 1,2,3, etc. and the user
- * would continue to get independent runs out of the single simulation. For
- * this simple example, the following might work:
+ * In this example, \c N could successivly be equal to 1,2,3, _etc._
+ * and the user would continue to get independent runs out of the
+ * single simulation. For this simple example, the following might work:
* \code
- * ./simulation 0
- * ...Results for run 0:...
+ * ./simulation 0
+ * ...Results for run 0:...
*
- * ./simulation 1
- * ...Results for run 1:...
+ * ./simulation 1
+ * ...Results for run 1:...
* \endcode
+ *
+ * \param [in] run The run number.
*/
static void SetRun (uint64_t run);
/**
- * \returns the current run number
- * @sa SetRun
+ * \brief Get the current run number.
+ * \returns The current run number
+ * \see SetRun
*/
static uint64_t GetRun (void);
+ /**
+ * Get the next automatically assigned stream index.
+ * \returns The next stream index.
+ */
static uint64_t GetNextStreamIndex(void);
};
-// for compatibility
+/** Alias for compatibility. */
typedef RngSeedManager SeedManager;
} // namespace ns3
--- a/src/core/model/rng-stream.cc Tue Jul 21 12:20:12 2015 -0700
+++ b/src/core/model/rng-stream.cc Tue Jul 21 16:20:17 2015 -0700
@@ -26,6 +26,10 @@
#include "fatal-error.h"
#include "log.h"
+/// \file
+/// \ingroup rngimpl
+/// Class RngStream and MRG32k3a implementation.
+
namespace ns3 {
// Note: Logging in this file is largely avoided due to the
@@ -36,26 +40,61 @@
} // namespace ns3
+/// \ingroup rngimpl
+/// Unnamed namespace for MRG32k3a implementation details.
namespace
{
+
+/// \ingroup rngimpl
+/// Type for 3x3 matrix of doubles.
typedef double Matrix[3][3];
+/// \ingroup rngimpl
+/// First component modulus, 2<sup>32</sup> - 209.
const double m1 = 4294967087.0;
+
+/// \ingroup rngimpl
+/// Second component modulus, 2<sup>32</sup> - 22853.
const double m2 = 4294944443.0;
+
+/// \ingroup rngimpl
+/// Normalization to obtain randoms on [0,1).
const double norm = 1.0 / (m1 + 1.0);
+
+/// \ingroup rngimpl
+/// First component multiplier of <i>n</i> - 2 value.
const double a12 = 1403580.0;
+
+/// \ingroup rngimpl
+/// First component multiplier of <i>n</i> - 3 value.
const double a13n = 810728.0;
+
+/// \ingroup rngimpl
+/// Second component multiplier of <i>n</i> - 1 value.
const double a21 = 527612.0;
+
+/// \ingroup rngimpl
+/// Second component multiplier of <i>n</i> - 3 value.
const double a23n = 1370589.0;
+
+/// \ingroup rngimpl
+/// Decomposition factor for computing a*s in less than 53 bits, 2<sup>17</sup>
const double two17 = 131072.0;
+
+/// \ingroup rngimpl
+/// IEEE-754 floating point precision, 2<sup>53</sup>
const double two53 = 9007199254740992.0;
-
+
+/// \ingroup rngimpl
+/// First component transition matrix.
const Matrix A1p0 = {
{ 0.0, 1.0, 0.0 },
{ 0.0, 0.0, 1.0 },
{ -810728.0, 1403580.0, 0.0 }
};
+/// \ingroup rngimpl
+/// Second component transition matrix.
const Matrix A2p0 = {
{ 0.0, 1.0, 0.0 },
{ 0.0, 0.0, 1.0 },
@@ -64,7 +103,17 @@
//-------------------------------------------------------------------------
-// Return (a*s + c) MOD m; a, s, c and m must be < 2^35
+/// \ingroup rngimpl
+/// Return (a*s + c) MOD m; a, s, c and m must be < 2^35
+///
+/// This computes the result exactly, without exceeding the 53 bit
+/// precision of doubles.
+///
+/// \param a First multiplicative argument.
+/// \param s Second multiplicative argument.
+/// \param c Additive argument.
+/// \param m Modulus.
+/// \returns <tt>(a*s +c) MOD m</tt>
//
double MultModM (double a, double s, double c, double m)
{
@@ -97,8 +146,14 @@
//-------------------------------------------------------------------------
-// Compute the vector v = A*s MOD m. Assume that -m < s[i] < m.
-// Works also when v = s.
+/// \ingroup rngimpl
+/// Compute the vector v = A*s MOD m. Assume that -m < s[i] < m.
+/// Works also when v = s.
+///
+/// \param A Matrix argument, 3x3.
+/// \param s Three component input vector.
+/// \param v Three component output vector.
+/// \param m Modulus.
//
void MatVecModM (const Matrix A, const double s[3], double v[3],
double m)
@@ -120,8 +175,14 @@
//-------------------------------------------------------------------------
-// Compute the matrix C = A*B MOD m. Assume that -m < s[i] < m.
-// Note: works also if A = C or B = C or A = B = C.
+/// \ingroup rngimpl
+/// Compute the matrix C = A*B MOD m. Assume that -m < s[i] < m.
+/// Note: works also if A = C or B = C or A = B = C.
+///
+/// \param A First matrix argument.
+/// \param B Second matrix argument.
+/// \param C Result matrix.
+/// \param m Modulus.
//
void MatMatModM (const Matrix A, const Matrix B,
Matrix C, double m)
@@ -153,7 +214,13 @@
//-------------------------------------------------------------------------
-// Compute the matrix B = (A^(2^e) Mod m); works also if A = B.
+/// \ingroup rngimpl
+/// Compute the matrix B = (A^(2^e) Mod m); works also if A = B.
+///
+/// \param src Matrix input argument \c A.
+/// \param dst Matrix output \c B.
+/// \param m Modulus.
+/// \param e The exponent.
//
void MatTwoPowModM (const Matrix src, Matrix dst, double m, int32_t e)
{
@@ -176,9 +243,15 @@
//-------------------------------------------------------------------------
-// Compute the matrix B = (A^n Mod m); works even if A = B.
+/*
+/// \ingroup rngimpl
+/// Compute the matrix B = (A^n Mod m); works even if A = B.
+///
+/// \param A Matrix input argument.
+/// \param B Matrix output.
+/// \param m Modulus.
+/// \param n Exponent.
//
-/*
void MatPowModM (const double A[3][3], double B[3][3], double m, int32_t n)
{
NS_LOG_FUNCTION (A << B << m << n);
@@ -212,13 +285,19 @@
}
*/
-// The following are the transition matrices of the two MRG components
-// (in matrix form), raised to all powers of 2 from 1 to 191
+/// The transition matrices of the two MRG components
+/// (in matrix form), raised to all powers of 2 from 1 to 191
+//
struct Precalculated
{
- Matrix a1[190];
- Matrix a2[190];
+ Matrix a1[190]; //!< First component transition matrix powers.
+ Matrix a2[190]; //!< Second component transition matrix powers.
};
+/// Compute the transition matrices of the two MRG components
+// raised to all powers of 2 from 1 to 191.
+///
+/// \returns The precalculated powers of the transition matrices.
+//
struct Precalculated PowerOfTwoConstants (void)
{
struct Precalculated precalculated;
@@ -230,6 +309,12 @@
}
return precalculated;
}
+/// Get the transition matrices raised to a power of 2.
+///
+/// \param n The power of 2.
+/// \param a1p The first transition matrix power.
+/// \param a2p The second transition matrix power.
+//
void PowerOfTwoMatrix (int n, Matrix a1p, Matrix a2p)
{
static struct Precalculated constants = PowerOfTwoConstants ();
--- a/src/core/model/rng-stream.h Tue Jul 21 12:20:12 2015 -0700
+++ b/src/core/model/rng-stream.h Tue Jul 21 16:20:17 2015 -0700
@@ -22,10 +22,21 @@
#include <string>
#include <stdint.h>
+/**
+ * \file
+ * \ingroup rngimpl
+ * Declaration of class RngStream.
+ */
+
namespace ns3 {
/**
- * \ingroup randomvariable
+ * \ingroup randomvariable
+ * \defgroup rngimpl RNG Implementation.
+ */
+
+/**
+ * \ingroup rngimpl
*
* \brief Combined Multiple-Recursive Generator MRG32k3a
*
@@ -38,17 +49,39 @@
class RngStream
{
public:
+ /**
+ * Construct from explicit seed, stream and substream values.
+ *
+ * \param seed The starting seed.
+ * \param stream The stream number.
+ * \param substream The sub-stream number.
+ */
RngStream (uint32_t seed, uint64_t stream, uint64_t substream);
- RngStream (const RngStream&);
+ /**
+ * Copy constructor.
+ *
+ * \param r The RngStream to copy.
+ */
+ RngStream (const RngStream & r);
/**
* Generate the next random number for this stream.
* Uniformly distributed between 0 and 1.
+ *
+ * \returns The next random.
*/
double RandU01 (void);
private:
+ /**
+ * Advance \p state of the RNG by leaps and bounds.
+ *
+ * \param nth The stream or substream index.
+ * \param by The log2 base of \p nth.
+ * \param state The state vector to advance.
+ */
void AdvanceNthBy (uint64_t nth, int by, double state[6]);
+ /** The RNG state vector. */
double m_currentState[6];
};
--- a/src/core/model/scheduler.h Tue Jul 21 12:20:12 2015 -0700
+++ b/src/core/model/scheduler.h Tue Jul 21 16:20:17 2015 -0700
@@ -66,6 +66,10 @@
class Scheduler : public Object
{
public:
+ /**
+ * Register this type.
+ * \return The object TypeId.
+ */
static TypeId GetTypeId (void);
/**
@@ -91,42 +95,63 @@
EventKey key; /**< Key for sorting and ordering Events. */
};
+ /** Destructor. */
virtual ~Scheduler () = 0;
/**
- * \param ev event to store in the event list
+ * Insert a new Event in the schedule.
+ *
+ * \param ev Event to store in the event list
*/
virtual void Insert (const Event &ev) = 0;
/**
+ * Test if the schedule is empty.
+ *
* \returns true if the event list is empty and false otherwise.
*/
virtual bool IsEmpty (void) const = 0;
/**
+ * Get a pointer to the next event.
+ *
+ * This method cannot be invoked if the list is empty.
+ *
* \returns a pointer to the next earliest event. The caller
* takes ownership of the returned pointer.
- *
- * This method cannot be invoked if the list is empty.
*/
virtual Event PeekNext (void) const = 0;
/**
+ * Remove the earliest event from the event list.
+ *
* This method cannot be invoked if the list is empty.
- * Remove the next earliest event from the event list.
+ *
+ * \return The Event.
*/
virtual Event RemoveNext (void) = 0;
/**
- * \param ev the event to remove
+ * Remove a specific event from the event list.
*
- * This methods cannot be invoked if the list is empty.
+ * This method cannot be invoked if the list is empty.
+ *
+ * \param ev the event to remove
*/
virtual void Remove (const Event &ev) = 0;
};
-/* Note the invariants which this function must provide:
- * - irreflexibility: f (x,x) is false)
+/**
+ * \ingroup Events
+ * Compare (less than) two events by EventKey.
+ *
+ * Note the invariants which this function must provide:
+ * - irreflexibility: f (x,x) is false
* - antisymmetry: f(x,y) = !f(y,x)
* - transitivity: f(x,y) and f(y,z) => f(x,z)
+ *
+ * \param [in] a The first event.
+ * \param [in] b The second event.
+ * \returns \c true if \c a < \c b
*/
-inline bool operator < (const Scheduler::EventKey &a, const Scheduler::EventKey &b)
+inline bool operator < (const Scheduler::EventKey &a,
+ const Scheduler::EventKey &b)
{
if (a.m_ts < b.m_ts)
{
@@ -142,11 +167,30 @@
return false;
}
}
-inline bool operator != (const Scheduler::EventKey &a, const Scheduler::EventKey &b)
+
+/**
+ * \ingroup Events
+ * Compare (not equal) two events by EventKey.
+ *
+ * \param [in] a The first event.
+ * \param [in] b The second event.
+ * \returns \c true if \c a != \c b
+ */
+inline bool operator != (const Scheduler::EventKey &a,
+ const Scheduler::EventKey &b)
{
return a.m_uid != b.m_uid;
}
-inline bool operator > (const Scheduler::EventKey &a, const Scheduler::EventKey &b)
+
+/**
+ * Compare (greater than) two events by EventKey.
+ *
+ * \param [in] a The first event.
+ * \param [in] b The second event.
+ * \returns \c true if \c a > \c b
+ */
+inline bool operator > (const Scheduler::EventKey &a,
+ const Scheduler::EventKey &b)
{
if (a.m_ts > b.m_ts)
{
@@ -163,9 +207,15 @@
}
}
-
-
-inline bool operator < (const Scheduler::Event &a, const Scheduler::Event &b)
+/**
+ * Compare (less than) two events by Event.
+ *
+ * \param [in] a The first event.
+ * \param [in] b The second event.
+ * \returns \c true if \c a < \c b
+ */
+inline bool operator < (const Scheduler::Event &a,
+ const Scheduler::Event &b)
{
return a.key < b.key;
}
--- a/src/core/model/simulator-impl.h Tue Jul 21 12:20:12 2015 -0700
+++ b/src/core/model/simulator-impl.h Tue Jul 21 16:20:17 2015 -0700
@@ -55,153 +55,35 @@
*/
static TypeId GetTypeId (void);
- /**
- * Execute the events scheduled with ScheduleDestroy().
- *
- * This method is typically invoked at the end of a simulation
- * to avoid false-positive reports by a leak checker.
- * After this method has been invoked, it is actually possible
- * to restart a new simulation with a set of calls to Simulator::Run,
- * Simulator::Schedule and Simulator::ScheduleWithContext.
- */
+ /** \copydoc Simulator::Destroy */
virtual void Destroy () = 0;
- /**
- * Check if the simulation should finish.
- *
- * Reasons to finish are because there are
- * no more events lefts to be scheduled, or if simulation
- * time has already reached the "stop time" (see Simulator::Stop()).
- *
- * \return \c true if no more events or stop time reached.
- */
+ /** \copydoc Simulator::IsFinished */
virtual bool IsFinished (void) const = 0;
- /**
- * Tell the Simulator the calling event should be the last one
- * executed.
- *
- * If a running event invokes this method, it will be the last
- * event executed by the Simulator::Run method before
- * returning to the caller.
- */
+ /** \copydoc Simulator::Stop(void) */
virtual void Stop (void) = 0;
- /**
- * Schedule the time delay until the Simulator should stop.
- *
- * Force the Simulator::Run method to return to the caller when the
- * expiration time of the next event to be processed is greater than
- * or equal to the stop time. The stop time is relative to the
- * current simulation time.
- * \param time The stop time, relative to the current time.
- */
+ /** \copydoc Simulator::Stop(const Time&) */
virtual void Stop (Time const &delay) = 0;
- /**
- * Schedule a future event execution (in the same context).
- *
- * \param time Delay until the event expires.
- * \param event The event to schedule.
- * \returns A unique identifier for the newly-scheduled event.
- */
+ /** \copydoc Simulator::Schedule(const Time&,const Ptr<EventImpl>&) */
virtual EventId Schedule (Time const &delay, EventImpl *event) = 0;
- /**
- * Schedule a future event execution (in a different context).
- *
- * \param time Delay until the event expires.
- * \param context Event context.
- * \param event The event to schedule.
- * \returns A unique identifier for the newly-scheduled event.
- */
+ /** \copydoc Simulator::ScheduleWithContext(uint32_t,const Time&,EventImpl*) */
virtual void ScheduleWithContext (uint32_t context, Time const &delay, EventImpl *event) = 0;
- /**
- * Schedule an event to run at the current virtual time.
- *
- * \param event The event to schedule.
- * \returns A unique identifier for the newly-scheduled event.
- */
+ /** \copydoc Simulator::ScheduleNow(const Ptr<EventImpl>&) */
virtual EventId ScheduleNow (EventImpl *event) = 0;
- /**
- * Schedule an event to run at the end of the simulation, after
- * the Stop() time or condition has been reached.
- *
- * \param event The event to schedule.
- * \returns A unique identifier for the newly-scheduled event.
- */
+ /** \copydoc Simulator::ScheduleDestroy(const Ptr<EventImpl>&) */
virtual EventId ScheduleDestroy (EventImpl *event) = 0;
- /**
- * Remove an event from the event list.
- *
- * This method has the same visible effect as the
- * ns3::EventId::Cancel method
- * but its algorithmic complexity is much higher: it has often
- * O(log(n)) complexity, sometimes O(n), sometimes worse.
- * Note that it is not possible to remove events which were scheduled
- * for the "destroy" time. Doing so will result in a program error (crash).
- *
- * \param id The event to remove from the list of scheduled events.
- */
+ /** \copydoc Simulator::Remove */
virtual void Remove (const EventId &id) = 0;
- /**
- * Set the cancel bit on this event: the event's associated function
- * will not be invoked when it expires.
- *
- * This method has the same visible effect as the
- * ns3::Simulator::Remove method but its algorithmic complexity is
- * much lower: it has O(1) complexity.
- * This method has the exact same semantics as ns3::EventId::Cancel.
- * Note that it is not possible to cancel events which were scheduled
- * for the "destroy" time. Doing so will result in a program error (crash).
- *
- * \param id the event to cancel
- */
+ /** \copydoc Simulator::Cancel */
virtual void Cancel (const EventId &id) = 0;
- /**
- * Check if an event has already run or been cancelled.
- *
- * This method has O(1) complexity.
- * Note that it is not possible to test for the expiration of
- * events which were scheduled for the "destroy" time. Doing so
- * will result in a program error (crash).
- * An event is said to "expire" when it starts being scheduled
- * which means that if the code executed by the event calls
- * this function, it will get true.
- *
- * \param id The event to test for expiration.
- * \returns \c true if the event has expired, false otherwise.
- */
+ /** \copydoc Simulator::IsExpired */
virtual bool IsExpired (const EventId &id) const = 0;
- /**
- * Run the simulation.
- *
- * The simulation will run until one of:
- * - No events are present anymore
- * - The user called Simulator::Stop
- * - The user called Simulator::Stop with a stop time and the
- * expiration time of the next event to be processed
- * is greater than or equal to the stop time.
- */
+ /** \copydoc Simulator::Run */
virtual void Run (void) = 0;
- /**
- * Return the current simulation virtual time.
- *
- * \returns The current virtual time.
- */
+ /** \copydoc Simulator::Now */
virtual Time Now (void) const = 0;
- /**
- * Get the remaining time until this event will execute.
- *
- * \param id The event id to analyse.
- * \return The delay left until the input event id expires.
- * if the event is not running, this method returns
- * zero.
- */
+ /** \copydoc Simulator::GetDelayLeft */
virtual Time GetDelayLeft (const EventId &id) const = 0;
- /**
- * Get the maximum representable simulation time.
- *
- * \return The maximum simulation time at which an event
- * can be scheduled.
- *
- * The returned value will always be bigger than or equal to Simulator::Now.
- */
+ /** \copydoc Simulator::GetMaximumSimulationTime */
virtual Time GetMaximumSimulationTime (void) const = 0;
/**
* Set the Scheduler to be used to manage the event list.
@@ -213,19 +95,9 @@
* before we start to use it.
*/
virtual void SetScheduler (ObjectFactory schedulerFactory) = 0;
- /**
- * Get the system id of this simulator.
- *
- * The system id is the identifier for this simulator instance
- * in a distributed simulation. For MPI this is the MPI rank.
- * \return The system id for this simulator.
- */
+ /** \copydoc Simulator::GetSystemId */
virtual uint32_t GetSystemId () const = 0;
- /**
- * Get the current simulation context.
- *
- * \return The current simulation context
- */
+ /** \copydoc Simulator::GetContext */
virtual uint32_t GetContext (void) const = 0;
};
--- a/src/core/model/simulator.h Tue Jul 21 12:20:12 2015 -0700
+++ b/src/core/model/simulator.h Tue Jul 21 16:20:17 2015 -0700
@@ -32,8 +32,8 @@
#include <string>
/**
- * \file
- * \ingroup simulator
+ * @file
+ * @ingroup simulator
* ns3::Simulator declaration.
*/
@@ -43,14 +43,14 @@
class Scheduler;
/**
- * \ingroup core
- * \defgroup simulator Simulator
- * \brief Control the virtual time and the execution of simulation events.
+ * @ingroup core
+ * @defgroup simulator Simulator
+ * @brief Control the virtual time and the execution of simulation events.
*/
/**
- * \ingroup simulator
+ * @ingroup simulator
*
- * \brief Control the scheduling of simulation events.
+ * @brief Control the scheduling of simulation events.
*
* The internal simulation clock is maintained
* as a 64-bit integer in a unit specified by the user
@@ -63,15 +63,15 @@
*
* A simple example of how to use the Simulator class to schedule events
* is shown in sample-simulator.cc:
- * \include src/core/examples/sample-simulator.cc
+ * @include src/core/examples/sample-simulator.cc
*
- * \todo Define what the simulation or event context means.
+ * @todo Define what the simulation or event context means.
*/
class Simulator
{
public:
/**
- * \param impl A new simulator implementation.
+ * @param impl A new simulator implementation.
*
* The simulator provides a mechanism to swap out different implementations.
* For example, the default implementation is a single-threaded simulator
@@ -85,9 +85,9 @@
static void SetImplementation (Ptr<SimulatorImpl> impl);
/**
- * \brief Get the SimulatorImpl singleton.
+ * @brief Get the SimulatorImpl singleton.
*
- * \internal
+ * @internal
* If the SimulatorImpl singleton hasn't been created yet,
* this function does so. At the same time it also creates
* the Scheduler. Both of these respect the global values
@@ -99,12 +99,13 @@
* since we can't really do any logging until we have
* a SimulatorImpl and Scheduler.
- * \return The SimulatorImpl singleton.
+ * @return The SimulatorImpl singleton.
*/
static Ptr<SimulatorImpl> GetImplementation (void);
/**
- * \param schedulerFactory a new event scheduler factory
+ * @brief Set the scheduler type with an ObjectFactory.
+ * @param schedulerFactory The configured ObjectFactory.
*
* The event scheduler can be set at any time: the events scheduled
* in the previous scheduler will be transfered to the new scheduler
@@ -112,166 +113,277 @@
*/
static void SetScheduler (ObjectFactory schedulerFactory);
- /** \copydoc SimulatorImpl::Destroy */
+ /**
+ * Execute the events scheduled with ScheduleDestroy().
+ *
+ * This method is typically invoked at the end of a simulation
+ * to avoid false-positive reports by a leak checker.
+ * After this method has been invoked, it is actually possible
+ * to restart a new simulation with a set of calls to Simulator::Run,
+ * Simulator::Schedule and Simulator::ScheduleWithContext.
+ */
static void Destroy (void);
- /** \copydoc SimulatorImpl::IsFinished */
+ /**
+ * Check if the simulation should finish.
+ *
+ * Reasons to finish are because there are
+ * no more events lefts to be scheduled, or if simulation
+ * time has already reached the "stop time" (see Simulator::Stop()).
+ *
+ * @return @c true if no more events or stop time reached.
+ */
static bool IsFinished (void);
- /** \copydoc SimulatorImpl::Run */
+ /**
+ * Run the simulation.
+ *
+ * The simulation will run until one of:
+ * - No events are present anymore
+ * - The user called Simulator::Stop
+ * - The user called Simulator::Stop with a stop time and the
+ * expiration time of the next event to be processed
+ * is greater than or equal to the stop time.
+ */
static void Run (void);
- /** \copydoc SimulatorImpl::Stop(void) */
+ /**
+ * Tell the Simulator the calling event should be the last one
+ * executed.
+ *
+ * If a running event invokes this method, it will be the last
+ * event executed by the Simulator::Run method before
+ * returning to the caller.
+ */
static void Stop (void);
- /** \copydoc SimulatorImpl::Stop(Time const &) */
+ /**
+ * Schedule the time delay until the Simulator should stop.
+ *
+ * Force the Simulator::Run method to return to the caller when the
+ * expiration time of the next event to be processed is greater than
+ * or equal to the stop time. The stop time is relative to the
+ * current simulation time.
+ * @param delay The stop time, relative to the current time.
+ */
static void Stop (Time const &delay);
/**
- * \name Schedule events (in the same context) to run at a future time.
+ * @name Schedule events (in the same context) to run at a future time.
*/
/** @{ */
/**
- * Schedule an event to expire at the relative time "time"
- * is reached. This can be thought of as scheduling an event
- * for the current simulation time plus the Time passed as a
- * parameter
+ * Schedule an event to expire after @p delay.
+ * This can be thought of as scheduling an event
+ * for the current simulation time plus the @p delay passed as a
+ * parameter.
*
* When the event expires (when it becomes due to be run), the
* input method will be invoked on the input object.
*
- * @param time the relative expiration time of the event.
- * @param mem_ptr member method pointer to invoke
- * @param obj the object on which to invoke the member method
- * @returns an id for the scheduled event.
+ * @tparam MEM @inferred Class method function signature type.
+ * @tparam OBJ @inferred Class type of the object.
+ * @param delay The relative expiration time of the event.
+ * @param mem_ptr Member method pointer to invoke
+ * @param obj The object on which to invoke the member method
+ * @returns The id for the scheduled event.
*/
template <typename MEM, typename OBJ>
static EventId Schedule (Time const &delay, MEM mem_ptr, OBJ obj);
/**
- * @param time the relative expiration time of the event.
- * @param mem_ptr member method pointer to invoke
- * @param obj the object on which to invoke the member method
- * @param a1 the first argument to pass to the invoked method
- * @returns an id for the scheduled event.
+ * @see Schedule(const Time&,MEM,OBJ)
+ * @tparam MEM @inferred Class method function signature type.
+ * @tparam OBJ @inferred Class type of the object.
+ * @tparam T1 @inferred Type of first argument.
+ * @param delay The relative expiration time of the event.
+ * @param mem_ptr Member method pointer to invoke
+ * @param obj The object on which to invoke the member method
+ * @param a1 The first argument to pass to the invoked method
+ * @returns The id for the scheduled event.
*/
template <typename MEM, typename OBJ, typename T1>
static EventId Schedule (Time const &delay, MEM mem_ptr, OBJ obj, T1 a1);
/**
- * @param time the relative expiration time of the event.
- * @param mem_ptr member method pointer to invoke
- * @param obj the object on which to invoke the member method
- * @param a1 the first argument to pass to the invoked method
- * @param a2 the second argument to pass to the invoked method
- * @returns an id for the scheduled event.
+ * @see Schedule(const Time&,MEM,OBJ)
+ * @tparam MEM @inferred Class method function signature type.
+ * @tparam OBJ @inferred Class type of the object.
+ * @tparam T1 @inferred Type of first argument.
+ * @tparam T2 @inferred Type of second argument.
+ * @param delay The relative expiration time of the event.
+ * @param mem_ptr Member method pointer to invoke
+ * @param obj The object on which to invoke the member method
+ * @param a1 The first argument to pass to the invoked method
+ * @param a2 The second argument to pass to the invoked method
+ * @returns The id for the scheduled event.
*/
template <typename MEM, typename OBJ, typename T1, typename T2>
static EventId Schedule (Time const &delay, MEM mem_ptr, OBJ obj, T1 a1, T2 a2);
/**
- * @param time the relative expiration time of the event.
- * @param mem_ptr member method pointer to invoke
- * @param obj the object on which to invoke the member method
- * @param a1 the first argument to pass to the invoked method
- * @param a2 the second argument to pass to the invoked method
- * @param a3 the third argument to pass to the invoked method
- * @returns an id for the scheduled event.
+ * @see Schedule(const Time&,MEM,OBJ)
+ * @tparam MEM @inferred Class method function signature type.
+ * @tparam OBJ @inferred Class type of the object.
+ * @tparam T1 @inferred Type of first argument.
+ * @tparam T2 @inferred Type of second argument.
+ * @tparam T3 @inferred Type of third argument.
+ * @param delay The relative expiration time of the event.
+ * @param mem_ptr Member method pointer to invoke
+ * @param obj The object on which to invoke the member method
+ * @param a1 The first argument to pass to the invoked method
+ * @param a2 The second argument to pass to the invoked method
+ * @param a3 The third argument to pass to the invoked method
+ * @returns The id for the scheduled event.
*/
template <typename MEM, typename OBJ,
typename T1, typename T2, typename T3>
static EventId Schedule (Time const &delay, MEM mem_ptr, OBJ obj, T1 a1, T2 a2, T3 a3);
/**
- * @param time the relative expiration time of the event.
- * @param mem_ptr member method pointer to invoke
- * @param obj the object on which to invoke the member method
- * @param a1 the first argument to pass to the invoked method
- * @param a2 the second argument to pass to the invoked method
- * @param a3 the third argument to pass to the invoked method
- * @param a4 the fourth argument to pass to the invoked method
- * @returns an id for the scheduled event.
+ * @see Schedule(const Time&,MEM,OBJ)
+ * @tparam MEM @inferred Class method function signature type.
+ * @tparam OBJ @inferred Class type of the object.
+ * @tparam T1 @inferred Type of first argument.
+ * @tparam T2 @inferred Type of second argument.
+ * @tparam T3 @inferred Type of third argument.
+ * @tparam T4 @inferred Type of fourth argument.
+ * @param delay The relative expiration time of the event.
+ * @param mem_ptr Member method pointer to invoke
+ * @param obj The object on which to invoke the member method
+ * @param a1 The first argument to pass to the invoked method
+ * @param a2 The second argument to pass to the invoked method
+ * @param a3 The third argument to pass to the invoked method
+ * @param a4 The fourth argument to pass to the invoked method
+ * @returns The id for the scheduled event.
*/
template <typename MEM, typename OBJ,
typename T1, typename T2, typename T3, typename T4>
static EventId Schedule (Time const &delay, MEM mem_ptr, OBJ obj, T1 a1, T2 a2, T3 a3, T4 a4);
/**
- * @param time the relative expiration time of the event.
- * @param mem_ptr member method pointer to invoke
- * @param obj the object on which to invoke the member method
- * @param a1 the first argument to pass to the invoked method
- * @param a2 the second argument to pass to the invoked method
- * @param a3 the third argument to pass to the invoked method
- * @param a4 the fourth argument to pass to the invoked method
- * @param a5 the fifth argument to pass to the invoked method
- * @returns an id for the scheduled event.
+ * @see Schedule(const Time&,MEM,OBJ)
+ * @tparam MEM @inferred Class method function signature type.
+ * @tparam OBJ @inferred Class type of the object.
+ * @tparam T1 @inferred Type of first argument.
+ * @tparam T2 @inferred Type of second argument.
+ * @tparam T3 @inferred Type of third argument.
+ * @tparam T4 @inferred Type of fourth argument.
+ * @tparam T5 @inferred Type of fifth argument.
+ * @param delay The relative expiration time of the event.
+ * @param mem_ptr Member method pointer to invoke
+ * @param obj The object on which to invoke the member method
+ * @param a1 The first argument to pass to the invoked method
+ * @param a2 The second argument to pass to the invoked method
+ * @param a3 The third argument to pass to the invoked method
+ * @param a4 The fourth argument to pass to the invoked method
+ * @param a5 The fifth argument to pass to the invoked method
+ * @returns The id for the scheduled event.
*/
template <typename MEM, typename OBJ,
typename T1, typename T2, typename T3, typename T4, typename T5>
static EventId Schedule (Time const &delay, MEM mem_ptr, OBJ obj,
T1 a1, T2 a2, T3 a3, T4 a4, T5 a5);
/**
- * @param time the relative expiration time of the event.
- * @param f the function to invoke
- * @returns an id for the scheduled event.
+ * @copybrief Schedule(const Time&,MEM,OBJ)
+ *
+ * When the event expires (when it becomes due to be run), the
+ * function will be invoked with any supplied arguments.
+ * @param delay The relative expiration time of the event.
+ * @param f The function to invoke
+ * @returns The id for the scheduled event.
*/
static EventId Schedule (Time const &delay, void (*f)(void));
/**
- * @param time the relative expiration time of the event.
- * @param f the function to invoke
- * @param a1 the first argument to pass to the function to invoke
- * @returns an id for the scheduled event.
+ * @see Schedule(const Time&,(*)())
+ * @tparam U1 @inferred Formal type of the first argument to the function.
+ * @tparam T1 @inferred Actual type of the first argument.
+ * @param delay The relative expiration time of the event.
+ * @param f The function to invoke
+ * @param a1 The first argument to pass to the function to invoke.
+ * @returns The id for the scheduled event.
*/
template <typename U1, typename T1>
static EventId Schedule (Time const &delay, void (*f)(U1), T1 a1);
/**
- * @param time the relative expiration time of the event.
- * @param f the function to invoke
- * @param a1 the first argument to pass to the function to invoke
- * @param a2 the second argument to pass to the function to invoke
- * @returns an id for the scheduled event.
+ * @see Schedule(const Time&,(*)())
+ * @tparam U1 @inferred Formal type of the first argument to the function.
+ * @tparam U2 @inferred Formal type of the second argument to the function.
+ * @tparam T1 @inferred Actual type of the first argument.
+ * @tparam T2 @inferred Actual type of the second argument.
+ * @param delay The relative expiration time of the event.
+ * @param f The function to invoke
+ * @param a1 The first argument to pass to the function to invoke
+ * @param a2 The second argument to pass to the function to invoke
+ * @returns The id for the scheduled event.
*/
template <typename U1, typename U2,
typename T1, typename T2>
static EventId Schedule (Time const &delay, void (*f)(U1,U2), T1 a1, T2 a2);
/**
- * @param time the relative expiration time of the event.
- * @param f the function to invoke
- * @param a1 the first argument to pass to the function to invoke
- * @param a2 the second argument to pass to the function to invoke
- * @param a3 the third argument to pass to the function to invoke
- * @returns an id for the scheduled event.
+ * @see Schedule(const Time&,void(*)())
+ * @tparam U1 @inferred Formal type of the first argument to the function.
+ * @tparam U2 @inferred Formal type of the second argument to the function.
+ * @tparam U3 @inferred Formal type of the third argument to the function.
+ * @tparam T1 @inferred Actual type of the first argument.
+ * @tparam T2 @inferred Actual type of the second argument.
+ * @tparam T3 @inferred Actual type of the third argument.
+ * @param delay The relative expiration time of the event.
+ * @param f The function to invoke
+ * @param a1 The first argument to pass to the function to invoke
+ * @param a2 The second argument to pass to the function to invoke
+ * @param a3 The third argument to pass to the function to invoke
+ * @returns The id for the scheduled event.
*/
template <typename U1, typename U2, typename U3,
typename T1, typename T2, typename T3>
static EventId Schedule (Time const &delay, void (*f)(U1,U2,U3), T1 a1, T2 a2, T3 a3);
/**
- * @param time the relative expiration time of the event.
- * @param f the function to invoke
- * @param a1 the first argument to pass to the function to invoke
- * @param a2 the second argument to pass to the function to invoke
- * @param a3 the third argument to pass to the function to invoke
- * @param a4 the fourth argument to pass to the function to invoke
- * @returns an id for the scheduled event.
+ * @see Schedule(const Time&,(*)(void))
+ * @tparam U1 @inferred Formal type of the first argument to the function.
+ * @tparam U2 @inferred Formal type of the second argument to the function.
+ * @tparam U3 @inferred Formal type of the third argument to the function.
+ * @tparam U4 @inferred Formal type of the fourth argument to the function.
+ * @tparam T1 @inferred Actual type of the first argument.
+ * @tparam T2 @inferred Actual type of the second argument.
+ * @tparam T3 @inferred Actual type of the third argument.
+ * @tparam T4 @inferred Actual type of the fourth argument.
+ * @param delay The relative expiration time of the event.
+ * @param f The function to invoke
+ * @param a1 The first argument to pass to the function to invoke
+ * @param a2 The second argument to pass to the function to invoke
+ * @param a3 The third argument to pass to the function to invoke
+ * @param a4 The fourth argument to pass to the function to invoke
+ * @returns The id for the scheduled event.
*/
template <typename U1, typename U2, typename U3, typename U4,
typename T1, typename T2, typename T3, typename T4>
static EventId Schedule (Time const &delay, void (*f)(U1,U2,U3,U4), T1 a1, T2 a2, T3 a3, T4 a4);
/**
- * @param time the relative expiration time of the event.
- * @param f the function to invoke
- * @param a1 the first argument to pass to the function to invoke
- * @param a2 the second argument to pass to the function to invoke
- * @param a3 the third argument to pass to the function to invoke
- * @param a4 the fourth argument to pass to the function to invoke
- * @param a5 the fifth argument to pass to the function to invoke
- * @returns an id for the scheduled event.
+ * @see Schedule(const Time&,void(*)(void))
+ * @tparam U1 @inferred Formal type of the first argument to the function.
+ * @tparam U2 @inferred Formal type of the second argument to the function.
+ * @tparam U3 @inferred Formal type of the third argument to the function.
+ * @tparam U4 @inferred Formal type of the fourth argument to the function.
+ * @tparam U5 @inferred Formal type of the fifth argument to the function.
+ * @tparam T1 @inferred Actual type of the first argument.
+ * @tparam T2 @inferred Actual type of the second argument.
+ * @tparam T3 @inferred Actual type of the third argument.
+ * @tparam T4 @inferred Actual type of the fourth argument.
+ * @tparam T5 @inferred Actual type of the fifth argument.
+ * @param delay The relative expiration time of the event.
+ * @param f The function to invoke
+ * @param a1 The first argument to pass to the function to invoke
+ * @param a2 The second argument to pass to the function to invoke
+ * @param a3 The third argument to pass to the function to invoke
+ * @param a4 The fourth argument to pass to the function to invoke
+ * @param a5 The fifth argument to pass to the function to invoke
+ * @returns The id for the scheduled event.
*/
template <typename U1, typename U2, typename U3, typename U4, typename U5,
typename T1, typename T2, typename T3, typename T4, typename T5>
@@ -280,9 +392,9 @@
/** @} */
/**
- * \name Schedule events (in a different context) to run at a particular time.
+ * @name Schedule events (in a different context) to run now or at a future time.
*
- * See \ref main-test-sync.cc for example usage.
+ * See @ref main-test-sync.cc for example usage.
*/
/** @{ */
/**
@@ -290,161 +402,213 @@
* A context of 0xffffffff means no context is specified.
* This method is thread-safe: it can be called from any thread.
*
- * @param time the relative expiration time of the event.
- * @param context user-specified context parameter
- * @param mem_ptr member method pointer to invoke
- * @param obj the object on which to invoke the member method
+ * @see Schedule(const Time&,MEM,OBJ)
+ * @tparam MEM @inferred Class method function signature type.
+ * @tparam OBJ @inferred Class type of the object.
+ * @param context User-specified context parameter
+ * @param delay The relative expiration time of the event.
+ * @param mem_ptr Member method pointer to invoke
+ * @param obj The object on which to invoke the member method
*/
template <typename MEM, typename OBJ>
static void ScheduleWithContext (uint32_t context, Time const &delay, MEM mem_ptr, OBJ obj);
/**
- * This method is thread-safe: it can be called from any thread.
- *
- * @param time the relative expiration time of the event.
- * @param context user-specified context parameter
- * @param mem_ptr member method pointer to invoke
- * @param obj the object on which to invoke the member method
- * @param a1 the first argument to pass to the invoked method
+ * @see ScheduleWithContext(uint32_t,const Time&,MEM,OBJ)
+ * @tparam MEM @inferred Class method function signature type.
+ * @tparam OBJ @inferred Class type of the object.
+ * @tparam T1 @inferred Type of first argument.
+ * @param context User-specified context parameter
+ * @param delay The relative expiration time of the event.
+ * @param mem_ptr Member method pointer to invoke
+ * @param obj The object on which to invoke the member method
+ * @param a1 The first argument to pass to the invoked method
*/
template <typename MEM, typename OBJ, typename T1>
static void ScheduleWithContext (uint32_t context, Time const &delay, MEM mem_ptr, OBJ obj, T1 a1);
/**
- * This method is thread-safe: it can be called from any thread.
- *
- * @param time the relative expiration time of the event.
- * @param context user-specified context parameter
- * @param mem_ptr member method pointer to invoke
- * @param obj the object on which to invoke the member method
- * @param a1 the first argument to pass to the invoked method
- * @param a2 the second argument to pass to the invoked method
+ * @see ScheduleWithContext(uint32_t,const Time&,MEM,OBJ)
+ * @tparam MEM @inferred Class method function signature type.
+ * @tparam OBJ @inferred Class type of the object.
+ * @tparam T1 @inferred Type of first argument.
+ * @tparam T2 @inferred Type of second argument.
+ * @param context User-specified context parameter
+ * @param delay The relative expiration time of the event.
+ * @param mem_ptr Member method pointer to invoke
+ * @param obj The object on which to invoke the member method
+ * @param a1 The first argument to pass to the invoked method
+ * @param a2 The second argument to pass to the invoked method
*/
template <typename MEM, typename OBJ, typename T1, typename T2>
static void ScheduleWithContext (uint32_t context, Time const &delay, MEM mem_ptr, OBJ obj, T1 a1, T2 a2);
/**
- * This method is thread-safe: it can be called from any thread.
- *
- * @param time the relative expiration time of the event.
- * @param context user-specified context parameter
- * @param mem_ptr member method pointer to invoke
- * @param obj the object on which to invoke the member method
- * @param a1 the first argument to pass to the invoked method
- * @param a2 the second argument to pass to the invoked method
- * @param a3 the third argument to pass to the invoked method
+ * @see ScheduleWithContext(uint32_t,const Time&,MEM,OBJ)
+ * @tparam MEM @inferred Class method function signature type.
+ * @tparam OBJ @inferred Class type of the object.
+ * @tparam T1 @inferred Type of first argument.
+ * @tparam T2 @inferred Type of second argument.
+ * @tparam T3 @inferred Type of third argument.
+ * @param context User-specified context parameter
+ * @param delay The relative expiration time of the event.
+ * @param mem_ptr Member method pointer to invoke
+ * @param obj The object on which to invoke the member method
+ * @param a1 The first argument to pass to the invoked method
+ * @param a2 The second argument to pass to the invoked method
+ * @param a3 The third argument to pass to the invoked method
*/
template <typename MEM, typename OBJ,
typename T1, typename T2, typename T3>
static void ScheduleWithContext (uint32_t context, Time const &delay, MEM mem_ptr, OBJ obj, T1 a1, T2 a2, T3 a3);
/**
- * This method is thread-safe: it can be called from any thread.
- *
- * @param time the relative expiration time of the event.
- * @param context user-specified context parameter
- * @param mem_ptr member method pointer to invoke
- * @param obj the object on which to invoke the member method
- * @param a1 the first argument to pass to the invoked method
- * @param a2 the second argument to pass to the invoked method
- * @param a3 the third argument to pass to the invoked method
- * @param a4 the fourth argument to pass to the invoked method
+ * @see ScheduleWithContext(uint32_t,const Time&,MEM,OBJ)
+ * @tparam MEM @inferred Class method function signature type.
+ * @tparam OBJ @inferred Class type of the object.
+ * @tparam T1 @inferred Type of first argument.
+ * @tparam T2 @inferred Type of second argument.
+ * @tparam T3 @inferred Type of third argument.
+ * @tparam T4 @inferred Type of fourth argument.
+ * @param context User-specified context parameter
+ * @param delay The relative expiration time of the event.
+ * @param mem_ptr Member method pointer to invoke
+ * @param obj The object on which to invoke the member method
+ * @param a1 The first argument to pass to the invoked method
+ * @param a2 The second argument to pass to the invoked method
+ * @param a3 The third argument to pass to the invoked method
+ * @param a4 The fourth argument to pass to the invoked method
*/
template <typename MEM, typename OBJ,
typename T1, typename T2, typename T3, typename T4>
static void ScheduleWithContext (uint32_t context, Time const &delay, MEM mem_ptr, OBJ obj, T1 a1, T2 a2, T3 a3, T4 a4);
/**
- * This method is thread-safe: it can be called from any thread.
- *
- * @param time the relative expiration time of the event.
- * @param context user-specified context parameter
- * @param mem_ptr member method pointer to invoke
- * @param obj the object on which to invoke the member method
- * @param a1 the first argument to pass to the invoked method
- * @param a2 the second argument to pass to the invoked method
- * @param a3 the third argument to pass to the invoked method
- * @param a4 the fourth argument to pass to the invoked method
- * @param a5 the fifth argument to pass to the invoked method
+ * @see ScheduleWithContext(uint32_t,const Time&,MEM,OBJ)
+ * @tparam MEM @inferred Class method function signature type.
+ * @tparam OBJ @inferred Class type of the object.
+ * @tparam T1 @inferred Type of first argument.
+ * @tparam T2 @inferred Type of second argument.
+ * @tparam T3 @inferred Type of third argument.
+ * @tparam T4 @inferred Type of fourth argument.
+ * @tparam T5 @inferred Type of fifth argument.
+ * @param context User-specified context parameter
+ * @param delay The relative expiration time of the event.
+ * @param mem_ptr Member method pointer to invoke
+ * @param obj The object on which to invoke the member method
+ * @param a1 The first argument to pass to the invoked method
+ * @param a2 The second argument to pass to the invoked method
+ * @param a3 The third argument to pass to the invoked method
+ * @param a4 The fourth argument to pass to the invoked method
+ * @param a5 The fifth argument to pass to the invoked method
*/
template <typename MEM, typename OBJ,
typename T1, typename T2, typename T3, typename T4, typename T5>
static void ScheduleWithContext (uint32_t context, Time const &delay, MEM mem_ptr, OBJ obj,
T1 a1, T2 a2, T3 a3, T4 a4, T5 a5);
/**
- * This method is thread-safe: it can be called from any thread.
+ * @copybrief ScheduleWithContext(uint32_t,const Time&,MEM,OBJ)
+ *
+ * When the event expires (when it becomes due to be run), the
+ * function will be invoked with any supplied arguments.
*
- * @param time the relative expiration time of the event.
- * @param context user-specified context parameter
- * @param f the function to invoke
+ * This method is thread-safe: it can be called from any thread.
+ * @param context User-specified context parameter
+ * @param delay The relative expiration time of the event.
+ * @param f The function to invoke
*/
static void ScheduleWithContext (uint32_t context, Time const &delay, void (*f)(void));
/**
- * This method is thread-safe: it can be called from any thread.
- *
- * @param time the relative expiration time of the event.
- * @param context user-specified context parameter
- * @param f the function to invoke
- * @param a1 the first argument to pass to the function to invoke
+ * @see ScheduleWithContext(uint32_t,const Time&,(*)())
+ * @tparam U1 @inferred Formal type of the first argument to the function.
+ * @tparam T1 @inferred Actual type of the first argument.
+ * @param context User-specified context parameter
+ * @param delay The relative expiration time of the event.
+ * @param f The function to invoke
+ * @param a1 The first argument to pass to the function to invoke
*/
template <typename U1,
typename T1>
static void ScheduleWithContext (uint32_t context, Time const &delay, void (*f)(U1), T1 a1);
/**
- * This method is thread-safe: it can be called from any thread.
- *
- * @param time the relative expiration time of the event.
- * @param context user-specified context parameter
- * @param f the function to invoke
- * @param a1 the first argument to pass to the function to invoke
- * @param a2 the second argument to pass to the function to invoke
+ * @see ScheduleWithContext(uint32_t,const Time&,(*)())
+ * @tparam U1 @inferred Formal type of the first argument to the function.
+ * @tparam U2 @inferred Formal type of the second argument to the function.
+ * @tparam T1 @inferred Actual type of the first argument.
+ * @tparam T2 @inferred Actual type of the second argument.
+ * @param context User-specified context parameter
+ * @param delay The relative expiration time of the event.
+ * @param f The function to invoke
+ * @param a1 The first argument to pass to the function to invoke
+ * @param a2 The second argument to pass to the function to invoke
*/
template <typename U1, typename U2,
typename T1, typename T2>
static void ScheduleWithContext (uint32_t context, Time const &delay, void (*f)(U1,U2), T1 a1, T2 a2);
/**
- * This method is thread-safe: it can be called from any thread.
- *
- * @param time the relative expiration time of the event.
- * @param context user-specified context parameter
- * @param f the function to invoke
- * @param a1 the first argument to pass to the function to invoke
- * @param a2 the second argument to pass to the function to invoke
- * @param a3 the third argument to pass to the function to invoke
+ * @see ScheduleWithContext(uint32_t,const Time&,(*)())
+ * @tparam U1 @inferred Formal type of the first argument to the function.
+ * @tparam U2 @inferred Formal type of the second argument to the function.
+ * @tparam U3 @inferred Formal type of the third argument to the function.
+ * @tparam T1 @inferred Actual type of the first argument.
+ * @tparam T2 @inferred Actual type of the second argument.
+ * @tparam T3 @inferred Actual type of the third argument.
+ * @param context User-specified context parameter
+ * @param delay The relative expiration time of the event.
+ * @param f The function to invoke
+ * @param a1 The first argument to pass to the function to invoke
+ * @param a2 The second argument to pass to the function to invoke
+ * @param a3 The third argument to pass to the function to invoke
*/
template <typename U1, typename U2, typename U3,
typename T1, typename T2, typename T3>
static void ScheduleWithContext (uint32_t context, Time const &delay, void (*f)(U1,U2,U3), T1 a1, T2 a2, T3 a3);
/**
- * This method is thread-safe: it can be called from any thread.
- *
- * @param time the relative expiration time of the event.
- * @param context user-specified context parameter
- * @param f the function to invoke
- * @param a1 the first argument to pass to the function to invoke
- * @param a2 the second argument to pass to the function to invoke
- * @param a3 the third argument to pass to the function to invoke
- * @param a4 the fourth argument to pass to the function to invoke
+ * @see ScheduleWithContext(uint32_t,const Time&,(*)())
+ * @tparam U1 @inferred Formal type of the first argument to the function.
+ * @tparam U2 @inferred Formal type of the second argument to the function.
+ * @tparam U3 @inferred Formal type of the third argument to the function.
+ * @tparam U4 @inferred Formal type of the fourth argument to the function.
+ * @tparam T1 @inferred Actual type of the first argument.
+ * @tparam T2 @inferred Actual type of the second argument.
+ * @tparam T3 @inferred Actual type of the third argument.
+ * @tparam T4 @inferred Actual type of the fourth argument.
+ * @param context User-specified context parameter
+ * @param delay The relative expiration time of the event.
+ * @param f The function to invoke
+ * @param a1 The first argument to pass to the function to invoke
+ * @param a2 The second argument to pass to the function to invoke
+ * @param a3 The third argument to pass to the function to invoke
+ * @param a4 The fourth argument to pass to the function to invoke
*/
template <typename U1, typename U2, typename U3, typename U4,
typename T1, typename T2, typename T3, typename T4>
static void ScheduleWithContext (uint32_t context, Time const &delay, void (*f)(U1,U2,U3,U4), T1 a1, T2 a2, T3 a3, T4 a4);
/**
- * This method is thread-safe: it can be called from any thread.
- *
- * @param time the relative expiration time of the event.
- * @param context user-specified context parameter
- * @param f the function to invoke
- * @param a1 the first argument to pass to the function to invoke
- * @param a2 the second argument to pass to the function to invoke
- * @param a3 the third argument to pass to the function to invoke
- * @param a4 the fourth argument to pass to the function to invoke
- * @param a5 the fifth argument to pass to the function to invoke
+ * @see ScheduleWithContext(uint32_t,const Time&,(*)())
+ * @tparam U1 @inferred Formal type of the first argument to the function.
+ * @tparam U2 @inferred Formal type of the second argument to the function.
+ * @tparam U3 @inferred Formal type of the third argument to the function.
+ * @tparam U4 @inferred Formal type of the fourth argument to the function.
+ * @tparam U5 @inferred Formal type of the fifth argument to the function.
+ * @tparam T1 @inferred Actual type of the first argument.
+ * @tparam T2 @inferred Actual type of the second argument.
+ * @tparam T3 @inferred Actual type of the third argument.
+ * @tparam T4 @inferred Actual type of the fourth argument.
+ * @tparam T5 @inferred Actual type of the fifth argument.
+ * @param context User-specified context parameter
+ * @param delay The relative expiration time of the event.
+ * @param f The function to invoke
+ * @param a1 The first argument to pass to the function to invoke
+ * @param a2 The second argument to pass to the function to invoke
+ * @param a3 The third argument to pass to the function to invoke
+ * @param a4 The fourth argument to pass to the function to invoke
+ * @param a5 The fifth argument to pass to the function to invoke
*/
template <typename U1, typename U2, typename U3, typename U4, typename U5,
typename T1, typename T2, typename T3, typename T4, typename T5>
@@ -461,17 +625,23 @@
* to expire "Now" are scheduled FIFO, after all normal events
* have expired.
*
- * @param mem_ptr member method pointer to invoke
- * @param obj the object on which to invoke the member method
+ * @tparam MEM @inferred Class method function signature type.
+ * @tparam OBJ @inferred Class type of the object.
+ * @param mem_ptr Member method pointer to invoke
+ * @param obj The object on which to invoke the member method
* @return The EventId of the scheduled event.
*/
template <typename MEM, typename OBJ>
static EventId ScheduleNow (MEM mem_ptr, OBJ obj);
/**
- * @param mem_ptr member method pointer to invoke
- * @param obj the object on which to invoke the member method
- * @param a1 the first argument to pass to the invoked method
+ * @see ScheduleNow(MEM,OBJ)
+ * @tparam MEM @inferred Class method function signature type.
+ * @tparam OBJ @inferred Class type of the object.
+ * @tparam T1 @inferred Type of first argument.
+ * @param mem_ptr Member method pointer to invoke
+ * @param obj The object on which to invoke the member method
+ * @param a1 The first argument to pass to the invoked method
* @return The EventId of the scheduled event.
*/
template <typename MEM, typename OBJ,
@@ -479,10 +649,15 @@
static EventId ScheduleNow (MEM mem_ptr, OBJ obj, T1 a1);
/**
- * @param mem_ptr member method pointer to invoke
- * @param obj the object on which to invoke the member method
- * @param a1 the first argument to pass to the invoked method
- * @param a2 the second argument to pass to the invoked method
+ * @see ScheduleNow(MEM,OBJ)
+ * @tparam MEM @inferred Class method function signature type.
+ * @tparam OBJ @inferred Class type of the object.
+ * @tparam T1 @inferred Type of first argument.
+ * @tparam T2 @inferred Type of second argument.
+ * @param mem_ptr Member method pointer to invoke
+ * @param obj The object on which to invoke the member method
+ * @param a1 The first argument to pass to the invoked method
+ * @param a2 The second argument to pass to the invoked method
* @return The EventId of the scheduled event.
*/
template <typename MEM, typename OBJ,
@@ -490,11 +665,17 @@
static EventId ScheduleNow (MEM mem_ptr, OBJ obj, T1 a1, T2 a2);
/**
- * @param mem_ptr member method pointer to invoke
- * @param obj the object on which to invoke the member method
- * @param a1 the first argument to pass to the invoked method
- * @param a2 the second argument to pass to the invoked method
- * @param a3 the third argument to pass to the invoked method
+ * @see ScheduleNow(MEM,OBJ)
+ * @tparam MEM @inferred Class method function signature type.
+ * @tparam OBJ @inferred Class type of the object.
+ * @tparam T1 @inferred Type of first argument.
+ * @tparam T2 @inferred Type of second argument.
+ * @tparam T3 @inferred Type of third argument.
+ * @param mem_ptr Member method pointer to invoke
+ * @param obj The object on which to invoke the member method
+ * @param a1 The first argument to pass to the invoked method
+ * @param a2 The second argument to pass to the invoked method
+ * @param a3 The third argument to pass to the invoked method
* @return The EventId of the scheduled event.
*/
template <typename MEM, typename OBJ,
@@ -502,12 +683,19 @@
static EventId ScheduleNow (MEM mem_ptr, OBJ obj, T1 a1, T2 a2, T3 a3);
/**
- * @param mem_ptr member method pointer to invoke
- * @param obj the object on which to invoke the member method
- * @param a1 the first argument to pass to the invoked method
- * @param a2 the second argument to pass to the invoked method
- * @param a3 the third argument to pass to the invoked method
- * @param a4 the fourth argument to pass to the invoked method
+ * @see ScheduleNow(MEM,OBJ)
+ * @tparam MEM @inferred Class method function signature type.
+ * @tparam OBJ @inferred Class type of the object.
+ * @tparam T1 @inferred Type of first argument.
+ * @tparam T2 @inferred Type of second argument.
+ * @tparam T3 @inferred Type of third argument.
+ * @tparam T4 @inferred Type of fourth argument.
+ * @param mem_ptr Member method pointer to invoke
+ * @param obj The object on which to invoke the member method
+ * @param a1 The first argument to pass to the invoked method
+ * @param a2 The second argument to pass to the invoked method
+ * @param a3 The third argument to pass to the invoked method
+ * @param a4 The fourth argument to pass to the invoked method
* @return The EventId of the scheduled event.
*/
template <typename MEM, typename OBJ,
@@ -515,13 +703,21 @@
static EventId ScheduleNow (MEM mem_ptr, OBJ obj,
T1 a1, T2 a2, T3 a3, T4 a4);
/**
- * @param mem_ptr member method pointer to invoke
- * @param obj the object on which to invoke the member method
- * @param a1 the first argument to pass to the invoked method
- * @param a2 the second argument to pass to the invoked method
- * @param a3 the third argument to pass to the invoked method
- * @param a4 the fourth argument to pass to the invoked method
- * @param a5 the fifth argument to pass to the invoked method
+ * @see ScheduleNow(MEM,OBJ)
+ * @tparam MEM @inferred Class method function signature type.
+ * @tparam OBJ @inferred Class type of the object.
+ * @tparam T1 @inferred Type of first argument.
+ * @tparam T2 @inferred Type of second argument.
+ * @tparam T3 @inferred Type of third argument.
+ * @tparam T4 @inferred Type of fourth argument.
+ * @tparam T5 @inferred Type of fifth argument.
+ * @param mem_ptr Member method pointer to invoke
+ * @param obj The object on which to invoke the member method
+ * @param a1 The first argument to pass to the invoked method
+ * @param a2 The second argument to pass to the invoked method
+ * @param a3 The third argument to pass to the invoked method
+ * @param a4 The fourth argument to pass to the invoked method
+ * @param a5 The fifth argument to pass to the invoked method
* @return The EventId of the scheduled event.
*/
template <typename MEM, typename OBJ,
@@ -529,14 +725,21 @@
static EventId ScheduleNow (MEM mem_ptr, OBJ obj,
T1 a1, T2 a2, T3 a3, T4 a4, T5 a5);
/**
- * @param f the function to invoke
+ * @copybrief ScheduleNow(MEM,OBJ)
+ *
+ * When the event expires (when it becomes due to be run), the
+ * function will be invoked with any supplied arguments.
+ * @param f The function to invoke
* @return The EventId of the scheduled event.
*/
static EventId ScheduleNow (void (*f)(void));
/**
- * @param f the function to invoke
- * @param a1 the first argument to pass to the function to invoke
+ * @see ScheduleNow(*)
+ * @tparam U1 @inferred Formal type of the first argument to the function.
+ * @tparam T1 @inferred Actual type of the first argument.
+ * @param f The function to invoke
+ * @param a1 The first argument to pass to the function to invoke
* @return The EventId of the scheduled event.
*/
template <typename U1,
@@ -544,9 +747,14 @@
static EventId ScheduleNow (void (*f)(U1), T1 a1);
/**
- * @param f the function to invoke
- * @param a1 the first argument to pass to the function to invoke
- * @param a2 the second argument to pass to the function to invoke
+ * @see ScheduleNow(*)
+ * @tparam U1 @inferred Formal type of the first argument to the function.
+ * @tparam U2 @inferred Formal type of the second argument to the function.
+ * @tparam T1 @inferred Actual type of the first argument.
+ * @tparam T2 @inferred Actual type of the second argument.
+ * @param f The function to invoke
+ * @param a1 The first argument to pass to the function to invoke
+ * @param a2 The second argument to pass to the function to invoke
* @return The EventId of the scheduled event.
*/
template <typename U1, typename U2,
@@ -554,10 +762,17 @@
static EventId ScheduleNow (void (*f)(U1,U2), T1 a1, T2 a2);
/**
- * @param f the function to invoke
- * @param a1 the first argument to pass to the function to invoke
- * @param a2 the second argument to pass to the function to invoke
- * @param a3 the third argument to pass to the function to invoke
+ * @see ScheduleNow(*)
+ * @tparam U1 @inferred Formal type of the first argument to the function.
+ * @tparam U2 @inferred Formal type of the second argument to the function.
+ * @tparam U3 @inferred Formal type of the third argument to the function.
+ * @tparam T1 @inferred Actual type of the first argument.
+ * @tparam T2 @inferred Actual type of the second argument.
+ * @tparam T3 @inferred Actual type of the third argument.
+ * @param f The function to invoke
+ * @param a1 The first argument to pass to the function to invoke
+ * @param a2 The second argument to pass to the function to invoke
+ * @param a3 The third argument to pass to the function to invoke
* @return The EventId of the scheduled event.
*/
template <typename U1, typename U2, typename U3,
@@ -565,11 +780,20 @@
static EventId ScheduleNow (void (*f)(U1,U2,U3), T1 a1, T2 a2, T3 a3);
/**
- * @param f the function to invoke
- * @param a1 the first argument to pass to the function to invoke
- * @param a2 the second argument to pass to the function to invoke
- * @param a3 the third argument to pass to the function to invoke
- * @param a4 the fourth argument to pass to the function to invoke
+ * @see ScheduleNow(*)
+ * @tparam U1 @inferred Formal type of the first argument to the function.
+ * @tparam U2 @inferred Formal type of the second argument to the function.
+ * @tparam U3 @inferred Formal type of the third argument to the function.
+ * @tparam U4 @inferred Formal type of the fourth argument to the function.
+ * @tparam T1 @inferred Actual type of the first argument.
+ * @tparam T2 @inferred Actual type of the second argument.
+ * @tparam T3 @inferred Actual type of the third argument.
+ * @tparam T4 @inferred Actual type of the fourth argument.
+ * @param f The function to invoke
+ * @param a1 The first argument to pass to the function to invoke
+ * @param a2 The second argument to pass to the function to invoke
+ * @param a3 The third argument to pass to the function to invoke
+ * @param a4 The fourth argument to pass to the function to invoke
* @return The EventId of the scheduled event.
*/
template <typename U1, typename U2, typename U3, typename U4,
@@ -577,12 +801,23 @@
static EventId ScheduleNow (void (*f)(U1,U2,U3,U4), T1 a1, T2 a2, T3 a3, T4 a4);
/**
- * @param f the function to invoke
- * @param a1 the first argument to pass to the function to invoke
- * @param a2 the second argument to pass to the function to invoke
- * @param a3 the third argument to pass to the function to invoke
- * @param a4 the fourth argument to pass to the function to invoke
- * @param a5 the fifth argument to pass to the function to invoke
+ * @see ScheduleNow(*)
+ * @tparam U1 @inferred Formal type of the first argument to the function.
+ * @tparam U2 @inferred Formal type of the second argument to the function.
+ * @tparam U3 @inferred Formal type of the third argument to the function.
+ * @tparam U4 @inferred Formal type of the fourth argument to the function.
+ * @tparam U5 @inferred Formal type of the fifth argument to the function.
+ * @tparam T1 @inferred Actual type of the first argument.
+ * @tparam T2 @inferred Actual type of the second argument.
+ * @tparam T3 @inferred Actual type of the third argument.
+ * @tparam T4 @inferred Actual type of the fourth argument.
+ * @tparam T5 @inferred Actual type of the fifth argument.
+ * @param f The function to invoke
+ * @param a1 The first argument to pass to the function to invoke
+ * @param a2 The second argument to pass to the function to invoke
+ * @param a3 The third argument to pass to the function to invoke
+ * @param a4 The fourth argument to pass to the function to invoke
+ * @param a5 The fifth argument to pass to the function to invoke
* @return The EventId of the scheduled event.
*/
template <typename U1, typename U2, typename U3, typename U4, typename U5,
@@ -592,26 +827,32 @@
/** @} */
/**
- * \name Schedule events to run at the end of the simulation.
+ * @name Schedule events to run at the end of the simulation, when Simulator:Destroy() is called.
*/
/** @{ */
/**
- * Schedule an event to expire at Destroy time. All events
- * scheduled to expire at "Destroy" time are scheduled FIFO,
+ * Schedule an event to expire when Simulator::Destroy is called.
+ * All events scheduled to expire at "Destroy" time are scheduled FIFO,
* after all normal events have expired and only when
* Simulator::Destroy is invoked.
*
- * @param mem_ptr member method pointer to invoke
- * @param obj the object on which to invoke the member method
+ * @tparam MEM @inferred Class method function signature type.
+ * @tparam OBJ @inferred Class type of the object.
+ * @param mem_ptr Member method pointer to invoke
+ * @param obj The object on which to invoke the member method
* @return The EventId of the scheduled event.
*/
template <typename MEM, typename OBJ>
static EventId ScheduleDestroy (MEM mem_ptr, OBJ obj);
/**
- * @param mem_ptr member method pointer to invoke
- * @param obj the object on which to invoke the member method
- * @param a1 the first argument to pass to the invoked method
+ * @see ScheduleDestroy(MEM,OBJ)
+ * @tparam MEM @inferred Class method function signature type.
+ * @tparam OBJ @inferred Class type of the object.
+ * @tparam T1 @inferred Type of first argument.
+ * @param mem_ptr Member method pointer to invoke
+ * @param obj The object on which to invoke the member method
+ * @param a1 The first argument to pass to the invoked method
* @return The EventId of the scheduled event.
*/
template <typename MEM, typename OBJ,
@@ -619,10 +860,15 @@
static EventId ScheduleDestroy (MEM mem_ptr, OBJ obj, T1 a1);
/**
- * @param mem_ptr member method pointer to invoke
- * @param obj the object on which to invoke the member method
- * @param a1 the first argument to pass to the invoked method
- * @param a2 the second argument to pass to the invoked method
+ * @see ScheduleDestroy(MEM,OBJ)
+ * @tparam MEM @inferred Class method function signature type.
+ * @tparam OBJ @inferred Class type of the object.
+ * @tparam T1 @inferred Type of first argument.
+ * @tparam T2 @inferred Type of second argument.
+ * @param mem_ptr Member method pointer to invoke
+ * @param obj The object on which to invoke the member method
+ * @param a1 The first argument to pass to the invoked method
+ * @param a2 The second argument to pass to the invoked method
* @return The EventId of the scheduled event.
*/
template <typename MEM, typename OBJ,
@@ -630,11 +876,17 @@
static EventId ScheduleDestroy (MEM mem_ptr, OBJ obj, T1 a1, T2 a2);
/**
- * @param mem_ptr member method pointer to invoke
- * @param obj the object on which to invoke the member method
- * @param a1 the first argument to pass to the invoked method
- * @param a2 the second argument to pass to the invoked method
- * @param a3 the third argument to pass to the invoked method
+ * @see ScheduleDestroy(MEM,OBJ)
+ * @tparam MEM @inferred Class method function signature type.
+ * @tparam OBJ @inferred Class type of the object.
+ * @tparam T1 @inferred Type of first argument.
+ * @tparam T2 @inferred Type of second argument.
+ * @tparam T3 @inferred Type of third argument.
+ * @param mem_ptr Member method pointer to invoke
+ * @param obj The object on which to invoke the member method
+ * @param a1 The first argument to pass to the invoked method
+ * @param a2 The second argument to pass to the invoked method
+ * @param a3 The third argument to pass to the invoked method
* @return The EventId of the scheduled event.
*/
template <typename MEM, typename OBJ,
@@ -642,12 +894,19 @@
static EventId ScheduleDestroy (MEM mem_ptr, OBJ obj, T1 a1, T2 a2, T3 a3);
/**
- * @param mem_ptr member method pointer to invoke
- * @param obj the object on which to invoke the member method
- * @param a1 the first argument to pass to the invoked method
- * @param a2 the second argument to pass to the invoked method
- * @param a3 the third argument to pass to the invoked method
- * @param a4 the fourth argument to pass to the invoked method
+ * @see ScheduleDestroy(MEM,OBJ)
+ * @tparam MEM @inferred Class method function signature type.
+ * @tparam OBJ @inferred Class type of the object.
+ * @tparam T1 @inferred Type of first argument.
+ * @tparam T2 @inferred Type of second argument.
+ * @tparam T3 @inferred Type of third argument.
+ * @tparam T4 @inferred Type of fourth argument.
+ * @param mem_ptr Member method pointer to invoke
+ * @param obj The object on which to invoke the member method
+ * @param a1 The first argument to pass to the invoked method
+ * @param a2 The second argument to pass to the invoked method
+ * @param a3 The third argument to pass to the invoked method
+ * @param a4 The fourth argument to pass to the invoked method
* @return The EventId of the scheduled event.
*/
template <typename MEM, typename OBJ,
@@ -655,13 +914,21 @@
static EventId ScheduleDestroy (MEM mem_ptr, OBJ obj,
T1 a1, T2 a2, T3 a3, T4 a4);
/**
- * @param mem_ptr member method pointer to invoke
- * @param obj the object on which to invoke the member method
- * @param a1 the first argument to pass to the invoked method
- * @param a2 the second argument to pass to the invoked method
- * @param a3 the third argument to pass to the invoked method
- * @param a4 the fourth argument to pass to the invoked method
- * @param a5 the fifth argument to pass to the invoked method
+ * @see ScheduleDestroy(MEM,OBJ)
+ * @tparam MEM @inferred Class method function signature type.
+ * @tparam OBJ @inferred Class type of the object.
+ * @tparam T1 @inferred Type of first argument.
+ * @tparam T2 @inferred Type of second argument.
+ * @tparam T3 @inferred Type of third argument.
+ * @tparam T4 @inferred Type of fourth argument.
+ * @tparam T5 @inferred Type of fifth argument.
+ * @param mem_ptr Member method pointer to invoke
+ * @param obj The object on which to invoke the member method
+ * @param a1 The first argument to pass to the invoked method
+ * @param a2 The second argument to pass to the invoked method
+ * @param a3 The third argument to pass to the invoked method
+ * @param a4 The fourth argument to pass to the invoked method
+ * @param a5 The fifth argument to pass to the invoked method
* @return The EventId of the scheduled event.
*/
template <typename MEM, typename OBJ,
@@ -669,14 +936,20 @@
static EventId ScheduleDestroy (MEM mem_ptr, OBJ obj,
T1 a1, T2 a2, T3 a3, T4 a4, T5 a5);
/**
- * @param f the function to invoke
+ * @copybrief ScheduleDestroy(MEM,OBJ)
+ * When Simulator::Destroy() is called, the
+ * function will be invoked with any supplied arguments.
+ * @param f The function to invoke
* @return The EventId of the scheduled event.
*/
static EventId ScheduleDestroy (void (*f)(void));
/**
- * @param f the function to invoke
- * @param a1 the first argument to pass to the function to invoke
+ * @see ScheduleDestory((*)())
+ * @tparam U1 @inferred Formal type of the first argument to the function.
+ * @tparam T1 @inferred Actual type of the first argument.
+ * @param f The function to invoke
+ * @param a1 The first argument to pass to the function to invoke
* @return The EventId of the scheduled event.
*/
template <typename U1,
@@ -684,9 +957,14 @@
static EventId ScheduleDestroy (void (*f)(U1), T1 a1);
/**
- * @param f the function to invoke
- * @param a1 the first argument to pass to the function to invoke
- * @param a2 the second argument to pass to the function to invoke
+ * @see ScheduleDestory((*)())
+ * @tparam U1 @inferred Formal type of the first argument to the function.
+ * @tparam U2 @inferred Formal type of the second argument to the function.
+ * @tparam T1 @inferred Actual type of the first argument.
+ * @tparam T2 @inferred Actual type of the second argument.
+ * @param f The function to invoke
+ * @param a1 The first argument to pass to the function to invoke
+ * @param a2 The second argument to pass to the function to invoke
* @return The EventId of the scheduled event.
*/
template <typename U1, typename U2,
@@ -694,10 +972,17 @@
static EventId ScheduleDestroy (void (*f)(U1,U2), T1 a1, T2 a2);
/**
- * @param f the function to invoke
- * @param a1 the first argument to pass to the function to invoke
- * @param a2 the second argument to pass to the function to invoke
- * @param a3 the third argument to pass to the function to invoke
+ * @see ScheduleDestory((*)())
+ * @tparam U1 @inferred Formal type of the first argument to the function.
+ * @tparam U2 @inferred Formal type of the second argument to the function.
+ * @tparam U3 @inferred Formal type of the third argument to the function.
+ * @tparam T1 @inferred Actual type of the first argument.
+ * @tparam T2 @inferred Actual type of the second argument.
+ * @tparam T3 @inferred Actual type of the third argument.
+ * @param f The function to invoke
+ * @param a1 The first argument to pass to the function to invoke
+ * @param a2 The second argument to pass to the function to invoke
+ * @param a3 The third argument to pass to the function to invoke
* @return The EventId of the scheduled event.
*/
template <typename U1, typename U2, typename U3,
@@ -705,11 +990,20 @@
static EventId ScheduleDestroy (void (*f)(U1,U2,U3), T1 a1, T2 a2, T3 a3);
/**
- * @param f the function to invoke
- * @param a1 the first argument to pass to the function to invoke
- * @param a2 the second argument to pass to the function to invoke
- * @param a3 the third argument to pass to the function to invoke
- * @param a4 the fourth argument to pass to the function to invoke
+ * @see ScheduleDestory((*)())
+ * @tparam U1 @inferred Formal type of the first argument to the function.
+ * @tparam U2 @inferred Formal type of the second argument to the function.
+ * @tparam U3 @inferred Formal type of the third argument to the function.
+ * @tparam U4 @inferred Formal type of the fourth argument to the function.
+ * @tparam T1 @inferred Actual type of the first argument.
+ * @tparam T2 @inferred Actual type of the second argument.
+ * @tparam T3 @inferred Actual type of the third argument.
+ * @tparam T4 @inferred Actual type of the fourth argument.
+ * @param f The function to invoke
+ * @param a1 The first argument to pass to the function to invoke
+ * @param a2 The second argument to pass to the function to invoke
+ * @param a3 The third argument to pass to the function to invoke
+ * @param a4 The fourth argument to pass to the function to invoke
* @return The EventId of the scheduled event.
*/
template <typename U1, typename U2, typename U3, typename U4,
@@ -717,12 +1011,23 @@
static EventId ScheduleDestroy (void (*f)(U1,U2,U3,U4), T1 a1, T2 a2, T3 a3, T4 a4);
/**
- * @param f the function to invoke
- * @param a1 the first argument to pass to the function to invoke
- * @param a2 the second argument to pass to the function to invoke
- * @param a3 the third argument to pass to the function to invoke
- * @param a4 the fourth argument to pass to the function to invoke
- * @param a5 the fifth argument to pass to the function to invoke
+ * @see ScheduleDestory((*)())
+ * @tparam U1 @inferred Formal type of the first argument to the function.
+ * @tparam U2 @inferred Formal type of the second argument to the function.
+ * @tparam U3 @inferred Formal type of the third argument to the function.
+ * @tparam U4 @inferred Formal type of the fourth argument to the function.
+ * @tparam U5 @inferred Formal type of the fifth argument to the function.
+ * @tparam T1 @inferred Actual type of the first argument.
+ * @tparam T2 @inferred Actual type of the second argument.
+ * @tparam T3 @inferred Actual type of the third argument.
+ * @tparam T4 @inferred Actual type of the fourth argument.
+ * @tparam T5 @inferred Actual type of the fifth argument.
+ * @param f The function to invoke
+ * @param a1 The first argument to pass to the function to invoke
+ * @param a2 The second argument to pass to the function to invoke
+ * @param a3 The third argument to pass to the function to invoke
+ * @param a4 The fourth argument to pass to the function to invoke
+ * @param a5 The fifth argument to pass to the function to invoke
* @return The EventId of the scheduled event.
*/
template <typename U1, typename U2, typename U3, typename U4, typename U5,
@@ -731,42 +1036,129 @@
/** @} */
- /** \copydoc SimulatorImpl::Remove */
+ /**
+ * Remove an event from the event list.
+ *
+ * This method has the same visible effect as the
+ * ns3::EventId::Cancel method
+ * but its algorithmic complexity is much higher: it has often
+ * O(log(n)) complexity, sometimes O(n), sometimes worse.
+ * Note that it is not possible to remove events which were scheduled
+ * for the "destroy" time. Doing so will result in a program error (crash).
+ *
+ * @param id The event to remove from the list of scheduled events.
+ */
static void Remove (const EventId &id);
- /** \copydoc SimulatorImpl::Cancel */
+ /**
+ * Set the cancel bit on this event: the event's associated function
+ * will not be invoked when it expires.
+ *
+ * This method has the same visible effect as the
+ * ns3::Simulator::Remove method but its algorithmic complexity is
+ * much lower: it has O(1) complexity.
+ * This method has the exact same semantics as ns3::EventId::Cancel.
+ * Note that it is not possible to cancel events which were scheduled
+ * for the "destroy" time. Doing so will result in a program error (crash).
+ *
+ * @param id the event to cancel
+ */
static void Cancel (const EventId &id);
- /** \copydoc SimulatorImpl::IsExpired */
+ /**
+ * Check if an event has already run or been cancelled.
+ *
+ * This method has O(1) complexity.
+ * Note that it is not possible to test for the expiration of
+ * events which were scheduled for the "destroy" time. Doing so
+ * will result in a program error (crash).
+ * An event is said to "expire" when it starts being scheduled
+ * which means that if the code executed by the event calls
+ * this function, it will get true.
+ *
+ * @param id The event to test for expiration.
+ * @returns @c true if the event has expired, false otherwise.
+ */
static bool IsExpired (const EventId &id);
- /** \copydoc SimulatorImpl::Now */
+ /**
+ * Return the current simulation virtual time.
+ *
+ * @returns The current virtual time.
+ */
static Time Now (void);
- /** \copydoc SimulatorImpl::GetDelayLeft */
+ /**
+ * Get the remaining time until this event will execute.
+ *
+ * @param id The event id to analyse.
+ * @return The delay left until the input event id expires.
+ * if the event is not running, this method returns
+ * zero.
+ */
static Time GetDelayLeft (const EventId &id);
- /** \copydoc SimulatorImpl::GetMaximumSimulationTime */
+ /**
+ * Get the maximum representable simulation time.
+ *
+ * @return The maximum simulation time at which an event
+ * can be scheduled.
+ *
+ * The returned value will always be bigger than or equal to Simulator::Now.
+ */
static Time GetMaximumSimulationTime (void);
- /** \copydoc SimulatorImpl::GetContext */
+ /**
+ * Get the current simulation context.
+ *
+ * @return The current simulation context
+ */
static uint32_t GetContext (void);
- /** \copydoc SimulatorImpl::Schedule */
+ /**
+ * Schedule a future event execution (in the same context).
+ *
+ * @param delay Delay until the event expires.
+ * @param event The event to schedule.
+ * @returns A unique identifier for the newly-scheduled event.
+ */
static EventId Schedule (Time const &delay, const Ptr<EventImpl> &event);
- /** \copydoc SimulatorImpl::ScheduleWithContext
+ /**
+ * Schedule a future event execution (in a different context).
* This method is thread-safe: it can be called from any thread.
+ *
+ * @param delay Delay until the event expires.
+ * @param context Event context.
+ * @param event The event to schedule.
+ * @returns A unique identifier for the newly-scheduled event.
*/
static void ScheduleWithContext (uint32_t context, const Time &delay, EventImpl *event);
- /** \copydoc SimulatorImpl::ScheduleDestroy */
+ /**
+ * Schedule an event to run at the end of the simulation, after
+ * the Stop() time or condition has been reached.
+ *
+ * @param event The event to schedule.
+ * @returns A unique identifier for the newly-scheduled event.
+ */
static EventId ScheduleDestroy (const Ptr<EventImpl> &event);
- /** \copydoc SimulatorImpl::ScheduleNow */
+ /**
+ * Schedule an event to run at the current virtual time.
+ *
+ * @param event The event to schedule.
+ * @returns A unique identifier for the newly-scheduled event.
+ */
static EventId ScheduleNow (const Ptr<EventImpl> &event);
- /** \copydoc SimulatorImpl::GetSystemId */
+ /**
+ * Get the system id of this simulator.
+ *
+ * The system id is the identifier for this simulator instance
+ * in a distributed simulation. For MPI this is the MPI rank.
+ * @return The system id for this simulator.
+ */
static uint32_t GetSystemId (void);
private:
@@ -777,37 +1169,37 @@
/**
* Implementation of the various Schedule methods.
- * \param [in] time Delay until the event should execute.
- * \param [in] event The event to execute.
- * \return The EventId.
+ * @param [in] delay Delay until the event should execute.
+ * @param [in] event The event to execute.
+ * @return The EventId.
*/
static EventId DoSchedule (Time const &delay, EventImpl *event);
/**
* Implementation of the various ScheduleNow methods.
- * \param [in] event The event to execute.
- * \return The EventId.
+ * @param [in] event The event to execute.
+ * @return The EventId.
*/
static EventId DoScheduleNow (EventImpl *event);
/**
* Implementation of the various ScheduleDestroy methods.
- * \param [in] event The event to execute.
- * \return The EventId.
+ * @param [in] event The event to execute.
+ * @return The EventId.
*/
static EventId DoScheduleDestroy (EventImpl *event);
};
/**
- * \ingroup simulator
- * \brief create an ns3::Time instance which contains the
+ * @ingroup simulator
+ * @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 at the absolute time "2 seconds":
- * \code
+ * @code
* Simulator::Schedule (Seconds (2.0) - Now (), &my_function);
- * \endcode
- * \return The current simulation time.
+ * @endcode
+ * @return The current simulation time.
*/
Time Now (void);
--- a/src/core/model/singleton.h Tue Jul 21 12:20:12 2015 -0700
+++ b/src/core/model/singleton.h Tue Jul 21 16:20:17 2015 -0700
@@ -22,14 +22,14 @@
/**
* \file
- * \ingroup core
+ * \ingroup access
* ns3::Singleton declaration and template implementation.
*/
namespace ns3 {
/**
- * \ingroup core
+ * \ingroup access
* \brief A template singleton
*
* This template class can be used to implement the singleton pattern.
@@ -39,7 +39,18 @@
* For a singleton whose lifetime is bounded by the simulation run,
* not the process, see SimulationSingleton.
*
- * \note If you call Get() again after the object has
+ * To force your `class ExampleS` to be a singleton, inherit from Singleton:
+ * \code
+ * class ExampleS : public Singleton<ExampleS> { ... };
+ * \endcode
+ *
+ * Then, to reach the singleton instance, just do
+ * \code
+ * ExampleS::Get ()->...;
+ * \endcode
+ *
+ * \note
+ * If you call Get() again after the object has
* been destroyed, the object will be re-created which will result in a
* memory leak as reported by most memory leak checkers. It is up to the
* user to ensure that Get() is never called from a static variable
--- a/src/core/model/synchronizer.h Tue Jul 21 12:20:12 2015 -0700
+++ b/src/core/model/synchronizer.h Tue Jul 21 16:20:17 2015 -0700
@@ -24,8 +24,8 @@
#include "object.h"
/**
- * \file
- * \ingroup realtime
+ * @file
+ * @ingroup realtime
* ns3::Synchronizer declaration.
*/
@@ -53,7 +53,7 @@
public:
/**
* Get the registered TypeId for this class.
- * \returns The TypeId.
+ * @returns The TypeId.
*/
static TypeId GetTypeId (void);
@@ -68,7 +68,7 @@
*
* The simulator sometimes needs to know this.
*
- * @returns \c true if locked with realtime, \c false if not.
+ * @returns @c true if locked with realtime, @c false if not.
*/
bool Realtime (void);
@@ -127,7 +127,7 @@
* @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
+ * 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
@@ -141,8 +141,8 @@
* @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.
+ * @returns @c true if the function ran to completion,
+ * @c false if it was interrupted by a Signal.
* @see DoSynchronize
* @see Signal
*/
@@ -219,7 +219,7 @@
virtual void DoSetOrigin (uint64_t ns) = 0;
/**
- * @brief Return \c 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.
@@ -227,7 +227,7 @@
* 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.
+ * @returns @c true if locked with realtime, @c false if not.
*/
virtual bool DoRealtime (void) = 0;
@@ -248,7 +248,7 @@
* time.
*
* This is where the real work of synchronization is done. The
- * \c nsCurrent argument is the simulation time (in ns). The job of
+ * @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
@@ -261,8 +261,8 @@
* @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.
+ * @returns @c true if the function ran to completion,
+ * @c false if it was interrupted by a Signal.
* @see Synchronize
* @see Signal
*/
--- a/src/core/model/system-wall-clock-ms.h Tue Jul 21 12:20:12 2015 -0700
+++ b/src/core/model/system-wall-clock-ms.h Tue Jul 21 16:20:17 2015 -0700
@@ -32,8 +32,8 @@
namespace ns3 {
/**
- * @ingroup core
- * @defgroup system System Services
+ * \ingroup core
+ * \defgroup system System Services
*
* System-independent interfaces to operating system services:
* files system, threading, wall clock time.
--- a/src/core/model/test.cc Tue Jul 21 12:20:12 2015 -0700
+++ b/src/core/model/test.cc Tue Jul 21 16:20:17 2015 -0700
@@ -19,6 +19,7 @@
#include "test.h"
#include "assert.h"
#include "abort.h"
+#include "singleton.h"
#include "system-path.h"
#include "log.h"
#include <cmath>
@@ -66,18 +67,39 @@
return true;
}
+/**
+ * \ingroup testingimpl
+ * Container for details of a test failure.
+ */
struct TestCaseFailure
{
+ /**
+ * Constructor.
+ *
+ * \param [in] _cond The name of the condition being tested.
+ * \param [in] _actual The actual value returned by the test.
+ * \param [in] _limit The expected value.
+ * \param [in] _message The associated message.
+ * \param [in] _file The soure file.
+ * \param [in] _line The source line.
+ */
TestCaseFailure (std::string _cond, std::string _actual,
std::string _limit, std::string _message,
std::string _file, int32_t _line);
- std::string cond;
- std::string actual;
- std::string limit;
- std::string message;
- std::string file;
- int32_t line;
+ std::string cond; /**< The name of the condition being tested. */
+ std::string actual; /**< The actual value returned by the test. */
+ std::string limit; /**< The expected value. */
+ std::string message; /**< The associated message. */
+ std::string file; /**< The soure file. */
+ int32_t line; /**< The source line. */
};
+/**
+ * Output streamer for TestCaseFailure.
+ *
+ * \param os The output stream.
+ * \param failure The TestCaseFailure to print.
+ * \returns The stream.
+ */
std::ostream & operator << (std::ostream & os, const TestCaseFailure & failure)
{
os << " test=\"" << failure.cond
@@ -90,53 +112,143 @@
return os;
}
+/**
+ * \ingroup testingimpl
+ * Container for results from a TestCase.
+ */
struct TestCase::Result
{
+ /** Constructor. */
Result ();
+
+ /** Test running time. */
SystemWallClockMs clock;
+ /** TestCaseFailure records for each child. */
std::vector<TestCaseFailure> failure;
+ /** \c true if any child TestCases failed. */
bool childrenFailed;
};
-class TestRunnerImpl
+/**
+ * \ingroup testingimpl
+ * Container for all tests.
+ */
+class TestRunnerImpl : public Singleton<TestRunnerImpl>
{
public:
+ /** Constructor. */
+ TestRunnerImpl ();
+
+ /**
+ * Add a new top-level TestSuite.
+ * \param [in] testSuite The new TestSuite.
+ */
void AddTestSuite (TestSuite *testSuite);
+ /** \copydoc TestCase::MustAssertOnFailure() */
bool MustAssertOnFailure (void) const;
+ /** \copydoc TestCase::MustContinueOnFailure() */
bool MustContinueOnFailure (void) const;
+ /**
+ * Check if this run should update the reference data.
+ * \return \c true if we should update the reference data.
+ */
bool MustUpdateData (void) const;
+ /**
+ * Get the path to the root of the source tree.
+ *
+ * The root directory is defined by the presence of two files:
+ * "VERSION" and "LICENSE".
+ *
+ * \returns The path to the root.
+ */
std::string GetTopLevelSourceDir (void) const;
+ /**
+ * Get the path to temporary directory.
+ * \return The temporary directory path.
+ */
std::string GetTempDir (void) const;
-
+ /** \copydoc TestRunner::Run() */
int Run (int argc, char *argv[]);
- static TestRunnerImpl *Instance (void);
+private:
-private:
- TestRunnerImpl ();
- ~TestRunnerImpl ();
-
+ /**
+ * Check if this is the root of the source tree.
+ * \param [in] path The path to test.
+ * \returns \c true if \p path is the root.
+ */
bool IsTopLevelSourceDir (std::string path) const;
+ /**
+ * Clean up characters not allowed in XML.
+ *
+ * XML files have restrictions on certain characters that may be present in
+ * data. We need to replace these characters with their alternate
+ * representation on the way into the XML file.
+ *
+ * Specifically, we make these replacements:
+ * Raw Source | Replacement
+ * :--------: | :---------:
+ * '<' | "<"
+ * '>' | ">"
+ * '&' | "&"
+ * '"' | "&39;"
+ * '\' | """
+ *
+ * \param [in] xml The raw string.
+ * \returns The sanitized string.
+ */
std::string ReplaceXmlSpecialCharacters (std::string xml) const;
+ /**
+ * Print the test report.
+ *
+ * \param test The TestCase to print.
+ * \param os The output stream.
+ * \param xml Generate XML output if \c true.
+ * \param level Indentation level.
+ */
void PrintReport (TestCase *test, std::ostream *os, bool xml, int level);
+ /**
+ * Print the list of all requested test suites.
+ *
+ * \param begin Iterator to the first TestCase to print.
+ * \param end Iterator to the end of the list.
+ * \param printTestType Preprend the test type label if \c true.
+ */
void PrintTestNameList (std::list<TestCase *>::const_iterator begin,
std::list<TestCase *>::const_iterator end,
bool printTestType) const;
+ /** Print the list of test types. */
void PrintTestTypeList (void) const;
+ /**
+ * Print the help text.
+ * \param [in] programName The name of the invoking program.
+ */
void PrintHelp (const char *programName) const;
+ /**
+ * Generate the list of tests matching the constraints.
+ *
+ * Test name and type contraints are or'ed. The duration constraint
+ * is and'ed.
+ *
+ * \param [in] testName Include a specific test by name.
+ * \param [in] testType Include all tests of give type.
+ * \param [in] maximumTestDuration Restrict to tests shorter than this.
+ * \returns The list of tests matching the filter constraints.
+ */
std::list<TestCase *> FilterTests (std::string testName,
enum TestSuite::Type testType,
enum TestCase::TestDuration maximumTestDuration);
+ /** Container type for the test. */
typedef std::vector<TestSuite *> TestSuiteVector;
- TestSuiteVector m_suites;
- std::string m_tempDir;
- bool m_verbose;
- bool m_assertOnFailure;
- bool m_continueOnFailure;
- bool m_updateData;
+ TestSuiteVector m_suites; //!< The list of tests.
+ std::string m_tempDir; //!< The temporary directory.
+ bool m_verbose; //!< Produce verbose output.
+ bool m_assertOnFailure; //!< \c true if we should assert on failure.
+ bool m_continueOnFailure; //!< \c true if we should continue on failure.
+ bool m_updateData; //!< \c true if we should update reference data.
};
@@ -363,7 +475,7 @@
m_type (type)
{
NS_LOG_FUNCTION (this << name << type);
- TestRunnerImpl::Instance ()->AddTestSuite (this);
+ TestRunnerImpl::Get ()->AddTestSuite (this);
}
TestSuite::Type
@@ -388,21 +500,6 @@
NS_LOG_FUNCTION (this);
}
-TestRunnerImpl::~TestRunnerImpl ()
-{
- NS_LOG_FUNCTION (this);
-}
-
-
-
-TestRunnerImpl *
-TestRunnerImpl::Instance (void)
-{
- NS_LOG_FUNCTION_NOARGS ();
- static TestRunnerImpl runner;
- return &runner;
-}
-
void
TestRunnerImpl::AddTestSuite (TestSuite *testSuite)
{
@@ -520,9 +617,15 @@
return result;
}
+/** Helper to indent output a specified number of steps. */
struct Indent
{
+ /**
+ * Constructor.
+ * \param level The number of steps. A step is " ".
+ */
Indent (int level);
+ /** The number of steps. */
int level;
};
Indent::Indent (int _level)
@@ -530,6 +633,12 @@
{
NS_LOG_FUNCTION (this << _level);
}
+/**
+ * Output streamer for Indent.
+ * \param os The output stream.
+ * \param val The Indent object.
+ * \returns The stream.
+ */
std::ostream &operator << (std::ostream &os, const Indent &val)
{
for (int i = 0; i < val.level; i++)
@@ -971,7 +1080,7 @@
TestRunner::Run (int argc, char *argv[])
{
NS_LOG_FUNCTION (argc << argv);
- return TestRunnerImpl::Instance ()->Run (argc, argv);
+ return TestRunnerImpl::Get ()->Run (argc, argv);
}
} // namespace ns3
--- a/src/core/model/test.h Tue Jul 21 12:20:12 2015 -0700
+++ b/src/core/model/test.h Tue Jul 21 16:20:17 2015 -0700
@@ -28,12 +28,13 @@
#include <limits>
#include <stdint.h>
+#include "non-copyable.h"
#include "system-wall-clock-ms.h"
/**
* \file
* \ingroup testing
- * Definition of the testing macros and declaration of the testing classes.
+ * \brief Definition of the testing macros and declaration of the testing classes.
*/
/**
@@ -1088,8 +1089,8 @@
*
* \param a The first of double precision floating point numbers to compare
* \param b The second of double precision floating point numbers to compare
- * \param epsilon The second of double precision floating point numberss to compare
- * \returns Returns true if the doubles are equal to a precision defined by epsilon
+ * \param epsilon The tolerance to use in the comparison.
+ * \returns Returns \c true if the doubles are equal to a precision defined by epsilon
*/
bool TestDoubleIsEqual (const double a, const double b,
const double epsilon = std::numeric_limits<double>::epsilon ());
@@ -1105,13 +1106,10 @@
* need to create subclasses of this base class, override the DoRun method,
* and use the NS_TEST_* macros within DoRun.
*/
-class TestCase
+class TestCase : private NonCopyable
{
public:
- /**
- * \enum TestDuration
- * \brief How long the test takes to execute.
- */
+ /** \brief How long the test takes to execute. */
enum TestDuration {
QUICK = 1, //!< Fast test.
EXTENSIVE = 2, //!< Medium length test.
@@ -1124,13 +1122,15 @@
virtual ~TestCase ();
/**
- * \return name of this test
+ * \return The name of this test
*/
std::string GetName (void) const;
protected:
/**
- * \param name the name of the new TestCase created
+ * \brief Constructor.
+ *
+ * \param name The name of the new TestCase created
*/
TestCase (std::string name);
@@ -1143,7 +1143,9 @@
void AddTestCase (TestCase *testCase, enum TestDuration duration);
/**
- * \param directory the directory where the test data is located
+ * \brief Set the data directory where reference trace files can be found.
+ *
+ * \param directory The directory where the test data is located
*
* In general, this method is invoked as SetDataDir (NS_TEST_SOURCEDIR);
* However, if a module contains a test directory with subdirectories
@@ -1157,27 +1159,33 @@
void SetDataDir (std::string directory);
/**
- * \return true if the tests have failed, false otherwise.
+ * \brief Check if any tests failed.
+ *
+ * \return \c true if any of the tests have failed, \c false otherwise.
*/
bool IsStatusFailure (void) const;
/**
- * \return true if the tests have succeeded, false otherwise.
+ * \brief Check if all tests passed.
+ *
+ * \return \c true if the tests have succeeded, \c false otherwise.
*/
bool IsStatusSuccess (void) const;
/**
- * \return a pointer to the parent of this test
+ * \brief Get the parent of this TestCsse.
+ *
+ * \return A pointer to the parent of this test.
*/
TestCase * GetParent () const;
/**
+ * \name Internal Interface
+ * These methods are the interface used by test macros and should not
+ * be used directly by normal test code.
* @{
- * \internal
- * The methods below are used only by test macros and should not
- * be used by normal users.
*/
/**
- * Log the failure of this TestCase.
+ * \brief Log the failure of this TestCase.
*
* \param cond The test condition.
* \param actual Actual value of the test.
@@ -1190,26 +1198,38 @@
std::string limit, std::string message,
std::string file, int32_t line);
/**
- * \return should we assert on failure, per the TestSuite configuration
+ * \brief Check if this run should assert on failure.
+ *
+ * \return \c true if we should assert on failure.
*/
bool MustAssertOnFailure (void) const;
/**
- * \return should we continue on failure, per the TestSuite configuration
+ * \brief Check if this run should continue on failure.
+ *
+ * \return \c true if we should continue on failure.
*/
bool MustContinueOnFailure (void) const;
/**
- * \param filename the bare (no path) file name
- * \return the full path to filename in the data directory
+ * \brief Construct the full path to a file in the data directory.
+ *
+ * The data directory is configured by SetDataDirectory().
+ *
+ * \param filename The bare (no path) file name
+ * \return The full path to \p filename in the data directory
*/
std::string CreateDataDirFilename (std::string filename);
/**
- * \param filename the bare (no path) file name
- * \return the full path to filename in the temporary directory.
+ * \brief Construct the full path to a file in a temporary directory.
+ *
* If the TestRunner is invoked with "--update-data", this will be
* the data directory instead.
+ *
+ * \param filename The bare (no path) file name
+ * \return The full path to \p filename in the temporary directory.
*/
std::string CreateTempDirFilename (std::string filename);
/**@}*/
+
private:
friend class TestRunnerImpl;
@@ -1235,28 +1255,22 @@
*/
virtual void DoTeardown (void);
- /**
- * Private, to block copying
- */
- TestCase (TestCase& tc);
- /**
- * Private, to block copying
- */
- TestCase& operator= (TestCase& tc);
-
// methods called by TestRunnerImpl
/**
- * Actually run this TestCase
+ * \brief Actually run this TestCase
*
* \param runner The test runner implementation.
*/
void Run (TestRunnerImpl *runner);
/**
- * \return the failure status of this TestCase and all it's children
+ * \copydoc IsStatusFailure()
*/
bool IsFailed (void) const;
- // Forward declaration is enough, since we only include a pointer here
+ /**
+ * \ingroup testingimpl
+ * \brief Container for results from a TestCase.
+ */
struct Result;
TestCase *m_parent; //!< Pointer to my parent TestCase
@@ -1300,14 +1314,14 @@
/**
* \brief get the kind of test this test suite implements
*
- * \returns the Type of the suite.
+ * \returns The Type of the suite.
*/
TestSuite::Type GetTestType (void);
private:
+ // Inherited
virtual void DoRun (void);
-
TestSuite::Type m_type; //!< Type of this TestSuite
};
@@ -1320,11 +1334,12 @@
{
public:
/**
- * Run the requested suite of tests.
+ * Run the requested suite of tests,
+ * according to the given command line arguments.
*
- * \param argc number of elements in \pname{argv}
- * \param argv vector of command line arguments
- * \returns success status
+ * \param argc The number of elements in \pname{argv}
+ * \param argv The vector of command line arguments
+ * \returns Success status
*/
static int Run (int argc, char *argv[]);
};
@@ -1335,7 +1350,7 @@
* \brief A simple way to store test vectors (for stimulus or from responses)
*/
template <typename T>
-class TestVectors
+class TestVectors : private NonCopyable
{
public:
/**
@@ -1348,41 +1363,32 @@
virtual ~TestVectors ();
/**
- * \param reserve the number of entries to reserve
+ * \brief Set the expected length of this vector.
+ *
+ * \param reserve The number of entries to reserve
*/
void Reserve (uint32_t reserve);
/**
- * \param vector the test vector to add
- * \returns the new test vector index
+ * \param vector The test vector to add
+ *
+ * \returns The new test vector index
*/
uint32_t Add (T vector);
/**
- * \return the number of test vectors
+ * \brief Get the total number of test vectors.
+ * \return The number of test vectors
*/
uint32_t GetN (void) const;
/**
- * Get the i'th test vector
- * \param i the requested vector index
- * \return the requested vector
+ * \brief Get the i'th test vector
+ * \param i The requested vector index
+ * \return The requested vector
*/
T Get (uint32_t i) const;
private:
- /**
- * Copy constructor, private to block copying
- */
- TestVectors (const TestVectors& tv);
- /**
- * Assignment, private to prevent copying
- */
- TestVectors& operator= (const TestVectors& tv);
- /**
- * Comparison (unimplemented?)
- */
- bool operator== (const TestVectors& tv) const;
-
typedef std::vector<T> TestVector; //!< Container type
TestVector m_vectors; //!< The list of test vectors
};
--- a/src/core/model/type-id.cc Tue Jul 21 12:20:12 2015 -0700
+++ b/src/core/model/type-id.cc Tue Jul 21 16:20:17 2015 -0700
@@ -47,6 +47,7 @@
// to find g_log
/**
+ * \ingroup object
* \brief TypeId information manager
*
* Information records are stored in a vector. Name and hash lookup
@@ -74,89 +75,272 @@
* collisions. The three-fold collision probability should be an
* acceptablly small error rate.
*/
-class IidManager
+class IidManager : public Singleton<IidManager>
{
public:
- IidManager ();
+ /**
+ * Create a new unique type id.
+ * \param [in] name The name of this type id.
+ * \returns The id.
+ */
uint16_t AllocateUid (std::string name);
+ /**
+ * Set the parent of a type id.
+ * \param [in] uid The id.
+ * \param [in] parent The id of the parent.
+ */
void SetParent (uint16_t uid, uint16_t parent);
+ /**
+ * Set the group name of a type id.
+ * \param [in] uid The id.
+ * \param [in] groupName The group name.
+ */
void SetGroupName (uint16_t uid, std::string groupName);
+ /**
+ * Set the size of the object class referred to by this id.
+ * \param [in] uid The id.
+ * \param [in] size The object size.
+ */
void SetSize (uint16_t uid, std::size_t size);
+ /**
+ * Add a constructor Callback to this type id.
+ * \param [in] uid The id.
+ * \param [in] callback The Callback for the constructor.
+ */
void AddConstructor (uint16_t uid, Callback<ObjectBase *> callback);
+ /**
+ * Mark this type id to be excluded from documentation.
+ * \param [in] uid The id.
+ */
void HideFromDocumentation (uint16_t uid);
+ /**
+ * Get a type id by name.
+ * \param [in] name The type id to find.
+ * \returns The type id. A type id of 0 means \p name wasn't found.
+ */
uint16_t GetUid (std::string name) const;
+ /**
+ * Get a type id by hash value.
+ * \param [in] hash The type id to find.
+ * \returns The type id. A type id of 0 means \p hash wasn't found.
+ */
uint16_t GetUid (TypeId::hash_t hash) const;
+ /**
+ * Get the name of a type id.
+ * \param [in] uid The id.
+ * \returns The name of the type id.
+ */
std::string GetName (uint16_t uid) const;
+ /**
+ * Get the hash of a type id.
+ * \param [in] uid The id.
+ * \returns The hash of the type id.
+ */
TypeId::hash_t GetHash (uint16_t uid) const;
+ /**
+ * Get the parent of a type id.
+ * \param [in] uid The id.
+ * \returns The parent type id of the type id.
+ */
uint16_t GetParent (uint16_t uid) const;
+ /**
+ * Get the group name of a type id.
+ * \param [in] uid The id.
+ * \returns The group name of the type id.
+ */
std::string GetGroupName (uint16_t uid) const;
+ /**
+ * Get the size of a type id.
+ * \param [in] uid The id.
+ * \returns The size of the type id.
+ */
std::size_t GetSize (uint16_t uid) const;
+ /**
+ * Get the constructor Callback of a type id.
+ * \param [in] uid The id.
+ * \returns The constructor Callback of the type id.
+ */
Callback<ObjectBase *> GetConstructor (uint16_t uid) const;
+ /**
+ * Check if a type id has a constructor Callback.
+ * \param [in] uid The id.
+ * \returns \c true if the type id has a constructor Callback.
+ */
bool HasConstructor (uint16_t uid) const;
+ /**
+ * Get the total number of type ids.
+ * \returns The total number.
+ */
uint32_t GetRegisteredN (void) const;
+ /**
+ * Get a type id by index.
+ *
+ * The type id value 0 indicates not registerd, so there is an offset
+ * of 1 between the index and the type id value. This function converts
+ * from an index to the type id value.
+ * \param [in] i The index.
+ * \returns The type id.
+ */
uint16_t GetRegistered (uint32_t i) const;
- void AddAttribute (uint16_t uid,
+ /**
+ * Record a new attribute in a type id.
+ * \param [in] uid The id.
+ * \param name The name of the new attribute
+ * \param help Some help text which describes the purpose of this
+ * attribute.
+ * \param flags Flags which describe how this attribute can be read and/or written.
+ * \param initialValue The initial value for this attribute.
+ * \param accessor An instance of the associated AttributeAccessor subclass.
+ * \param checker An instance of the associated AttributeChecker subclass.
+ */
+ void AddAttribute (uint16_t uid,
std::string name,
std::string help,
uint32_t flags,
Ptr<const AttributeValue> initialValue,
- Ptr<const AttributeAccessor> spec,
+ Ptr<const AttributeAccessor> accessor,
Ptr<const AttributeChecker> checker);
+ /**
+ * Set the initial value of an Attribute.
+ * \param [in] uid The id.
+ * \param i The attribute to manipulate
+ * \param initialValue The new initial value to use for this attribute.
+ */
void SetAttributeInitialValue(uint16_t uid,
uint32_t i,
Ptr<const AttributeValue> initialValue);
+ /**
+ * Get the number of attributes.
+ * \param [in] uid The id.
+ * \returns The number of attributes associated to this TypeId
+ */
uint32_t GetAttributeN (uint16_t uid) const;
+ /**
+ * Get Attribute information by index.
+ * \param [in] uid The id.
+ * \param i Index into attribute array
+ * \returns The information associated to attribute whose index is \p i.
+ */
struct TypeId::AttributeInformation GetAttribute(uint16_t uid, uint32_t i) const;
+ /**
+ * Record a new TraceSource.
+ * \param [in] uid The id.
+ * \param name The name of the new trace source
+ * \param help Some help text which describes the purpose of this
+ * trace source.
+ * \param accessor A pointer to a TraceSourceAccessor which can be
+ * used to connect/disconnect sinks to this trace source.
+ * \param callback Fully qualified typedef name for the callback signature.
+ * Generally this should begin with the "ns3::" namespace qualifier.
+ * \returns This TypeId instance.
+ */
void AddTraceSource (uint16_t uid,
std::string name,
std::string help,
Ptr<const TraceSourceAccessor> accessor,
std::string callback);
+ /**
+ * Get the number of Trace sources.
+ * \param [in] uid The id.
+ * \returns The number of trace sources defined in this TypeId.
+ */
uint32_t GetTraceSourceN (uint16_t uid) const;
+ /**
+ * Get the trace source by index.
+ * \param [in] uid The id.
+ * \param i Index into trace source array.
+ * \returns Detailed information about the requested trace source.
+ */
struct TypeId::TraceSourceInformation GetTraceSource(uint16_t uid, uint32_t i) const;
+ /**
+ * Check if this TypeId should not be listed in documentation.
+ * \param [in] uid The id.
+ * \returns \c true if this TypeId should be hidden from the user.
+ */
bool MustHideFromDocumentation (uint16_t uid) const;
private:
+ /**
+ * Check if a type id has a given TraceSource.
+ * \param [in] uid The id.
+ * \param [in] name The TraceSource name.
+ * \returns \c true if \p uid has the TraceSource \p name.
+ */
bool HasTraceSource (uint16_t uid, std::string name);
+ /**
+ * Check if a type id has a given Attribute.
+ * \param [in] uid The id.
+ * \param [in] name The Attribute name.
+ * \returns \c true if \p uid has the Attribute \p name.
+ */
bool HasAttribute (uint16_t uid, std::string name);
+ /**
+ * Hashing function.
+ * \param [in] name The type id name.
+ * \returns The hashed value of \p name.
+ */
static TypeId::hash_t Hasher (const std::string name);
+ /** The information record about a single type id. */
struct IidInformation {
+ /** The type id name. */
std::string name;
+ /** The type id hash value. */
TypeId::hash_t hash;
+ /** The parent type id. */
uint16_t parent;
+ /** The group name. */
std::string groupName;
+ /** The size of the object represented by this type id. */
std::size_t size;
+ /** \c true if a constructor Callback has been registered. */
bool hasConstructor;
+ /** The constructor Callback. */
Callback<ObjectBase *> constructor;
+ /** \c true if this type should be omitted from documentation. */
bool mustHideFromDocumentation;
+ /** The container of Attributes. */
std::vector<struct TypeId::AttributeInformation> attributes;
+ /** The container of TraceSources. */
std::vector<struct TypeId::TraceSourceInformation> traceSources;
};
+ /** Iterator type. */
typedef std::vector<struct IidInformation>::const_iterator Iterator;
+ /**
+ * Retrieve the information record for a type.
+ * \param [in] uid The id.
+ * \returns The information record.
+ */
struct IidManager::IidInformation *LookupInformation (uint16_t uid) const;
+ /** The container of all type id records. */
std::vector<struct IidInformation> m_information;
+ /** Type of the by-name index. */
typedef std::map<std::string, uint16_t> namemap_t;
+ /** The by-name index. */
namemap_t m_namemap;
+ /** Type of the by-hash index. */
typedef std::map<TypeId::hash_t, uint16_t> hashmap_t;
+ /** The by-hash index. */
hashmap_t m_hashmap;
-
- // To handle the first collision, we reserve the high bit as a
- // chain flag:
- enum { HashChainFlag = 0x80000000};
+
+ enum {
+ /**
+ * Hash chaining flag.
+ *
+ * To handle the first collision, we reserve the high bit as a
+ * chain flag.
+ */
+ HashChainFlag = 0x80000000
+ };
};
-IidManager::IidManager ()
-{
- NS_LOG_FUNCTION (this);
-}
- //static
+//static
TypeId::hash_t
IidManager::Hasher (const std::string name)
{
@@ -548,7 +732,7 @@
TypeId::TypeId (const char *name)
{
NS_LOG_FUNCTION (this << name);
- uint16_t uid = Singleton<IidManager>::Get ()->AllocateUid (name);
+ uint16_t uid = IidManager::Get ()->AllocateUid (name);
NS_ASSERT (uid != 0);
m_tid = uid;
}
@@ -563,7 +747,7 @@
TypeId::LookupByName (std::string name)
{
NS_LOG_FUNCTION (name);
- uint16_t uid = Singleton<IidManager>::Get ()->GetUid (name);
+ uint16_t uid = IidManager::Get ()->GetUid (name);
NS_ASSERT_MSG (uid != 0, "Assert in TypeId::LookupByName: " << name << " not found");
return TypeId (uid);
}
@@ -571,7 +755,7 @@
TypeId::LookupByNameFailSafe (std::string name, TypeId *tid)
{
NS_LOG_FUNCTION (name << tid);
- uint16_t uid = Singleton<IidManager>::Get ()->GetUid (name);
+ uint16_t uid = IidManager::Get ()->GetUid (name);
if (uid == 0)
{
return false;
@@ -582,7 +766,7 @@
TypeId
TypeId::LookupByHash (hash_t hash)
{
- uint16_t uid = Singleton<IidManager>::Get ()->GetUid (hash);
+ uint16_t uid = IidManager::Get ()->GetUid (hash);
NS_ASSERT_MSG (uid != 0, "Assert in TypeId::LookupByHash: 0x"
<< std::hex << hash << std::dec << " not found");
return TypeId (uid);
@@ -590,7 +774,7 @@
bool
TypeId::LookupByHashFailSafe (hash_t hash, TypeId *tid)
{
- uint16_t uid = Singleton<IidManager>::Get ()->GetUid (hash);
+ uint16_t uid = IidManager::Get ()->GetUid (hash);
if (uid == 0)
{
return false;
@@ -603,13 +787,13 @@
TypeId::GetRegisteredN (void)
{
NS_LOG_FUNCTION_NOARGS ();
- return Singleton<IidManager>::Get ()->GetRegisteredN ();
+ return IidManager::Get ()->GetRegisteredN ();
}
TypeId
TypeId::GetRegistered (uint32_t i)
{
NS_LOG_FUNCTION (i);
- return TypeId (Singleton<IidManager>::Get ()->GetRegistered (i));
+ return TypeId (IidManager::Get ()->GetRegistered (i));
}
bool
@@ -638,35 +822,35 @@
TypeId::SetParent (TypeId tid)
{
NS_LOG_FUNCTION (this << tid);
- Singleton<IidManager>::Get ()->SetParent (m_tid, tid.m_tid);
+ IidManager::Get ()->SetParent (m_tid, tid.m_tid);
return *this;
}
TypeId
TypeId::SetGroupName (std::string groupName)
{
NS_LOG_FUNCTION (this << groupName);
- Singleton<IidManager>::Get ()->SetGroupName (m_tid, groupName);
+ IidManager::Get ()->SetGroupName (m_tid, groupName);
return *this;
}
TypeId
TypeId::SetSize (std::size_t size)
{
NS_LOG_FUNCTION (this << size);
- Singleton<IidManager>::Get ()->SetSize (m_tid, size);
+ IidManager::Get ()->SetSize (m_tid, size);
return *this;
}
TypeId
TypeId::GetParent (void) const
{
NS_LOG_FUNCTION (this);
- uint16_t parent = Singleton<IidManager>::Get ()->GetParent (m_tid);
+ uint16_t parent = IidManager::Get ()->GetParent (m_tid);
return TypeId (parent);
}
bool
TypeId::HasParent (void) const
{
NS_LOG_FUNCTION (this);
- uint16_t parent = Singleton<IidManager>::Get ()->GetParent (m_tid);
+ uint16_t parent = IidManager::Get ()->GetParent (m_tid);
return parent != m_tid;
}
bool
@@ -684,7 +868,7 @@
TypeId::GetGroupName (void) const
{
NS_LOG_FUNCTION (this);
- std::string groupName = Singleton<IidManager>::Get ()->GetGroupName (m_tid);
+ std::string groupName = IidManager::Get ()->GetGroupName (m_tid);
return groupName;
}
@@ -692,21 +876,21 @@
TypeId::GetName (void) const
{
NS_LOG_FUNCTION (this);
- std::string name = Singleton<IidManager>::Get ()->GetName (m_tid);
+ std::string name = IidManager::Get ()->GetName (m_tid);
return name;
}
TypeId::hash_t
TypeId::GetHash (void) const
{
- hash_t hash = Singleton<IidManager>::Get ()->GetHash (m_tid);
+ hash_t hash = IidManager::Get ()->GetHash (m_tid);
return hash;
}
std::size_t
TypeId::GetSize (void) const
{
NS_LOG_FUNCTION (this);
- std::size_t size = Singleton<IidManager>::Get ()->GetSize (m_tid);
+ std::size_t size = IidManager::Get ()->GetSize (m_tid);
return size;
}
@@ -714,7 +898,7 @@
TypeId::HasConstructor (void) const
{
NS_LOG_FUNCTION (this);
- bool hasConstructor = Singleton<IidManager>::Get ()->HasConstructor (m_tid);
+ bool hasConstructor = IidManager::Get ()->HasConstructor (m_tid);
return hasConstructor;
}
@@ -722,7 +906,7 @@
TypeId::DoAddConstructor (Callback<ObjectBase *> cb)
{
NS_LOG_FUNCTION (this << &cb);
- Singleton<IidManager>::Get ()->AddConstructor (m_tid, cb);
+ IidManager::Get ()->AddConstructor (m_tid, cb);
}
TypeId
@@ -733,7 +917,7 @@
Ptr<const AttributeChecker> checker)
{
NS_LOG_FUNCTION (this << name << help << &initialValue << accessor << checker);
- Singleton<IidManager>::Get ()->AddAttribute (m_tid, name, help, ATTR_SGC, initialValue.Copy (), accessor, checker);
+ IidManager::Get ()->AddAttribute (m_tid, name, help, ATTR_SGC, initialValue.Copy (), accessor, checker);
return *this;
}
@@ -746,7 +930,7 @@
Ptr<const AttributeChecker> checker)
{
NS_LOG_FUNCTION (this << name << help << flags << &initialValue << accessor << checker);
- Singleton<IidManager>::Get ()->AddAttribute (m_tid, name, help, flags, initialValue.Copy (), accessor, checker);
+ IidManager::Get ()->AddAttribute (m_tid, name, help, flags, initialValue.Copy (), accessor, checker);
return *this;
}
@@ -755,7 +939,7 @@
Ptr<const AttributeValue> initialValue)
{
NS_LOG_FUNCTION (this << i << initialValue);
- Singleton<IidManager>::Get ()->SetAttributeInitialValue (m_tid, i, initialValue);
+ IidManager::Get ()->SetAttributeInitialValue (m_tid, i, initialValue);
return true;
}
@@ -764,7 +948,7 @@
TypeId::GetConstructor (void) const
{
NS_LOG_FUNCTION (this);
- Callback<ObjectBase *> cb = Singleton<IidManager>::Get ()->GetConstructor (m_tid);
+ Callback<ObjectBase *> cb = IidManager::Get ()->GetConstructor (m_tid);
return cb;
}
@@ -772,7 +956,7 @@
TypeId::MustHideFromDocumentation (void) const
{
NS_LOG_FUNCTION (this);
- bool mustHide = Singleton<IidManager>::Get ()->MustHideFromDocumentation (m_tid);
+ bool mustHide = IidManager::Get ()->MustHideFromDocumentation (m_tid);
return mustHide;
}
@@ -780,14 +964,14 @@
TypeId::GetAttributeN (void) const
{
NS_LOG_FUNCTION (this);
- uint32_t n = Singleton<IidManager>::Get ()->GetAttributeN (m_tid);
+ uint32_t n = IidManager::Get ()->GetAttributeN (m_tid);
return n;
}
struct TypeId::AttributeInformation
TypeId::GetAttribute(uint32_t i) const
{
NS_LOG_FUNCTION (this << i);
- return Singleton<IidManager>::Get ()->GetAttribute(m_tid, i);
+ return IidManager::Get ()->GetAttribute(m_tid, i);
}
std::string
TypeId::GetAttributeFullName (uint32_t i) const
@@ -801,13 +985,13 @@
TypeId::GetTraceSourceN (void) const
{
NS_LOG_FUNCTION (this);
- return Singleton<IidManager>::Get ()->GetTraceSourceN (m_tid);
+ return IidManager::Get ()->GetTraceSourceN (m_tid);
}
struct TypeId::TraceSourceInformation
TypeId::GetTraceSource(uint32_t i) const
{
NS_LOG_FUNCTION (this << i);
- return Singleton<IidManager>::Get ()->GetTraceSource(m_tid, i);
+ return IidManager::Get ()->GetTraceSource(m_tid, i);
}
TypeId
@@ -825,7 +1009,7 @@
std::string callback)
{
NS_LOG_FUNCTION (this << name << help << accessor);
- Singleton<IidManager>::Get ()->AddTraceSource (m_tid, name, help, accessor, callback);
+ IidManager::Get ()->AddTraceSource (m_tid, name, help, accessor, callback);
return *this;
}
@@ -833,7 +1017,7 @@
TypeId::HideFromDocumentation (void)
{
NS_LOG_FUNCTION (this);
- Singleton<IidManager>::Get ()->HideFromDocumentation (m_tid);
+ IidManager::Get ()->HideFromDocumentation (m_tid);
return *this;
}
--- a/src/core/model/type-id.h Tue Jul 21 12:20:12 2015 -0700
+++ b/src/core/model/type-id.h Tue Jul 21 16:20:17 2015 -0700
@@ -41,6 +41,7 @@
class ObjectBase;
/**
+ * \ingroup object
* \brief a unique identifier for an interface.
*
* This class records a lot of meta-information about a
@@ -57,80 +58,102 @@
class TypeId
{
public:
- /**
- * Flags describing when a given attribute can be read or written
- */
+ /** Flags describing when a given attribute can be read or written. */
enum AttributeFlag {
ATTR_GET = 1<<0, /**< The attribute can be read */
ATTR_SET = 1<<1, /**< The attribute can be written */
ATTR_CONSTRUCT = 1<<2, /**< The attribute can be written at construction-time */
ATTR_SGC = ATTR_GET | ATTR_SET | ATTR_CONSTRUCT, /**< The attribute can be read, and written at any time */
};
+ /** Attribute implementation. */
struct AttributeInformation {
+ /** Attribute name. */
std::string name;
+ /** Attribute help string. */
std::string help;
+ /** AttributeFlags value. */
uint32_t flags;
+ /** Default initial value. */
Ptr<const AttributeValue> originalInitialValue;
+ /** Configured initial value. */
Ptr<const AttributeValue> initialValue;
+ /** Accessor object. */
Ptr<const AttributeAccessor> accessor;
+ /** Checker object. */
Ptr<const AttributeChecker> checker;
};
+ /** TraceSource implementation. */
struct TraceSourceInformation {
+ /** Trace name. */
std::string name;
+ /** Trace help string. */
std::string help;
+ /** Callback function signature type. */
std::string callback;
+ /** Trace accessor. */
Ptr<const TraceSourceAccessor> accessor;
};
- /**
- * Type of hash values
- */
+ /** Type of hash values. */
typedef uint32_t hash_t;
/**
- * \param name the name of the requested TypeId
- * \returns the unique id associated with the requested
- * name.
+ * Get a TypeId by name.
+ *
+ * \param name The name of the requested TypeId
+ * \returns The unique id associated with the requested name.
*
* This method cannot fail: it will crash if the input
* name is not a valid TypeId name.
*/
static TypeId LookupByName (std::string name);
/**
- * \param name the name of the requested TypeId
- * \param tid a pointer to the TypeId instance where the
+ * Get a TypeId by name.
+ *
+ * \param name The name of the requested TypeId
+ * \param tid A pointer to the TypeId instance where the
* result of this function should be stored.
- * \returns true if the requested name was found, false otherwise.
+ * \returns \c true if the requested name was found.
*/
static bool LookupByNameFailSafe (std::string name, TypeId *tid);
/**
- * \param hash the hash to lookup
- * \returns the unique id associated with the requested hash.
+ * Get a TypeId by hash.
+ *
+ * \param hash The hash to lookup
+ * \returns The unique id associated with the requested hash.
*
* This method cannot fail: it will crash if the input
* hash does not match an existing TypeId.
*/
static TypeId LookupByHash (hash_t hash);
/**
- * \param hash the hash of the requested TypeId
- * \param tid a pointer to the TypeId instance where the
+ * Get a TypeId by hash.
+ *
+ * \param hash The hash of the requested TypeId
+ * \param tid A pointer to the TypeId instance where the
* result of this function should be stored.
- * \returns true if the requested hash was found, false otherwise.
+ * \returns \c true if the requested hash was found.
*/
static bool LookupByHashFailSafe (hash_t hash, TypeId *tid);
/**
- * \returns the number of TypeId instances registered.
+ * Get the number of registered TypeIds.
+ *
+ * \returns The number of TypeId instances registered.
*/
static uint32_t GetRegisteredN (void);
/**
- * \param i index
- * \returns the TypeId instance whose index is i.
+ * Get a TypeId by index.
+ *
+ * \param i Index of the TypeId.
+ * \returns he TypeId instance whose index is \c i.
*/
static TypeId GetRegistered (uint32_t i);
/**
- * \param name the name of the interface to construct.
+ * Constructor.
+ *
+ * \param name The name of the interface to construct.
*
* No two instances can share the same name. The name is expected to be
* the full c++ typename of associated c++ object.
@@ -138,22 +161,30 @@
explicit TypeId (const char * name);
/**
- * \returns the parent of this TypeId
+ * Get the parent of this TypeId.
+ *
+ * \returns The parent of this TypeId
*
* This method cannot fail. It will return itself
* if this TypeId has no parent. i.e., it is at the top
* of the TypeId hierarchy. Currently, this is the
- * case for the TypeId associated to the Object class
+ * case for the TypeId associated to the ns3::ObjectBase class
* only.
*/
TypeId GetParent (void) const;
-
+
+ /**
+ * Check if this TypeId has a parent.
+ *
+ * \return \c true if this TypeId has a parent.
+ */
bool HasParent (void) const;
/**
- * \param other a parent TypeId
- * \returns true if the input TypeId is really a parent
- * of this TypeId, false otherwise.
+ * Check if this TypeId is a child of another.
+ *
+ * \param other A parent TypeId
+ * \returns \c true if the input TypeId is really a parent of this TypeId.
*
* Calling this method is roughly similar to calling dynamic_cast
* except that you do not need object instances: you can do the check
@@ -162,80 +193,106 @@
bool IsChildOf (TypeId other) const;
/**
- * \returns the name of the group associated to this TypeId.
+ * Get the group name.
+ *
+ * \returns The name of the group associated to this TypeId.
*/
std::string GetGroupName (void) const;
/**
- * \returns the name of this interface.
+ * Get the name.
+ *
+ * \returns The name of this interface.
*/
std::string GetName (void) const;
/**
- * \returns the hash of this interface.
+ * Get the hash.
+ *
+ * \returns The hash of this interface.
*/
hash_t GetHash (void) const;
/**
- * \returns the size of this interface.
+ * Get the size of this object.
+ *
+ * \returns The size of this interface.
*/
std::size_t GetSize (void) const;
/**
- * \returns true if this TypeId has a constructor
+ * Check if this TypeId has a constructor.
+ *
+ * \returns \c true if this TypeId has a constructor
*/
bool HasConstructor (void) const;
/**
- * \returns the number of attributes associated to this TypeId
+ * Get the number of attributes.
+ *
+ * \returns The number of attributes associated to this TypeId
*/
uint32_t GetAttributeN (void) const;
/**
- * \param i index into attribute array
- * \returns the information associated to attribute whose
- * index is i.
+ * Get Attribute information by index.
+ *
+ * \param i Index into attribute array
+ * \returns The information associated to attribute whose index is \p i.
*/
struct TypeId::AttributeInformation GetAttribute(uint32_t i) const;
/**
- * \param i index into attribute array
- * \returns the full name associated to the attribute whose
- * index is i.
+ * Get the Attribute name by index.
+ *
+ * \param i Index into attribute array
+ * \returns The full name associated to the attribute whose index is \p i.
*/
std::string GetAttributeFullName (uint32_t i) const;
/**
- * \returns a callback which can be used to instanciate an object
+ * Get the constructor callback.
+ *
+ * \returns A callback which can be used to instanciate an object
* of this type.
*/
Callback<ObjectBase *> GetConstructor (void) const;
/**
- * \returns true if this TypeId should be hidden from the user,
- * false otherwise.
+ * Check if this TypeId should not be listed in documentation.
+ *
+ * \returns \c true if this TypeId should be hidden from the user.
*/
bool MustHideFromDocumentation (void) const;
/**
- * \returns the number of trace sources defined in this TypeId.
+ * Get the number of Trace sources.
+ *
+ * \returns The number of trace sources defined in this TypeId.
*/
uint32_t GetTraceSourceN (void) const;
/**
- * \param i index into trace source array.
- * \returns detailed information about the requested trace source.
+ * Get the trace source by index.
+ *
+ * \param i Index into trace source array.
+ * \returns Detailed information about the requested trace source.
*/
struct TypeId::TraceSourceInformation GetTraceSource(uint32_t i) const;
/**
- * \param tid the TypeId of the base class.
- * \return this TypeId instance.
+ * Set the parent TypeId.
+ *
+ * \param tid The TypeId of the base class.
+ * \return This TypeId instance.
*
* Record in this TypeId which TypeId is the TypeId
* of the base class of the subclass.
*/
TypeId SetParent (TypeId tid);
/**
- * \return this TypeId instance.
+ * Set the parent TypeId.
+ *
+ * \tparam T The parent TypeID type.
+ * \return This TypeId instance.
*
* Record in this TypeId which TypeId is the TypeId
* of the base class of the subclass.
@@ -244,8 +301,10 @@
TypeId SetParent (void);
/**
- * \param groupName the name of the group this TypeId belongs to.
- * \returns this TypeId instance.
+ * Set the group name.
+ *
+ * \param groupName The name of the group this TypeId belongs to.
+ * \returns This TypeId instance.
*
* The group name is purely an advisory information used to
* group together types according to a user-specific grouping
@@ -254,7 +313,7 @@
TypeId SetGroupName (std::string groupName);
/**
- * Set the size of this type, based on the \p sizeof operator.
+ * Set the size of this type.
*
* Call this way:
* \code
@@ -265,29 +324,30 @@
* type hasn't been registered.
*
* \param size The size of the object, in bytes.
- * \returns this TypeId instance.
+ * \returns This TypeId instance.
*/
TypeId SetSize (std::size_t size);
/**
- * \returns this TypeId instance
- *
* Record in this TypeId the fact that the default constructor
* is accessible.
+ *
+ * \tparam T The class name represented by this TypeId.
+ * \returns This TypeId instance
*/
template <typename T>
TypeId AddConstructor (void);
/**
- * \param name the name of the new attribute
- * \param help some help text which describes the purpose of this
+ * Record in this TypeId the fact that a new attribute exists.
+ *
+ * \param name The name of the new attribute
+ * \param help Some help text which describes the purpose of this
* attribute.
- * \param initialValue the initial value for this attribute.
- * \param accessor an instance of the associated AttributeAccessor subclass.
- * \param checker an instance of the associated AttributeChecker subclass.
- * \returns this TypeId instance
- *
- * Record in this TypeId the fact that a new attribute exists.
+ * \param initialValue The initial value for this attribute.
+ * \param accessor An instance of the associated AttributeAccessor subclass.
+ * \param checker An instance of the associated AttributeChecker subclass.
+ * \returns This TypeId instance
*/
TypeId AddAttribute (std::string name,
std::string help,
@@ -296,24 +356,26 @@
Ptr<const AttributeChecker> checker);
/**
- * \param i the attribute to manipulate
- * \param initialValue the new initial value to use for this attribute.
- * \returns true if the call was successfuly, false otherwise.
+ * Set the initial value of an Attribute.
+ *
+ * \param i The attribute to manipulate
+ * \param initialValue The new initial value to use for this attribute.
+ * \returns \c true if the call was successfuly.
*/
bool SetAttributeInitialValue(uint32_t i,
Ptr<const AttributeValue> initialValue);
/**
- * \param name the name of the new attribute
- * \param help some help text which describes the purpose of this
+ * Record in this TypeId the fact that a new attribute exists.
+ *
+ * \param name The name of the new attribute
+ * \param help Some help text which describes the purpose of this
* attribute
- * \param flags flags which describe how this attribute can be read and/or written.
- * \param initialValue the initial value for this attribute.
- * \param accessor an instance of the associated AttributeAccessor subclass.
- * \param checker an instance of the associated AttributeChecker subclass.
- * \returns this TypeId instance
- *
- * Record in this TypeId the fact that a new attribute exists.
+ * \param flags Flags which describe how this attribute can be read and/or written.
+ * \param initialValue The initial value for this attribute.
+ * \param accessor An instance of the associated AttributeAccessor subclass.
+ * \param checker An instance of the associated AttributeChecker subclass.
+ * \returns This TypeId instance
*/
TypeId AddAttribute (std::string name,
std::string help,
@@ -323,17 +385,14 @@
Ptr<const AttributeChecker> checker);
/**
- * \param name the name of the new trace source
- * \param help some help text which describes the purpose of this
+ * Record a new TraceSource.
+ *
+ * \param name The name of the new trace source
+ * \param help Some help text which describes the purpose of this
* trace source.
- * \param accessor a pointer to a TraceSourceAccessor which can be
+ * \param accessor A pointer to a TraceSourceAccessor which can be
* used to connect/disconnect sinks to this trace source.
- * \param callback fully qualified typedef name for the callback signature.
- * Generally this should begin with the "ns3::" namespace qualifier.
* \returns this TypeId instance.
- *
- * \deprecated This method will go away in future versions of ns-3.
- * See instead AddTraceSource(std::string,std::string,Ptr<const TraceSourceAccessor>,std::string)
*/
TypeId AddTraceSource (std::string name,
std::string help,
@@ -341,80 +400,143 @@
NS_DEPRECATED;
/**
- * \param name the name of the new trace source
- * \param help some help text which describes the purpose of this
+ * Record a new TraceSource.
+ *
+ * \param name The name of the new trace source
+ * \param help Some help text which describes the purpose of this
* trace source.
- * \param accessor a pointer to a TraceSourceAccessor which can be
+ * \param accessor A pointer to a TraceSourceAccessor which can be
* used to connect/disconnect sinks to this trace source.
- * \param callback fully qualified typedef name for the callback signature.
+ * \param callback Fully qualified typedef name for the callback signature.
* Generally this should begin with the "ns3::" namespace qualifier.
- * \returns this TypeId instance.
+ * \returns This TypeId instance.
*/
TypeId AddTraceSource (std::string name,
std::string help,
Ptr<const TraceSourceAccessor> accessor,
std::string callback);
+ /**
+ * Hide this TypeId from documentation.
+ * \returns This TypeId instance.
+ */
TypeId HideFromDocumentation (void);
/**
- * \param name the name of the requested attribute
- * \param info a pointer to the TypeId::AttributeInformation data structure
+ * Find an Attribute by name.
+ *
+ * \param name The name of the requested attribute
+ * \param info A pointer to the TypeId::AttributeInformation data structure
* where the result value of this method will be stored.
- * \returns true if the requested attribute could be found, false otherwise.
+ * \returns \c true if the requested attribute could be found.
*/
bool LookupAttributeByName (std::string name, struct AttributeInformation *info) const;
/**
- * \param name the name of the requested trace source
- * \returns the trace source accessor which can be used to connect and disconnect
- * trace sinks with the requested trace source on an object instance.
+ * Find a TraceSource by name.
*
* If no matching trace source is found, this method returns zero.
+ *
+ * \param name The name of the requested trace source
+ * \returns The trace source accessor which can be used to connect and disconnect
+ * trace sinks with the requested trace source on an object instance.
*/
Ptr<const TraceSourceAccessor> LookupTraceSourceByName (std::string name) const;
/**
- * \returns the internal integer which uniquely identifies this
- * TypeId.
+ * Get the internal id of this TypeId.
+ *
+ * \returns The internal integer which uniquely identifies this TypeId.
*
* This is really an internal method which users are not expected
* to use.
*/
uint16_t GetUid (void) const;
/**
- * \param tid the internal integer which uniquely identifies
- * this TypeId.
+ * Set the internal id of this TypeId.
*
- * This method is even more internal than TypeId::GetUid. Use
+ * \param tid The internal integer which uniquely identifies this TypeId.
+ * This TypeId should already have been registered.
+ *
+ * Typically this is used in serialization/deserialization.
+ *
+ * This method is even more internal than GetUid(). Use
* at your own risk and don't be surprised that it eats raw
* babies on full-moon nights.
*/
void SetUid (uint16_t tid);
- // construct an invalid TypeId.
+ /** Default constructor. This produces an invalid TypeId. */
inline TypeId ();
+ /**
+ * Copy constructor.
+ * \param [in] o The other TypeId.
+ */
inline TypeId (const TypeId &o);
+ /**
+ * Assignment.
+ * \param [in] o The other TypeId.
+ * \returns The copied TypeId.
+ */
inline TypeId &operator = (const TypeId &o);
+ /** Destructor. */
inline ~TypeId ();
private:
- friend class AttributeList;
- friend bool operator == (TypeId a, TypeId b);
- friend bool operator != (TypeId a, TypeId b);
- friend bool operator < (TypeId a, TypeId b);
+ /**
+ * \name Comparison operators.
+ * Standard comparison operators.
+ * @{
+ */
+ friend inline bool operator == (TypeId a, TypeId b);
+ friend inline bool operator != (TypeId a, TypeId b);
+ friend bool operator < (TypeId a, TypeId b);
+ /**@}*/
-
+ /**
+ * Construct from an integer value.
+ * \param [in] tid The TypeId value as an integer.
+ */
explicit TypeId (uint16_t tid);
+ /**
+ * Implementation for AddConstructor().
+ *
+ * \param [in] callback Callback which constructs an instance of this TypeId.
+ */
void DoAddConstructor (Callback<ObjectBase *> callback);
-
+
+ /** The TypeId value. */
uint16_t m_tid;
};
-
+
+/**
+ * \relates TypeId
+ * Output streamer.
+ *
+ * \param [in] os The output stream.
+ * \param [in] tid The TypeId.
+ * \returns The output stream.
+ */
std::ostream & operator << (std::ostream &os, TypeId tid);
+/**
+ * \relates TypeId
+ * Input Streamer.
+ * \param [in] is The input stream.
+ * \param [out] tid The TypeId to set from the stream.
+ * \returns The input stream.
+ */
std::istream & operator >> (std::istream &is, TypeId &tid);
+
+ /**
+ * Comparison operator.
+ * \param [in] a One value.
+ * \param [in] b The other value.
+ * \returns The result of the comparison.
+ * @{
+ */
inline bool operator == (TypeId a, TypeId b);
inline bool operator != (TypeId a, TypeId b);
bool operator < (TypeId a, TypeId b);
+/** @} */
ATTRIBUTE_HELPER_HEADER (TypeId);
--- a/src/core/model/wall-clock-synchronizer.h Tue Jul 21 12:20:12 2015 -0700
+++ b/src/core/model/wall-clock-synchronizer.h Tue Jul 21 16:20:17 2015 -0700
@@ -23,8 +23,8 @@
#include "synchronizer.h"
/**
- * \file
- * \ingroup realtime
+ * @file
+ * @ingroup realtime
* ns3::WallClockSynchronizer declaration.
*/
@@ -37,9 +37,9 @@
*
* Enable this synchronizer using:
*
- * \code
+ * @code
* DefaultValue::Bind ("Synchronizer", "WallClockSynchronizer");
- * \endcode
+ * @endcode
*
* before calling any simulator functions.
*
@@ -47,21 +47,21 @@
* access to several clocks we could use as a wall clock. We don't care about
* 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 \c 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 \c 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.
*
- * \todo Add more on jiffies, sleep, processes, etc.
+ * @todo Add more on jiffies, sleep, processes, etc.
*
- * \internal
+ * @internal
* Nanosleep takes a <tt>struct timeval</tt> as an input so we have to
- * deal with conversion between Time and \c timeval here.
+ * deal with conversion between Time and @c timeval here.
* They are both interpreted as elapsed times.
*/
class WallClockSynchronizer : public Synchronizer
@@ -69,7 +69,7 @@
public:
/**
* Get the registered TypeId for this class.
- * \returns The TypeId.
+ * @returns The TypeId.
*/
static TypeId GetTypeId (void);
@@ -88,15 +88,15 @@
protected:
/**
* @brief Do a busy-wait until the normalized realtime equals the argument
- * or the condition variable becomes \c true.
+ * or the condition variable becomes @c true.
- * The condition becomes \c true if an outside entity (a network device
+ * 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.
+ * @returns @c true if we reached the target time,
+ * @c false if we retured because the condition was set.
*/
bool SpinWait (uint64_t ns);
/**
@@ -114,13 +114,13 @@
* 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
+ * 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.
+ * 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.
+ * @returns @c true if we reached the target time,
+ * @c false if we retured because the condition was set.
*/
bool SleepWait (uint64_t ns);
@@ -160,33 +160,33 @@
uint64_t GetNormalizedRealtime (void);
/**
- * @brief Convert an absolute time in ns to a \c timeval
+ * @brief Convert an absolute time in ns to a @c timeval
*
* @param ns Absolute time in ns.
- * @param tv Converted \c timeval.
+ * @param tv Converted @c timeval.
*/
void NsToTimeval (int64_t ns, struct timeval *tv);
/**
- * @brief Convert a \c timeval to absolute time, in ns.
+ * @brief Convert a @c timeval to absolute time, in ns.
*
- * @param tv The input \c timeval.
+ * @param tv The input @c timeval.
* @returns The absolute time, in ns.
*/
uint64_t TimevalToNs (struct timeval *tv);
/**
- * @brief Add two \c timeval.
+ * @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.
+ * @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);
- /** Size of the system clock tick, as reported by \c clock_getres, in ns. */
+ /** 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;