Freeing Unmanaged Resources

The presence of the garbage collector means that you will usually not worry about objects that you no longer need; you will simply allow all references to those objects to go out of scope and allow the garbage collector to free memory as required. However, the garbage collector does not know how to free unmanaged resources (such as file handles, network connections, and database connections). When managed classes encapsulate direct or indirect references to unmanaged resources, you need to make special provision to ensure that the unmanaged resources are released when an instance of the class is garbage collected.

When defining a class, you can use two mechanisms to automate the freeing of unmanaged resources. These mechanisms are often implemented together because each provides a slightly different approach to the solution of the problem. The mechanisms are:

• Declaring a destructor (or finalizer) as a member of your class

• Implementing the System.IDisposable interface in your class

The following sections discuss each of these mechanisms in turn, and then look at how to implement them together for best effect.

Destructors

You’ve seen that constructors allow you to specify actions that must take place whenever an instance of a class is created. Conversely, destructors are called before an object is destroyed by the garbage collector. Given this behavior, a destructor would initially seem like a great place to put code to free unmanaged resources and perform a general cleanup. Unfortunately, things are not so straightforward.

Tip 

Although we talk about destructors in C#, in the underlying .NET architecture these are known as finalizers. When you define a destructor in C#, what is emitted into the assembly by the compiler is actually a method called Finalize(). That’s something that doesn’t affect any of your source code, but you’ll need to be aware of the fact if you need to examine the contents of an assembly.

