This browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
Download Microsoft Edge
More info about Internet Explorer and Microsoft Edge
public value class GCHandle
public value class GCHandle : IEquatable<System::Runtime::InteropServices::GCHandle>
public struct GCHandle
public struct GCHandle : IEquatable<System.Runtime.InteropServices.GCHandle>
[System.Runtime.InteropServices.ComVisible(true)]
public struct GCHandle
type GCHandle = struct
[<System.Runtime.InteropServices.ComVisible(true)>]
type GCHandle = struct
Public Structure GCHandle
Public Structure GCHandle
Implements IEquatable(Of GCHandle)
Inheritance
GCHandle
Examples
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;
public delegate bool CallBack(int handle, IntPtr param);
internal static class NativeMethods
// passing managed object as LPARAM
// BOOL EnumWindows(WNDENUMPROC lpEnumFunc, LPARAM lParam);
[DllImport("user32.dll")]
internal static extern bool EnumWindows(CallBack cb, IntPtr param);
public class App
public static void Main()
Run();
public static void Run()
TextWriter tw = Console.Out;
GCHandle gch = GCHandle.Alloc(tw);
CallBack cewp = new CallBack(CaptureEnumWindowsProc);
// platform invoke will prevent delegate to be garbage collected
// before call ends
NativeMethods.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;
Imports System.IO
Imports System.Threading
Imports System.Windows.Forms
Imports System.Runtime.InteropServices
Imports System.Security.Permissions
Public Delegate Function CallBack(ByVal handle As Integer, ByVal param As IntPtr) As Boolean
Friend Module NativeMethods
' passing managed object as LPARAM
' BOOL EnumWindows(WNDENUMPROC lpEnumFunc, LPARAM lParam);
<DllImport("user32.dll")>
Friend Function EnumWindows(ByVal cb As CallBack, ByVal param As IntPtr) As Boolean
End Function
End Module
Module App
Sub Main()
Run()
End Sub
<SecurityPermission(SecurityAction.Demand, UnmanagedCode:=True)>
Sub Run()
Dim tw As TextWriter = Console.Out
Dim gch As GCHandle = GCHandle.Alloc(tw)
Dim cewp As CallBack
cewp = AddressOf CaptureEnumWindowsProc
' platform invoke will prevent delegate to be garbage collected
' before call ends
NativeMethods.EnumWindows(cewp, GCHandle.ToIntPtr(gch))
gch.Free()
End Sub
Function CaptureEnumWindowsProc(ByVal handle As Integer, ByVal param As IntPtr) As Boolean
Dim gch As GCHandle = GCHandle.FromIntPtr(param)
Dim tw As TextWriter = CType(gch.Target, TextWriter)
tw.WriteLine(handle)
Return True
End Function
End Module
The
GCHandle
structure is used 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
. When the handle has been allocated, you can use it 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
GCHandle
to create a pinned object that returns a memory address to prevent 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.
