vtkGarbageCollector Class Reference

#include <vtkGarbageCollector.h>

Inheritance diagram for vtkGarbageCollector:

[legend]Collaboration diagram for vtkGarbageCollector:

[legend]List of all members.

---

Detailed Description

Detect and break reference loops.

vtkGarbageCollector is used by VTK classes that may be involved in reference counting loops (such as Algorithm <-> Executive). It detects strongly connected components of the reference graph that have been leaked deletes them. The garbage collector uses the ReportReferences method to search the reference graph and construct a net reference count for each connected component. If the net reference count is zero the entire set of objects is deleted. Deleting each component may leak other components, which are then collected recursively.

To enable garbage collection for a class, add these members:

  public:
   virtual void Register(vtkObjectBase* o)
     {
     this->RegisterInternal(o, 1);
     }
   virtual void UnRegister(vtkObjectBase* o)
     {
     this->UnRegisterInternal(o, 1);
     }

  protected:

   virtual void ReportReferences(vtkGarbageCollector* collector)
     {
     // Report references held by this object that may be in a loop.
     this->Superclass::ReportReferences(collector);
     vtkGarbageCollectorReport(collector, this->OtherObject, "Other Object");
     }

The implementations should be in the .cxx file in practice. It is important that the reference be reported using the real pointer or smart pointer instance that holds the reference. When collecting the garbage collector will actually set this pointer to NULL. The destructor of the class should be written to deal with this. It is also expected that an invariant is maintained for any reference that is reported. The variable holding the reference must always either be NULL or refer to a fully constructed valid object. Therefore code like "this->Object->UnRegister(this)" must be avoided if "this->Object" is a reported reference because it is possible that the object is deleted before UnRegister returns but then "this->Object" will be left as a dangling pointer. Instead use code like

vtkObjectBase* obj = this->Object; this->Object = 0; obj->UnRegister(this);

so that the reported reference maintains the invariant.

If subclassing from a class that already supports garbage collection, one need only provide the ReportReferences method.

Tests:

vtkGarbageCollector (Tests)

Definition at line 93 of file vtkGarbageCollector.h.

Public Types
typedef vtkObject	Superclass
Public Member Functions
virtual const char *	GetClassName ()
virtual int	IsA (const char *type)
void	PrintSelf (ostream &os, vtkIndent indent)
Static Public Member Functions
static int	IsTypeOf (const char *type)
static vtkGarbageCollector *	SafeDownCast (vtkObject *o)
static vtkGarbageCollector *	New ()
static void	Collect ()
static void	Collect (vtkObjectBase *root)
static void	DeferredCollectionPush ()
static void	DeferredCollectionPop ()
static void	SetGlobalDebugFlag (int flag)
static int	GetGlobalDebugFlag ()
Protected Member Functions
	vtkGarbageCollector ()
	~vtkGarbageCollector ()
Friends
class	vtkGarbageCollectorManager
class	vtkObjectBaseToGarbageCollectorFriendship
void VTK_COMMON_EXPORT	vtkGarbageCollectorReportInternal (vtkGarbageCollector *, vtkObjectBase *, void *, const char *)

---

Member Typedef Documentation

typedef vtkObject vtkGarbageCollector::Superclass

Reimplemented from vtkObject. Definition at line 96 of file vtkGarbageCollector.h.

---

Constructor & Destructor Documentation

vtkGarbageCollector::vtkGarbageCollector (   )  [protected]

vtkGarbageCollector::~vtkGarbageCollector (   )  [protected]

---

Member Function Documentation

virtual const char* vtkGarbageCollector::GetClassName (   )  [virtual]

Reimplemented from vtkObject.

static int vtkGarbageCollector::IsTypeOf (  const char *  type  )  [static]

Return 1 if this class type is the same type of (or a subclass of) the named class. Returns 0 otherwise. This method works in combination with vtkTypeRevisionMacro found in vtkSetGet.h. Reimplemented from vtkObject.

virtual int vtkGarbageCollector::IsA (  const char *  type  )  [virtual]

Return 1 if this class is the same type of (or a subclass of) the named class. Returns 0 otherwise. This method works in combination with vtkTypeRevisionMacro found in vtkSetGet.h. Reimplemented from vtkObject.

static vtkGarbageCollector* vtkGarbageCollector::SafeDownCast (  vtkObject *  o  )  [static]

Reimplemented from vtkObject.

void vtkGarbageCollector::PrintSelf (  ostream &  os, vtkIndent  indent )  [virtual]

Methods invoked by print to print information about the object including superclasses. Typically not called by the user (use Print() instead) but used in the hierarchical print process to combine the output of several classes. Reimplemented from vtkObject.

static vtkGarbageCollector* vtkGarbageCollector::New (   )  [static]

Create an object with Debug turned off, modified time initialized to zero, and reference counting on. Reimplemented from vtkObject.

static void vtkGarbageCollector::Collect (   )  [static]

Collect immediately using any objects whose collection was previously deferred as a root for the reference graph walk. Strongly connected components in the reference graph are identified. Those with a net reference count of zero are deleted. When a component is deleted it may remove references to other components that are not part of the same reference loop but are held by objects in the original component. These removed references are handled as any other and their corresponding checks may be deferred. This method keeps collecting until no deferred collection checks remain.

static void vtkGarbageCollector::Collect (  vtkObjectBase *  root  )  [static]

Collect immediately using the given object as the root for a reference graph walk. Strongly connected components in the reference graph are identified. Those with a net reference count of zero are deleted. When a component is deleted it may remove references to other components that are not part of the same reference loop but are held by objects in the original component. These removed references are handled as any other and their corresponding checks may be deferred. This method does continue collecting in this case.

static void vtkGarbageCollector::DeferredCollectionPush (   )  [static]

Push/Pop whether to do deferred collection. Whenever the total number of pushes exceeds the total number of pops collection will be deferred. Code can call the Collect method directly to force collection.

static void vtkGarbageCollector::DeferredCollectionPop (   )  [static]

Collect immediately using the given object as the root for a reference graph walk. Strongly connected components in the reference graph are identified. Those with a net reference count of zero are deleted. When a component is deleted it may remove references to other components that are not part of the same reference loop but are held by objects in the original component. These removed references are handled as any other and their corresponding checks may be deferred. This method does continue collecting in this case.

static void vtkGarbageCollector::SetGlobalDebugFlag (  int  flag  )  [static]

Set/Get global garbage collection debugging flag. When set to 1, all garbage collection checks will produce debugging information.

static int vtkGarbageCollector::GetGlobalDebugFlag (   )  [static]

Set/Get global garbage collection debugging flag. When set to 1, all garbage collection checks will produce debugging information.

---

Friends And Related Function Documentation

friend class vtkGarbageCollectorManager [friend]

Definition at line 164 of file vtkGarbageCollector.h.

friend class vtkObjectBaseToGarbageCollectorFriendship [friend]

Definition at line 165 of file vtkGarbageCollector.h.

void VTK_COMMON_EXPORT vtkGarbageCollectorReportInternal (  vtkGarbageCollector *  , vtkObjectBase *  , void *  , const char *  )  [friend]

---

The documentation for this class was generated from the following file:

• dox/Common/vtkGarbageCollector.h

---