--- a/src/core/model/object.h Sun Dec 07 20:53:37 2014 -0800
+++ b/src/core/model/object.h Sun Dec 07 22:08:04 2014 -0800
@@ -30,6 +30,12 @@
#include "attribute-construction-list.h"
#include "simple-ref-count.h"
+/**
+ * \file
+ * \ingroup object
+ * ns3::Object class declaration, which is the root of the Object hierarchy
+ * and Aggregation.
+ */
namespace ns3 {
@@ -38,192 +44,271 @@
class AttributeValue;
class TraceSourceAccessor;
+/**
+ * \ingroup core
+ * \defgroup object Object
+ * \brief Base classes which provide memory management and object aggregation.
+ */
+
+/**
+ * \ingroup object
+ * \ingroup ptr
+ * Standard Object deleter, used by SimpleRefCount
+ * to delete an Object when the reference count drops to zero.
+ */
struct ObjectDeleter
{
+ /**
+ * Smart pointer deleter implementation for Object.
+ *
+ * Delete implementation, forwards to the Object::DoDelete()
+ * method.
+ *
+ * \param [in] object The Object to delete.
+ */
inline static void Delete (Object *object);
};
/**
- * \ingroup core
- * \defgroup object Object
- * \brief Base classes which provides memory management and object aggregation.
- */
-/**
* \ingroup object
- * \brief a base class which provides memory management and object aggregation
+ * \brief A base class which provides memory management and object aggregation
*
- * The memory management scheme is based on reference-counting with dispose-like
- * functionality to break the reference cycles. The reference count is increamented
- * and decremented with the methods Object::Ref and Object::Unref. If a reference cycle is
- * present, the user is responsible for breaking it by calling Object::Dispose in
- * a single location. This will eventually trigger the invocation of Object::DoDispose
- * on itself and all its aggregates. The Object::DoDispose method is always automatically
- * invoked from the Object::Unref method before destroying the object, even if the user
- * did not call Object::Dispose directly.
+ * The memory management scheme is based on reference-counting with
+ * dispose-like functionality to break the reference cycles.
+ * The reference count is incremented and decremented with
+ * the methods Ref() and Unref(). If a reference cycle is
+ * present, the user is responsible for breaking it
+ * by calling Dispose() in a single location. This will
+ * eventually trigger the invocation of DoDispose() on itself and
+ * all its aggregates. The DoDispose() method is always automatically
+ * invoked from the Unref() method before destroying the Object,
+ * even if the user did not call Dispose() directly.
*/
-class Object : public SimpleRefCount<Object,ObjectBase,ObjectDeleter>
+class Object : public SimpleRefCount<Object, ObjectBase, ObjectDeleter>
{
public:
/**
* \brief Register this type.
- * \return The object TypeId.
+ * \return The Object TypeId.
*/
static TypeId GetTypeId (void);
/**
- * \brief Iterate over the objects aggregated to an ns3::Object.
+ * \brief Iterate over the Objects aggregated to an ns3::Object.
*
- * This iterator does not allow you to iterate over the initial
- * object used to call Object::GetAggregateIterator.
+ * This iterator does not allow you to iterate over the parent
+ * Object used to call Object::GetAggregateIterator.
*
- * Note: this is a java-style iterator.
+ * \note This is a java-style iterator.
*/
class AggregateIterator
{
public:
+ /** Default constructor, which has no Object. */
AggregateIterator ();
/**
- * \returns true if HasNext can be called and return a non-null
- * pointer, false otherwise.
+ * Check if there are more Aggregates to iterate over.
+ *
+ * \returns \c true if Next() can be called and return a non-null
+ * pointer, \c false otherwise.
*/
bool HasNext (void) const;
/**
- * \returns the next aggregated object.
+ * Get the next Aggregated Object.
+ *
+ * \returns The next aggregated Object.
*/
Ptr<const Object> Next (void);
private:
friend class Object;
- AggregateIterator (Ptr<const Object> object); //!< Constructor
- Ptr<const Object> m_object; //!< Parent Object
- uint32_t m_current; //!< Current position in parent's aggegrates
+ /**
+ * Construct from an Object.
+ *
+ * This is private, with Object as friend, so only Objects can create
+ * useful AggregateIterators.
+ *
+ * \param [in] object The Object whose Aggregates should be iterated over.
+ */
+ AggregateIterator (Ptr<const Object> object);
+ Ptr<const Object> m_object; //!< Parent Object.
+ uint32_t m_current; //!< Current position in parent's aggegrates.
};
+ /** Constructor. */
Object ();
+ /** Destructor. */
virtual ~Object ();
- /*
+ /**
* Implement the GetInstanceTypeId method defined in ObjectBase.
*/
virtual TypeId GetInstanceTypeId (void) const;
/**
- * \returns a pointer to the requested interface or zero if it could not be found.
+ * Get a pointer to the requested aggregated Object.
+ *
+ * \returns A pointer to the requested Object, or zero
+ * if it could not be found.
*/
template <typename T>
inline Ptr<T> GetObject (void) const;
/**
- * \param tid the interface id of the requested interface
- * \returns a pointer to the requested interface or zero if it could not be found.
+ * Get a pointer to the requested aggregated Object.
+ *
+ * \param tid The TypeId of the requested Object.
+ * \returns A pointer to the requested Object, or zero
+ * if it could not be found.
*/
template <typename T>
Ptr<T> GetObject (TypeId tid) const;
/**
- * Run the DoDispose methods of this object and all the
- * objects aggregated to it.
- * After calling this method, the object is expected to be
- * totally unusable except for the Ref and Unref methods.
+ * Dispose of this Object.
*
- * Note that you can call Dispose many times on the same object or
- * different objects aggregated together, and DoDispose will be
- * called only once for each aggregated object.
+ * Run the DoDispose() methods of this Object and all the
+ * Objects aggregated to it.
+ * After calling this method, this Object is expected to be
+ * totally unusable except for the Ref() and Unref() methods.
+ *
+ * \note You can call Dispose() many times on the same Object or
+ * different Objects aggregated together, and DoDispose() will be
+ * called only once for each aggregated Object.
*
* This method is typically used to break reference cycles.
*/
void Dispose (void);
/**
- * \param other another object pointer
+ * Aggregate two Objects together.
*
- * This method aggregates the two objects together: after this
- * method returns, it becomes possible to call GetObject
+ * \param other The other Object pointer
+ *
+ * This method aggregates the two Objects together: after this
+ * method returns, it becomes possible to call GetObject()
* on one to get the other, and vice-versa.
*
- * This method calls the virtual method NotifyNewAggregates to
- * notify all aggregated objects that they have been aggregated
+ * This method calls the virtual method NotifyNewAggregates() to
+ * notify all aggregated Objects that they have been aggregated
* together.
*
- * \sa NotifyNewAggregate
+ * \sa NotifyNewAggregate()
*/
void AggregateObject (Ptr<Object> other);
/**
- * \returns an iterator to the first object aggregated to this
- * object.
+ * Get an iterator to the Objects aggregated to this one.
*
- * If no objects are aggregated to this object, then, the returned
- * iterator will be empty and AggregateIterator::HasNext will
- * always return false.
+ * \returns An iterator to the first Object aggregated to this
+ * Object.
+ *
+ * If no Objects are aggregated to this Object, then, the returned
+ * iterator will be empty and AggregateIterator::HasNext() will
+ * always return \c false.
*/
AggregateIterator GetAggregateIterator (void) const;
/**
- * This method calls the virtual DoInitialize method on all the objects
- * aggregated to this object. DoInitialize will be called only once over
- * the lifetime of an object, just like DoDispose is called only
+ * Invoke DoInitialize on all Objects aggregated to this one.
+ *
+ * This method calls the virtual DoInitialize() method on all the Objects
+ * aggregated to this Object. DoInitialize() will be called only once over
+ * the lifetime of an Object, just like DoDispose() is called only
* once.
*
- * \sa DoInitialize
+ * \sa DoInitialize()
*/
void Initialize (void);
protected:
/**
- * This method is invoked whenever two sets of objects are aggregated together.
- * It is invoked exactly once for each object in both sets.
- * This method can be overriden by subclasses who wish to be notified of aggregation
- * events. These subclasses must chain up to their base class NotifyNewAggregate method.
- * It is safe to call GetObject and AggregateObject from within this method.
+ * Notify all Objects aggregated to this one of a new Object being
+ * aggregated.
+ *
+ * This method is invoked whenever two sets of Objects are aggregated
+ * together. It is invoked exactly once for each Object in both sets.
+ * This method can be overriden by subclasses who wish to be notified
+ * of aggregation events. These subclasses must chain up to their
+ * base class NotifyNewAggregate() method.
+ *
+ * It is safe to call GetObject() and AggregateObject() from within
+ * this method.
*/
virtual void NotifyNewAggregate (void);
/**
- * This method is called only once by Object::Initialize. If the user
- * calls Object::Initialize multiple times, DoInitialize is called only the
+ * Initialize() implementation.
+ *
+ * This method is called only once by Initialize(). If the user
+ * calls Initialize() multiple times, DoInitialize() is called only the
* first time.
*
- * Subclasses are expected to override this method and _chain up_
+ * Subclasses are expected to override this method and chain up
* to their parent's implementation once they are done. It is
- * safe to call GetObject and AggregateObject from within this method.
+ * safe to call GetObject() and AggregateObject() from within this method.
*/
virtual void DoInitialize (void);
/**
- * This method is called by Object::Dispose or by the object's
+ * Destructor implementation.
+ *
+ * This method is called by Dispose() or by the Object's
* destructor, whichever comes first.
*
* Subclasses are expected to implement their real destruction
* code in an overriden version of this method and chain
* up to their parent's implementation once they are done.
- * i.e., for simplicity, the destructor of every subclass should
+ * _i.e_, for simplicity, the destructor of every subclass should
* be empty and its content should be moved to the associated
- * DoDispose method.
+ * DoDispose() method.
*
- * It is safe to call GetObject from within this method.
+ * It is safe to call GetObject() from within this method.
*/
virtual void DoDispose (void);
/**
- * \param o the object to copy.
+ * Copy an Object.
+ *
+ * \param o the Object to copy.
*
* Allow subclasses to implement a copy constructor.
+ *
* While it is technically possible to implement a copy
* constructor in a subclass, we strongly discourage you
- * to do so. If you really want to do it anyway, you have
+ * from doing so. If you really want to do it anyway, you have
* to understand that this copy constructor will _not_
- * copy aggregated objects. i.e., if your object instance
- * is already aggregated to another object and if you invoke
- * this copy constructor, the new object instance will be
- * a pristine standalone object instance not aggregated to
- * any other object. It is thus _your_ responsability
+ * copy aggregated Objects, _i.e_, if your Object instance
+ * is already aggregated to another Object and if you invoke
+ * this copy constructor, the new )bject instance will be
+ * a pristine standalone Object instance not aggregated to
+ * any other )bject. It is thus _your_ responsability
* as a caller of this method to do what needs to be done
- * (if it is needed) to ensure that the object stays in a
+ * (if it is needed) to ensure that the Object stays in a
* valid state.
*/
Object (const Object &o);
+
private:
+ /**
+ * Copy an Object.
+ *
+ * \param object A pointer to the object to copy.
+ * \returns A copy of the input object.
+ *
+ * This method invoke the copy constructor of the input object
+ * and returns the new instance.
+ */
+ /**@{*/
template <typename T>
friend Ptr<T> CopyObject (Ptr<T> object);
template <typename T>
friend Ptr<T> CopyObject (Ptr<const T> object);
+ /**@}*/
+
+ /**
+ * Set the TypeId and construct all Attributes of an Object.
+ *
+ * \tparam T The type of the derived object we are constructing.
+ * \param [in] object The uninitialized object pointer.
+ * \return The derived object.
+ */
template <typename T>
friend Ptr<T> CompleteConstruct (T *object);
@@ -232,6 +317,8 @@
friend struct ObjectDeleter;
/**
+ * The list of Objects aggregated to this one.
+ *
* This data structure uses a classic C-style trick to
* hold an array of variable size without performing
* two memory allocations: the declaration of the structure
@@ -239,105 +326,110 @@
* memory for this struct, we effectively allocate a larger
* chunk of memory than the struct to allow space for a larger
* variable sized buffer whose size is indicated by the element
- * 'n'
+ * \c n
*/
struct Aggregates {
+ /** The number of entries in \c buffer. */
uint32_t n;
+ /** The array of Objects. */
Object *buffer[1];
};
/**
- * Find an object of TypeId tid in the aggregates of this Object.
+ * Find an Object of TypeId tid in the aggregates of this Object.
*
- * \param tid the TypeId we're looking for
- * \return the matching Object, if it is found
+ * \param tid The TypeId we're looking for
+ * \return The matching Object, if it is found
*/
Ptr<Object> DoGetObject (TypeId tid) const;
/**
- * \return is reference count non zero
+ * Verify that this Object is still live, by checking it's reference count.
+ * \return \c true if the reference count is non zero.
*/
bool Check (void) const;
/**
- * \return Do any of our aggregates have non zero reference count?
+ * Check if any aggregated Objects have non-zero reference counts.
+ *
+ * \return \c true if any of our aggregates have non zero reference count.
*
* In some cases, when an event is scheduled against a subclass of
- * Object, and if no one owns a reference directly to this object, the
- * object is alive, has a refcount of zero and the method ran when the
- * event expires runs against the raw pointer which means that we are
- * manipulating an object with a refcount of zero. So, instead we
+ * Object, and if no one owns a reference directly to this Object, the
+ * Object is alive, has a refcount of zero and the method run when the
+ * event expires runs against the raw pointer, which means that we are
+ * manipulating an Object with a refcount of zero. So, instead we
* check the aggregate reference count.
*/
bool CheckLoose (void) const;
/**
- * \param tid an TypeId
+ * Set the TypeId of this Object.
+
+ * \param tid The TypeId value to set.
*
* Invoked from ns3::CreateObject only.
- * Initialize the m_tid member variable to
- * keep track of the type of this object instance.
+ * Initialize the \c m_tid member variable to
+ * keep track of the type of this Object instance.
*/
void SetTypeId (TypeId tid);
/**
- * \param attributes the attribute values used to initialize
- * the member variables of this object's instance.
- *
- * Invoked from ns3::ObjectFactory::Create and ns3::CreateObject only.
- * Initialize all the member variables which were
- * registered with the associated TypeId.
+ * Initialize all member variables registered as Attributes of this TypeId.
+ *
+ * \param attributes The attribute values used to initialize
+ * the member variables of this Object's instance.
+ *
+ * Invoked from ns3::ObjectFactory::Create and ns3::CreateObject only.
+ * Initialize all the member variables which were
+ * registered with the associated TypeId.
*/
void Construct (const AttributeConstructionList &attributes);
/**
* Keep the list of aggregates in most-recently-used order
*
- * \param aggregates the list of aggregated objects
- * \param i the most recently used entry in the list
+ * \param aggregates The list of aggregated Objects.
+ * \param i The most recently used entry in the list.
*/
void UpdateSortedArray (struct Aggregates *aggregates, uint32_t i) const;
/**
- * Attempt to delete this object. This method iterates
- * over all aggregated objects to check if they all
- * have a zero refcount. If yes, the object and all
+ * Attempt to delete this Object.
+ *
+ * This method iterates over all aggregated Objects to check if they all
+ * have a zero refcount. If yes, the Object and all
* its aggregates are deleted. If not, nothing is done.
*/
void DoDelete (void);
/**
- * Identifies the type of this object instance.
+ * Identifies the type of this Object instance.
*/
TypeId m_tid;
/**
- * Set to true when the DoDispose method of the object
- * has run, false otherwise.
+ * Set to \c true when the DoDispose() method of the Object has run,
+ * \c false otherwise.
*/
bool m_disposed;
/**
- * Set to true once the DoInitialize method has run,
- * false otherwise
+ * Set to \c true once the DoInitialize() method has run,
+ * \c false otherwise
*/
bool m_initialized;
/**
- * a pointer to an array of 'aggregates'. i.e., a pointer to
- * each object aggregated to this object is stored in this
- * array. The array is shared by all aggregated objects
+ * A pointer to an array of 'aggregates'.
+ *
+ * A pointer to each Object aggregated to this Object is stored in this
+ * array. The array is shared by all aggregated Objects
* so the size of the array is indirectly a reference count.
*/
struct Aggregates * m_aggregates;
/**
- * Indicates the number of times the object was accessed with a
- * call to GetObject. This integer is used to implement a
- * heuristic to sort the array of aggregates to put at the start
- * of the array the most-frequently accessed elements.
+ * The number of times the Object was accessed with a
+ * call to GetObject().
+ *
+ * This integer is used to implement a heuristic to sort
+ * the array of aggregates in most-frequently accessed order.
*/
uint32_t m_getObjectCount;
};
-/**
- * \param object a pointer to the object to copy.
- * \returns a copy of the input object.
- *
- * This method invoke the copy constructor of the input object
- * and returns the new instance.
- */
template <typename T>
Ptr<T> CopyObject (Ptr<const T> object);
template <typename T>
@@ -347,16 +439,17 @@
namespace ns3 {
+
+/*************************************************************************
+ * The Object implementation which depends on templates
+ *************************************************************************/
+
void
ObjectDeleter::Delete (Object *object)
{
object->DoDelete ();
}
-/*************************************************************************
- * The Object implementation which depends on templates
- *************************************************************************/
-
template <typename T>
Ptr<T>
Object::GetObject () const
@@ -410,61 +503,161 @@
}
template <typename T>
-Ptr<T> CompleteConstruct (T *p)
+Ptr<T> CompleteConstruct (T *object)
{
- p->SetTypeId (T::GetTypeId ());
- p->Object::Construct (AttributeConstructionList ());
- return Ptr<T> (p, false);
+ object->SetTypeId (T::GetTypeId ());
+ object->Object::Construct (AttributeConstructionList ());
+ return Ptr<T> (object, false);
}
+/**
+ * \ingroup object
+ * @{
+ */
+/**
+ * Create an object by type, with varying number of constructor parameters.
+ *
+ * \tparam T The type of the derived object to construct.
+ * \return The derived object.
+ */
template <typename T>
Ptr<T> CreateObject (void)
{
return CompleteConstruct (new T ());
}
-
+/**
+ * \copybrief CreateObject()
+ * \tparam T The type of the derived object to construct.
+ * \tparam T1 The type of the constructor argument.
+ * \param a1 The constructor argument
+ * \return The derived object.
+ */
template <typename T, typename T1>
Ptr<T> CreateObject (T1 a1)
{
return CompleteConstruct (new T (a1));
}
+/**
+ * \copybrief CreateObject()
+ * \tparam T The type of the derived object to construct.
+ * \tparam T1 The type of the first constructor argument.
+ * \tparam T2 The type of the second constructor argument.
+ * \param a1 The constructor first argument
+ * \param a2 The constructor second argument
+ * \return The derived object.
+ */
template <typename T, typename T1, typename T2>
Ptr<T> CreateObject (T1 a1, T2 a2)
{
return CompleteConstruct (new T (a1,a2));
}
+/**
+ * \copybrief CreateObject()
+ * \tparam T The type of the derived object to construct.
+ * \tparam T1 The type of the first constructor argument.
+ * \tparam T2 The type of the second constructor argument.
+ * \tparam T3 The type of the third constructor argument.
+ * \param a1 The constructor first argument
+ * \param a2 The constructor second argument
+ * \param a3 The constructor third argument
+ * \return The derived object.
+ */
template <typename T, typename T1, typename T2, typename T3>
Ptr<T> CreateObject (T1 a1, T2 a2, T3 a3)
{
return CompleteConstruct (new T (a1,a2,a3));
}
+/**
+ * \copybrief CreateObject()
+ * \tparam T The type of the derived object to construct.
+ * \tparam T1 The type of the first constructor argument.
+ * \tparam T2 The type of the second constructor argument.
+ * \tparam T3 The type of the third constructor argument.
+ * \tparam T4 The type of the fourth constructor argument.
+ * \param a1 The constructor first argument
+ * \param a2 The constructor second argument
+ * \param a3 The constructor third argument
+ * \param a4 The constructor fourth argument
+ * \return The derived object.
+ */
template <typename T, typename T1, typename T2, typename T3, typename T4>
Ptr<T> CreateObject (T1 a1, T2 a2, T3 a3, T4 a4)
{
return CompleteConstruct (new T (a1,a2,a3,a4));
}
+/**
+ * \copybrief CreateObject()
+ * \tparam T The type of the derived object to construct.
+ * \tparam T1 The type of the first constructor argument.
+ * \tparam T2 The type of the second constructor argument.
+ * \tparam T3 The type of the third constructor argument.
+ * \tparam T4 The type of the fourth constructor argument.
+ * \tparam T5 The type of the fifth constructor argument.
+ * \param a1 The constructor first argument
+ * \param a2 The constructor second argument
+ * \param a3 The constructor third argument
+ * \param a4 The constructor fourth argument
+ * \param a5 The constructor fifth argument
+ * \return The derived object.
+ */
template <typename T, typename T1, typename T2, typename T3, typename T4, typename T5>
Ptr<T> CreateObject (T1 a1, T2 a2, T3 a3, T4 a4, T5 a5)
{
return CompleteConstruct (new T (a1,a2,a3,a4,a5));
}
+/**
+ * \copybrief CreateObject()
+ * \tparam T The type of the derived object to construct.
+ * \tparam T1 The type of the first constructor argument.
+ * \tparam T2 The type of the second constructor argument.
+ * \tparam T3 The type of the third constructor argument.
+ * \tparam T4 The type of the fourth constructor argument.
+ * \tparam T5 The type of the fifth constructor argument.
+ * \tparam T6 The type of the sixth constructor argument.
+ * \param a1 The constructor first argument
+ * \param a2 The constructor second argument
+ * \param a3 The constructor third argument
+ * \param a4 The constructor fourth argument
+ * \param a5 The constructor fifth argument
+ * \param a6 The constructor sixth argument
+ * \return The derived object.
+ */
template <typename T, typename T1, typename T2, typename T3, typename T4, typename T5, typename T6>
Ptr<T> CreateObject (T1 a1, T2 a2, T3 a3, T4 a4, T5 a5, T6 a6)
{
return CompleteConstruct (new T (a1,a2,a3,a4,a5,a6));
}
+/**
+ * \copybrief CreateObject()
+ * \tparam T The type of the derived object to construct.
+ * \tparam T1 The type of the first constructor argument.
+ * \tparam T2 The type of the second constructor argument.
+ * \tparam T3 The type of the third constructor argument.
+ * \tparam T4 The type of the fourth constructor argument.
+ * \tparam T5 The type of the fifth constructor argument.
+ * \tparam T6 The type of the sixth constructor argument.
+ * \tparam T7 The type of the seventh constructor argument.
+ * \param a1 The constructor first argument
+ * \param a2 The constructor second argument
+ * \param a3 The constructor third argument
+ * \param a4 The constructor fourth argument
+ * \param a5 The constructor fifth argument
+ * \param a6 The constructor sixth argument
+ * \param a7 The constructor seventh argument
+ * \return The derived object.
+ */
template <typename T, typename T1, typename T2, typename T3, typename T4, typename T5, typename T6, typename T7>
Ptr<T> CreateObject (T1 a1, T2 a2, T3 a3, T4 a4, T5 a5, T6 a6, T7 a7)
{
return CompleteConstruct (new T (a1,a2,a3,a4,a5,a6,a7));
}
-
+/**@}*/
} // namespace ns3