In object-oriented programming, the dispose pattern is a design pattern for resource management. In this pattern, a resource is held by an object, and released by calling a conventional method – usually called close, dispose, free, release depending on the language – which releases any resources the object is holding onto. Many programming languages offer language constructs to avoid having to call the dispose method explicitly in common situations.

The dispose pattern is primarily used in languages whose runtime environment have automatic garbage collection (see motivation below).

Motivation

FILE *f = fopen(filename, mode);
// Do something with f.
fclose(f);

f = open(filename)
# Do something with f.
f.close()

Early exit

A key problem with the dispose pattern is that if the dispose method is not called, the resource is leaked. A common cause of this is early exit from a function, due to an early return or exception.

For example:

def func(filename):
    f = open(filename)
    if a:
        return x
    f.close()
    return y

If the function returns at the first return, the file is never closed and the resource is leaked.

def func(filename):
    f = open(filename)
    g(f)  # Do something with f that may raise an exception.
    f.close()

If the intervening code raises an exception, the function exits early and the file is never closed, so the resource is leaked.

Both of these can be handled by a try...finally construct, which ensures that the finally clause is always executed on exit:

def func(filename):
    try:
        f = open(filename)
        # Do something.
    finally:
        f.close()

More generically:

Resource resource = getResource();
try {
    // Resource has been acquired; perform actions with the resource.
    ...
} finally {
    // Release resource, even if an exception was thrown.
    resource.dispose();
}

The try...finally construct is necessary for proper exception safety, since the finally block enables execution of cleanup logic regardless of if an exception is thrown or not in the try block.

One disadvantage of this approach is that it requires the programmer to explicitly add cleanup code in a finally block. This leads to code size bloat, and failure to do so will lead to resource leakage in the program.

Language constructs

To make the safe use of the dispose pattern less verbose, several languages have some kind of built-in support for resources held and released in the same block of code.

The C# language features the using statement^[2] that automatically calls the Dispose method on an object that implements the IDisposable interface:

using (Resource resource = GetResource())
{
    // Perform actions with the resource.
    ...
}

which is equal to:

Resource resource = GetResource()
try 
{
    // Perform actions with the resource.
    ...
}
finally 
{
    // Resource might not been acquired, or already freed
    if (resource != null) 
        ((IDisposable)resource).Dispose(); 
}

Similarly, the Python language has a with statement that can be used to similar effect with a context manager object. The context manager protocol requires implementing __enter__ and __exit__ methods which get automatically called by the with statement construct, to prevent duplication of code that would otherwise occur with the try/finally pattern.^[3]

with resource_context_manager() as resource:
    # Perform actions with the resource.
    ...
# Perform other actions where the resource is guaranteed to be deallocated.
...

The Java language introduced a new syntax called try-with-resources in Java version 7.^[4] It can be used on objects that implement the AutoCloseable interface (that defines method close()):

try (OutputStream x = new OutputStream(...)) {
    // Do something with x
} catch (IOException ex) {
    // Handle exception

  // The resource x is automatically closed
} // try

Problems

Beyond the key problem of correct resource management in the presence of returns and exceptions, and heap-based resource management (disposing objects in a different scope from where they are created), there are many further complexities associated with the dispose pattern. These problems are largely avoided by RAII. However, in common simple use these complexities do not arise: acquire a single resource, do something with it, automatically release it.

A fundamental problem is that having a resource is no longer a class invariant (the resource is held from object creation until it is disposed, but the object is still live at this point), so the resource may not be available when the object tries to use it, for example trying to read from a closed file. This means that all methods on the object that use the resource potentially fail, concretely usually by returning an error or raising an exception. In practice this is minor, as use of resources can usually fail for other reasons as well (for example, trying to read past the end of a file), so these methods already might fail, and not having a resource just adds another possible failure. A standard way to implement this is to add a boolean field to the object, called disposed, which is set to true by dispose, and checked by a guard clause to all methods (that use the resource), raising an exception (such as ObjectDisposedException in .NET) if the object has been disposed.^[5]

Further, it is possible to call dispose on an object more than once. While this may indicate a programming error (each object holding a resource must be disposed exactly once), it is simpler, more robust, and thus usually preferable for dispose to be idempotent (meaning "calling multiple times is the same as calling once").^[5] This is easily implemented by using the same boolean disposed field and checking it in a guard clause at the start of dispose, in that case returning immediately, rather than raising an exception.^[5] Java distinguishes disposable types (those that implement AutoCloseable) from disposable types where dispose is idempotent (the subtype Closeable).

Disposal in the presence of inheritance and composition of objects that hold resources have analogous problems to destruction/finalization (via destructors or finalizers). Further, since the dispose pattern usually does not have language support for this, boilerplate code is necessary. Firstly, if a derived class overrides a dispose method in the base class, the overriding method in the derived class generally needs to call the dispose method in the base class, in order to properly release resources held in the base. Secondly, if an object has a "has a" relationship with another object that holds a resource (i.e., if an object indirectly uses a resource through another object that directly uses a resource), should the indirectly using object be disposable? This corresponds to whether the relationship is owning (object composition) or viewing (object aggregation), or even just communicating (association), and both conventions are found (indirect user is responsible for the resource or is not responsible). If the indirect use is responsible for the resource, it must be disposable, and dispose the owned objects when it is disposed (analogous to destroying or finalizing owned objects).

Composition (owning) provides encapsulation (only the object that is used needs to be tracked), but at the cost of considerable complexity when there are further relationships between objects, while aggregation (viewing) is considerably simpler, at the cost of lacking encapsulation. In .NET, convention is to only have direct user of resources be responsible: "You should implement IDisposable only if your type uses unmanaged resources directly."^[6] See resource management for details, and further examples.

See also

• Object lifetime
• Resource Acquisition Is Initialization (RAII)

Notes

References

Further reading

• Microsoft Developer Network: Dispose Pattern