Pinning and GC Handles

Because managed objects located on the GC heap can be relocated during garbage collections occurring at unpredictable times, you must pin them in order to obtain their address and prevent them from being moved around in memory.

Pinning can be done either by using the fixed scope (see example in Listing 8-1) in C# or by allocating a pinning GC handle (see Listing 8-2). P/Invoke stubs, which we will cover later, also pin objects in a way equivalent to the fixed statement. Use fixed if the pinning requirement can be confined to the scope of a function, as it is more efficient than the GC handle approach. Otherwise, use GCHandle.Alloc to allocate a pinning handle to pin an object indefinitely (until you explicitly free the GC handle by calling GCHandle.Free). Stack objects (value types) do not require pinning, because they’re not subject to garbage collection. A pointer can be obtained directly for stack-located objects by using the ampersand (&) reference operator.

Listing 8-1.  Using fixed scope and pointer casting to reinterpret data in a buffer

using (var fs = new FileStream(@"C:Devsamples.dat", FileMode.Open)) {
  var buffer = new byte[4096];
  int bytesRead = fs.Read(buffer, 0, buffer.Length);
  unsafe {
   double sum = 0.0;
   fixed (byte* pBuff = buffer) {
     double* pDblBuff = (double*)pBuff;
     for (int i = 0; i < bytesRead / sizeof(double); i++)
      sum + = pDblBuff[i];
   }
  }
}

GC handles are a way to refer to a managed object residing on the GC heap via an immutable pointer-sized handle value (even if the object’s address changes), which can even be stored by native code. GC handles come in four varieties, specified by the GCHandleType enumeration: Weak, WeakTrackRessurection, Normal and Pinned. The Normal and Pinned types prevent an object from being garbage collected even if there is no other reference to it. The Pinned type additionally pins the object and enables its memory address to be obtained. Weak and WeakTrackResurrection do not prevent the object from being collected, but enable obtaining a normal (strong) reference if the object hasn’t been garbage collected yet. It is used by the WeakReference type.

Listing 8-2.  Using a pinning GCHandle for pinning and pointer casting to reinterpret data in a buffer

using (var fs = new FileStream(@"C:Devsamples.dat", FileMode.Open)) {
  var buffer = new byte[4096];
  int bytesRead = fs.Read(buffer, 0, buffer.Length);
  GCHandle gch = GCHandle.Alloc(buffer, GCHandleType.Pinned);
  unsafe {
   double sum = 0.0;
   double* pDblBuff = (double *)(void *)gch.AddrOfPinnedObject();
   for (int i = 0; i < bytesRead / sizeof(double); i++)
     sum + = pDblBuff[i];
   gch.Free();
  }
}

Lifetime Management

In many cases, native code continues to hold unmanaged resources across function calls, and will require an explicit call to free the resources. If that’s the case, implement the IDisposable interface in the wrapping managed class, in addition to a finalizer. This will enable clients to deterministically dispose unmanaged resources, while the finalizer should be a last-resort safety net in case you forgot to dispose explicitly.

Allocating Unmanaged Memory

Managed objects taking more than 85,000 bytes (commonly, byte buffers and strings) are placed on the Large Object Heap (LOH), which is garbage collected together with Gen2 of the GC heap, which is quite expensive. The LOH also often becomes fragmented because it is never compacted; rather free spaces are re-used if possible. Both these issues increase memory usage and CPU usage by the garbage collector. Therefore, it is more efficient to use managed memory pooling or to allocate these buffers from unmanaged memory (e.g. by calling Marshal.AllocHGlobal). If you later need to access unmanaged buffers from managed code, use a “streaming” approach, where you copy small chunks of the unmanaged buffer to managed memory and work with one chunk at a time. You can use System.UnmanagedMemoryStream and System.UnmanagedMemoryAccessor to make the job easier.

Memory Pooling

