F5/unison
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

doxygen doc

Browse Source
This commit is contained in:
Mathieu Lacage
2008-03-10 13:09:32 -07:00
parent a4c5f55812
commit 603615d2d0
5 changed files with 234 additions and 58 deletions
Download Patch File Download Diff File Expand all files Collapse all files

122
src/core/attribute.h
View File

@@ -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<const AttributeChecker> 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<const AttributeChecker> 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<AttributeValue>" ?. 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<T> 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<const AttributeChecker> checker) const;
/**
* Forward to AttributeValue::DeserializeFromString
*/
bool DeserializeFromString (std::string value, Ptr<const AttributeChecker> checker);
/**
* \returns a new Attribute object which wraps an instance of the requested
* subclass of AttributeValue.
*/
template <typename T>
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 <typename T, typename T1>
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 <typename T>
T DynCast (void) const;
/**
* \param pointer a pointer to convert into an Attribute.
*/
template <typename T>
Attribute (Ptr<T> pointer);
/**
* \returns a pointer converted from this Attribute instance.
*/
template <typename T>
operator Ptr<T> ();
@@ -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;

7
src/core/object-factory.cc
View File

@@ -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="<<name);
}
m_parameters.SetWithTid (m_tid, name, value);
}
TypeId
@@ -49,10 +46,12 @@ ObjectFactory::Create (void) const
std::ostream & operator << (std::ostream &os, const ObjectFactory &factory)
{
// XXX
return os;
}
std::istream & operator >> (std::istream &is, ObjectFactory &factory)
{
// XXX
return is;
}

35
src/core/object-factory.h
View File

@@ -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<Object> 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 <typename T>
Ptr<T> Create (void) const;

50
src/core/object.cc
View File

@@ -390,7 +390,7 @@ TypeId::TypeId ()
: m_tid (0)
{}
TypeId::TypeId (const char * name)
TypeId::TypeId (const char *name)
{
uint16_t uid = Singleton<IidManager>::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 "<<tid.GetName ()<<"::"<<name);
}
ok = DoSet (&info, value);
if (!ok)
{
NS_FATAL_ERROR ("Could not set value for attribute "<<tid.GetName ()<<"::"<<name);
}
}
void

78
src/core/object.h
View File

@@ -30,6 +30,10 @@
#include "object-base.h"
#include "attribute-helper.h"
/**
* This macro should be invoked once for every class which
* defines a new GetTypeId method.
*/
#define NS_OBJECT_ENSURE_REGISTERED(type) \
static struct X##type##RegistrationClass \
{ \
@@ -62,9 +66,21 @@ class TypeId
{
public:
enum {
/**
* The attribute can be read
*/
ATTR_GET = 1<<0,
/**
* The attribute can be written
*/
ATTR_SET = 1<<1,
/**
* The attribute can be written at construction-time.
*/
ATTR_CONSTRUCT = 1<<2,
/**
* The attribute can be read, and written at any time.
*/
ATTR_SGC = ATTR_GET | ATTR_SET | ATTR_CONSTRUCT,
};
@@ -74,7 +90,7 @@ public:
* name.
*
* This method cannot fail: it will crash if the input
* name is not a valid interface name.
* name is not a valid TypeId name.
*/
static TypeId LookupByName (std::string name);
/**
@@ -86,7 +102,7 @@ public:
static bool LookupByNameFailSafe (std::string name, TypeId *tid);
/**
* \returns the number of TypeId instances constructed
* \returns the number of TypeId instances registered.
*/
static uint32_t GetRegisteredN (void);
/**
@@ -98,7 +114,8 @@ public:
/**
* \param name the name of the interface to construct.
*
* No two instances can share the same name.
* No two instances can share the same name. The name is expected to be
* the full c++ typename of associated c++ object.
*/
TypeId (const char * name);
@@ -250,18 +267,36 @@ public:
Ptr<const AttributeAccessor> accessor,
Ptr<const AttributeChecker> 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<const TraceSourceAccessor> accessor);
/**
* \brief store together a set of attribute properties.
*/
struct AttributeInfo {
// The accessor associated to the attribute.
Ptr<const AttributeAccessor> 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<const AttributeChecker> 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<const TraceSourceAccessor> 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;