Export (0) Print
Expand All

GCHandle Structure

Updated: March 2011

Provides a means for accessing a managed object from unmanaged memory.

Namespace:  System.Runtime.InteropServices
Assembly:  mscorlib (in mscorlib.dll)

[ComVisibleAttribute(true)]
public struct GCHandle

The GCHandle structure is used in conjunction with the GCHandleType enumeration to create a handle corresponding to any managed object. This handle can be one of four types: Weak, WeakTrackResurrection, Normal, or Pinned. Once allocated, you can use a GCHandle to prevent the managed object from being collected by the garbage collector when an unmanaged client holds the only reference. Without such a handle, the object can be collected by the garbage collector before completing its work on behalf of the unmanaged client.

You can also use the GCHandle to create a pinned object that returns a memory address and prevents the garbage collector from moving the object in memory.

When the handle goes out of scope you must explicitly release it by calling the Free method; otherwise, memory leaks may occur. When you free a pinned handle, the associated object will be unpinned and will become eligible for garbage collection, if there are no other references to it.

The following example shows an App class that creates a handle to a managed object using the GCHandle.Alloc method, which prevents the managed object from being collected. A call to the EnumWindows method passes a delegate and a managed object (both declared as managed types, but not shown), and casts the handle to an IntPtr. The unmanaged function passes the type back to the caller as a parameter of the callback function.

using System;
using System.IO;
using System.Threading;
using System.Windows.Forms;
using System.Runtime.InteropServices;
using System.Security.Permissions;

public delegate bool CallBack(int handle, IntPtr param);

public class LibWrap
{
	// passing managed object as LPARAM 
	// BOOL EnumWindows(WNDENUMPROC lpEnumFunc, LPARAM lParam);

	[DllImport("user32.dll")]
	public static extern bool EnumWindows(CallBack cb, IntPtr param);
}

public class App
{
	public static void Main()
	{
		Run();
	}

        [SecurityPermission(SecurityAction.Demand, UnmanagedCode=true)]
	public static void Run()
        {
		TextWriter tw = System.Console.Out;
		GCHandle gch = GCHandle.Alloc(tw);

		CallBack cewp = new CallBack(CaptureEnumWindowsProc);

		// platform invoke will prevent delegate to be garbage collected 
		// before call ends

		LibWrap.EnumWindows(cewp, GCHandle.ToIntPtr(gch));
		gch.Free();
        }

	private static bool CaptureEnumWindowsProc(int handle, IntPtr param)
	{
		GCHandle gch = GCHandle.FromIntPtr(param);
		TextWriter tw = (TextWriter)gch.Target;
		tw.WriteLine(handle);
		return true;
	}
}

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Windows 7, Windows Vista, Windows XP SP2, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP Starter Edition, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003, Windows Server 2000 SP4, Windows Millennium Edition, Windows 98, Windows CE, Windows Mobile for Smartphone, Windows Mobile for Pocket PC, Xbox 360, Zune

The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

.NET Framework

Supported in: 3.5, 3.0, 2.0, 1.1, 1.0

.NET Compact Framework

Supported in: 3.5, 2.0, 1.0

XNA Framework

Supported in: 3.0, 2.0, 1.0

Date

History

Reason

March 2011

Freed objects are eligible for garbage collection when all references are released.

Customer feedback.

Community Additions

ADD
Show:
© 2014 Microsoft