If you are heavily using buffers to communicate with native code, you can either allocate them from GC heap or from an unmanaged heap. The former approach becomes inefficient for high allocation rates and if the buffers aren’t very small. Managed buffers will need to be pinned, which promotes fragmentation. The latter approach is also problematic, because most managed code expects buffers to be managed byte arrays (byte[]) rather than pointers. You cannot convert a pointer to a managed array without copying, but this is bad for performance.

We propose a solution (see Figure 8-2) which provides a copy-free access from both managed and unmanaged code and does not stress the GC. The idea is to allocate large managed memory buffers (segments) which reside on the Large Object Heap. There is no penalty associated with pinning these segments because they’re already non-relocatable.

A simple allocator, where the allocation pointer (an index actually) of a segment moves only forward with each allocation will then allocate buffers of varying sizes (up to the segment size) and will return a wrapper object around those buffers. Once the pointer approaches the end and an allocation fails, a new segment is obtained from the segment pool and allocation is attempted again.

Segments have a reference count that is incremented for every allocation and decremented when the wrapper object is disposed of. Once its reference count reaches zero, it can be reset, by setting the pointer to zero and optionally zero filling memory, and then returned to the segment pool.

The wrapper object stores the segment’s byte[], the offset where data begins, its length, and an unmanaged pointer. In effect, the wrapper is a window into the segment’s large buffer. It will also reference the segment in order to decrement the segment in-use count once the wrapper is disposed. The wrapper could provide convenience methods such a safe indexer access which accounts for the offset and verifies that access is within bounds.

Since .NET developers have a habit of assuming that buffer data always begins at index 0 and lasts the entire length of the array, you will need to modify code not to assume that, but to rely on additional offset and length parameters that will be passed along with the buffer. Most .NET BCL methods that work with buffers have overloads which take offset and length explicitly.

The major downside to this approach is the loss of automatic memory management. In order for segments to be recycled, you will have to explicitly dispose of the wrapper object. Implementing a finalizer isn’t a good solution, because this will more than negate the performance benefits.

PInvoke.net and P/Invoke Interop Assistant

Creating P/Invoke signatures can be hard and tedious. There are many rules to obey and many nuances to know. Producing an incorrect signature can result in hard to diagnose bugs. Fortunately, there are two resources which make this easier: the PInvoke.net website and the P/Invoke Interop Assistant tool.

PInvoke.net is a very helpful Wiki-style website, where you can find and contribute P/Invoke signatures for various Microsoft APIs. PInvoke.net was created by Adam Nathan, a senior software development engineer at Microsoft who previously worked on the .NET CLR Quality Assurance team and has written an extensive book about COM interoperability. You can also download a free Visual Studio add-on to access P/Invoke signatures without leaving Visual Studio.

P/Invoke Interop Assistant is a free tool from Microsoft downloadable from CodePlex, along with source code. It contains a database (an XML file) describing Win32 functions, structures, and constants which are used to generate a P/Invoke signature. It can also generate a P/Invoke signature given a C function declaration, and can generate native callback function declaration and native COM interface signature given a managed assembly.

Figure 8-3 shows Microsoft’s P/Invole Interop Assistant tool showing the search results for “CreateFile” on the left side and the P/Invoke signature along with associated structures is shown on the right. The P/Invoke Interop Assistant tool (along with other useful CLR interop-related tools) can be obtained from http://clrinterop.codeplex.com/ .

Binding

When you first call a P/Invoke’d function, the native DLL and its dependencies are loaded into the process via the Win32 LoadLibrary function (if they’ve not already been loaded). Next, the desired exported function is searched for, possibly searching for mangled variants first. Search behavior depends on the values of the CharSet and ExactSpelling fields of DllImport.

• If ExactSpelling is true, P/Invoke searches only for a function with the exact name, taking into account only the calling convention mangling. If this fails, P/Invoke will not continue searching for other name variations and will throw an EntryPointNotFoundException.

• If ExactSpelling is false, then behavior is determined by the CharSet property:

