May 1999
rwilms@kottan.ruhr.de (Rolf K. Wilms)

TheExorcist is a development tool for VAST finding the shortest path of object pointer references 
between objects in the Smalltalk image, in particular to the Smalltalk roots. This is very useful 
to find out why there are still instances of classes that should have been garbage collected.

If you ever spent hours tracking down the cause for unwanted references to objects, especially through 
the code of someone else, you'll probably appreciate a tool which can solve the problem within
a couple of minutes.

To install, load the configuration map 'TheExorcist 1.0' from the ENVY library exorcist.dat.

Afterwards you can obtain the object pointer reference path to the Smalltalk roots (global namespace and processes)
by sending #referencePathToRoot to any object. The result (path to the roots) will be an OrderedCollection and since 
there is no special GUI, it is best to inspect that collection.

Be prepared to wait a few minutes (no progress indicator) for the result. A plain VAST 4.5 image takes about 25 seconds
on a PII 400 / 192 megs in the worst case, smaller machines and/or bigger images will take some more time.

TheExorcist is made up of two applications. One contains a generic, high performance shortest path finder for 
(cyclic) digraphs, the other represents the objects in the image as a graph using #exoReferencesDo: to iterate over the 
objects (nodes) referenced by the receiver object via object pointers (the edges of the graph).


	TheExorcist (c) 1999 by rwilms@kottan.ruhr.de (Rolf K. Wilms)
	is free to use and distribute but without any warranty.

	Finding unwanted references to an object:
	-------------------------------------------------------------------

	If you like to know where the references to an object which should have
	been garbage collected come from, then send the message #referencePathToRoot
	to this object and inspect the result.

	The result is an OrderedCollection starting with an object A directly referencing the receiver object.
	The next element is an object B directly referencing A and so on, until a global or a Process is reached (a 'root').

	When scanning (backwards) through the result collection you will quickly find the cause for the references to the
	receiver object. 

	Example:

	Say you wanted to unload an Application and Envy told you there were instances of Class 'TheClass'.
	Then you may execute 

		TheClass allInstances first referencePathToRoot

	wait a few minutes and see why this instance is still there.