Motivation

It’s clear that a lot of programmers are uncomfortable with exceptions [1] [2]; in the feedback of an article I wrote about casting, it seemed that many programmers saw the throwing of a NullReferenceException at a cast to be an incredible catastrophe.

In this article, I’ll share a philosophy that I hope will help programmers overcome the widespread fear of exceptions. It’s motivated by five goals:

1. Do no harm
2. To write as little error handling code as possible,
3. To think about error handling as little as possible
4. To handle errors should handled correctly when possible,
5. Otherwise errors should be handled sanely

To do that, I

1. Use finally to stabilize program state when exceptions are thrown
2. Catch and handle exceptions locally when the effects of the error are local and completely understood
3. Wrap independent units of work in try-catch blocks to handle errors that have global impact

This isn’t the last word on error handling, but it avoids many of the pitfalls that people fall into with exceptions. By building upon this strategy, I believe it’s possible to develop an effective error handling strategy for most applications: future articles will build on this topic, so keep posted by subscribing to the Generation 5 RSS Feed.

The Tragedy of Checked Exceptions

Java’s done a lot of good, but checked exceptions are probably the worst legacy that Java has left us. Java has influenced Python, PHP, Javascript, C# and many of the popular languages that we use today. Unfortunately, checked exceptions taught Java programmers to catch exceptions prematurely, a habit that Java programmers carried into other languages, and has result in a code base that sets bad examples.

Most exceptions in Java are checked, which means that the compiler will give you an error if you write

[01] public void myMethod() {
[02]    throw new ItDidntWorkException()
[03] };

unless you either catch the exception inside myMethod or you replace line [01] with

