The CER is a region of reliable managed code that is guaranteed to run to completion without interruption. Even an asynchronous exception will not prevent the region from executing to completion. Within the CER, developers are constrained to certain actions. These are actions that will not cause an asynchronous exception, such as a memory exception or thread abort. The CLR performs a variety of checks and does some preparation to ensure that code in the CER runs without interruption. This is a short list of some of the actions that should be avoided in a CER:

In a CER, the CLR delays an asynchronous exception event, such as a thread abort, until the region is exited.

You can create CER regions using the RuntimeHelpers.PrepareConstrainedRegions method. Call the PrepareConstrainedRegions static method immediately prior to a try statement. This places the subsequent catch or finally block in a CER. The RuntimeHelpers class is in the System.Runtime.CompilerServices namespace. The code in the try block is not reliable and can be interrupted. However, the related catch or finally block is within a CER and is uninterruptible. From the catch or finally block in a CER, you can call only methods with a strong reliability contract.

Code in a CER can call only reliable methods. Reliable methods have a reliability contract as defined within the ReliabilityContractAttribute, which is an attribute. This class is found in the System.Runtime.ConstrainedExecution namespace. Reliability contracts can be applied to an individual method, methods of a class, or an entire assembly. The ReliabilityContractAttribute constructor has two parameters. The first parameter is the ConsistencyGuarantee property, which indicates the potential scope of corruption if an asynchronous exception occurs during execution. For example, Consistency.MayCorruptAppDomain means that an asynchronous exception can leave the application domain in an unreliable state. The second parameter is the Cer property, which is a completion guarantee. Cer.Success is the highest guarantee and promises that the code will successfully complete, assuming valid input. With the reliability contract, developers make reliability assurances. The CLR does not strictly enforce the reliability constraints. Instead, the CLR relies on developer commitment.

Here is an example of a CER region:

[ReliabilityContract(Consistency.WillNotCorruptState,
        Cer.Success)]
class ZClass {

    void MethodA() {
        RuntimeHelpers.PrepareConstrainedRegions();
        try {
        }
        finally {
            // CER Region
        }
    }
}

Stephen Toub has written a detailed and informative article on CERs called "Keep Your Code Running with the Reliability Features of the .NET Framework." It can be found at the following link: http://msdn.microsoft.com/msdnmag/issues/05/10/reliability/default.aspx.

A CER is used in a variety of places: with annotated try statements, as described in this section, methods executed using the RuntimeHelpers.ExecuteCodeWithGuaranteedCleanup method, and classes derived from the CriticalFinalizerObject class. CriticalFinalizerObject class is introduced in the next section; but the ExecuteCodeWithGuaranteedCleanup method is outside the scope of this book.

Asynchronous exceptions can prevent a finalizer from running, and critical cleanup code might not execute. Resource leakage and other problems can occur when critical finalization code is abandoned. Objects derived from the CriticalFinalizerObject class, which is located in the System.Runtime namespace, have critical finalizers. The finalizer runs uninterrupted in a CER. As such, any method called from the finalizer must have a strong reliability contract. The CLR assures that critical finalizables of critical finalizer objects are executed. Conditions that can prevent a normal finalizer from running, such as a forcible thread abort or an unload of the application domain, do not affect a critical finalizer. This is especially an issue in environments that host managed applications, such as SQL Server. A CLR host can asynchronously interrupt a managed application, which can strand important finalizers. Critical finalizer objects solve this potential problem. During normal garbage collection, regular finalizers always run before critical finalizers.

When passing handles during interoperability, handles can be mishandled, which can cause leaks or other problems. There are two primary causes:

The solution is to use safe handles, which are classes derived from SafeHandle. The SafeHandle class itself derives and implements the CriticalFinalizerObject type. SafeHandle is an abstract class and must be inherited in another class. Specifically implemented safe handles include SafeHandle, SafeFileHandle, SafeWaitHandle, SafeHandleMinusOneIsInvalid, and SafeHandleZeroOrMinusOneIsInvalid. SafeHandle is in the System.Runtime.InteropServices namespace. The remaining SafeHandle classes mentioned in this paragraph are found in the Microsoft.Win32.SafeHandles namespace. Safe handles support reference counting. Review the documentation of the SafeHandle class for information on the specific implementation of reference counting.

When passed as a parameter in platform invocation, safe handles increment the reference count. After the call is completed, the reference count is decremented automatically, which prevents the handle from being inadvertently released in managed code during a native call.

In the following code, the PipeHandle class is a safe wrapper for a pipe handle. The class exposes the CreatePipe and the CloseHandle application programming interfaces (APIs) through interoperability. Because the CloseHandle method will be called in a CER, a reliability contract is placed on that method. PipeHandle derives from the SafeHandleMinusOneIsInvalid class for the proper behavior, which is derived from SafeHandle. The finalizer of the base class automatically calls the ReleaseHandle method. The overridden ReleaseHandle method should implement the proper behavior to release the pertinent handle.

