/usr/include/vtk-5.8/vtkGarbageCollector.h is in libvtk5-dev 5.8.0-5.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 | /*=========================================================================
Program: Visualization Toolkit
Module: vtkGarbageCollector.h
Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen
All rights reserved.
See Copyright.txt or http://www.kitware.com/Copyright.htm for details.
This software is distributed WITHOUT ANY WARRANTY; without even
the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
PURPOSE. See the above copyright notice for more information.
=========================================================================*/
// .NAME vtkGarbageCollector - Detect and break reference loops
// .SECTION Description
// 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:
//
// \code
//
// 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");
// }
// \endcode
//
// 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
//
// \code
// vtkObjectBase* obj = this->Object;
// this->Object = 0;
// obj->UnRegister(this);
// \endcode
//
// 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.
#ifndef __vtkGarbageCollector_h
#define __vtkGarbageCollector_h
#include "vtkObject.h"
#include "vtkGarbageCollectorManager.h" // Needed for singleton initialization.
// This function is a friend of the collector so that it can call the
// internal report method.
void VTK_COMMON_EXPORT
vtkGarbageCollectorReportInternal(vtkGarbageCollector*,
vtkObjectBase*, void*,
const char*);
// This allows vtkObjectBase to get at the methods it needs.
class vtkObjectBaseToGarbageCollectorFriendship;
class VTK_COMMON_EXPORT vtkGarbageCollector : public vtkObject
{
public:
vtkTypeMacro(vtkGarbageCollector,vtkObject);
void PrintSelf(ostream& os, vtkIndent indent);
static vtkGarbageCollector* New();
// Description:
// 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 Collect();
// Description:
// 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 Collect(vtkObjectBase* root);
// Description:
// 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 DeferredCollectionPush();
static void DeferredCollectionPop();
// Description:
// Set/Get global garbage collection debugging flag. When set to 1,
// all garbage collection checks will produce debugging information.
static void SetGlobalDebugFlag(int flag);
static int GetGlobalDebugFlag();
protected:
vtkGarbageCollector();
~vtkGarbageCollector();
private:
// Description:
// Called by UnRegister method of an object that supports garbage
// collection. The UnRegister may not actually decrement the
// reference count, but instead hands the reference to the garbage
// collector. If a reference can be given, this method accepts it
// from the caller by returning 1. If the reference cannot be
// accepted then it returns 0. This may be the case when delayed
// garbage collection is disabled, or when the collector has decided
// it is time to do a check.
static int GiveReference(vtkObjectBase* obj);
// Description:
// Called by Register method of an object that supports garbage
// collection. The Register may not actually increment the
// reference count if it can take a reference previously handed to
// the garbage collector. If a reference can be taken, this method
// hands it back to the caller by returning 1. If no reference is
// available, returns 0.
static int TakeReference(vtkObjectBase* obj);
// Singleton management functions.
static void ClassInitialize();
static void ClassFinalize();
//BTX
friend class vtkGarbageCollectorManager;
friend class vtkObjectBaseToGarbageCollectorFriendship;
//ETX
// Internal report callback and friend function that calls it.
virtual void Report(vtkObjectBase* obj, void* ptr, const char* desc);
friend void VTK_COMMON_EXPORT
vtkGarbageCollectorReportInternal(vtkGarbageCollector*,
vtkObjectBase*, void*,
const char*);
private:
vtkGarbageCollector(const vtkGarbageCollector&); // Not implemented.
void operator=(const vtkGarbageCollector&); // Not implemented.
};
//BTX
class vtkSmartPointerBase;
// Description:
// Function to report a reference held by a smart pointer to a collector.
void VTK_COMMON_EXPORT
vtkGarbageCollectorReport(vtkGarbageCollector* collector,
vtkSmartPointerBase& ptr,
const char* desc);
// Description:
// Function to report a reference held by a raw pointer to a collector.
template <class T>
void vtkGarbageCollectorReport(vtkGarbageCollector* collector, T*& ptr,
const char* desc)
{
vtkGarbageCollectorReportInternal(collector, ptr, &ptr, desc);
}
//ETX
#endif
|