• If set to CharSet.Ansi (default), P/Invoke searches the exact (unmangled) name first, and then the mangled name (with “A” appended).
• If set to CharSet.Unicode, P/Invoke searches the mangled name first (with “W” appended), and then the unmanaged name.

The default value for ExactSpelling is false for C# and True for VB.NET. The CharSet.Auto value behaves like CharSet.Unicode on any modern operating system (later than Windows ME).

Marshaler Stubs

When you first call a P/Invoke’d function, right after loading the native DLL, a P/Invoke marshaler stub will be generated on demand, and will be re-used for subsequent calls. The marshaler performs the following steps once called:

1. Checks for callers’ unmanaged code execution permissions.
2. Converts managed arguments to their appropriate native in-memory representation, possibly allocating memory.
3. Sets thread’s GC mode to pre-emptive, so GC can occur without waiting the thread to reach a safe point.
4. Calls the native function.
5. Restores thread GC mode to co-operative.
6. Optionally saves Win32 error code in Thread Local Storage for later retrieval by Marshal.GetLastWin32Error.
7. Optionally converts HRESULT to an exception and throws it.
8. Converts native exception if thrown to a managed exception.
9. Converts the return value and output parameters back to their managed in-memory representations.
10. Cleans up any temporarily allocated memory.

P/Invoke can also be used to call managed code from native code. A reverse marshaler stub can be generated for a delegate (via Marshal.GetFunctionPointerForDelegate) if it is passed as a parameter in a P/Invoke call to a native function. The native function will receive a function pointer in place of the delegate, which it can call to invoke the managed method. The function pointer points to a dynamically generated stub which in addition to parameter marshaling, also knows the target object’s address (this pointer).

In .NET Framework 1.x, marshaler stubs consisted of either generated assembly code (for simple signatures) or of generated ML (Marshaling Language) code (for complex signatures). ML is an internal byte code and is executed by an internal interpreter. With the introduction of AMD64 and Itanium support in .NET Framework 2.0, Microsoft realized that implementing a parallel ML infrastructure for every CPU architecture would be a great burden. Instead, stubs for 64-bit versions of .NET Framework 2.0 were implemented exclusively in generated IL code. While the IL stubs were significantly faster than the interpreted ML stubs, they were still slower than the x86 generated assembly stubs, so Microsoft opted to retain the x86 implementation. In .NET Framework 4.0, the IL stub generation infrastructure was significantly optimized, which made IL stubs faster compared even to the x86 assembly stubs. This allowed Microsoft to remove the x86-specific stub implementation entirely and to unify stub generation across all architectures.

Microsoft provides a freely downloadable tool called IL Stub Diagnostics from CodePlex along with source code. It subscribes to the CLR ETW IL stub generation/cache hit events and displays the generated IL stub code in the UI.

Below we show an annotated example IL marshaling stub, consisting of five sections of code: initialization, marshaling of input parameters, invocation, marshaling back of return value and/or output parameters and cleanup. The marshaler stub is for the following signature:

// Managed signature:
[DllImport("Server.dll")]static extern int Marshal_String_In(string s);
// Native Signature:
unmanaged int __stdcall Marshal_String_In(char *s)

In the initialization section, the stub declares local (stack) variables, obtains a stub context and demands unmanaged code execution permissions.

// IL Stub:
// Code size	153 (0x0099)
.maxstack 3
// Local variables are:
// IsSuccessful, pNativeStrPtr, SizeInBytes, pStackAllocPtr, result, result, result
.locals (int32,native int,int32,native int,int32,int32,int32)
 
call native int [mscorlib] System.StubHelpers.StubHelpers::GetStubContext()
// Demand unmanaged code execution permissioncall void [mscorlib] System.StubHelpers.StubHelpers::DemandPermission(native int)

In the marshaling section, the stub marshals input parameters native function. In this example, we marshal a single string input parameter. The marshaler may call helper types under the System.StubHelpersnamespace or the System.Runtime.InteropServices.Marshal class to assist in converting of specific types and of type categories from managed to native representation and back. In this example, we call CSTRMarshaler::ConvertToNative to marshal the string.