In the AnonymousPipe constructor, two PipeHandle instances are initialized, which are a read and write handle. Because these are safe handles, the underlying handle is safer from leaks and corruption. In the following sample code, the DllImport attribute imports a native function:

public sealed class PipeHandle :
    SafeHandleMinusOneIsInvalid {

    private PipeHandle()
        : base(true) {
    }

   [ReliabilityContract(Consistency.WillNotCorruptState,
            Cer.Success)]
    protected override bool ReleaseHandle() {
        return CloseHandle(handle);
    }

   [DllImport("kernel32.dll")]
    extern public static bool CreatePipe(
        out PipeHandle hReadPipe,
        out PipeHandle hWritePipe,
        IntPtr securityAttributes,
        int nSize);

   [ReliabilityContract(Consistency.WillNotCorruptState,
           Cer.Success)]
   [DllImport("kernel32.dll")]
    public static extern bool CloseHandle(IntPtr handle);
}

public class AnonymousPipe {
    public AnonymousPipe() {

        PipeHandle.CreatePipe(out readHandle, out writeHandle,
            IntPtr.Zero, 10);
        MessageBox.Show((readHandle.DangerousGetHandle())
            .ToInt32().ToString());
        MessageBox.Show((writeHandle.DangerousGetHandle())
            .ToInt32().ToString());
    }

    private PipeHandle readHandle = null;
    private PipeHandle writeHandle = null;
}

The wrapper for an unhandled resource can hide the true memory cost of an object. Incorrect accounting of unhandled memory in the managed environment can cause unexpected out-of-memory exceptions.

To solve this problem, you can add memory pressure, which accounts for unmanaged memory in the managed environment. This prevents a wrapper to an unmanaged resource from hiding an elephant in the closet. Memory pressure forces garbage collection sooner, which collects unused instances of the wrapper class. The wrapper releases the unmanaged resource to reduce the memory pressure on both managed and unmanaged memory.

The GC.AddMemoryPressure method adds artificial memory pressure on the managed heap for an unmanaged resource, whereas the GC.RemoveMemoryPressure method removes memory pressure. Both methods should be integrated into the wrapper class of the unmanaged resource. Call AddMemoryPressure and RemoveMemoryPressure in the setup and cleanup for the class, respectively. Each instance of the MyDevice unmanaged resource uses 40 KB of memory on the unmanaged heap. In the following code, the constructor and destructor for the MyDevice wrapper now account for the unmanaged memory:

public MyDevice() {
    GC.AddMemoryPressure(40000);
    obj = new MyDeviceLib.DeviceClass();
    ++count;
}

~MyDevice() {
    GC.RemoveMemoryPressure(40000);
    // resource released
    --count;
}

Some native resources are available in limited quantities. Exhausting the resource can hang the application, crash the environment, or cause other adverse reactions. The availability of a limited resource should be tracked. When the resource is exhausted, corrective action should occur. Some limited kernel resources, such as a window, are assigned handles. The HandleCollector class manages handles to limited kernel resources. Despite the name, the HandleCollector class is not limited to tracking kernel handles. You can use the HandleCollector class to manage any resource that has limited availability. The HandleCollector class is found in the System.Runtime.InteropServices namespace.

The HandleCollector class has a three-argument constructor that configures the important properties of the type. The arguments are the name, initial threshold, and maximum threshold. Names allows you to name the collector. The initial threshold sets the minimal level for possible garbage collection. The maximum threshold sets the level where garbage collection is forced. Hopefully, this will garbage-collect managed resources that are holding unmanaged resources. In the cleanup, these objects will release these resources and lower the handle count.

In the managed classes, define a static instance of the HandleCollector. In the constructor, call HandleCollector.Add. In the cleanup code, call HandleCollector.Remove.

The following code shows the MyDevice class revised for the HandleCollector class. The MyDevice unmanaged resource supports an initial threshold of three simultaneous connections and a maximum of five. You can test the effectiveness of the wrapper in the UseResource application by clicking the Connect button, which applies pressure, and monitoring the message boxes:

public sealed class MyDevice {
    static private HandleCollector track =
        new HandleCollector("devices", 3, 5);

    static private int count = 0;

    public MyDevice() {
        GC.AddMemoryPressure(40000);
        track.Add();
        obj = new MyDeviceLib.DeviceClass();
        ++count;
        MessageBox.Show("Device count: " + count.ToString());
    }

    private MyDeviceLib.DeviceClass obj;
    public void Open() {
        obj.OpenDevice();
    }

    public void Close() {
        obj.CloseDevice();
    }

    public void Start() {
        obj.StartCommunicating();
    }

    public void Stop() {
        obj.StopCommunicating();
    }

    ~MyDevice() {
        GC.RemoveMemoryPressure(40000);
        track.Remove();
        // resource released
        --count;
    }
}