From 603615d2d064de83ea0e33ec00878c6dcbaf38c6 Mon Sep 17 00:00:00 2001 From: Mathieu Lacage Date: Mon, 10 Mar 2008 13:09:32 -0700 Subject: [PATCH] doxygen doc --- src/core/attribute.h | 122 ++++++++++++++++++++++++++++++++++++- src/core/object-factory.cc | 7 +-- src/core/object-factory.h | 35 ++++++++++- src/core/object.cc | 50 ++++----------- src/core/object.h | 78 ++++++++++++++++++++---- 5 files changed, 234 insertions(+), 58 deletions(-) diff --git a/src/core/attribute.h b/src/core/attribute.h index 1959176ca..3082cf15d 100644 --- a/src/core/attribute.h +++ b/src/core/attribute.h @@ -31,6 +31,14 @@ class AttributeAccessor; class AttributeChecker; class Attribute; +/** + * \brief Hold a value for an Attribute. + * + * Instances of this class are usually created by Attribute::Create<> and + * should always be wrapped into an Attribute object. + * Most subclasses of this base class are implemented by the + * ATTRIBUTE_HELPER_* macros. + */ class AttributeValue { public: @@ -39,14 +47,49 @@ public: AttributeValue &operator = (const AttributeValue &o); virtual ~AttributeValue (); + /** + * \returns a deep copy of this class, wrapped into an Attribute object. + */ virtual Attribute Copy (void) const = 0; + /** + * \param checker the checker associated to the attribute + * \returns a string representation of this value. + * + * In most cases, this method will not make any use of the checker argument. + * However, in a very limited set of cases, the checker argument is needed to + * perform proper serialization. A nice example of code which needs it is + * the EnumValue::SerializeToString code. + */ virtual std::string SerializeToString (Ptr checker) const = 0; + /** + * \param value a string representation of the value + * \param checker a pointer to the checker associated to the attribute. + * \returns true if the input string was correctly-formatted and could be + * successfully deserialized, false otherwise. + * + * Upon return of this function, this AttributeValue instance contains + * the deserialized value. + * In most cases, this method will not make any use of the checker argument. + * However, in a very limited set of cases, the checker argument is needed to + * perform proper serialization. A nice example of code which needs it is + * the EnumValue::SerializeToString code. + */ virtual bool DeserializeFromString (std::string value, Ptr checker) = 0; private: friend class Attribute; uint32_t m_count; }; +/** + * \brief an opaque wrapper around a value to set or retrieved + * from an attribute. + * + * This class is really a smart pointer to an instance of AttributeValue. + * Of course, the question is "why not use a Ptr" ?. The + * answer is long and complicated but the crux of the issue is that if we + * do not reproduce the smart pointer code in this class, we cannot provide + * transparent handling of Ptr values through the attribute system. + */ class Attribute { public: @@ -55,20 +98,51 @@ public: Attribute &operator = (const Attribute &o); ~Attribute (); + /** + * Forward to AttributeValue::Copy + */ Attribute Copy (void) const; + /** + * Forward to AttributeValue::SerializeToString + */ std::string SerializeToString (Ptr checker) const; + /** + * Forward to AttributeValue::DeserializeFromString + */ bool DeserializeFromString (std::string value, Ptr checker); + /** + * \returns a new Attribute object which wraps an instance of the requested + * subclass of AttributeValue. + */ template static Attribute Create (void); + /** + * \param a1 a value to pass through to the constructor of the class T. + * \returns a new Attribute object which wraps an instance of the requested + * subclass of AttributeValue. + */ template static Attribute Create (T1 a1); + /** + * This method performs a dynamic_cast on the underlying AttributeValue. + * This method is typically used to implement conversion operators + * from the type Attribute. In most cases, these conversion operators + * will be generated for you by the ATTRIBUTE_HELPER_* macros. + * \returns the casted pointer. + */ template T DynCast (void) const; + /** + * \param pointer a pointer to convert into an Attribute. + */ template Attribute (Ptr pointer); + /** + * \returns a pointer converted from this Attribute instance. + */ template operator Ptr (); @@ -77,6 +151,14 @@ private: AttributeValue *m_value; }; +/** + * \brief allow setting and getting the value of an attribute. + * + * The goal of this class is to hide from the user how an attribute + * is actually set or get to or from a class instance. Implementations + * of this base class are usually provided through the MakeAccessorHelper + * template functions, hidden behind an ATTRIBUTE_HELPER_* macro. + */ class AttributeAccessor : public ObjectBase { public: @@ -88,15 +170,38 @@ public: /** * \param object the object instance to set the value in * \param value the value to set - * \returns true if the value is valid and it could be set - * successfully, false otherwise. + * \returns true if the value could be set successfully, false otherwise. + * + * This method expects that the caller has checked that the input value is + * valid with AttributeChecker::Check. */ virtual bool Set (ObjectBase * object, Attribute value) const = 0; + /** + * \param object the object instance to get the value from + * \param attribute a pointer to where the value should be set. + * \returns true if the value could be read successfully, and + * stored in the input value, false otherwise. + * + * This method expects that the caller has checked that the input value is + * valid with AttributeChecker::Check. + */ virtual bool Get (const ObjectBase * object, Attribute value) const = 0; private: mutable uint32_t m_count; }; +/** + * \brief Represent the type of an attribute + * + * Each type of attribute has an associated unique AttributeChecker + * subclass. The type of the subclass can be safely used by users + * to infer the type of the associated attribute. i.e., we expect + * binding authors to use the checker associated to an attribute + * to detect the type of the associated attribute. + * + * Most subclasses of this base class are implemented by the + * ATTRIBUTE_HELPER_* macros. + */ class AttributeChecker : public ObjectBase { public: @@ -104,7 +209,20 @@ public: void Ref (void) const; void Unref (void) const; virtual ~AttributeChecker (); + /** + * \param value a pointer to the value to check + * \returns true if the input value is both of the right type + * and if its value is within the requested range. Returns + * false otherwise. + */ virtual bool Check (Attribute value) const = 0; + /** + * \returns a new instance of an AttributeValue (wrapper in an Attribute + * instance) which matches the type of the underlying attribute. + * + * This method is typically used to create a temporary variable prior + * to calling Attribute::DeserializeFromString. + */ virtual Attribute Create (void) const = 0; private: mutable uint32_t m_count; diff --git a/src/core/object-factory.cc b/src/core/object-factory.cc index 4a784a0fe..a42a896ed 100644 --- a/src/core/object-factory.cc +++ b/src/core/object-factory.cc @@ -28,10 +28,7 @@ ObjectFactory::Set (std::string name, Attribute value) { return; } - if (!m_parameters.SetWithTid (m_tid, name, value)) - { - NS_FATAL_ERROR ("Error setting attribute name="<> (std::istream &is, ObjectFactory &factory) { + // XXX return is; } diff --git a/src/core/object-factory.h b/src/core/object-factory.h index 2fe9ed927..2cb85a4ab 100644 --- a/src/core/object-factory.h +++ b/src/core/object-factory.h @@ -6,19 +6,52 @@ namespace ns3 { +/** + * \brief instantiate subclasses of ns3::Object. + * + * This class can also hold a set of attributes to set + * automatically during the object construction. + */ class ObjectFactory { public: ObjectFactory (); + /** + * \param tid the TypeId of the object to instantiate. + */ void SetTypeId (TypeId tid); - void SetTypeId (std::string tid); + /** + * \param tid the TypeId of the object to instantiate. + */ void SetTypeId (const char *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 + */ void Set (std::string name, Attribute value); + /** + * \returns the currently-selected TypeId to use to create an object + * instance. + */ TypeId GetTypeId (void) const; + /** + * \returns a new object instance. + */ Ptr Create (void) const; + /** + * \returns a new object instance. + * + * 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. + */ template Ptr Create (void) const; diff --git a/src/core/object.cc b/src/core/object.cc index 9c5cebdfd..8d9009d27 100644 --- a/src/core/object.cc +++ b/src/core/object.cc @@ -390,7 +390,7 @@ TypeId::TypeId () : m_tid (0) {} -TypeId::TypeId (const char * name) +TypeId::TypeId (const char *name) { uint16_t uid = Singleton::Get ()->AllocateUid (name); NS_ASSERT (uid != 0); @@ -474,31 +474,6 @@ TypeId::LookupAttributeByName (std::string name, struct TypeId::AttributeInfo *i } while (nextTid != tid); return false; } -bool -TypeId::LookupAttributeByPosition (uint32_t i, struct TypeId::AttributeInfo *info) const -{ - uint32_t cur = 0; - TypeId tid; - TypeId nextTid = *this; - do { - tid = nextTid; - for (uint32_t j = 0; j < tid.GetAttributeListN (); j++) - { - if (cur == i) - { - info->accessor = tid.GetAttributeAccessor (j); - info->flags = tid.GetAttributeFlags (j); - info->initialValue = tid.GetAttributeInitialValue (j); - info->checker = tid.GetAttributeChecker (j); - return true; - } - cur++; - } - nextTid = tid.GetParent (); - } while (nextTid != tid); - return false; -} - TypeId TypeId::SetParent (TypeId tid) @@ -793,21 +768,20 @@ AttributeList::SetFailSafe (std::string name, Attribute value) bool ok = DoSet (&info, value); return ok; } -bool +void AttributeList::SetWithTid (TypeId tid, std::string name, Attribute value) { struct TypeId::AttributeInfo info; - tid.LookupAttributeByName (name, &info); - bool ok = DoSet (&info, value); - return ok; -} -bool -AttributeList::SetWithTid (TypeId tid, uint32_t position, Attribute value) -{ - struct TypeId::AttributeInfo info; - tid.LookupAttributeByPosition (position, &info); - bool ok = DoSet (&info, value); - return ok; + bool ok = tid.LookupAttributeByName (name, &info); + if (!ok) + { + NS_FATAL_ERROR ("Could not find attribute "< accessor, Ptr checker); + /** + * \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. + * \returns this TypeId instance. + */ TypeId AddTraceSource (std::string name, std::string help, Ptr accessor); + /** + * \brief store together a set of attribute properties. + */ struct AttributeInfo { + // The accessor associated to the attribute. Ptr accessor; + // The initial value associated to the attribute. Attribute initialValue; + // The set of access control flags associated to the attribute. uint32_t flags; + // The checker associated to the attribute. Ptr checker; }; /** * \param name the name of the requested attribute + * \param info a pointer to the TypeId::AttributeInfo data structure + * where the result value of this method will be stored. + * \returns true if the requested attribute could be found, false otherwise. */ bool LookupAttributeByName (std::string name, struct AttributeInfo *info) const; @@ -280,11 +315,6 @@ private: Ptr LookupTraceSourceByName (std::string name) const; - /** - * \param i the position of the requested attribute - * \returns the Accessor associated to the requested attribute - */ - bool LookupAttributeByPosition (uint32_t i, struct AttributeInfo *info) const; /** * \param fullName the full name of the requested attribute * \returns the Accessor associated to the requested attribute @@ -317,7 +347,7 @@ public: AttributeList &operator = (const AttributeList &o); ~AttributeList (); /** - * \param name the name of the attribute to set + * \param name the full name of the attribute to set * \param value the value to set * * This method checks that a attribute with the requested @@ -326,10 +356,24 @@ public: * the program terminates with a message. */ void Set (std::string name, Attribute value); + /** + * \param name the full name of the attribute to set + * \param value the value to set + * \returns true if the requested attribute exists and could be + * stored, false otherwise. + */ bool SetFailSafe (std::string name, Attribute value); - - bool SetWithTid (TypeId tid, std::string name, Attribute value); - bool SetWithTid (TypeId tid, uint32_t position, Attribute value); + /** + * \param tid the TypeId associated to this attribute + * \param name the name (not full!) of the attribute + * \param value the value to set + * + * This method checks that a attribute with the requested + * name exists and that the value specified is an acceptable + * value of that attribute. If any of these checks fails, + * the program terminates with a message. + */ + void SetWithTid (TypeId tid, std::string name, Attribute value); /** * Clear the content of this instance. @@ -348,6 +392,7 @@ public: */ static AttributeList *GetGlobal (void); + // XXX: untested. std::string SerializeToString (void) const; bool DeserializeFromString (std::string value); private: @@ -390,6 +435,12 @@ public: * it will crash immediately. */ void SetAttribute (std::string name, Attribute value); + /** + * \param name the name of the attribute to set + * \param value the name of the attribute to set + * \returns true if the requested attribute exists and could be set, + * false otherwise. + */ bool SetAttributeFailSafe (std::string name, Attribute value); /** * \param name the name of the attribute to read @@ -402,7 +453,8 @@ public: * \param name the name of the attribute to read * \param value a reference to the object where the value of the * attribute should be stored. - * \returns true if the requested attribute was found, false otherwise. + * + * If the input attribute name does not exist, this method crashes. */ Attribute GetAttribute (std::string name) const;