Title: Exception Handling in C#

In the absence of exceptions the classic way to handle errors is to intertwine your statements with error checks. For example:

  public sealed class Painful {
      ...
      private static char[] ReadSource(string filename) {
          FileInfo file = new FileInfo(filename);
          if (errorCode == 2342) goto handler;
          int length = (int)file.Length;
          char[] source = new char[length];
          if (errorCode == -734) goto handler;
          TextReader reader = file.OpenText();
          if (errorCode == 2664) goto handler;
          reader.Read(source, 0, length);
          if (errorCode == -5227) goto handler;
          reader.Close();
          Process(filename, source);
          return source;
          handler:
          ...
      }
  }

This style of programming is tedious, repetitive, awkward, complex, and obscures the essential functionality. And it's too easy to ignore errors (either deliberately or accidentally). There have to be better ways. And there are. But some are better than others.

The fundamental thing that exceptions allow you to do is to separate the essential functionality from the error handling. In other words, we can rewrite the mess above like this:

  ...
  public sealed class PainLess {

      public static int Main(string[] args) {
          try {
              string filename = args[0];
              char[] source = ReadSource(filename);
              Process(filename, source);
              return 0;
          }
          catch (SecurityException caught) {...}
          catch (IOException caught) {...}
          catch (OutOfMemoryException caught) {...}
          ...
      }

      private static char[] ReadSource(string filename) {
          FileInfo file = new FileInfo(filename);
          int length = (int)file.Length;
          char[] source = new char[length];
          TextReader reader = file.OpenText();
          reader.Read(source, 0, length);
          reader.Close();
          return source;
      }
  }

There are several things to notice about this transformation.

However, by far and away the most important thing is how clean, simple and easy to understand ReadSource is. It contains the statements required to implement its essential functionality and nothing else. There is no apparent concession to error handling. This is possible because if an exception occurs the call stack will unwind all by itself. This version of ReadSource is the "ideal" we are aiming it. It is as direct as we can make it.

Ironically, exceptions allow us to get close to this ideal version of ReadSource but at the same time prevent us from quite reaching it. The problem is that ReadSource is an example of code that acquires a resource (a TextReader), uses the resource (Read), and then releases the resource (Close). The problem is that if an exception occurs after acquiring the resource but before releasing it then the release will not take place. The solution has become part of the context. Nevertheless, this "ideal" version of ReadSource is useful; we can compare forthcoming versions of ReadSource to it as a crude estimate of their "idealness".

The solution to this lost release problem depends on the language you're using. In C++ you can release the resource in the destructor of an object held on the stack (the misnamed Resource Acquisition Is Initialization idiom). In Java you can use a finally block. C# allows you to create user-defined struct types that live on the stack but does not allow struct destructors. (This is because a C# destructor is really a Finalize method in disguise and Finalize is called by the garbage collector. Structs, being value types, are never subject to garbage collection.) Therefore, initially at least, C# must follow the Java route and use a finally block. A first cut implementation using a finally block might look like this:

  private static char[] ReadSource(string filename) {
      try {
          FileInfo file = new FileInfo(filename);
          int length = (int)file.Length;
          char[] source = new char[length];
          TextReader reader = file.OpenText();
          reader.Read(source, 0, length);
      }
      finally {
          reader.Close();
      }
      return source;
  }

This version has had to introduce a try block (since a finally block must follow a try block) which isn't in the ideal solution but apart from that it's the same as the "ideal" version of ReadSource. It would be a reasonable solution if it worked. But it doesn't. The problem is that the try block forms a scope so reader is not in scope inside the finally block and source is not in scope at the return statement.

To solve this problem you have to move the declarations of reader and source outside the try block. A second attempt might be:

  private static char[] ReadSource(string filename) {
      TextReader reader;
      char[] source;
      try {
          FileInfo file = new FileInfo(filename);
          int length = (int)file.Length;
          source = new char[length];
          reader = file.OpenText();
          reader.Read(source, 0, length);
      }
      finally {
          reader.Close();
      }
      return source;
  }

This version has moved the declaration of reader and source out of the try block and consequently, inside the try block, assigns to reader and source rather than initializing them. That's another difference (and two extra lines) from the "ideal" version of ReadSource. Nevertheless, you might consider it a reasonable solution if it worked. But it doesn't. The problem is that assignment is not the same as initialization and the compiler knows it. If an exception is thrown before reader is assigned then the call to reader.Close() in the finally block will be on reader which won't be assigned. C#, like Java, doesn't allow that.

Clearly you have to initialize reader. A third attempt therefore might be:

  private static char[] ReadSource(string filename) {
      TextReader reader = null;
      char[] source;
      try {
          FileInfo file = new FileInfo(filename);
          int length = (int)file.Length;
          source = new char[length];
          reader = file.OpenText();
          reader.Read(source, 0, length);
      }
      finally {
          reader.Close();
      }
      return source;
  }

This version introduces null which isn't in the "ideal" version of ReadSource. Nevertheless, you might still consider it a reasonable solution if it worked. But it doesn't (although it does compile). The problem is the call to reader.Close() could easily throw a NullReferenceException.

