# HG changeset patch # User Peter D. Barnes, Jr. # Date 1418018884 28800 # Node ID e57bfdb4f12c4a88dbb2e74b3a09465d0da3de5a # Parent be1aa0c5ac72e0b15f299cea159e3822d50a650a [Doxygen] Objects diff -r be1aa0c5ac72 -r e57bfdb4f12c src/core/model/object-base.cc --- a/src/core/model/object-base.cc Sun Dec 07 20:53:37 2014 -0800 +++ b/src/core/model/object-base.cc Sun Dec 07 22:08:04 2014 -0800 @@ -27,12 +27,26 @@ #include #endif +/** + * \file + * \ingroup object + * ns3::ObjectBase class definition. + */ + namespace ns3 { NS_LOG_COMPONENT_DEFINE ("ObjectBase"); NS_OBJECT_ENSURE_REGISTERED (ObjectBase); +/** + * Ensure the TypeId for ObjectBase gets fully configured + * to anchor the inheritance tree properly. + * + * \relates ns3::ObjectBase + * + * \return The TypeId for ObjectBase. + */ static TypeId GetObjectIid (void) { diff -r be1aa0c5ac72 -r e57bfdb4f12c src/core/model/object-base.h --- a/src/core/model/object-base.h Sun Dec 07 20:53:37 2014 -0800 +++ b/src/core/model/object-base.h Sun Dec 07 22:08:04 2014 -0800 @@ -26,8 +26,14 @@ #include /** + * \file * \ingroup object - * \brief Register the class in the ns-3 factory. + * ns3::ObjectBase class declaration and NS_OBJECT_ENSURE_REGISTERED() definition. + */ + +/** + * \ingroup object + * \brief Register an Object subclass with the TypeId system. * * This macro should be invoked once for every class which * defines a new GetTypeId method. @@ -52,12 +58,12 @@ /** * \ingroup object * - * \brief implement the ns-3 type and attribute system + * \brief Anchor the ns-3 type and attribute system. * * Every class which wants to integrate in the ns-3 type and attribute * system should derive from this base class. This base class provides: - * - a way to associate an ns3::TypeId to each object instance - * - a way to set and get the attributes registered in the ns3::TypeId. + * - A way to associate an ns3::TypeId to each object instance. + * - A way to set and get the attributes registered in the ns3::TypeId. */ class ObjectBase { @@ -68,83 +74,125 @@ static TypeId GetTypeId (void); /** - * Virtual destructor + * Virtual destructor. */ virtual ~ObjectBase (); /** - * \return the TypeId associated to the most-derived type - * of this instance. + * Get the most derived TypeId for this Object. * * This method is typically implemented by ns3::Object::GetInstanceTypeId * but some classes which derive from ns3::ObjectBase directly * have to implement it themselves. + * + * \return The TypeId associated to the most-derived type + * of this instance. */ virtual TypeId GetInstanceTypeId (void) const = 0; /** - * \param name the name of the attribute to set - * \param value the name of the attribute to set + * + * Set a single attribute, raising fatal errors if unsuccessful. + * + * This will either succeed at setting the attribute + * or it will raise NS_FATAL_ERROR() on these conditions: * - * Set a single attribute. This cannot fail: if the input is invalid, - * it will crash immediately. + * - The attribute doesn't exist in this Object. + * - The attribute can't be set (no Setter). + * - The attribute couldn't be deserialized from the AttributeValue. + * + * \param [in] name The name of the attribute to set. + * \param [in] value The name of the attribute to set. */ void SetAttribute (std::string name, const AttributeValue &value); /** - * \param name the name of the attribute to set - * \param value the name of the attribute to set - * \return true if the requested attribute exists and could be set, - * false otherwise. + * Set a single attribute without raising errors. + * + * If the atttribute could not be set this will return \c false, + * but not raise any errors. + * + * \param [in] name The name of the attribute to set. + * \param [in] value The value to set it to. + * \return \c true if the requested attribute exists and could be set, + * \c false otherwise. */ bool SetAttributeFailSafe (std::string name, const AttributeValue &value); /** - * \param name the name of the attribute to read - * \param value a reference to the value where the result should be stored. - * \return the attribute read. + * Get the value of an attribute, raising fatal errors if unsuccessful. + * + * This will either succeed at setting the attribute + * or it will raise NS_FATAL_ERROR() on these conditions: * - * If the input attribute name does not exist, this method crashes. + * - The attribute doesn't exist in this Object. + * - The attribute can't be read (no Getter). + * - The attribute doesn't support string formatting. + * - The attribute couldn't be serialized into the AttributeValue. + * + * \param [in] name The name of the attribute to read. + * \param [out] value Where the result should be stored. */ void GetAttribute (std::string name, AttributeValue &value) const; /** - * \param name the name of the attribute to read - * \param attribute the attribute where the result value should be stored - * \return true if the requested attribute was found, false otherwise. + * Get the value of an attribute without raising erros. + * + * If the atttribute could not be read this will return \c false, + * but not raise any errors. + * + * \param [in] name The name of the attribute to read. + * \param [out] value Where the result value should be stored. + * \return \c true if the requested attribute was found, \c false otherwise. */ - bool GetAttributeFailSafe (std::string name, AttributeValue &attribute) const; + bool GetAttributeFailSafe (std::string name, AttributeValue &value) const; /** - * \param name the name of the targetted trace source - * \param context the trace context associated to the callback - * \param cb the callback to connect to the trace source. + * Connect a TraceSource to a Callback with a context. + * + * The target trace source should be registered with TypeId::AddTraceSource. * - * The targetted trace source should be registered with TypeId::AddTraceSource. + * \param name The name of the target trace source. + * \param context The trace context associated to the callback. + * \param cb The callback to connect to the trace source. + * \returns \c true. */ bool TraceConnect (std::string name, std::string context, const CallbackBase &cb); /** - * \param name the name of the targetted trace source - * \param cb the callback to connect to the trace source. + * Connect a TraceSource to a Callback without a context. + * + * The target trace source should be registered with TypeId::AddTraceSource. * - * The targetted trace source should be registered with TypeId::AddTraceSource. + * \param name The name of the target trace source. + * \param cb The callback to connect to the trace source. + * \returns \c true. */ bool TraceConnectWithoutContext (std::string name, const CallbackBase &cb); /** - * \param name the name of the targetted trace source - * \param context the trace context associated to the callback - * \param cb the callback to disconnect from the trace source. + * Disconnect from a TraceSource a Callback previously connected + * with a context. + * + * The target trace source should be registered with TypeId::AddTraceSource. * - * The targetted trace source should be registered with TypeId::AddTraceSource. + * \param name The name of the target trace source. + * \param context The trace context associated to the callback. + * \param cb The callback to disconnect from the trace source. + * \returns \c true. */ bool TraceDisconnect (std::string name, std::string context, const CallbackBase &cb); /** - * \param name the name of the targetted trace source - * \param cb the callback to disconnect from the trace source. + * Disconnect from a TraceSource a Callback previously connected + * without a context. * - * The targetted trace source should be registered with TypeId::AddTraceSource. + * The target trace source should be registered with TypeId::AddTraceSource. + * + * \param name The name of the target trace source. + * \param cb The callback to disconnect from the trace source. + * \returns \c true. */ bool TraceDisconnectWithoutContext (std::string name, const CallbackBase &cb); protected: /** + * Notifier called once the ObjectBase is fully constructucted. + * * This method is invoked once all member attributes have been * initialized. Subclasses can override this method to be notified * of this event but if they do this, they must chain up to their @@ -152,8 +200,7 @@ */ virtual void NotifyConstructionCompleted (void); /** - * \param attributes the attribute values used to initialize - * the member variables of this object's instance. + * Complete construction of ObjectBase; invoked by derived classes. * * Invoked from subclasses to initialize all of their * attribute members. This method will typically be invoked @@ -161,6 +208,9 @@ * from ns3::Object. If you derive from ns3::ObjectBase directly, * you should make sure that you invoke this method from * your most-derived constructor. + * + * \param attributes The attribute values used to initialize + * the member variables of this object's instance. */ void ConstructSelf (const AttributeConstructionList &attributes); @@ -172,7 +222,7 @@ * \param [in] spec The accessor for the storage location. * \param [in] checker The checker to use in validating the value. * \param [in] value The value to attempt to store. - * \returns true if the \c value could be validated by the \p checker + * \returns \c true if the \c value could be validated by the \p checker * and written to the storage location. */ bool DoSet (Ptr spec, diff -r be1aa0c5ac72 -r e57bfdb4f12c src/core/model/object-factory.h --- a/src/core/model/object-factory.h Sun Dec 07 20:53:37 2014 -0800 +++ b/src/core/model/object-factory.h Sun Dec 07 22:08:04 2014 -0800 @@ -24,6 +24,12 @@ #include "object.h" #include "type-id.h" +/** + * \file + * \ingroup object + * ns3::ObjectFactory class declaration. + */ + namespace ns3 { class AttributeValue; @@ -31,7 +37,7 @@ /** * \ingroup object * - * \brief instantiate subclasses of ns3::Object. + * \brief Instantiate subclasses of ns3::Object. * * This class can also hold a set of attributes to set * automatically during the object construction. @@ -41,53 +47,95 @@ class ObjectFactory { public: + /** + * Default constructor. + * + * This factory is not capable of constructing a real Object + * until it has at least a TypeId. + */ ObjectFactory (); + /** + * Construct a factory for a specific TypeId by name. + * + * \param typeId The name of the TypeId this factory should create. + */ ObjectFactory (std::string typeId); /** - * \param tid the TypeId of the object to instantiate. + * Set the TypeId of the Objects to be created by this factory. + * + * \param tid The TypeId of the object to instantiate. */ + /**@{*/ void SetTypeId (TypeId tid); - /** - * \param tid the TypeId of the object to instantiate. - */ void SetTypeId (const char *tid); + void SetTypeId (std::string tid); + /**@}*/ + /** - * \param tid the TypeId of the object to instantiate. - */ - void SetTypeId (std::string tid); - /** - * \param name the name of the attribute to set during object construction - * \param value the value of the attribute to set during object construction + * Set an attribute to be set during construction. + * + * \param name The name of the attribute to set. + * \param value The value of the attribute to set. */ void Set (std::string name, const AttributeValue &value); /** - * \returns the currently-selected TypeId to use to create an object - * instance. + * Get the TypeId which will be created by this ObjectFactory. + * \returns The currently-selected TypeId. */ TypeId GetTypeId (void) const; /** - * \returns a new object instance. + * Create an Object instance of the configured TypeId. + * + * \returns A new object instance. */ Ptr Create (void) const; /** - * \returns a new object instance. + * Create an Object instance of the requested type. * * This method performs an extra call to ns3::Object::GetObject before * returning a pointer of the requested type to the user. This method * is really syntactical sugar. + * + * \tparam T The requested Object type. + * \returns A new object instance. */ template Ptr Create (void) const; private: + /** + * Print the factory configuration on an output stream. + * + * The configuration will be printed as a string with the form + * "[=|...]" + * + * \param [in] os The stream. + * \param [in] factory The ObjectFactory. + * \returns The stream. + */ friend std::ostream & operator << (std::ostream &os, const ObjectFactory &factory); + /** + * Read a factory configuration from an input stream. + * + * The configuration should be in the form + * "[=|...]" + * + * \param [in] is The input stream. + * \param [out] factory The factory to configure as described by the stream. + * \return The stream. + */ friend std::istream & operator >> (std::istream &is, ObjectFactory &factory); + /** The TypeId this factory will create. */ TypeId m_tid; - AttributeConstructionList m_parameters; + /** + * The list of attributes and values to be used in constructing + * objects by this factory. + */ + AttributeConstructionList m_parameters; }; std::ostream & operator << (std::ostream &os, const ObjectFactory &factory); @@ -95,28 +143,29 @@ /** - * \param n1 name of attribute - * \param v1 value of attribute - * \param n2 name of attribute - * \param v2 value of attribute - * \param n3 name of attribute - * \param v3 value of attribute - * \param n4 name of attribute - * \param v4 value of attribute - * \param n5 name of attribute - * \param v5 value of attribute - * \param n6 name of attribute - * \param v6 value of attribute - * \param n7 name of attribute - * \param v7 value of attribute - * \param n8 name of attribute - * \param v8 value of attribute - * \param n9 name of attribute - * \param v9 value of attribute - * \returns a pointer to a newly allocated object. + * \ingroup object + * Allocate an Object on the heap and initialize with a set of attributes. * - * This allocates an object on the heap and initializes - * it with a set of attributes. + * \tparam T The requested Object type. + * \param n1 Name of attribute + * \param v1 Value of attribute + * \param n2 Name of attribute + * \param v2 Value of attribute + * \param n3 Name of attribute + * \param v3 Value of attribute + * \param n4 Name of attribute + * \param v4 Value of attribute + * \param n5 Name of attribute + * \param v5 Value of attribute + * \param n6 Name of attribute + * \param v6 Value of attribute + * \param n7 Name of attribute + * \param v7 Value of attribute + * \param n8 Name of attribute + * \param v8 Value of attribute + * \param n9 Name of attribute + * \param v9 Value of attribute + * \returns A pointer to a newly allocated object. */ template Ptr diff -r be1aa0c5ac72 -r e57bfdb4f12c src/core/model/object-ptr-container.h --- a/src/core/model/object-ptr-container.h Sun Dec 07 20:53:37 2014 -0800 +++ b/src/core/model/object-ptr-container.h Sun Dec 07 22:08:04 2014 -0800 @@ -28,9 +28,9 @@ namespace ns3 { /** - * \ingroup object + * \ingroup attribute_ObjectPtrContainer * - * \brief contain a set of ns3::Object pointers. + * \brief Container for a set of ns3::Object pointers. * * This class it used to get attribute access to an array of * ns3::Object pointers. @@ -45,25 +45,53 @@ ObjectPtrContainerValue (); /** - * \returns an iterator to the first object contained in this set + * Get an iterator to the first Object. + * + * \returns An iterator to the first Object. */ Iterator Begin (void) const; /** - * \returns an iterator to the last object contained in this set + * Get an iterator to the _past-the-end_ Object. + * + * \returns An iterator to the _past-the-end_ Object. */ Iterator End (void) const; /** - * \returns the number of objects contained in this set. + * Get the number of Objects. + * + * \returns The number of objects. */ uint32_t GetN (void) const; /** - * \param i the index of the requested object. - * \returns the requested object + * Get a specific Object. + * + * \param i The index of the requested object. + * \returns The requested object */ Ptr Get (uint32_t i) const; + /** + * Get a copy of this container. + * + * \returns A copy of this container. + */ virtual Ptr Copy (void) const; + /** + * Serialize each of the Object pointers to a string. + * + * Note this serializes the Ptr values, not the Objects themselves. + * + * \param checker The checker to use (currently not used.) + * \returns The string form of the Objects. + */ virtual std::string SerializeToString (Ptr checker) const; + /** + * Deserialize from a string. (Not implemented; raises a fatal error.) + * + * \param value The serialized string form. + * \param checker The checker to use. + * \returns \c true. + */ virtual bool DeserializeFromString (std::string value, Ptr checker); private: @@ -174,7 +202,10 @@ } // namespace internal -/** AttributeAccessor implementation for ObjectPtrContainerValue. */ +/** + * \ingroup attribute_ObjectPtrContainer + * AttributeAccessor implementation for ObjectPtrContainerValue. + */ class ObjectPtrContainerAccessor : public AttributeAccessor { public: diff -r be1aa0c5ac72 -r e57bfdb4f12c src/core/model/object.cc --- a/src/core/model/object.cc Sun Dec 07 20:53:37 2014 -0800 +++ b/src/core/model/object.cc Sun Dec 07 22:08:04 2014 -0800 @@ -31,7 +31,11 @@ #include #include - +/** + * \file + * \ingroup object + * ns3::Object class definition. + */ namespace ns3 { @@ -368,6 +372,7 @@ for (uint32_t i = 0; i < n; i++) { Object *current = m_aggregates->buffer[i]; + /// \todo Shortcircuit this loop. refcount += current->GetReferenceCount (); } return (refcount > 0); diff -r be1aa0c5ac72 -r e57bfdb4f12c src/core/model/object.h --- 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 +class Object : public SimpleRefCount { 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 Next (void); private: friend class Object; - AggregateIterator (Ptr object); //!< Constructor - Ptr 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 object); + Ptr 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 inline Ptr 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 Ptr 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 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 friend Ptr CopyObject (Ptr object); template friend Ptr CopyObject (Ptr 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 friend Ptr 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 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 Ptr CopyObject (Ptr object); template @@ -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 Ptr Object::GetObject () const @@ -410,61 +503,161 @@ } template -Ptr CompleteConstruct (T *p) +Ptr CompleteConstruct (T *object) { - p->SetTypeId (T::GetTypeId ()); - p->Object::Construct (AttributeConstructionList ()); - return Ptr (p, false); + object->SetTypeId (T::GetTypeId ()); + object->Object::Construct (AttributeConstructionList ()); + return Ptr (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 Ptr 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 Ptr 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 Ptr 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 Ptr 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 Ptr 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 Ptr 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 Ptr 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 Ptr 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