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.

GCHandles, Boxing and Heap Corruption

clyon — Fri, 17 Sep 2004 18:58:00 GMT

A GCHandle is a struct used to hold onto a managed object to be used by unmanaged code. With a GCHandle you can (among other things):

Prevent an object from being garbage collected if unmanaged code has the only live reference to it
Pin an object in memory, so it won’t be relocated in memory by the garbage collector
Get the memory address of the pinned object

The last point is interesting. When dealing with managed code, addresses of reference objects (objects allocated on the heap) are not constant. As the GC tries to reclaim memory, it moves objects around in memory and compacts the heap. If you’re P/Invoking into an unmanaged DLL, you may need to pass the address of some object. That’s where GCHandles come in.

The syntax for allocating a pinned GCHandle is as follows (C# code):

Int[] arr = new int[10];
GCHandle gch = GCHandle.Alloc(arr, GCHandleType.Pinned);

The above code pins arr in memory (so it won’t be moved), and creates a new GCHandle that “wraps” arr. You can now get the address of arr using GCHandle.AddrOfPinnedObject.

Note: you can only pin blittable types in memory (types that have the same representation in managed and unmanaged code). Blittable types include primitive types and arrays.

The problem occurs when you accidentally misuse Alloc. For example, I’ve seen code like this:

Object obj = new Object();
GCHandle gch2 = GCHandle.Alloc(Marshal.SizeOf(typeof(obj)), GCHandleType.Pinned);

It looks like the developer tried to allocate a GCHandle with the same size as obj in memory. So what does this code actually do?

Marshall.SizeOf returns an int that when passed to a method expecting an Object, is boxed into a newly heap-allocated Object. So the new GCHandle obediently pins this new Object in memory. Then when you pass gch2.AddrOfPinnedObject to your unmanaged code… trouble.

Consider an unmanaged method takes an array of ints, and increments each element. You’ve passed it an address, and it dutifully increments each value it finds for the length of the array. Congratulations, you’ve just corrupted memory.

If you’re lucky, this crashes the runtime right away. If you’re unlucky, your app may continue to run and crash sometime in the future or your app’s data may be messed up.

Chris Lyon's WebLog : GCHandles

The Truth About GCHandles

GCHandles, Boxing and Heap Corruption