Chris Lyon's WebLog : Dispose

New Dispose Guidelines

clyon — Thu, 14 Apr 2005 23:39:00 GMT

Joe Duffy has posted the revised Dispose, Finalization, and Resource Management Design Guideline. It's a great (and long) read. Check it out!

The Truth About GCHandles

clyon — Fri, 18 Mar 2005 20:43:00 GMT

I've heard several people asking why GCHandle doesn't implement IDisposable, considering it wraps an unmanaged resource (a handle) and needs to be explicitly freed (using GCHandle.Free()). Before I explain the reason, I want to give a little background on GCHandles and their dangers.

What's a GCHandle?

A GCHandle is a struct that contains a handle to an object. It's mainly used for holding onto a managed object that gets passed to the unmanaged world to prevent the GC from collecting the object. You can also create a Pinned GCHandle to a managed object and retrieve the object's address in memory.

How are GCHandles dangerous?

When you create a new GCHandle, a new entry in the AppDomain's handle table is created. This entry is kept until the handle is freed (via GCHandle.Free()) or the AppDomain is unloaded.

Things get tricky if you were to make a copy of a GCHandle:

Object obj = new Object();
GCHandle gch = GCHandle.Alloc(obj, GCHandleType.Normal);
GCHandle gch2 = gch;

Since GCHandle is value type, gch2 has its own copy of the handle. You now have two handles that point to the same entry in the handle table. Unfortunately, since gch2 is a copy of –not a reference to– gch, anything that happens to gch doesn't happen to gch2. For example, calling gch.Free() will delete the entry from the handle table, but not update gch2, so gch2.IsAllocated will return true, but gch2.Target will be null. The same problem arises with casting to and from IntPtrs, and when GCHandles get boxed. Unlike double-freeing a single GCHandle, freeing the copy will NOT throw an InvalidOperationException. You have to be very careful not to double-Free your handles since this can corrupt the handle table.

Why don't GCHandles implement IDisposable?

One of the main purposes of IDisposable to avoid the use of finalizers. This is because finalizers are not run deterministically, and result in promoting a finalizable object a generation, effectively keeping in memory longer. Since GCHandle is a value type, it has no finalizer, and is not collected by the GC, so these problems are eliminated. Another other main use of IDisposable is to clean up unmanaged resources as soon as you are done with them. With a GCHandle, the resource is the handle which is cleaned up by calling GCHandle.Free(). If Free isn't called, the handle gets cleaned up when the appdomain is unloaded.

One of the side effects of having a struct implement IDisposable, is that users may be tempted to cast their GCHandles as IDisposable, which boxes the GCHandle into an IDisposable object on the heap, and the two GCHandles get out-of-sync. The same problem arises with the putting a disposable struct into a using block:

struct Test : IDisposable
{
    public bool disposed; // initialized to false
    public void Dispose()
    {
        disposed = true;
    }
}

public void Foo()
{
    Test t = new Test();
    using (t)
    {
        // do stuff
    }

    if (!t.disposed)
    {
        t.Dispose();
    }
}

t.disposed will return false, since it was a copy of t whose Dispose method was called. If t were a GCHandle, then the handle would be removed from the appdomain's handle table, and calling Free after the using would result in a double Free, even though IsAllocated would return true!

Remember, GCHandles are advanced structures, and one should be very careful to ensure they are cleaned up properly. Unfortunately, IDisposable makes it easy to get this wrong, so the BCL designers erred on the side of caution, and gave GCHandle a Free() method to use.

Dispose Dos and Don'ts

clyon — Thu, 23 Sep 2004 16:50:00 GMT

Due to the positive response on my previous entry on Dispose, I thought I'd write another, this time on what one should and shouldn't do with a Dispose method.

Dispose should contain code to release any unmanaged resources associated with the object's instance. For example, any handles should be released, database connections closed, etc. This simulates deterministic finalization by letting the developer do the resource cleanup when he/she is done with the object. You may want to use an IsDisposed bool and check it inside Dispose.
Dispose should be safely callable multiple times. In my example above, if some user of your class called Dispose twice, we would crash with an unhandled InvalidOperationException trying to “double free” the GCHandle.
If you inherit from an IDisposable object, call the base class' Dispose method. Unlike finalizers, which the GC calls, Dispose is only called by user code (sometimes automatically in C#, as I covered previously). This means any unmanaged resources held by your object's parent, must also be disposed of.
Suppress finalization in Dispose. There has been some debate about whether GC.SuppressFinalization(this) should go before or after the cleanup code. Some argue after, in case something goes wrong before you've finished cleaning up. Others argue before, otherwise you may open up a race condition between your finalizer and your Dispose method. You should consider both strategies depending on your object's implementation.
Don't throw exceptions in Dispose. Nothing should go wrong with your object calling Dispose. Mainly for reasons stated above.
Throw ObjectDisposedException if a caller tries to use a released resource. You may be in a situation where you've disposed of your object because you no longer need the unmanaged resource, but you still need to have the object hanging around. If this is the case, any methods that would normally access the resource should throw an ObjectDisposedException, while other (possibly useful) methods should not.
Don't call Dispose from one thread, while still using the object on another. Try to make the thread that created the object be the one that disposes of it. This is more general good multithreaded programming advice, then Dispose specific.
Whenever possible, follow the Dispose Pattern. That link, one more time: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpgenref/html/cpconfinalizedispose.asp.