There’s a slight optimization here: if the managed string is short enough, it is marshaled to memory allocated on the stack (which is faster). Otherwise, memory has to be allocated from the heap.

   ldc.i4     0x0     // IsSuccessful = 0 [push 0 to stack]
   stloc.0     //     [store to IsSuccessful]
IL_0010:
       nop //     argument {
       ldc.i4     0x0     // pNativeStrPtr = null [push 0 to stack]
       conv.i     //     [convert to an int32 to "native int" (pointer)]
       stloc.3     //     [store result to pNativeStrPtr]
       ldarg.0     // if (managedString == null)
       brfalse     IL_0042     // goto IL_0042
       ldarg.0     // [push managedString instance to stack]
       // call the get Length property (returns num of chars)
       call     instance int32 [mscorlib] System.String::get_Length()
   ldc.i4     0x2     // Add 2 to length, one for null char in managedString and
       // one for an extra null we put in [push constant 2 to stack]
       add     // [actual add, result pushed to stack]
       //     load static field, value depends on lang. for non-Unicode
       //     apps system setting
   ldsfld System.Runtime.InteropServices.Marshal::SystemMaxDBCSCharSize
       mul     // Multiply length by SystemMaxDBCSCharSize to get amount of
   // bytes
   stloc.2 // Store to SizeInBytes
   ldc.i4 0x105 // Compare SizeInBytes to 0x105, to avoid allocating too much
   // stack memory [push constant 0x105]
       //     CSTRMarshaler::ConvertToNative will handle the case of
       //     pStackAllocPtr == null and will do a CoTaskMemAlloc of the
   // greater size
   ldloc.2 // [Push SizeInBytes]
   clt // [If SizeInBytes > 0x105, push 1 else push 0]
   brtrue IL_0042 // [If 1 goto IL_0042]
   ldloc.2 // Push SizeInBytes (argument of localloc)
   localloc // Do stack allocation, result pointer is on top of stack
   stloc.3 // Save to pStackAllocPtr
IL_0042:
   ldc.i4 0x1 // Push constant 1 (flags parameter)
       ldarg.0     //     Push managedString argument
   ldloc.3 // Push pStackAllocPtr (this can be null)
   // Call helper to convert to Unicode to ANSI
   call  native int [mscorlib]System.StubHelpers.CSTRMarshaler::ConvertToNative(int32,string,   native   int)
     stloc.1     // Store result in pNativeStrPtr,
   // can be equal to pStackAllocPtr
       ldc.i4 0x1     // IsSuccessful = 1 [push 1 to stack]
   stloc.0 // [store to IsSuccessful]
   nop
   nop
   nop

In the next section, the stub obtains the native function pointer from the stub context and invokes it. The call instruction actually does more work than we can see here, such as changing the GC mode and catching the native function’s return in order to suspend execution of managed code while the GC is in progress and is in a phase that requires suspension of managed code execution.

   ldloc.1     // Push pStackAllocPtr to stack,
               //     for the user function, not for GetStubContext
   call     native int [mscorlib] System.StubHelpers.StubHelpers::GetStubContext()
   ldc.i4     0x14 // Add 0x14 to context ptr
   add     //     [actual add, result is on stack]
   ldind.i // [deref ptr, result is on stack]
   ldind.i     //     [deref function ptr, result is on stack]
   calli     unmanaged stdcall int32(native int) // Call user function

The following section is actually structured as two sections that handle the “unmarshaling” (conversion of native types to managed types) of the return value and output parameters, respectively. In this example, the native function returns an int which does not require marshaling and is just copied as-is to a local variable. Since there are no output parameters, the latter section is empty.