The syntax for a destructor will be familiar to C++ developers. It looks like a method, with the same name as the containing class, but prefixed with a tilde (~). It has no return type, and takes no parameters and no access modifiers. Here is an example:

  class MyClass {    ~MyClass()    {       // destructor implementation    } } 

When the C# compiler compiles a destructor, it implicitly translates the destructor code to the equivalent of a Finalize() method that ensures the Finalize() method of the parent class is executed. The following example shows the C# code equivalent to the IL that the compiler would generate for the ~MyClass destructor:

  protected override void Finalize() {    try    {       // destructor implementation    }    finally    {       base.Finalize();    } } 

As shown, the code implemented in the ~MyClass destructor is wrapped in a try block contained in the Finalize() method. A call to the parent’s Finalize() method is ensured by placing the call in a finally block. try and finally blocks are discussed in Chapter 13, “Errors and Exceptions.”

Experienced C++ developers make extensive use of destructors, sometimes not only to clean up resources but also to provide debugging information or perform other tasks. C# destructors are used far less than their C++ equivalents. The problem with C# destructors as compared to their C++ counterparts is that they are nondeterministic. When a C++ object is destroyed, its destructor runs immediately. However, because of the way the garbage collector works, there is no way to know when an object’s destructor will actually execute. Hence, you cannot place any code in the destructor that relies on being run at a certain time, and you shouldn’t rely on the destructor being called for different class instances in any particular order. When your object is holding scarce and critical resources that need to be freed as soon as possible, you don’t want to wait for garbage collection.

Another problem with C# destructors is that the implementation of a destructor delays the final removal of an object from memory. Objects that do not have a destructor are removed from memory in one pass of the garbage collector, but objects that have destructors require two passes to be destroyed: The first pass calls the destructor without removing the object, and the second pass actually deletes the object. In addition, the runtime uses a single thread to execute the Finalize() methods of all objects. If you use destructors frequently, and use them to execute lengthy cleanup tasks, the impact on performance can be noticeable.

The IDisposable Interface

In C#, the recommended alternative to using a destructor is using the System.IDisposable interface. The IDisposable interface defines a pattern (with language-level support) that provides a deterministic mechanism for freeing unmanaged resources and avoids the garbage collector–related problems inherent with destructors. The IDisposable interface declares a single method named Dispose(), which takes no parameters and returns void. Here is an implementation for MyClass:

  class MyClass : IDisposable {    public void Dispose()    {       // implementation    } } 

The implementation of Dispose() should explicitly free all unmanaged resources used directly by an object and call Dispose() on any encapsulated objects that also implement the IDisposable interface. In this way, the Dispose() method provides precise control over when unmanaged resources are freed.

Suppose that you have a class named ResourceGobbler, which relies on the use of some external resource and implements IDisposable. If you want to instantiate an instance of this class, use it, and then dispose of it, you could do it like this:

  ResourceGobbler theInstance = new ResourceGobbler(); // do your processing theInstance.Dispose(); 

Unfortunately, this code fails to free the resources consumed by theInstance if an exception occurs during processing, so you should write the code as follows using a try block (which is discussed fully in Chapter 13):

  ResourceGobbler theInstance = null; try {    theInstance = new ResourceGobbler();    // do your processing } finally {    if (theInstance != null)   { theInstance.Dispose();    } } 

This version ensures that Dispose() is always called on theInstance and that any resources consumed by it are always freed, even if an exception occurs during processing. However, it would make for confusing code if you always had to repeat such a construct. C# offers a syntax that you can use to guarantee that Dispose() will automatically be called against an object that implements IDisposable when its reference goes out of scope. The syntax to do this involves the using keyword - though now in a very different context, which has nothing to do with namespaces. The following code generates IL code equivalent to the try block just shown:

  using (ResourceGobbler theInstance = new ResourceGobbler()) {    // do your processing } 

The using statement, followed in brackets by a reference variable declaration and instantiation, will cause that variable to be scoped to the accompanying statement block. In addition, when that variable goes out of scope, its Dispose() method will be called automatically, even if an exception occurs. However, if you are already using try blocks to catch other exceptions, it is cleaner and avoids additional code indentation if you avoid the using statement and simply call Dispose() in the Finally clause of the existing try block.

Tip 

For some classes, the notion of a Close() method is more logical than Dispose(); for example, when dealing with files or database connections. In these cases, it is common to implement the IDisposable interface and then implement a separate Close() method that simply calls Dispose(). This approach provides clarity in the use of your classes but also supports the using statement provided by C#.

Implementing IDisposable and a Destructor

The previous sections discussed two alternatives for freeing unmanaged resources used by the classes you create:

• The execution of a destructor is enforced by the runtime but is nondeterministic and places an unacceptable overhead on the runtime because of the way garbage collection works.

• The IDisposable interface provides a mechanism that allows users of a class to control when resources are freed but requires discipline to ensure that Dispose() is called.

In general, the best approach is to implement both mechanisms in order to gain the benefits of both while overcoming their limitations. You implement IDisposable on the assumption that most programmers will call Dispose() correctly, but implement a destructor as a safety mechanism in case Dispose() is not called. Here is an example of a dual implementation:

  public class ResourceHolder : IDisposable {    private bool isDisposed = false;    public void Dispose()    {       Dispose(true);       GC.SuppressFinalize(this);    }    protected virtual void Dispose(bool disposing)    {       if (!isDisposed)       {          if (disposing)          {             // Cleanup managed objects by calling their             // Dispose() methods.          }          // Cleanup unmanaged objects       }       isDisposed = true;    }    ~ResourceHolder()    {       Dispose (false);    }    public void SomeMethod()    {       // Ensure object not already disposed before execution of any method       if(isDisposed)       {          throw new ObjectDisposedException("ResourceHolder");       }       // method implementation/...    } } 

You can see from this code that there is a second protected overload of Dispose(), which takes one bool parameter - and this is the method that does all cleaning up. Dispose(bool) is called by both the destructor and by IDisposable.Dispose(). The point of this approach is to ensure that all cleanup code is in one place.

The parameter passed to Dispose(bool) indicates whether Dispose(bool) has been invoked by the destructor or by IDisposable.Dispose() - Dispose(bool) should not be invoked from anywhere else in your code. The idea is this:

• If a consumer calls IDisposable.Dispose(), that consumer is indicating that all managed and unmanaged resources associated with that object should be cleaned up.

• If a destructor has been invoked, all resources still need to be cleaned up. However, in this case, you know that the destructor must have been called by the garbage collector and you should not attempt to access other managed objects because you can no longer be certain of their state. In this situation, the best you can do is clean up the known unmanaged resources and hope that any referenced managed objects also have destructors that will perform their own cleaning up.

The isDisposed member variable indicates whether the object has already been disposed of and allows you to ensure that you do not try to dispose of member variables more than once. It also allows you to test whether an object has been disposed before executing any instance methods, as shown in SomeMethod(). This simplistic approach is not thread-safe and depends on the caller ensuring that only one thread is calling the method concurrently. Requiring a consumer to enforce synchronization is a reasonable assumption and one that is used repeatedly throughout the .NET class libraries (in the Collection classes for example). Threading and synchronization are discussed in Chapter 18, “Threading and Synchronization.”

Finally, IDisposable.Dispose() contains a call to the method System.GC.SuppressFinalize(). GC is the class that represents the garbage collector, and the SuppressFinalize() method tells the garbage collector that a class no longer needs to have its destructor called. Because your implementation of Dispose() has already done all the cleanup required, there’s nothing left for the destructor to do. Calling SuppressFinalize() means that the garbage collector will treat that object as if it doesn’t have a destructor at all.