GCHandle: when to use GCHandleType.Normal explicitly?

From the documentation for GCHandle :

  Provides a way to access a managed object from unmanaged memory.

If you are going to access an object from unmanaged code, you need to pin the object. In order to get a pinned object, you must ensure that it is marshaled to unmanaged memory.

If you only need an opaque descriptor to pass to unmanaged code so that unmanaged code can pass it again without accessing it, then you don't need the pinned object, but you still need to make sure it's not garbage collected.

Consider this class:

public class MyClass
{
    DateTime dt = DateTime.Now;
}

      

        
        
        
      

    

If you try to attach a handle to it like this:

MyClass o = new MyClass();
GCHandle h = GCHandle.Alloc(o, GCHandleType.Pinned);

      

        
        
        
      

    

you will get an exception with the message:

Object contains non-primitive or non-blittable data.

This is because the returned handle allows you to get the address of the pinned object. To use this address from unmanaged code, the object must be converted from managed to unmanaged memory.

This code does not throw an exception:

MyClass o = new MyClass();
GCHandle h = GCHandle.Alloc(o, GCHandleType.Normal);

      

        
        
        
      

    

Because you cannot use the returned handle to get the address.

So, to answer your questions:

1. The managed object (MyClass mc = new MyClass ()) has no entry in the GC descriptor table. It will be a garbage collector when not referenced from managed code (I guess that's what Jeffrey Richter calls application code. I haven't read the book).
2. I use GCHandleType.Normal when I need to pass an opaque handle to unmanaged code .

One scenario is pure C API for managed assembly. The API might look something like this:

MYHANDLE h1 = MyLib_CreateComponent();
MYHANDLE h2 = MyLib_CreateComponent();

MyLib_SetX(h1, 9.81);
double y1 = MYLib_CalcY(h1);
MyLib_SetX(h2, 3.14);
double y2 = MyLib_CalcY(h2);

printf("z = %f\n", y1 + y2);

MyLib_DestroyComponent(h1);
MyLib_DestroyComponent(h2); 

      

        
        
        
      

    

There is no direct access to the object from C code.

The C # implementation for the MyLib_CreateComponent () function would look like this:

 public static int CreateComponent()
 {
     MyClass instance = new MyClass();
     GCHandle gch = GCHandle.Alloc(instance, GCHandleType.Normal);
     IntPtr ip = GCHandle.ToIntPtr(h);
     h = ip.ToInt32();
     return h;
 }

      

        
        
        
      

    

Inside the managed code, I would create a method to grab the object using a handle:

static MyClass GetObjectFromHandle(int hComp)
{
    IntPtr ip = new IntPtr(hComp);
    GCHandle h = GCHandle.FromIntPtr(ip);
    MyClass comp = h.Target as MyClass;
    return comp;
}