src/core/object.h
author Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
Mon, 02 Jun 2008 10:30:24 -0700
changeset 3190 51fe9001a679
parent 3182 61fe7fe81ebd
child 3394 1680d5004ee8
permissions -rw-r--r--
add some doxygen, remove a couple of XXX
     1 /* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
     2 /*
     3  * Copyright (c) 2007 INRIA, Gustavo Carneiro
     4  *
     5  * This program is free software; you can redistribute it and/or modify
     6  * it under the terms of the GNU General Public License version 2 as
     7  * published by the Free Software Foundation;
     8  *
     9  * This program is distributed in the hope that it will be useful,
    10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
    11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    12  * GNU General Public License for more details.
    13  *
    14  * You should have received a copy of the GNU General Public License
    15  * along with this program; if not, write to the Free Software
    16  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
    17  *
    18  * Authors: Gustavo Carneiro <gjcarneiro@gmail.com>,
    19  *          Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
    20  */
    21 #ifndef OBJECT_H
    22 #define OBJECT_H
    23 
    24 #include <stdint.h>
    25 #include <string>
    26 #include <vector>
    27 #include "ptr.h"
    28 #include "attribute.h"
    29 #include "object-base.h"
    30 #include "attribute-list.h"
    31 
    32 
    33 namespace ns3 {
    34 
    35 class Object;
    36 class AttributeAccessor;
    37 class AttributeValue;
    38 class AttributeList;
    39 class TraceSourceAccessor;
    40 
    41 /**
    42  * \ingroup core
    43  * \defgroup object Object
    44  */
    45 /**
    46  * \ingroup object
    47  * \brief a base class which provides memory management and object aggregation
    48  *
    49  * The memory management scheme is based on reference-counting with dispose-like
    50  * functionality to break the reference cycles. The reference count is increamented
    51  * and decremented with the methods Object::Ref and Object::Unref. If a reference cycle is
    52  * present, the user is responsible for breaking it by calling Object::Dispose in
    53  * a single location. This will eventually trigger the invocation of Object::DoDispose 
    54  * on itself and all its aggregates. The Object::DoDispose method is always automatically
    55  * invoked from the Object::Unref method before destroying the object, even if the user 
    56  * did not call Object::Dispose directly.
    57  */
    58 class Object : public ObjectBase
    59 {
    60 public:
    61   static TypeId GetTypeId (void);
    62 
    63   /**
    64    * \brief Iterate over the objects aggregated to an ns3::Object.
    65    *
    66    * This iterator does not allow you to iterate over the initial
    67    * object used to call Object::GetAggregateIterator. 
    68    *
    69    * Note: this is a java-style iterator.
    70    */
    71   class AggregateIterator
    72   {
    73   public:
    74     AggregateIterator ();
    75 
    76     /**
    77      * \returns true if HasNext can be called and return a non-null
    78      *          pointer, false otherwise.
    79      */
    80     bool HasNext (void) const;
    81 
    82     /**
    83      * \returns the next aggregated object.
    84      */
    85     Ptr<const Object> Next (void);
    86   private:
    87     friend class Object;
    88     AggregateIterator (Ptr<const Object> first);
    89     Ptr<const Object> m_first;
    90     Ptr<const Object> m_current;
    91   };
    92 
    93   Object ();
    94   virtual ~Object ();
    95 
    96   /*
    97    * Implement the GetInstanceTypeId method defined in ObjectBase.
    98    */
    99   virtual TypeId GetInstanceTypeId (void) const;
   100 
   101   /**
   102    * Increment the reference count. This method should not be called
   103    * by user code. Object instances are expected to be used in conjunction
   104    * of the Ptr template which would make calling Ref unecessary and 
   105    * dangerous.
   106    */
   107   inline void Ref (void) const;
   108   /**
   109    * Decrement the reference count. This method should not be called
   110    * by user code. Object instances are expected to be used in conjunction
   111    * of the Ptr template which would make calling Ref unecessary and 
   112    * dangerous.
   113    */
   114   inline void Unref (void) const;
   115   /**
   116    * \returns a pointer to the requested interface or zero if it could not be found.
   117    */
   118   template <typename T>
   119   Ptr<T> GetObject (void) const;
   120   /**
   121    * \param tid the interface id of the requested interface
   122    * \returns a pointer to the requested interface or zero if it could not be found.
   123    */
   124   template <typename T>
   125   Ptr<T> GetObject (TypeId tid) const;
   126   /**
   127    * Run the DoDispose methods of this object and all the
   128    * objects aggregated to it.
   129    * After calling this method, the object is expected to be
   130    * totally unusable except for the Ref and Unref methods.
   131    * It is an error to call Dispose twice on the same object 
   132    * instance.
   133    *
   134    * This method is typically used to break reference cycles.
   135    */
   136   void Dispose (void);
   137   /**
   138    * \param other another object pointer
   139    *
   140    * This method aggregates the two objects together: after this
   141    * method returns, it becomes possible to call GetObject
   142    * on one to get the other, and vice-versa. 
   143    */
   144   void AggregateObject (Ptr<Object> other);
   145 
   146   /**
   147    * \returns an iterator to the first object aggregated to this
   148    *          object.
   149    *
   150    * If no objects are aggregated to this object, then, the returned
   151    * iterator will be empty and AggregateIterator::HasNext will
   152    * always return false.
   153    */
   154   AggregateIterator GetAggregateIterator (void) const;
   155 
   156 protected:
   157   /**
   158    * This method is called by Object::Dispose or by the object's 
   159    * destructor, whichever comes first.
   160    *
   161    * Subclasses are expected to implement their real destruction
   162    * code in an overriden version of this method and chain
   163    * up to their parent's implementation once they are done.
   164    * i.e., for simplicity, the destructor of every subclass should
   165    * be empty and its content should be moved to the associated
   166    * DoDispose method.
   167    */
   168   virtual void DoDispose (void);
   169   /**
   170    * \param o the object to copy.
   171    *
   172    * Allow subclasses to implement a copy constructor.
   173    * While it is technically possible to implement a copy
   174    * constructor in a subclass, we strongly discourage you
   175    * to do so. If you really want to do it anyway, you have
   176    * to understand that this copy constructor will _not_
   177    * copy aggregated objects. i.e., if your object instance
   178    * is already aggregated to another object and if you invoke
   179    * this copy constructor, the new object instance will be
   180    * a pristine standlone object instance not aggregated to
   181    * any other object. It is thus _your_ responsability
   182    * as a caller of this method to do what needs to be done
   183    * (if it is needed) to ensure that the object stays in a
   184    * valid state.
   185    */
   186   Object (const Object &o);
   187 private:
   188 
   189   template <typename T>
   190   friend Ptr<T> CreateObject (const AttributeList &attributes);
   191   template <typename T>
   192   friend Ptr<T> CopyObject (Ptr<T> object);
   193   template <typename T>
   194   friend Ptr<T> CopyObject (Ptr<const T> object);
   195 
   196   friend class ObjectFactory;
   197   friend class AggregateIterator;
   198 
   199   Ptr<Object> DoGetObject (TypeId tid) const;
   200   bool Check (void) const;
   201   bool CheckLoose (void) const;
   202   /**
   203    * Attempt to delete this object. This method iterates
   204    * over all aggregated objects to check if they all 
   205    * have a zero refcount. If yes, the object and all
   206    * its aggregates are deleted. If not, nothing is done.
   207    */
   208   void MaybeDelete (void) const;
   209   /**
   210    * \param tid an TypeId
   211    *
   212    * Invoked from ns3::CreateObject only.
   213    * Initialize the m_tid member variable to
   214    * keep track of the type of this object instance.
   215    */
   216   void SetTypeId (TypeId tid);
   217    /**
   218    * \param attributes the attribute values used to initialize 
   219    *        the member variables of this object's instance.
   220    *
   221    * Invoked from ns3::ObjectFactory::Create and ns3::CreateObject only.
   222    * Initialize all the member variables which were
   223    * registered with the associated TypeId.
   224    */
   225   void Construct (const AttributeList &attributes);
   226 
   227   /**
   228    * The reference count for this object. Each aggregate
   229    * has an individual reference count. When the global
   230    * reference count (the sum of all reference counts) 
   231    * reaches zero, the object and all its aggregates is 
   232    * deleted.
   233    */
   234   mutable uint32_t m_count;
   235   /**
   236    * Identifies the type of this object instance.
   237    */
   238   TypeId m_tid;
   239   /**
   240    * Set to true when the DoDispose method of the object
   241    * has run, false otherwise.
   242    */
   243   bool m_disposed;
   244   /**
   245    * A pointer to the next aggregate object. This is a circular
   246    * linked list of aggregated objects: the last one points
   247    * back to the first one. If an object is not aggregated to
   248    * any other object, the value of this field is equal to the
   249    * value of the 'this' pointer.
   250    */
   251   Object *m_next;
   252 };
   253 
   254 /**
   255  * \param object a pointer to the object to copy.
   256  * \returns a copy of the input object.
   257  *
   258  * This method invoke the copy constructor of the input object
   259  * and returns the new instance.
   260  */
   261 template <typename T>
   262 Ptr<T> CopyObject (Ptr<const T> object);
   263 template <typename T>
   264 Ptr<T> CopyObject (Ptr<T> object);
   265 
   266 
   267 /**
   268  * \param attributes a list of attributes to set on the 
   269  *        object during construction.
   270  * \returns a pointer to a newly allocated object.
   271  *
   272  * This allocates an object on the heap and initializes
   273  * it with a set of attributes.
   274  */
   275 template <typename T>
   276 Ptr<T> CreateObject (const AttributeList &attributes);
   277 
   278 /**
   279  * \param n1 name of attribute
   280  * \param v1 value of attribute
   281  * \param n2 name of attribute
   282  * \param v2 value of attribute
   283  * \param n3 name of attribute
   284  * \param v3 value of attribute
   285  * \param n4 name of attribute
   286  * \param v4 value of attribute
   287  * \param n5 name of attribute
   288  * \param v5 value of attribute
   289  * \param n6 name of attribute
   290  * \param v6 value of attribute
   291  * \param n7 name of attribute
   292  * \param v7 value of attribute
   293  * \param n8 name of attribute
   294  * \param v8 value of attribute
   295  * \param n9 name of attribute
   296  * \param v9 value of attribute
   297  * \returns a pointer to a newly allocated object.
   298  *
   299  * This allocates an object on the heap and initializes
   300  * it with a set of attributes.
   301  */
   302 template <typename T>
   303 Ptr<T> 
   304 CreateObject (std::string n1 = "", const AttributeValue & v1 = EmptyAttributeValue (),
   305               std::string n2 = "", const AttributeValue & v2 = EmptyAttributeValue (),
   306               std::string n3 = "", const AttributeValue & v3 = EmptyAttributeValue (),
   307               std::string n4 = "", const AttributeValue & v4 = EmptyAttributeValue (),
   308               std::string n5 = "", const AttributeValue & v5 = EmptyAttributeValue (),
   309               std::string n6 = "", const AttributeValue & v6 = EmptyAttributeValue (),
   310               std::string n7 = "", const AttributeValue & v7 = EmptyAttributeValue (),
   311               std::string n8 = "", const AttributeValue & v8 = EmptyAttributeValue (),
   312               std::string n9 = "", const AttributeValue & v9 = EmptyAttributeValue ());
   313   
   314 
   315 
   316 } // namespace ns3
   317 
   318 namespace ns3 {
   319 
   320 /*************************************************************************
   321  *   The Object implementation which depends on templates
   322  *************************************************************************/
   323 
   324 void
   325 Object::Ref (void) const
   326 {
   327   m_count++;
   328 }
   329 void
   330 Object::Unref (void) const
   331 {
   332   NS_ASSERT (Check ());
   333   m_count--;
   334   if (m_count == 0)
   335     {
   336       MaybeDelete ();
   337     }
   338 }
   339 
   340 template <typename T>
   341 Ptr<T> 
   342 Object::GetObject () const
   343 {
   344   Ptr<Object> found = DoGetObject (T::GetTypeId ());
   345   if (found != 0)
   346     {
   347       return Ptr<T> (dynamic_cast<T *> (PeekPointer (found)));
   348     }
   349   return 0;
   350 }
   351 
   352 template <typename T>
   353 Ptr<T> 
   354 Object::GetObject (TypeId tid) const
   355 {
   356   Ptr<Object> found = DoGetObject (tid);
   357   if (found != 0)
   358     {
   359       return Ptr<T> (dynamic_cast<T *> (PeekPointer (found)));
   360     }
   361   return 0;
   362 }
   363 
   364 /*************************************************************************
   365  *   The helper functions which need templates.
   366  *************************************************************************/
   367 
   368 template <typename T>
   369 Ptr<T> CopyObject (Ptr<T> object)
   370 {
   371   Ptr<T> p = Ptr<T> (new T (*PeekPointer (object)), false);
   372   NS_ASSERT (p->m_tid == object->m_tid);
   373   return p;
   374 }
   375 
   376 template <typename T>
   377 Ptr<T> CopyObject (Ptr<const T> object)
   378 {
   379   Ptr<T> p = Ptr<T> (new T (*PeekPointer (object)), false);
   380   NS_ASSERT (p->m_tid == object->m_tid);
   381   return p;
   382 }
   383 
   384 
   385 template <typename T>
   386 Ptr<T> CreateObject (const AttributeList &attributes)
   387 {
   388   Ptr<T> p = Ptr<T> (new T (), false);
   389   p->SetTypeId (T::GetTypeId ());
   390   p->Object::Construct (attributes);
   391   return p;  
   392 }
   393 
   394 template <typename T>
   395 Ptr<T> 
   396 CreateObject (std::string n1 = "", const AttributeValue & v1 = EmptyAttributeValue (),
   397               std::string n2 = "", const AttributeValue & v2 = EmptyAttributeValue (),
   398               std::string n3 = "", const AttributeValue & v3 = EmptyAttributeValue (),
   399               std::string n4 = "", const AttributeValue & v4 = EmptyAttributeValue (),
   400               std::string n5 = "", const AttributeValue & v5 = EmptyAttributeValue (),
   401               std::string n6 = "", const AttributeValue & v6 = EmptyAttributeValue (),
   402               std::string n7 = "", const AttributeValue & v7 = EmptyAttributeValue (),
   403               std::string n8 = "", const AttributeValue & v8 = EmptyAttributeValue (),
   404               std::string n9 = "", const AttributeValue & v9 = EmptyAttributeValue ())
   405 {
   406   AttributeList attributes;
   407   if (n1 == "")
   408     {
   409       goto end;
   410     }
   411   attributes.SetWithTid (T::GetTypeId (), n1, v1);
   412   if (n2 == "")
   413     {
   414       goto end;
   415     }
   416   attributes.SetWithTid (T::GetTypeId (), n2, v2);
   417   if (n3 == "")
   418     {
   419       goto end;
   420     }
   421   attributes.SetWithTid (T::GetTypeId (), n3, v3);
   422   if (n4 == "")
   423     {
   424       goto end;
   425     }
   426   attributes.SetWithTid (T::GetTypeId (), n4, v4);
   427   if (n5 == "")
   428     {
   429       goto end;
   430     }
   431   attributes.SetWithTid (T::GetTypeId (), n5, v5);
   432   if (n6 == "")
   433     {
   434       goto end;
   435     }
   436   attributes.SetWithTid (T::GetTypeId (), n6, v6);
   437   if (n7 == "")
   438     {
   439       goto end;
   440     }
   441   attributes.SetWithTid (T::GetTypeId (), n7, v7);
   442   if (n8 == "")
   443     {
   444       goto end;
   445     }
   446   attributes.SetWithTid (T::GetTypeId (), n8, v8);
   447   if (n9 == "")
   448     {
   449       goto end;
   450     }
   451   attributes.SetWithTid (T::GetTypeId (), n9, v9);
   452  end:
   453   return CreateObject<T> (attributes);
   454 }
   455 
   456 } // namespace ns3
   457 
   458 #endif /* OBJECT_H */
   459