One way to solve this problem is to guard the call to reader.Close(). A fourth attempt therefore might be:

  private static char[] ReadSource(string filename) {
      TextReader reader = null;
      char[] source;
      try {
          FileInfo file = new FileInfo(filename);
          int length = (int)file.Length;
          source = new char[length];
          reader = file.OpenText();
          reader.Read(source, 0, length);
      }
      finally {
          if (reader != null)
              reader.Close();
      }
      return source;
  }

Of course, the guard on reader.Close() isn't in the "ideal" version of ReadSource. But this is a reasonable version if only because it does, finally, work. It's quite different from the "ideal" version but with a bit of effort you can refactor it to this:

  private static char[] ReadSource(string filename) {
      FileInfo file = new FileInfo(filename);
      int length = (int)file.Length;
      char[] source = new char[length];
      TextReader reader = file.OpenText();
      try {
          reader.Read(source, 0, length);
      }
      finally {
          if (reader != null)
              reader.Close();
      }
      return source;
  }

In some cases you might be able to drop the null guard inside the finally block but in general this is the best you can do with a finally block solution. (Consider if file.OpenText returned null.) You have to add a try block, a finally block, and an if guard. And if you are using Java you have to do those three things every time. And therein is the biggest problem. If this solution was truly horrible and completely and utterly different to the ideal solution it wouldn't matter a jot if we could abstract it all away. But in Java you can't. The Java road stops here, but the C# road continues.

In C#, the nearest you can get to the "ideal" version is this:

  private static char[] ReadSource(string filename) {
      FileInfo file = new FileInfo(filename);
      int length = (int)file.Length;
      char[] source = new char[length];
      using (TextReader reader = file.OpenText()){ reader.Read(source, 0, length); }
      return source;
  }

This is pretty close. And as I'll explain shortly it has a number of features that improve on the "ideal" version. But first let's look under the lid to see how it actually works.

The C# ECMA specification states that a using statement:

  using (type variable = initialization)
      embeddedStatement

is equivalent to:

  {
      type variable = initialization;
      try { embeddedStatement }
      finally {
          if (variable != null) {
              ((IDisposable)variable).Dispose();
          }
      }
  }

This relies on the IDisposable interface from the System namespace:

  namespace System {
      public interface IDisposable {
          void Dispose();
      }
  }

Note that the cast inside the finally block implies that variable must be of a type that supports the IDisposable interface (either via inheritance or conversion operator). If it doesn't you'll get a compile time error.

Not surprisingly, TextReader supports the Disposable interface and implements Dispose to call Close. This means that this:

  using (TextReader reader = file.OpenText()) {
      reader.Read(source, 0, length);
  }

is translated, under the hood, into this:

  { TextReader reader = file.OpenText();
      try { reader.Read(source, 0, length); }
      finally {
          if (reader != null) {
              ((IDisposable)reader).Dispose();
          }
      }
  }

Apart from the cast to IDisposable this is identical to the best general Java solution. The cast is required because this is a general solution.

It's instructive to consider what would happen if TextReader didn't implement the Disposable interface. The lessons from this will show us how to implement Disposability in our own classes. One solution is the Object Adapter pattern. For example:

  public sealed class AutoTextReader: Idisposable {
      public AutoTextReader(TextReader target) {
          // PreCondition(target != null);
          adaptee = target;
      }

      // readonly property
      public TextReader TextReader {
          get { return adaptee; }
      }

      public void Dispose() {
          adaptee.Close();
      }

      private readonly TextReader adaptee;
  }

which you would use like this:

  using (AutoTextReader scoped = new AutoTextReader(file.OpenText())) {
      scoped.TextReader.Read(source, 0, length);
  }

To make things a little easier you can create an implicit conversion operator:

  public sealed class AutoTextReader: Idisposable {
      ...
      public static implicit operator AutoTextReader(TextReader target) {
          return new AutoTextReader(target);
      }
      ...
  }

which would allow you to write this:

  using (AutoTextReader scoped = file.OpenText()) {
      scoped.TextReader.Read(source, 0, length);
  }

AutoTextReader is a sealed class intended, as its name suggests, to be used as a local variable. It makes sense to implement it as a struct instead of class:

  public struct AutoTextReader : Idisposable {
      // exactly as before
  }

Using a struct instead of a class also gives you a couple of free optimizations. Since a struct is a value type it can never be null. This means the compiler can omit the null guard from generated finally block. Also, since you cannot derive from a struct its runtime type is always the same as its compile time type. This means the compiler can also omit the cast to IDisposable from the generated finally block and thus avoid a boxing operation. In other words, when AutoTextReader is a struct, this:

  using (AutoTextReader scoped = file.OpenText()) {
      scoped.TextReader.Read(source, 0, length);
  }

is translated into this:

  {
      AutoTextReader scoped = new file.OpenText();
      try {
          scoped.TextReader.Read(source, 0, length);
      }
      finally {
          scoped.Dispose();
      }
  }

It should come as no surprise that I prefer the using statement solution to the finally block solution. In fact, the using statement solution scores several extra points in comparison to the "ideal" solution. A using statement

This is reminiscent of C++ declarations in conditions. Both allow you to restrict the scope of a variable so it's only usable when in scope and is only in scope when usable. This is more than just a syntactic nicety since any attempt to use a released resource could well throw an exception.