// UnmarshalReturn {
     nop   //   return {
     stloc.s   0x5   // Store user function result (int) into x, y and z
     ldloc.s   0x5
     stloc.s   0x4
     ldloc.s   0x4
     nop   // } return
     stloc.s   0x6
    //   } UnmarshalReturn
  // Unmarshal {
     nop // argument {
     nop // } argument
     leave   IL_007e // Exit try protected block
  IL_007e:
     ldloc.s   0x6   // Push z
     ret   //   Return z
  //   }   Unmarshal

Finally, the cleanup section releases memory that was allocated temporarily for the sake of marshaling. It performs cleanup in a finally block so that cleanup happens even if an exception is thrown by the native function. It may also perform some cleanup only in case of an exception. In COM interop, it may translate an HRESULT return value indicating an error into an exception.

// ExceptionCleanup {
IL_0081:
// } ExceptionCleanup
// Cleanup {
   ldloc.0 // If (IsSuccessful && !pStackAllocPtr)
   ldc.i4 0x0 // Call ClearNative(pNativeStrPtr)
   ble IL_0098
   ldloc.3
   brtrue IL_0098
   ldloc.1
   call void [mscorlib] System.StubHelpers.CSTRMarshaler::ClearNative(native int)
IL_0098:
   endfinally
IL_0099:
// } Cleanup
.try IL_0010 to IL_007e finally handler IL_0081 to IL_0099

In conclusion, the IL marshaler stub is non-trivial even for this trivial function signature. Complex signatures result in even lengthier and slower IL marshaler stubs.

Blittable Types

Most native types share a common in-memory representation with managed code. These types, called blittable types, do not require conversion, and are passed as-is across managed-to-native boundaries, which is significantly faster than marshaling non-blittable types. In fact, the marshaler stub can optimize this case even further by pinning a managed object and passing a direct pointer to the managed object to native code, avoiding one or two memory copy operations (one for each required marshaling direction).

A blittable type is one of the following types:

• System.Byte (byte)
• System.SByte (sbyte)
• System.Int16 (short)
• System.UInt16 (ushort)
• System.Int32 (int)
• System.UInt32 (uint)
• Syste.Int64 (long)
• System.UInt64 (ulong)
• System.IntPtr
• System.UIntPtr
• System.Single (float)
• System.Double (double)

In addition, a single-dimensional array of blittable types (where all elements are of the same type) is also blittable, so is a structure or class consisting solely of blittable fields.

A System.Boolean (bool) is not blittable because it can have 1, 2 or 4 byte representation in native code, a System.Char (char) is not blittable because it can represent either an ANSI or Unicode character and a System.String (string) is not blittable because its native representation can be either ANSI or Unicode, and it can be either a C-style string or a COM BSTR and the managed string needs to be immutable (which is risky if the native code modifies the string, breaking immutability). A type containing an object reference field is not blittable, even if it’s a reference to a blittable type or an array thereof. Marshaling non-blittable types involves allocation of memory to hold a transformed version of the parameter, populating it appropriately and finally releasing of previously allocated memory.

You can get better performance by marshaling string input parameters manually (see the following code for an example). The native callee must take a C-style UTF-16 string and it should never write to the memory occupied by the string, so this optimization is not always possible. Manual marshaling involves pinning the input string and modifying the P/Invoke signature to take an IntPtr instead of a string and passing a pointer to the pinned string object.

class Win32Interop {
  [DllImport("NativeDLL.DLL", CallingConvention = CallingConvention.Cdecl)]
  public static extern void NativeFunc(IntPtr pStr); // takes IntPtr instead of string

}

 
//Managed caller calls the P/Invoke function inside a fixed scope which does string pinning:
unsafe
{
   string str = "MyString";
   fixed (char *pStr = str) {
   //You can reuse pStr for multiple calls.
   Win32Interop.NativeFunc((IntPtr)pStr);
   }
}

Converting a native C-style UTF-16 string to a managed string can also be optimized by using System.String’sconstructor taking a char* as parameter. The System.String constructor will make a copy of the buffer, so the native pointer can be freed after the managed string has been created. Note that no validation is done to ensure that the string only contains valid Unicode characters.

