Difference between revisions of "LS2Module:Reference counting"

From ismods.com: dedicated to promoting white hat, EULA-compliant Inner Space and LavishScript mods
Jump to: navigation, search
(Created page with "Reference counting is a method of 'garbage collection' used by LavishScript 2. This allows objects to be reused, instead of being immediately destroyed in favor of a fresh cop...")
 
 
Line 40: Line 40:
  
 
== Working with reference counted objects ==  
 
== Working with reference counted objects ==  
The SDK provides [[LS2SmartRef]]<T> to simplify management of reference counted objects.
+
When the API expects to provide you with a reference counted object, it will do so using a T** parameter. When you are finished with your reference to the provided object, you will need to call its Delete() method.  
  
LS2SmartRef<T> allows your smart reference to be used as a T*, T**, or T&. Use the -> operator to access members of T (your object), or the . operator to access members of LS2SmartRef (such as to change the reference). Using a LS2SmartRef also ensures that the reference will be freed in the case of an exception (whereas using your own pointer to the T will require manual exception handling).
+
The SDK provides [[LS2SmartRef]]<T> to simplify management of reference counted objects by automatically tracking the count of an object. Using a LS2SmartRef also ensures that the reference will be freed in the case of an exception (whereas using your own pointer to the T will require manual exception handling).
 +
 
 +
LS2SmartRef<T> allows your smart reference to be used as a T*, T**, or T&. Use the -> operator to access members of T (your object), or the . operator to access members of LS2SmartRef (such as to change the reference).  
  
 
; An example of LS2SmartRef usage
 
; An example of LS2SmartRef usage
 +
// set up a LS2SmartRef to hold an LavishScript2::ILS2CodeBoxType reference
 
  LavishScript2::LS2SmartRef<LavishScript2::ILS2CodeBoxType> pIDisposable;
 
  LavishScript2::LS2SmartRef<LavishScript2::ILS2CodeBoxType> pIDisposable;
 +
 +
// call ResolveType, which needs a LavishScript2::ILS2CodeBoxType** in parameter 2
 +
// we will grab a reference to System.IDisposable, and assign it into pIDisposable
 
  LavishScript2::ILS2StandardEnvironment::s_pInstance->ResolveType(L"System.IDisposable",pIDisposable); // LavishScript2::ILS2CodeBoxType**
 
  LavishScript2::ILS2StandardEnvironment::s_pInstance->ResolveType(L"System.IDisposable",pIDisposable); // LavishScript2::ILS2CodeBoxType**
  pMyType->AddInterface(pIDisposable); // LavishScript2::ILS2CodeBoxType&
+
   
  pIDisposable.Clear(); // not necessary to explicitly call, it will be cleared when the LS2SmartRef leaves scope
+
// say we have another LavishScript2::ILS2CodeBoxType reference called pMyType...
 
+
  // let's register IDisposable as an interface implemented by pMyType...
 +
pMyType->RegisterInterface(pIDisposable);
 +
 +
// pIDisposable will automatically Clear when it leaves scope
 +
// but for the sake of providing an example using a method from LS2SmartRef...
 +
pIDisposable.Clear();
  
 
[[Category:LavishScript 2]]
 
[[Category:LavishScript 2]]
 
[[Category:LS2Module SDK]]
 
[[Category:LS2Module SDK]]

Latest revision as of 13:50, 25 November 2012

Reference counting is a method of 'garbage collection' used by LavishScript 2. This allows objects to be reused, instead of being immediately destroyed in favor of a fresh copy of the same object.

The LavishScript 2 reference counting model assumes 3 things about an object
  1. It starts with a reference count of 1 and will be deleted when that count reaches 0
  2. It has virtual int AddRef() to increment the reference count
  3. It has virtual int Delete() to decrement the reference count (and potentially delete the object and free the memory)

Most LavishScript 2 objects are reference counted with this model.

Example LavishScript 2 Reference Count implementation

Support LS2SmartRef<T> and LS2CodeBoxValue_ObjectRefCountedT<T> for your type T by following this model
class MyClass
{
public:
   MyClass()
   {
      m_RefCount=1; // always assume we have a reference to begin with!
   }

   virtual int AddRef()
   {
      m_RefCount++;
      return m_RefCount;
   }

   virtual int Delete()
   {
      m_RefCount--;
      if (m_RefCount<=0)
      {
         delete this;
         return 0;
      }
      return m_RefCount;
   }

   int m_RefCount;
};

Working with reference counted objects

When the API expects to provide you with a reference counted object, it will do so using a T** parameter. When you are finished with your reference to the provided object, you will need to call its Delete() method.

The SDK provides LS2SmartRef<T> to simplify management of reference counted objects by automatically tracking the count of an object. Using a LS2SmartRef also ensures that the reference will be freed in the case of an exception (whereas using your own pointer to the T will require manual exception handling).

LS2SmartRef<T> allows your smart reference to be used as a T*, T**, or T&. Use the -> operator to access members of T (your object), or the . operator to access members of LS2SmartRef (such as to change the reference).

An example of LS2SmartRef usage
// set up a LS2SmartRef to hold an LavishScript2::ILS2CodeBoxType reference
LavishScript2::LS2SmartRef<LavishScript2::ILS2CodeBoxType> pIDisposable;

// call ResolveType, which needs a LavishScript2::ILS2CodeBoxType** in parameter 2
// we will grab a reference to System.IDisposable, and assign it into pIDisposable
LavishScript2::ILS2StandardEnvironment::s_pInstance->ResolveType(L"System.IDisposable",pIDisposable); // LavishScript2::ILS2CodeBoxType**

// say we have another LavishScript2::ILS2CodeBoxType reference called pMyType...
// let's register IDisposable as an interface implemented by pMyType...
pMyType->RegisterInterface(pIDisposable);

// pIDisposable will automatically Clear when it leaves scope
// but for the sake of providing an example using a method from LS2SmartRef... 
pIDisposable.Clear();