Delphi Language Guide Delphi for Microsoft Win32 Delphi for the Microsoft. Net framework

The Dispose Pattern
Another way to free up resources is to implement the dispose pattern. Classes adhering to the dispose pattern must
implement the .NET interface called IDisposable. IDisposable contains only one method, called Dispose. Unlike the
Finalize method, the Dispose method is public. It can be called directly by a user of the class, as opposed to relying
on the garbage collector to call it. This gives you back control of freeing resources, but calling Dispose still does not
reclaim memory for the object itself - that is still for the garbage collector to do. Note that some classes in the .NET
Framework implement both Dispose, and another method such as 
Close
. Typically the 
Close
 method simply calls
Dispose, but the extra method is provided because it seems more "natural" for certain classes such as files.
Delphi for .NET classes are free to use the Finalize method for freeing system resources, however the recommended
method is to implement the dispose pattern. The Delphi for .NET compiler recognizes a very specific destructor
pattern in your class, and implements the IDisposable interface for you. This enables you to continue writing new
code for the .NET platform the same way you always have, while allowing much of your existing Win32 Delphi code
to run in the garbage collected environment of the CLR.
The compiler recognizes the following specific pattern of a Delphi destructor:
TMyClass = class(TObject)
  destructor Destroy; override;
end;
Your destructor must fit this pattern exactly:
The name of the destructor must be 
Destroy
.
The keyword override must be specified.
The destructor cannot take any parameters.
In the compiler's implementation of the dispose pattern, the Free method is written so that if the class implements
the IDisposable interface (which it does), then the Dispose method is called, which in turn calls your destructor.
You can still implement the IDisposable interface directly, if you choose. However, the compiler's automatic
implementation of the Free-Dispose-Destroy mechanism cannot coexist with your implementation of IDisposable.
The two methods of implementing IDisposable are mutually exclusive. You must choose to either implement
IDisposable directly, or equip your class with the familiar 
destructor Destroy; override
 pattern and rely on
the compiler to do the rest. The 
Free
 method will call Dispose in either case, but if you implement Dispose yourself,
you must call your destructor yourself. If you want to implement IDisposable yourself, your destructor cannot be
called 
Destroy
.
Note:
You can declare destructors with other names; the compiler only provides the IDisposable implementation
when the destructor fits the above pattern.
The Dispose method is not called automatically; the Free method must be called in order for Dispose to be called.
If an object is freed by the garbage collector because there are no references to it, but you did not explicitly call Free
on the object, the object will be freed, but the destructor will not execute.
Note:
When the garbage collector frees the memory used by an object, it also reclaims the memory used by all
fields of the object instance as well. This means the most common reason for implementing destructors in
Delphi for Win32 - to release allocated memory - no longer applies. However, in most cases, unmanaged
resources such as window handles or file handles still need to be released.
To eliminate the possibility of destructors being called more than once, the Delphi for .NET compiler introduces a
field called 
DisposeCount
 into every class declaration. If the class already has a field by this name, the name
collision will cause the compiler to produce a syntax error in the destructor.
217

---