Marshaling Direction, Value and Reference Types

As mentioned earlier, function parameters can be marshaled by the marshaler stub in either or both directions. Which direction a parameter gets marshaled is determined by a number of factors:

• Whether the parameter is a value or reference type.
• Whether the parameter is being passed by value or by reference.
• Whether the type is blittable or not.
• Whether marshaling direction-modifying attributes (System.RuntimeInteropService.InAttribute and System.RuntimeInteropService.OutAttribute) are applied to the parameter.

For the purposes of this discussion, we define the “in” direction to be the managed to native marshaling direction; conversely the “out” direction is the native to managed direction. Below is a list of default marshaling direction rules:

• Parameters passed by value, regardless whether they’re value or reference types, are marshaled in the “in” direction only.

• You do not need to apply the In attribute manually.
• StringBuilder is an exception to this rule and is always marshaled “in/out”.

• Parameters passed by reference (via the ref C# keyword or the ByRef VB .NET keyword), regardless whether they’re value or reference types, are marshaled “in/out”.

Specifying the OutAttribute alone will inhibit the “in” marshaling, so the native callee may not see initializations done by the caller. The C# out keyword behaves like ref keyword but adds an OutAttribute.

Due to the blittable parameter pinning optimization mentioned above, blittable reference types will get an effective “in/out” marshaling, even if the above rules tell otherwise. You should not rely on this behavior if you need “out” or “in/out” marshaling behavior, but instead you should specify direction attributes explicitly, as this optimization will stop working if you later add a non-blittable field or if this is a COM call that crosses an apartment boundary.

The difference between marshaling value types versus reference types manifests in how they are passed on the stack.

• Value types passed by value are pushed as copies on the stack, so they are effectively always marshaled “in”, regardless of modifying attributes.
• Value types passed by reference and reference types passed by value are passed by pointer.
• Reference types passed by reference are passed as pointer to a pointer.

Code Access Security

The .NET Code Access Security mechanism enables running partially trusted code in a sandbox, with restricted access to runtime capabilities (e.g. P/Invoke) and BCL functionality (e.g. file and registry access). When calling native code, CAS requires that all assemblies whose methods appear in the call stack to have the UnmanagedCode permission. The marshaler stub will demand this permission for each call, which involves walking the call stack to ensure that all code has this permission.

Lifetime Management

When you hold a reference to a COM object in .NET, you are actually holding a reference to an RCW. The RCW always holds a single reference to the underlying COM object and there is only one RCW instance per COM object. The RCW maintains its own reference count, separate from the COM reference count. This reference count’s value is usually one but can be greater if a number of interface pointers have been marshaled or if the same interface has been marshaled by multiple threads.

Normally, when the last managed reference to the RCW is gone and there is a subsequent garbage collection at the generation where the RCW resides; the RCW’s finalizer runs and it decrements the COM objects’s reference count (which was one) by calling the Release method on the IUnknown interface pointer for the COM underlying object. The COM object subsequently destroys itself and releases its memory.

Since the .NET GC runs at non-deterministic times and is not aware of the unmanaged memory burden caused by it holding the RCWs and subsequently COM objects alive, it will not hasten garbage collections and memory usage may become be very high.

If necessary, you can call the Marshal.ReleaseComObject method to explicitly release the object. Each call will decrement RCW’s reference count and when it reaches zero, the underlying COM object’s reference count will be decremented (just like in the case of the RCW’s finalizer running), thus releasing it. You must ensure that you do not continue to use the RCW after calling Marshal.ReleaseComObject. If the RCW reference count is greater than zero, you will need to call Marshal.ReleaseComObject in a loop until the return value equals zero. It is a best practice to call Marshal.ReleaseComObject inside a finally block, to ensure that the release occurs even in the case of an exception being thrown somewhere between the instantiation and the release of the COM object.

Apartment Marshaling

COM implements its own thread synchronization mechanisms for managing cross-thread calls, even for objects not designed for multi-threading. These mechanisms can degrade performance if one is not aware of them. While this issue is not specific for interoperability with .NET, it is nonetheless worth discussing as it is a common pitfall, likely because developers that are accustomed to typical .NET thread synchronizations conventions might be unaware of what COM is doing behind the scenes.

COM assigns objects and threads apartments which are boundaries across which COM will marshal calls. COM has several apartment types:

• Single–threaded apartment (STA), each hosts a single thread, but can host any number of objects. There can be any number of STA apartments in a process.
• Multi–threaded apartment (MTA), hosts any number of threads and any number of objects,but there is only one MTA apartment in a process. This is the default for .NET threads.
• Neutral-threaded apartment (NTA), hosts objects but not threads. There is only one NTA apartment in a process.

A thread is assigned to an apartment when a call is made to CoInitialize or CoInitializeEx to initialize COM for that thread. Calling CoInitialize will assign the thread to a new STA apartment, while CoInitializeEx allows you to specify either an STA or an MTA assignment. In .NET, you do not call those functions directly, but instead mark a thread’s entry point (or Main) with the STAThread or MTAThread attribute. Alternatively, you can call Thread.SetApartmentState method or the Thread.ApartmentState property before a thread is started. If not otherwise specified, .NET initializes threads (including the main thread) as MTA.

COM objects are assigned to apartments based on the ThreadingModel registry value, which can be:

• Single – object resides in the default STA.
• Apartment (STA) – object must reside in any STA, and only that STA’s thread is allowed to call the object directly. Different instances can reside in different STA.
• Free (MTA) – object resides in the MTA. Any number of MTA threads can call it directly and concurrently. Object must ensure thread-safety.
• Both – object resides in the creator’s apartment (STA or MTA). In essense, it becomes either STA-like or MTA-like object once created.
• Neutral – object resides in the neutral apartment and never requires marshaling. This is the most efficient mode.

Refer to Figure 8-6 for a visual representation of apartments, threads and objects.

If you create an object with a threading model incompatible with that of the creator thread’s apartment, you will receive an interface pointer which actually points to a proxy. If the COM object’s interface needs to be passed to a different thread belonging to a different apartment, the interface pointer should not be passed directly, but instead needs to be marshaled. COM will return a proxy object as appropriate.

Marshaling involves translating the function’s call (including parameters) to a message which will be posted to the recipient STA apartment’s message queue. For STA objects, this is implemented as a hidden window whose window procedure receives the messages and dispatches calls to the COM object via a stub. In this way, STA COM objects are always invoked by the same thread, which is obviously thread-safe.

When the caller’s apartment is incompatible with the COM object’s apartment, a thread switch and cross-thread parameter marshaling occurs.

TLB Import and Code Access Security

Code Access Security does the same security checking as in P/Invoke. You can use the /unsafe switch with the tlbimp.exe utility which will emit the SuppressUnmanagedCodeSecurity attribute on generated types. Use this only in full-trust environments as this may introduce security issues.

NoPIA

Prior to .NET Framework 4.0, you had to distribute interop assemblies or Primary Interop Assemblies (PIA) alongside with your application or add-in. These assemblies tend to be large (even more so compared to the code that uses them), and they are not typically installed by the vendor of the COM component; instead they are installed as redistributable packages, because they are not required for the operation of the COM component itself. Another reason for not installing the PIAs is that they have to be installed in the GAC, which imposes a .NET Framework dependency on the installer of an otherwise completely native application.

Starting with .NET Framework 4.0, the C# and VB.NET compilers can examine which COM interfaces and which methods within them are required, and can copy and embed only the required interface definitions into the caller assembly, eliminating the need to distribute PIA DLLs and reducing code size. Microsoft calls this feature NoPIA. It works both for Primary Interop Assemblies and for interop assemblies in general.

PIA assemblies had an important feature called type equivalence. Since they have a strong name and are put into the GAC, different managed components can exchange the RCWs, and from .NET’s perspective, they would have equivalent type. In contrast, interop assemblies generated by tlbimp.exe would not have this feature, since each component would have its own distinct interop assembly. With NoPIA, since there is a strongly named assembly is not used, Microsoft came up with a solution which treats RCWs from different assemblies as the same type, as long as the interfaces have the same GUID.

To enable NoPIA, select Properties on the interop assembly under References, and set “Embed Interop Types” to True (see Figure 8-7).

Exceptions

Most COM interface methods report success or failure via an HRESULT return value. Negative HRESULT values (with most significant bit set) indicate failure, while zero (S_OK) or positive values report success. Additionally, a COM object may provide richer error information by calling the SetErrorInfo function, passing an IErrorInfo object which is created by calling CreateErrorInfo. When calling a COM method via COM interop, the marshaler stub converts the HRESULT into a managed exception according to the HRESULT value and the data contained inside the IErrorInfo object. Since throwing exceptions is relatively expensive, COM functions that fail frequently will negatively impact performance. You can suppress automatic exception translation by marking methods with the PreserveSigAttribute. You will have to change the managed signature to return an int, and the retval parameter will become an “out” parameter.

The marshal_as Helper Library

In this section, we will elaborate on the marshal_as helper library provided as part of Visual C++ 2008 and later.

marshal_as is a template library for simplified and convenient marshaling of managed to native types and vice versa. It can marshal many native string types, such as char *, wchar_t *, std::string, std::wstring, CStringT<char>, CStringT<wchar_t>, BSTR, bstr_t and CComBSTR to managed types and vice versa. It handles Unicode/ANSI conversions and handles memory allocations/release automatically.

The library is declared and implemented inline in marshal.h (for base types), in marshal_windows.h (for Windows types), in marshal_cppstd.h (for STL data types) and in marshal_atl.h (for ATL data types).

marshal_as can be extended to handle conversion of user-defined types. This helps avoid code duplication when marshaling the same type in many places and allows having a uniform syntax for marshaling of different types.

The following code is an example of extending marshal_as to handle conversion of a managed array of strings to an equivalent native array of strings.

namespace msclr {
 namespace interop {
   template<>
   ref class context_node<const wchar_t**, array<String^>^> : public context_node_base {
   private:
     const wchar_t** _tasks;
     marshal_context _context;
   public:
     context_node(const wchar_t**& toObject, array<String^>^ fromObject) {
     //Conversion logic starts here
     _tasks = NULL;
   const wchar_t **pTasks = new const wchar_t*[fromObject->Length];
   for (int i = 0; i < fromObject->Length; i++) {
   String ^t = fromObject[i];
   pTasks[i] = _context.marshal_as<const wchar_t *>(t);
   }
   toObject = _tasks = pTasks;
   }
 
   ∼context_node() {
   this->!context_node();
   }
 
   protected:
   !context_node() {
     //When the context is deleted, it will free the memory
   //allocated for the strings (belongs to marshal_context),
     //so the array is the only memory that needs to be freed.
     if (_tasks != nullptr) {
   delete[] _tasks;
     _tasks = nullptr;
   }
     }
   };
 }
}
//You can now rewrite Employee::DoWork like this:
  void DoWork(array<String^>^ tasks) {
    //All unmanaged memory is freed automatically once marshal_context
    //gets out of scope.
  msclr::interop::marshal_context ctx;
    _employee->DoWork(ctx.marshal_as<const wchar_t **>(tasks), tasks->Length);
}

IL Code vs. Native Code

An unmanaged class will by default be compiled to IL code in C++/CLI rather than to machine code. This can degrade performance relative to optimized native code, because Visual C++ compiler can optimize code better than the JIT can.

You can use #pragma unmanaged and #pragma managed before a section of code to override complication behavior. Additionally, in a VC++ project you can also enable C++/CLI support for individual compilation units (.cpp files).