Questions tagged [idisposable]

Purpose

IDisposable is an interface within the Microsoft .NET Framework's Base Class Library (BCL). It is intended to provide a generic, deterministic method of releasing unmanaged resources within .NET application code.

Unmanaged Resources

A managed resource is any object in memory that, in its entirety, can be monitored and released by the .NET garbage collector when they are no longer needed. The vast majority of types available within the .NET libraries (as well as user-defined types) represent managed resources. Because these are managed resources, it is not necessary to release the memory that these objects require; once they are no longer in use, the .NET garbage collector will periodically "collect" these objects and free this memory for other uses.

An unmanaged resource is any resource (typically something existing outside of the application runtime, such as a file handle or database connection) which is not--and cannot be--monitored and released by the .NET runtime garbage collector. Typical examples of unmanaged resources are network connections, file handles, and Windows GDI graphics handles. All of these resources, while represented in .NET code by a traditional object, are outside of the reach of the .NET garbage collector, as the procedure for obtaining and releasing such resources are specific to the type of resource, and all require calls into unmanaged code.

IDisposable

IDisposable is an interface within the BCL that defines a single parameterless, non-returning function called Dispose. A type that implements this interface indicates to the developer that, at some level of encapsulation, this type utilizes an unmanaged resource of some kind. In this case, the developer is required to call Dispose on the instance once it is no longer needed. The underlying type's implementation of Dispose should then perform whatever actions are necessary to release the resource, including calling unmanaged code.

Use Cases

There are two* (by design) cases in which a type should implement IDisposable:

1. The type interacts directly with an unmanaged resource (it calls an unmanaged or external function to acquire a resource, and another unmanaged or external function to release it).
2. The type makes use of an unmanaged resource indirectly through other types that implement IDisposable. In other words, the type makes use of an unmanaged resource that is not managed by another instance and exists beyond the lifetime of a single function call.

In the first case, the use is obvious: the type makes use of the resource directly, so it must acquire and release the resource directly. In the second case, the type makes use of other IDisposable types and must be told when it is safe to call Dispose on those resources.

_{*A type may also implement IDisposable in order to take advantage of the using language constructs within VB.NET and C#, but this choice is generally made for aesthetic or idiomatic reasons, not out of technical applicability, so those cases fall outside the scope of this article.}

Implementation

Depending on the reason that a type implements the IDisposable interface, the implementation may vary slightly. There are, in general, two forms of implementation of IDisposable:

1. Simple, strict implementation of the interface (a single Dispose function)
2. Finalizer-compatible implementation (two versions of Dispose)

Simple

If the type falls into the second use-case outlined above (indirect use of an unmanaged resource purely by encapsulation), then the first implementation should be used. An example appears below:

public class WidgetFile : IDisposable
{
    private FileStream fileStream;

    public WidgetFile(string fileName)
    {
        fileStream = new FileStream(fileName, FileMode.Open);
    }

    public void Dispose()
    {
        fileStream.Dispose();
    }
}

In this case, the WidgetFile encapsulates an IDisposable type, System.IO.FileStream. Since the type (and its parent type(s)) only indirectly interact with an unmanaged resource, the simple implementation is both adequate and preferred.

Finalizer-Based

If, however, the type (or one of its parent types) interacts directly with an unmanaged resource, then a more defensive, finalizer-based approach is required:

[DllImport("Widget.dll")]
private static extern IntPtr GetGadgetHandle(string fileName);
[DllImport("Widget.dll")]
private static extern void ReleaseGadgetHandle(IntPtr handle);

public class SuperWidgetFile : IDisposable
{
    private IntPtr handle;
    private WidgetFile file;

    public SuperWidgetFile(string fileName)
    {
        handle = GetGadgetHandle(fileName);
        file = new WidgetFile(fileName);
    }

    public void Dispose()
    {
        Dispose(true);
    }

    ~SuperWidgetFile()
    {
        Dispose(false);
    }

    protected virtual void Dispose(bool disposing)
    {
        if(disposing)
        {
            file.Dispose();
            GC.SuppressFinalize(this);
        }

        if(handle != IntPtr.Zero)
        {
            ReleaseGadgetHandle(handle);
            handle = IntPtr.Zero;
        }
    }
}

This implementation is obviously more complex than the simple, strict interface implementation. This is because, while a conscientious developer will always call Dispose on an instance of an IDisposable type when it is no longer needed, mistakes do happen and there is the possibility that the object may be unused but not have Dispose called. In this case, the instance itself (since it is a managed resource) will be collected by the garbage collector, while the unmanaged resource it refers to will never be released explicitly.

However, the garbage collector provides the ability to write code that executes before an object is collected and destroyed, called a "finalizer". The function defined as ~SuperWidgetFile() is the finalizer for the SuperWidgetFile type.

When using this approach, the implementing class must:

1. Provide a protected virtual void Dispose(bool disposing) function
2. Implement the interface and provide a Dispose() function, which calls Dispose(true)
3. Create a finalizer which calls Dispose(false)

The boolean disposing parameter is designed to designate the source of the function call. If it came from an explicit disposal (the desired path), then it should evaluate to true. If it came from the finalizer, then it should evaluate to false. This is because, as we have done, all IDisposable types that interact with unmanaged resources directly must use the finalizer approach, and these objects may have been collected already. Because of this, the type should only perform the release of its own unmanaged resources within the finalizer.

If the object is disposed explicitly (disposing == true), the type calls GC.SuppressFinalize(this), which tells the garbage collector that this object's finalizer does not need to be called when it is collected.

Common Questions

Q: Are IDisposable types "special"? Does the .NET runtime or garbage collector treat them differently by automatically calling Dispose, collecting them early, etc.?

A: NO. Fundamentally, IDiposable is just an interface, no different from any other interface defined in the .NET libraries or in user code. At runtime, objects implementing IDisposable follow exactly the same rules for collection as all other objects. The only "special treatment" afforded IDisposable types exist at the language level, where language shorthand allow for greater ease in remembering to call Dispose, such as within the using constructs in VB.NET and C#. Again, these are language features only. They do not have any impact on runtime behavior.

Q: Do I always need to call Dispose?

A: YES. While you may have personal knowledge of a particular type and what it actually does when Dispose is called, there should be a very clear, well-defined, and unavoidable reason to avoid calling Dispose when an object is no longer in use. The absolute easiest method of ensuring that you properly dispose of your disposable objects is to enclose them in using blocks:

using(SuperWidgetFile file = new SuperWidgetFile(@"C:\widget.wgt"))
{
    // widget code
}

However, this construct only works when the lifetime of the instance begins and ends within a single function call; in other cases, you will have to ensure that you call Dispose explicitly.