If you have any other Dispose Do's and Don'ts, please post them in the comments.

Demystifying Dispose

clyon — Tue, 21 Sep 2004 16:47:00 GMT

One commonly misunderstood feature is the relationship between disposable objects (Objects that implement the IDisposable interface) and the GC. I know there are a lot of online resources about patterns and best practices but there is still a lot of confusion. I remember going to a Dev Lab to answer some questions by Whidbey early adopters, and being asked at what point in an object’s lifetime does the GC call Dispose. The answer: Never.

Dispose is just a method, like any other. Its purpose is allow deterministic resource cleanup, much like C++’s destructors, but without freeing the object’s memory. Like a C++ destructor, the developer puts whatever cleanup code is necessary to be performed when the object’s lifetime is up. Unlike a destructor, the object lives on after being "disposed of". This means an object may be in an invalid state after being disposed, and developers should consider using ObjectDisposedExceptions when methods in a disposed object are called.

What happens when you call Dispose()

Any cleanup your object need done in a timely fashion should be done in Dispose. Things like closing database connections, closing files, releasing bitmaps, etc. Unmanaged resources in particular should be released in Dispose. This is because the GC has no knowledge of anything not allocated on the managed heap. For example, a Bitmap object that encapsulates a 2MB image file reports only its managed size (the size of the managed object) to the GC. The GC knows nothing about the 2MB unmanaged image, thus will not collect it from memory. By calling Dispose, you tell the Bitmap object that you are finished with it, and it will release the image itself.

What doesn’t happen when you call Dispose()

Calling Dispose does not prioritize the object for garbage collection. It simply unloads the object’s (unmanaged) resources from memory.
Calling Dispose does not deallocate the object from memory. Only the GC does that when it performs a collection of the generation in which the object resides.
The CLR does not insert or run any code not in Dispose. The behaviour of Dispose is defined by the developer.
Dispose must be called explicitly by the application. It is never called by the runtime. The only exceptions are when using C#’s using statement (see ShawnFa’s article for a good explanation of what exactly goes on), and the foreach keyword in C# will result in Dispose being called on the Enumerator
Dispose is NOT threadsafe. This means two threads can call Dispose on the same object at the same time. Like for any other synchronization-sensitive method, take steps to make sure this doesn’t happen. I’ll give an example of when this might happen in the next section.

What about the finalizer?

There are a few reasons why not to rely on the finalizer to clean up resources that I’ll cover in a future blog entry on finalizers. The main reasons you should be concerned with are performance and determinism. Finalizers are expensive to run, and there’s no order (or even guarantee) that they will be run (for example, the finalizer thread may time out, or be killed on AppDomain unload).

That being said, the finalizer should be your last chance to clean up resources, in case someone using your class forgets to dispose of it when done. A call to Dispose inside the finalizer reduces duplication of code. However, you want to make sure the resources don’t get released twice. In your Dispose method, you want to make sure you call GC.SuppressFinalize(this) after your clean up code. If you suppress the finalizer before the clean up, you’re limiting your ability to recover from failures during the cleanup.

Some of you may have noticed a race condition in my description above. Consider a situation where the call to Dispose is the last time your object is being referenced. As soon as Dispose is entered, the object is eligible for collection by the GC. Before that happens, the object’s finalizer gets called, which calls Dispose. You now have two threads inside Dispose, possibly double-freeing resources (this could be bad, as in the case of GCHandles). Make sure you follow the pattern I linked to above and use a disposing flag to avoid problems like this.

For more information about an object being collected while one of its methods are being run, check out these (very complete) blog posts by Chris Brumme: (Finalization and Lifetime, GC.KeepAlive, handle recycling).

If your .NET application is using unmanaged resources, make sure to implement the Dispose pattern, secure in the knowledge that nothing magical is going on.

EDIT: Added point about Dispose and foreach. Thanks Steve!

Edit: Minor corrections.