[04] public void myMethod() throws ItDidntWorkException {

The compiler is also aware of any checked exceptions that are thrown by methods underneath myMethod, and forces you to either catch them inside myMethod or to declare them in the throws clause of myMethod.

I thought that this was a great idea when I started programming Java in 1995. With the hindsight of a decade, we can see that it’s a disaster. The trouble is that every time you call a method that throws an exception, you create an immediate crisis: you break the build. Rather than conciously planning an error handling strategy, programmers do something, anything, to make the compiler shut up. Very often you see people bypass exceptions entirely, like this:

[05] public void someMethod() {
[06]    try {
[07]       objectA.anotherMethod();
[08]    } catch(SubsystemAScrewedUpException ex) { };
[09] }

Often you get this instead:

[10]    try {
[11]       objectA.anotherMethod();
[12]    } catch(SubsystemAScrewedUp ex) {
[13]        // something ill-conceived to keep the compiler happy
[14]    }
[15]    // Meanwhile,  the programmer makes a mistake here because
[16]    // writing an exception handler broke his concentration

This violates the first principle, to “do no harm.” It’s simple, and often correct, to pass the exception up to the calling function,

[17] public int someMethod() throws SubsystemAScrewedUp {

But, this still breaks the build, because now every function that calls someMethod() needs to do something about the exception. Imagine a program of some complexity that’s maintained by a few programmers, in which method A() calls method B() which calls method C() all the way to method F().

The programmer who works on method F() can change the signature of that method, but he may not have the authority to change the signature of the methods above. Depending on the culture of the shop, he might be able to do it himself, he might talk about it with the other programmers over IM, he might need to get the signatures of three managers, or he might need to wait until the next group meeting. If they keep doing this, however, A() might end up with a signature like

[18] public String A() throws SubsystemAScrewedUp, IOException, SubsystemBScrewedUp,
[19]   WhateverExceptionVendorZCreatedToWrapANullPointerException, ...

This is getting out of hand, and they realize they can save themselvesa lot of suffering by just writing

[20] public int someMethod() throws Exception {

all the time, which is essentially disabling the checked exception mechanism. Let’s not dismiss the behavior of the compiler out of hand, however, because it’s teaching us an important lesson: error handling is a holistic property of a program: an error handled in method F() can have implications for methods A()…E(). Errors often break the assumption of encapsulation, and require a global strategy that’s applied consistently throughout the code.

PHP, C# and other post-Java languages tend to not support checked exceptions. Unfortunately, checked exception thinking has warped other langages, so you’ll find that catch statements are used neurotically everywhere.

Exception To The Rule: Handling Exceptions Locally

Sometimes you can anticipate an exception, and know what exact action to take. Consider the case of a compiler, or a program that processes a web form, which might find more than one error in user input. Imagine something like (in C#):

[21] List<string> errors=new List<string>();
[22] uint quantity=0;
[23] ... other data fields ...
[24]
[25] try {
[26]   quantity=UInt32.Parse(Params["Quantity"]);
[27] } catch(Exception ex) {
[28]   errors.Add("You must enter a valid quantity");
[29] }
[30]
[31] ... other parsers/validators ...
[32]
[33] if (errors.Empty()) {
[34]    ... update database,  display success page ...
[35] } else {
[36]    ... redraw form with error messages ...
[37] }

Here it makes sense to catch the exception locally, because the exceptions that can happen on line [22] are completely handled, and don’t have an effect on other parts of the application. The one complaint you might make is that I should be catching something more specific than Exception. Well, that would bulk the code up considerably and violate the DRY (don’t repeat yourself) principle: UInt32.Parse can throw three different exceptions: ArgumentNullException, FormatException, and OverflowException. On paper, the process of looking up the “Quantity” key in Params could throw an ArgumentNullException or a KeyNotFoundException.

I don’t think either ArgumentNullException can really happen, and I think the KeyNotFoundException would only occur in development, or if somebody was trying to submit the HTML form with an unauthorized program. Probably the best thing to do in either case would be to abort the script with a 500 error and log the details, but the error handling on line [24] is sane in that it prevents corruption of the database.

The handling of FormatException and OverflowException, in the other case, is fully correct. The user gets an error message that tells them what they need to do to fix the situation.

This example demonstrates a bit of why error handling is so difficult and why the perfect can be the enemy of the good: the real cause of an IOException could be a microscopic scratch on the surface of a hard drive, and operating system error, or the fact that somebody spilled a coke on a router in Detroit — diagnosing the problem and offering the right solution is an insoluble problem.

Fixing it up with finally

The first exception handling construct that should be on your fingertips is finally, not catch. Unfortunately, finally is a bit obscure: the pattern in most languages is

[38] try {
[39]    ... do something that might throw an exception ...
[40] } finally {
[41]    ... clean up ...
[42] }

The code in the finally clause get runs whether or not an exception is thrown in the try block. Finally is a great place to release resources, roll back transactions, and otherwise protect the state of the application by enforcing invariants. Let’s think back to the chain of methods A() through F(): with finally, the maintainer of B() can implement a local solution to a global problem that starts in F(): no matter what goes wrong downstream, B() can repair invariants and repair the damage. For instance, if B()’s job is to write something into a transactional data store, B() can do something like:

[43] Transaction tx=new Transaction();
[44] try {
[45]    ...
[46]    C();
[47]    ...
[48]    tx.Commit();
[49] } finally {
[50]    if (tx.Open)
[51]        tx.Rollback();
[52] }

This lets the maintainer of B() act defensively, and offer the guarantee that the persistent data store won’t get corrupted because of an exception that was thrown in the try block. Because B() isn’t catching the exception, it can do this without depriving upstream methods, such as A() from doing the same.

C# gets extra points because it has syntactic sugar that makes a simple case simple: The using directive accepts an IDisposable as an argument and wraps the block after it with a finally clause that calls the Dispose() method of the IDisposable. ASP.NET applications can fail catastrophically if you don’t Dispose() database connections and result sets, so

[53] using (var reader=sqlCommand.ExecuteReader()) {
[54]   ... scroll through result set ...
[55] }

is a widespread and effective pattern.

PHP loses points because it doesn’t support finally. Granted, finally isn’t as important in PHP, because all resources are released when a PHP script ends. The absense of finally, however, encourages PHP programmers to overuse catch, which perpetuates exception phobia. The PHP developers are adding great features to PHP 5.3, such as late static binding, so we can hope that they’ll change their mind and bring us a finally clause.

Where should you catch exceptions?

At high levels of your code, you should wrap units of work in a try-catch block. A unit of work is something that makes sense to either give up on or retry. Let’s work out a few simple examples:

Scripty Command line program: This program is going to be used predominantly by the person who wrote it and close associates, so it’s acceptable for the program to print a stack trace if it fails. The “unit of work” is the whole program.

Command line script that processes a million records: It’s likely that some records are corrupted or may trigger bugs in the program. Here it’s reasonable for the “unit of work” to be the processing of a single record. Records that cause exceptions should be logged, together with a stack trace of the exception.

Web application: For a typical web application in PHP, JSP or ASP.NET, the “unit of work” is the web request. Ideally the application returns a “500 Internal Error”, displays a message to the user (that’s useful but not overly revealing) and logs the stack trace (and possibly other information) so the problem can be investigated. If the application is in debugging mode, it’s sane to display the stack trace to the web browser.

GUI application: The “unit of work” is most often an event handler that’s called by the GUI framework. You push a button, something does wrong, then what? Unlike server-side web applications, which tend to assume that exceptions don’t involve corruption of static memory or of a database, GUI applications tend to shut down when they experience unexpected exceptions. [3] As a result, GUI applications tend to need infrastructure to convert common and predictable exceptions (such as network timeouts) into human readable error messages.

Mail server: A mail server stores messages in a queue and delivers them over a unreliable network. Exceptions occur because of full disks (locally or remote), network failures, DNS misconfigurations, remote server falures, and an occasionaly cosmic ray. The “unit of work” is the delivery of a single message. If an exception is thrown during delivery of the message, it stays in the queue: the mail server attempts to resend on a schedule, discarding it if it is unable to deliver after seven days.

What should you do when you’ve caught one?

That’s the subject of another article. Subscribe to my RSS feed if you want to read it when it’s ready. For now, I’ll enumerate a few questions to think about:

1. What do tell the end user?
2. What do you tell the developer?
3. What do you tell the sysadmin?
4. Will the error clear if up if we try to repeat this unit of work again?
5. How long would we need to wait?
6. Could we do something else instead?
7. Did the error happen because the state of the application is corrupted?
8. Did the error cause the state of the application to get corrupted?

Conclusion

Error handling is tough. Because errors come from many sources such as software defects, bad user input, configuration mistakes, and both permanent and transient hardware failures, it’s impossible for a developer to anticipate and perfectly handle everything that can go wrong. Exceptions are an excellent method of separating error handling logic from the normal flow of programs, but many programmers are too eager to catch exceptions: this either causes errors to be ignores, or entangles error handling with mainline logic, complicating both. The long term impact is that many programmers are afraid of exceptions and turn to return values as an error signals, which is a step backwards.

A strategy that (i) uses finally as the first resort for containing corrupting and maintaining invariants, (ii) uses catch locally when the exceptions thrown in an area are completely understood, and (iii) surrounds independent units of work with try-catch blocks is an effective basis for using exceptions that can be built upon to develop an exception handling policy for a particular application.

Error handling is a topic that I spend entirely too much time thinking about, so I’ll be writing about it more. Subscribe to my RSS Feed if you think I’ve got something worthwhile to say.

Introduction

The first language I used that put dictionaries on my fingertips was Perl, where the solution to just about any problem involved writing something like

$hashtable{$key}=$value;

Perl called a dictionary a ‘hash’,  a reference to the way Perl implemented dictionaries.  (Dictionaries are commonly implemented with hashtables and b-trees,  but can also be implemented with linked-list and other structures.)  The syntax of Perl is a bit odd, as you’d need to use $, # or % to reference scalar,  array or hash variables in different contexts,  but dictionaries with similar semantics became widespread in dynamic languages of that and succeeding generations, such as Python, PHP and Ruby.  ‘Map’ container classes were introduced in Java about a decade ago,  and programmers are using dictionaries increasingly in static languages such as Java and C#.

Dictionaries are a convenient and efficient data structure, but there’s are areas in which different mplementations behave differently: for instance,  in what happens if you try to access an undefined key.   I think that cross-training is good for developers,  so this article compares this aspect of the semantics of dictionaries in four popular languages:  PHP,  Python,  Java and C#.

Use cases

There are two use cases for dictionaries, so far as error handling is concerned:

1. When you expect to look up undefined values, and
2. When you don’t

Let’s look at three examples:

Computing A Histogram

One common use for a dictionary is for counting items, or recording that items in a list or stream have been seen. In C#, this is typically written something like:

[01] var count=Dictionary<int,int>();
[02] foreach(int i in inputList) {
[03]   if (!counts.Contains(i))
[04]       count[i]=0;
[05]
[06]   count[i]=count[i]+1
[07] }

The Dictionary count now contains the frequency of items inputList, which could be useful for plotting a histogram. A similar pattern can be used if we wish to make a list of unique items found in inputList. In either case,  looking up values that aren’t already in the hash is a fundamental part of the algorithm.

Processing Input

Sometimes, we’re getting input from another subsystem, and expect that some values might not be defined. For instance, suppose a web site has a search feature with a number of optional features, and that queries are made by GET requests like:

[08] search.php?q=kestrel
[09] search.php?q=admiral&page=5
[10] search.php?q=laurie+anderson&page=3&in_category=music&after_date=1985-02-07

In this case, the only required search parameter is “q”, the query string — the rest are optional. In PHP (like many other environments), you can get at GET variables via a hashtable, specifically, the $_GET superglobal, so (depending on how strict the error handling settings in your runtime are) you might write something like

[11] if ($_GET["q"])) {
[12]     throw new InvalidInputException("You must specify a query");
[13] }
[14]
[15] if($_GET["after_date"]) {
[16]  ... add another WHERE clause to a SQL query ...
[17] }

This depends, quite precisely, on two bits of sloppiness in PHP and Perl: (a) Dereferencing an undefined key on a hash returns an undefined value, which is something like a null. (b) both languages have a liberal definition of true and false in an if() statement. As a result, the code above is a bit quirky. The if() at line 11 evaluates false if q is undefined, or if q is the empty string. That’s good. However, both the numeric value 0 and the string “0″ also evaluate false. As a result, this code won’t allow a user to search for “0″, and will ignore an (invalid) after_date of 0, rather than entering the block at line [16], which hopefully would validate the date.

Java and C# developers might enjoy a moment of schadenfreude at the above example, but they’ve all seen, written and debugged examples of input handling code that just as quirky as the above PHP code — with several times the line count. To set the record straight, PHP programmers can use the isset() function to precisely test for the existence of a hash key:

[11] if (isset($_GET["q"]))) {
[12]     throw new InvalidInputException("You must specify a query");
[13] }

The unusual handling of “0″ is the kind of fault that can survive for years in production software:  so long as nobody searches for “0″,  it’s quite harmless.  (See what you get if you search for a negative integer on Google.)  The worst threat that this kind of permissive evaluation poses is when it opens the door to a security attack,  but we’ve also seen that highly complex logic that strives to be “correct” in every situation can hide vulnerabilities too.

Relatively Rigid Usage

Let’s consider a third case: passing a bundle of context in an asynchronous communications call in a Silverlight application written in C#. You can do a lot worse than to use the signatures:

[14] void BeginAsyncCall(InputType input,Dictionary<string, object> context,CallbackDelegate callback);
[15] void CallbackDelegate(ReturnType returnValue,Dictionary<string,object> context);

The point here is that the callback might need to know something about the context in which the asynchronous function was called to do it’s work. However, this information may be idiosyncratic to the particular context in which the async function is called,  and is certainly not the business of the asynchronous function. You might write something like

[16] void Initiator() {
[17]   InputType input=...;
[18]   var context=Dictionary<string,object>();
[19]   context["ContextItemOne"]= (TypeA) ...;
[20]   context["ContextItemTwo"]= (TypeB) ...;
[21]   context["ContextItemThre"] = (TypeC) ...;
[22]   BeginAsyncCall(input,context,TheCallback);
[23] }
[24]
[25] void TheCallback(ReturnType output,Dictionary<string,object> context) {
[26]   ContextItemOne = (TypeA) context["ContextItemOne"];
[27]   ContextItemTwo = (TypeB) context["ContextItemTwo"];
[28]   ContextItemThree = (TypeC) context["ContextItemThree"];
[29]   ...
[30] }

This is nice, isn’t it?  You can pass any data values you want between Initiator and TheCallback. Sure,  the compiler isn’t checking the types of your arguments,  but loose coupling is called for in some situations.  Unfortunately it’s a little too loose in this case,  because we spelled the name of a key incorrectly on line 21.

What happens?

The [] operator on a dot-net Dictionary throws a KeyNotFoundException when we try to look up a key that doesn’t exist.   I’ve set a global exception handler for my Silverlight application which,  in debugging mode,  displays the stack trace.  The error gets quickly diagnosed and fixed.

Four ways to deal with a missing value

There are four tools that hashtables give programmers to access values associated with keys and detect missing values:

1. Test if key exists
2. Throw exception if key doesn’t exist
3. Return default value (or null) if key doesn’t exist
4. TryGetValue

#1: Test if key exists

PHP:    isset($hashtable[$key])
Python: key in hashtable
C#:     hashtable.Contains(key)
Java:   hashtable.containsKey(key)

This operator can be used together with the #2 or #3 operator to safely access a hashtable.  Line [03]-[04] illustrates a common usage pattern.

One strong advantage of the explicit test is that it’s more clear to developers who spend time working in different language environments — you don’t need to remember or look in the manual to know if the language you’re working in today uses the #2 operator or the #3 operator.

Code that depends on the existence test can be more verbose than alternatives,  and can  be structurally unstable:  future edits can accidentally change the error handling properties of the code.  In multithreaded environments,  there’s a potential risk that an item can be added or removed between the existance check and an access — however,  the default collections in most environment are not thread-safe,  so you’re likely to have worse problems if a collection is being accessed concurrently.

#2 Throw exception if key doesn’t exist

Python: hashtable[key]
C#:     hashtable[key]

This is a good choice when the non-existence of a key is really an exceptional event.  In that case,  the error condition is immediately propagated via the exception handling mechanism of the language,  which,  if properly used,  is almost certainly better than anything you’ll develop.  It’s awkward,  and probably inefficient,  if you think that non-existent keys will happen frequently.  Consider the following rewrite of the code between [01]-[07]

[31] var count=Dictionary<int,int>();
[32] foreach(int i in inputList) {
[33]   int oldCount;
[34]   try {
[35]       oldCount=count[i];
[36]   } catch (KeyNotFoundException ex) {
[37]       oldCount=0
[38]   }
[39]
[40]   count[i]=oldCount+1
[41] }

It may be a matter of taste,  but I think that’s just awful.

#3 Return a default (often null) value if key doesn’t exist

PHP:    $hashtable[key] (well,  almost)
Python: hashtable.get(key, [default value])
Java:   hashtable.get(key)

This can be a convenient and compact operation.  Python’s form is particularly attractive because it lets us pick a specific default value.  If we use an extension method to add a Python-style GetValue operation in C#,  the code from [01]-[07] is simplified to

[42] var count=Dictionary<int,int>();
[43] foreach(int i in inputList)
[44]   count[i]=count.GetValue(i,0)+1;

It’s reasonable for the default default value to be null (or rather,  the default value of the type),  as it is in Python,  in which case we could use the ??-operator to write

[42] var count=Dictionary<int,int>();
[43] foreach(int i in inputList)
[44]   count[i]=(count.GetValue(i) ?? 0)+1;

(A ?? B equals A if A is not null,  otherwise it equals B.)   The price for this simplicity is two kinds of sloppiness:

1. We can’t tell the difference between a null (or default) value associated with a key and no value associated with a key
2. The potential of null value exports chaos into the environment:  trying to use a null value can cause a NullReferenceException if we don’t explictly handle the null.  NullReferenceExceptions don’t bother me if they happen locally to the function that returns them,  but they can be a bear to understand when a null gets written into an instance variable that’s accessed much later.

Often people don’t care about 1,  and the risk of 2 can be handled by specifying a non-null default value.

Note that PHP’s implementation of hashtables has a particularly annoying characteristic.  Error handling in php is influenced by the error_reporting configuration variable which can be set in the php.ini file and other places.  If the E_STRICT bit is not set in error_reporting,   PHP barrels on past places where incorrect variable names are used:

[45] $correctVariableName="some value";
[46] echo "[{$corectValiableName}]"; // s.i.c.

In that case, the script prints “[]” (treats the undefined variable as an empty string) rather than displaying an error or warning message.  PHP will give a warning message if E_STRICT is set,  but then it applies the same behavior to hashtables:  an error message is printed if you try to dereference a key that doesn’t exist — so PHP doesn’t consistently implement type #3 access.

#4 TryGetValue

There are quite a few methods (Try-* methods) in the .net framework that have a signature like this:

[47] bool Dictionary<K,V>.TryGetValue(K key,out V value);

This method has crisp and efficient semantics which could be performed in an atomic thread-safe manner:  it returns true if finds the key,  and otherwise returns false.  The output parameter value is set to the value associated with the key if a value is associated with the key,  however,  I couldn’t find a clear statement of what happens if the key isn’t found.  I did a little experiment:

[48] var d = new Dictionary<int, int>();
[49] d[1] = 5;
[50] d[2] = 7;
[51] int outValue = 99;
[52] d.TryGetValue(55, out outValue)
[53] int newValue = outValue;

I set a breakpoint on line 53 and found thate the value of outValue was 0,  which is the default value of the int type.  It seems,  therefore,  that TryGetValue returns the default value of the type when it fails to find the key.  I wouldn’t count on this behavior,  as it is undocumented.

The semantics of TryGetValue are crisp and precise.  It’s particularly nice that something like TryGetValue could be implemented as an atomic operation,  if the underyling class is threadsafe.  I fear,  however,  that TryGetValue exports chaos into it’s environment.  For instance,  I don’t like declaring a variable without an assignment,  like below:

[54] int outValue;
[55] if (d.TryGetValue(55,outValue)) {
[56] ... use outValue ...
[57] }

The variable outValue exists before the place where it’s set,  and outside of the block where it has a valid value.  It’s easy for future maintainers of the code to try to use outValue between lines [54]-[55] or after line [57].  It’s also easy to write something like 51],  where the value 99 is completely irrelevant to the program.  I like the construction

[58] if (d.Contains(key)) {
[59]    int value=d[key];
[60]    ... do something with value ...
[61] }

because the variable value only exists in the block [56]-[58] where it has a defined value.

Hacking Hashables

A comparison of hashtables in different languages isn’t just academic.  If you don’t like the operations that your language gives you for hashtables,  you’re free to implement new operations.  Let’s take two simple examples.  It’s nice to have a Python-style get() in PHP that never gives a warning message,  and it’s easy to implement

[62] function array_get($array,$key,$defaultValue=false) {
[63]   if (!isset($array[$key]))
[64]      return $defaultValue;
[65]
[66]   return $array[$key];
[67] }

Note that the third parameter of this function uses a default value of false,  so it’s possible to call it in a two-parameter form

[68] $value=array_get($array,$key);

with a default default of false,  which is reasonable in PHP.

Extension methods make it easy to add a Python-style get() to C#;  I’m going to call it GetValue() to be consistent with TryGetValue():

[69] public static class DictionaryExtensions {
[70]   public static V GetValue<K, V>(this IDictionary<K, V> dict, K key) {
[71]      return dict.GetValue(key, default(V));
[72]   }
[73]
[74]   public static V GetValue<K, V>(this IDictionary<K, V> dict, K key, V defaultValue) {
[75]      V value;
[76]      return dict.TryGetValue(key, out value) ? value : defaultValue;
[77]   }
[78] }

Conclusion

Today’s programming languages put powerful data structures,  such as dictionaries,  on your fingertips.  When we look closely,  we see subtle differences in the APIs used access dictionaries in different languages.  A study of the different APIs and their consequences can help us think about how to write code that is more reliable and maintainable,  and informs API design in every language

When you’re writing applications that use asynchronous callbacks (i.e. Silverlight, AJAX, or GWT) you’ll eventually run into the problem of keeping track of the context that a request is being done in. This isn’t a problem in synchronous programming, because local variables continue to exist after one function calls another function synchronously:

int AddToCount(int amount,string countId)  {
   int countValue=GetCount(countId);
   return countValue+amount;
}

This doesn’t work if the GetCount function is asynchronous, where we need to write something like

int AddToCountBegin(int amount,string countId,CountCallback outerCallback) {
     GetCountBegin(countId,AddToCountCallback);
}

void AddToCountCallback(int countValue) {
    ... some code to get the values of amount and outerCallback ...
    outerCallback(countValue+amount);
}

Several things change in this example: (i) the AddToCount function gets broken up into two functions: one that does the work before the GetCount invocation, and one that does the work after GetCount completes. (ii) We can’t return a meaningful value from AddToCountCallback, so it needs to ‘return’ a value via a specified callback function. (iii) Finally, the values of outerCallback and amount aren’t automatically shared between the functions, so we need to make sure that they are carried over somehow.
There are three ways of passing context from a function that calls and asynchronous function to the callback function:

1. As an argument to the callback function
2. As an instance variable of the class of which the callback function is a class
3. Via a closure

Let’s talk about these alternatives:

1. Argument to the Callback Function

In this case, a context object is passed to the asynchronous function, which passes the context object to the callback. The advantage here is that there aren’t any constraints on how the callback function is implemented, other than by accepting the context object as a callback. In particular, the callback function can be static. A major disadvantage is that the asynchronous function has to support this: it has to accept a state object which it later passes to the callback function.

The implementation of HttpWebRequest.BeginGetResponse(AsyncCallback a,Object state) in the Silverlight libraries is a nice example. If you wish to pass a context object to the AsyncCallback, you can pass it in the second parameter, state. Your callback function will implement the AsyncCallback delegate, and will get something that implements IAsyncResult as a parameter. The state that you passed into BeginGetResponse will come back in the IAsyncResult.AsyncState property. For example:

class MyHttpContext {
	public HttpWebRequest Request;
        public SomeObject FirstContextParameter;
        public AnotherObject AnotherContextParameter;
}

protected void myHttpCallback(IAsyncResult abstractResult) {
	MyHttpContext context = (MyHttpContext) abstractResult.AsyncState;
	HttpWebResponse Response=(HttpWebResponse) context.Request.EndGetResponse(abstractResult);
}

public doHttpRequest(...) {
	...
        MyHttpContext context=new MyHttpContext();
	context.Request=Request;
	context.FirstContextParameter = ... some value ...;
	context.AnotherContextParameter = .. another value ...;
	Request.BeginGetResponse();
	Request.Callback(myHttpCallback,context);
}

Note that, in this API, the Request object needs to be available in myHttpCallback because myHttpCallbacks get the response by calling the HttpWebResponse.EndGetResponse() method. We could simply pass the Request object in the state parameter, but we’re passing an object we defined, myHttpCallback, because we’d like to carry additional state into myHttpCallback.

Note that the corresponding method for doing XMLHttpRequests in GWT, the use of a RequestBuilder object doesn’t allow using method (1) to pass context information — there is no state parameter. in GWT you need to use method (2) or (3) to pass context at the RequestBuilder or GWT RPC level. You’re free, of course, to use method (1) when you’re chaining asynchronous callbacks: however, method (2) is more natural in Java where, instead of a delegate, you need to pass an object reference to designate a callback function.

2. Instance Variable Of The Callback Function’s Class

Functions (or Methods) are always attached to a class in C# and Java: thus, the state of a callback function can be kept in either static or instance variables of the associated class. I don’t advise using static variables for this, because it’s possible for more than one asynchronous request to be flight at a time: if two request store state in the same variables, you’ll introduce race conditions that will cause a world of pain. (see how race conditions arise in asynchronous communications.)

Method 2 is particularly effective when both the calling and the callback functions are methods of the same class. Using objects whose lifecycle is linked to a single asynchronous request is an effective way to avoid conflicts between requests (see the asynchronous command pattern and asynchronous functions.)

Here’s an example, lifted from the asynchronous functions article:

    public class HttpGet : IAsyncFunction<String>
    {
        private Uri Path;
        private CallbackFunction<String> OuterCallback;
        private HttpWebRequest Request;

        public HttpGet(Uri path)
        {
            Path = path;
        }

        public void Execute(CallbackFunction<String> outerCallback)
        {
            OuterCallback = outerCallback;
            try
            {
                Request = (HttpWebRequest)WebRequest.Create(Path);
                Request.Method = "GET";
                Request.BeginGetRequestStream(InnerCallback,null);
            }
            catch (Exception ex)
            {
                OuterCallback(CallbackReturnValue<String>.CreateError(ex));
            }
        }

        public void InnerCallback(IAsyncResult result)
        {
            try
            {
                HttpWebResponse response = (HttpWebResponse) Request.EndGetResponse(result);
                TextReader reader = new StreamReader(response.GetResponseStream());
                OuterCallback(CallbackReturnValue<String>.CreateOk(reader.ReadToEnd()));
            } catch(Exception ex) {
                OuterCallback(CallbackReturnValue<String>.CreateError(ex));
            }
        }
    }

Note that two pieces of context are being passed into the callback function: an HttpWebRequest object named Request (necessary to get the response) and a CallbackFunction<String> delegate named OuterCallback that receives the return value of the asynchronous function.

Unlike Method 1, Method 2 makes it possible to keep an unlimited number of context variables that are unique to a particular case in a manner that is both typesafe and oblivious to the function being called — you don’t need to cast an Object to something more specific, and you don’t need to create a new class to hold multiple variables that you’d like to pass into the callback function.

Method 2 comes into it’s own when it’s used together with polymorphism, inheritance and initialization patterns such as the factory pattern: if the work done by the requesting and callback methods can be divided into smaller methods, a hierarchy of asynchronous functions or commands can reuse code efficiently.

3. Closures

In both C# and Java, it’s possible for a method defined inside a method to have access to variables in the enclosing method. In C# this is a matter of creating an anonymous delegate, while in Java it’s necessary to create an anonymous class.

Using closures results in the shortest code, if not the most understandable code. In some cases, execution proceeds in a straight downward line through the code — much like a synchronous version of the code. However, people sometimes get confused the indentation, and, more seriously, parameters after the closure definition and code that runs immediately after the request is fired end up in an awkward place (after the definition of the callback function.)

    public class HttpGet : IAsyncFunction<String>
    {
        private Uri Path;

        public HttpGet(Uri path)
        {
            Path = path;
        }

        public void Execute(CallbackFunction<String> outerCallback)
        {
            OuterCallback = outerCallback;
            try
            {
                HttpWebRequest request = (HttpWebRequest)WebRequest.Create(Path);
                Request.Method = "GET";
                Request.BeginGetRequestStream(delegate(IAsyncResult result) {
	            try {
                        response = request.EndGetResponse(result);
                        TextReader reader = new StreamReader(response.GetResponseStream());
                        outerCallback(CallbackReturnValue<String>.CreateOk(reader.ReadToEnd()));
                    } catch(Exception ex) {
                        outerCallback(CallbackReturnValue<String>.CreateError(ex));
                    }

            },null); // <--- note parameter value after delegate definition

            }
            catch (Exception ex)
            {
                outerCallback(CallbackReturnValue<String>.CreateError(ex));
            }
        }
    }

The details are different in C# and Java: anonymous classes in Java can access local, static and instance variables from the enclosing context that are declared final — this makes it impossible for variables to be stomped on while an asynchronous request is in flight. C# closures, on the other hand, can access only local variables: most of the time this prevents asynchronous requests from interfering with one another, unless a single method fires multiple asynchronous requests, in which case counter-intuitive things can happen.

Conclusion

In addition to receiving return value(s), callback functions need to know something about the context they run in: to write reliable applications, you need to be conscious of where this information is; better yet, a strategy for where you’re going to put it. Closures, created with anonymous delegates (C#) or classes (Java) produce the shortest code, but not necessarily the clearest. Passing context in an argument to the callback function requires the cooperation of the called function, but it makes few demands on the calling and callback functions: the calling and callback functions can both be static. When a single object contains both calling and callback functions, context can be shared in a straightforward and typesafe manner; and when the calling and callback functions can be broken into smaller functions, opportunities for efficient code reuse abound.

CORRECTION:  The threading model in Silverlight has changed as of Silverlight 2 Beta 2.  It is now possible to initiate asynchronous communication from any thread,  however,  asynchronous callbacks now run in “new” threads that come from a thread pool.  The issues in this article still apply,  with two additions:  (1) the possibility of race conditions and deadlocks between asynchronous callback threads and (2) all updates to user interface components must be done from the user interface thread.  (Fortunately,  it’s easy to get back to the UI thread.)  Subscribe to our RSS Feed to keep informed of breaking developments in Silverlight development.

There’s a lot of confusion about how asynchronous communication works in RIA’s such as Silverlight, GWT and Javascript. When I start talking about the problems of concurrency control, many people tell me that there aren’t any concurrency problems since everything runs in a single thread. [1]

It’s important to understand the basics of what is going on when you’re writing asynchronous code, so I’ve put together a simple example to show how execution works in RIA’s and how race conditions are possible. This example applies to Javascript, Silverlight, GWT and Flex, as well as a number of other environments based on Javascript. This example doesn’t represent best practices, but rather what can happen when you’re not using a proactive strategy that eliminates concurrency problems:

In the diagram above, execution starts when the user pushes a button (a). This starts the user interface thread by invoking an onClick handler. The user interface thread starts two XmlHttpRequests, (b) and (c). The event handler eventually returns, so execution stops in the user interface thread.

In the meantime, the browser still has two XmlHttpRequests running. Callbacks from http requests, timers and user interfaces go into a queue — they get executed right away if the user interface thread is doing nothing, but get delayed if the user interface thread is active.

Http request (b) completes first, causing the http callback for request (b) to start. Had something been a little different with the web browser, web server or network, request (c) could have returned first, causing the callback for request (c) to start. If the result of the program depends on the order that the callbacks for (b) and (c) run, we have a race condition. The callback for http request (b) starts a new http request (d), which runs for a long time.

In the meantime, the user is moving the mouse and triggers a mouseover event while the request (b) callback is running. Right after the request (b) callback completes, the web browser starts the UI thread, which causes a mouseover event handler (e) to run. Note that the user can trigger user interface events while XmlHttpRequests are running, causing event handlers to run in an unpredictable order: if this causes your program to malfunction, your program has a bug.

While the event handler (e) is running, request (c) completes: like the mouseover event, this event is queued and runs once event handler (e) completes. Before (e) completes, it starts a new http request (f). The browser looks into the event queue when (e) completes, and starts the callback for (c). Http request (f) completes while callback (c) is running, gets queued, and runs after (c) is running.

At the end of this example, the callback for (f) completes, causing the UI thread to stop. The http request (c) is still in flight — it completes in the future, somewhere off the end of the page.

This example did not include any timers, or any mechanism of deferred execution such as DeferredCommand in GWT or Dispatcher.Invoke() in Silverlight. This is but another mechanism to add callback references to the event queue.

As you can see, there’s a lot of room for mischief: http requests can return in an arbitrary order and users can initiate events at arbitrary times. The order that things happen in can depend on the browser, it’s settings, on the behavior of the server, and everything in between. Some users might use the application in a way that avoids certain problems (they’ll think it’s wonderful) and others might consistently or occasionally trigger an event that causes catastrophe. These kind of bugs can be highly difficult to reproduce and repair.

Asynchronous RIAs have problems with race conditions that are similar to threaded applications, but not exactly the same. Today’s languages and platforms have excellent and well documented mechanisms for dealing with threads, but today’s RIAs do not have mature mechanisms for dealing with concurrency. Over time we’ll see libraries and frameworks that help, but asynchronous safety isn’t something that can be applied like deodorant: it involves non local interactions between distant parts of the program. The simplest applications can dodge the bullet, but applications beyond a certain level of complexity require an understanding of asynchronous execution and the consistent use of patterns that avoid trouble.

[1] Although it is possible to create new threads in Silverlight, all communication and user interface access must be done from the user interface thread — many Silverlight applications are single-threaded, and adding multiple threads complicates the issue.

Asynchronous Commands are a useful way to organize asynchronous activities, but they don’t have any way to pass values or control back to a caller. This post contains a simple Asynchronous Function library that lets you do that. In C# you call an Asynchronous Function like:

 void CallingMethod(...) {
    ... do some things ...
    IAsyncFunction<String> httpGet=new HttpGet(... parameters...);
    anAsynchronousFunction.Execute(CallbackMethod);
}

void CallbackMethod(CallbackReturnValue<String> crv) {
    if (crv.Error!=null) { ... handle Error,  which is an Exception ...}
    String returnValue=crv.Value;
    ... do something with the return value ...
}

We’re using generics so that return values can be passed back in a type safe manner. The type of the return value of the asynchronous function is specified in the type parameter of IAsyncFunction and CallbackReturnValue.

Asynchronous functions catch exceptions and pass them back in  in the CallbackReturnValue.  This makes it possible to propagate exceptions back to the caller,  as in synchronous functions.  The code to do this must has to be manually replicated in each asynchronous function,  however,  the code can be put into a wrapper delegate.

You could do the same thing in Java, but the CallbackMethod would need to be a class that implements an interface rather than a delegate.

Continue Reading »

I’m in the middle of updating my Silverlight code to use asynchronous HTTP requests — fortunately, I spent last summer writing a GWT application, where HTTP requests have always been asynchronous, so I’ve got a library of patterns for solving common problems.

For instance, suppose that you’re doing a search, and then you’re displaying the result of the search. The most reliable way to do this is to use Pattern Zero, which is, do a single request to the server that retrieves all the information — in that case you don’t need to worry about what happens if, out of 20 HTTP requests, one fails.

Sometimes you can’t redesign the client-server protocol, or you’d like to take advantage of caching, in which case you might do something like this (in psuedo code):

getAListOfResults(new AsyncCallback {
     ... clearGUI();
         foreach(result as item) {
            fetchItem(item,new AsyncCallback {
               ... addItemToGui()
         }
}

First we retrieve a list of items, then we retrieve information about each item: this is straightforward, but not always reliable. Even if your application runs in a single thread, as it would in GWT or if you did everything in the UI thread in Silverlight, you can still have race conditions: for instance, results can come back in a random order, and getAListOfResults() can be called more than once by multiple callbacks — that’s really the worst of the problems, because it can cause results to appear more than once in the GUI.

There are a number of solutions to this problem, and a number of non-solutions. A simple solution is to make sure that getAListOfResults() never gets called until the result set has come back. I was able to do that for quite a while last summer, but the application finally reached a level of complexity where it was impossible… or would have required a major redesign of the app. Another is to use pessimistic locking: to not let getAListOfResults() run while result sets are coming back — I think this can be made to work, but if you’re not careful, your app can display stale data or permanently lock up.

Fortunately there’s a pattern to retrieve result sets using optimistic locking that displays fresh data and can’t fail catastrophically

Continue Reading »