In chapter 3 we saw the Action<T> delegate type. As a reminder, its signature is very simple (aside from the fact that it’s generic):

public delegate void Action<T>(T obj)

In other words, an Action<T> does something with an instance of T. So an Action<string> could reverse the string and print it out, an Action<int> could print out the square root of the number passed to it, and an Action<IList <double>> could find the average of all the numbers given to it and print that out. By complete coincidence, these examples are all implemented using anonymous methods in listing 5.5.

Example 5.5. Anonymous methods used with the Action<T> delegate type

listing 5.5 shows a few of the different features of anonymous methods. First, the syntax of anonymous methods: use the delegate keyword, followed by the parameters (if there are any), followed by the code for the action of the delegate instance, in a block. The string reversal code shows that the block can contain local variable declarations, and the “list averaging” code demonstrates looping within the block. Basically, anything you can do in a normal method body, you can do in an anonymous method.^[4] Likewise, the result of an anonymous method is a delegate instance that can be used like any other one . Be warned that contravariance doesn’t apply to anonymous methods: you have to specify the parameter types that match the delegate type exactly.

In terms of implementation, we are still creating a method for each delegate instance: the compiler will generate a method within the class and use that as the action it uses to create the delegate instance, just as if it were a normal method. The CLR neither knows nor cares that an anonymous method was used. You can see the extra methods within the compiled code using ildasm or Reflector. (Reflector knows how to interpret the IL to display anonymous methods in the method that uses them, but the extra methods are still visible.)

It’s worth pointing out at this stage that listing 5.5 is “exploded” compared with how you may well see anonymous methods in real code. You’ll often see them used as parameters to another method (rather than assigned to a variable of the delegate type) and with very few line breaks—compactness is part of the reason for using them, after all. For example, we mentioned in chapter 3 that List<T> has a ForEach method that takes an Action<T> as a parameter and performs that action on each element. Listing 5.6 shows an extreme example of this, applying the same “square rooting” action we used in listing 5.5, but in a compact form.

List<int> x = new List<int>();
x.Add(5);
x.Add(10);
x.Add(15);
x.Add(20);
x.Add(25);

x.ForEach(delegate(int n){Console.WriteLine(Math.Sqrt(n));});

That’s pretty horrendous—especially when at first sight the last six characters appear to be ordered almost at random. There’s a happy medium, of course. I tend to break my usual “braces on a line on their own” rule for anonymous methods (as I do for trivial properties) but still allow a decent amount of whitespace. I’d usually write the last line of Listing 5.6 as something like

x.ForEach(delegate(int n)
   { Console.WriteLine(Math.Sqrt(n)); }
);

The parentheses and braces are now less confusing, and the “what it does” part stands out appropriately. Of course, how you space out your code is entirely your own business, but I encourage you to actively think about where you want to strike the balance, and talk about it with your teammates to try to achieve some consistency. Consistency doesn’t always lead to the most readable code, however—sometimes keeping everything on one line is the most straightforward format.

You should also consider how much code it makes sense to include in anonymous methods. The first two examples in listing 5.5 are reasonable, but printMean is probably doing enough work to make it worth having as a separate method. Again, it’s a balancing act.

So far the only interaction we’ve had with the calling code is through parameters. What about return values?

The Action<T> delegate has a void return type, so we haven’t had to return anything from our anonymous methods. To demonstrate how we can do so when we need to, we’ll use the new Predicate<T> delegate type. We saw this briefly in chapter 3, but here’s its signature just as a reminder:

public delegate bool Predicate<T>(T obj)

listing 5.7 shows an anonymous method creating an instance of Predicate<T> to return whether the argument passed in is odd or even. Predicates are usually used in filtering and matching—you could use the code in Listing 5.7 to filter a list to one containing just the even elements, for instance.

Predicate<int> isEven = delegate(int x)
   { return x%2 == 0; };

Console.WriteLine(isEven(1));
Console.WriteLine(isEven(4));

The new syntax is almost certainly what you’d have expected—we just return the appropriate value as if the anonymous method were a normal method. You may have expected to see a return type declared near the parameter type, but there’s no need. The compiler just checks that all the possible return values are compatible with the declared return type of the delegate type it’s trying to convert the anonymous method into.

Relatively few delegates in .NET 2.0 return values—in particular, few event handlers do, partly because when the event is raised only the return value from the last action to be called would be available. The Predicate<T> delegate type we’ve used so far isn’t used very widely in .NET 2.0, but it becomes important in .NET 3.5 where it’s a key part of LINQ. Another useful delegate type with a return value is Comparison<T>, which can be used when sorting items. This works very well with anonymous methods. Often you only need a particular sort order in one situation, so it makes sense to be able to specify that order inline, rather than exposing it as a method within the rest of the class. Listing 5.8 demonstrates this, printing out the files within the C: directory, ordering them first by name and then (separately) by size.

static void SortAndShowFiles(string title,
                             Comparison<FileInfo> sortOrder)
{
   FileInfo[] files = new DirectoryInfo(@"C:").GetFiles();

   Array.Sort(files, sortOrder);

   Console.WriteLine (title);
   foreach (FileInfo file in files)
   {
      Console.WriteLine (" {0} ({1} bytes)",
                         file.Name, file.Length);
   }
}
...
SortAndShowFiles("Sorted by name:",
                 delegate(FileInfo first, FileInfo second)
   { return first.Name.CompareTo(second.Name); }
);


SortAndShowFiles("Sorted by length:",
                 delegate(FileInfo first, FileInfo second)
   { return first.Length.CompareTo(second.Length); }
);

If we weren’t using anonymous methods, we’d have to have a separate method for each of these sort orders. Instead, listing 5.8 makes it clear what we’ll sort by in each case right where we call SortAndShowFiles. (Sometimes you’ll be calling Sort directly at the point where the anonymous method is called for. In this case we’re performing the same fetch/sort/display sequence twice, just with different sort orders, so I encapsulated that sequence in its own method.)

There’s one special syntactic shortcut that is sometimes available. If you don’t care about the parameters of a delegate, you don’t have to declare them at all. Let’s see how that works.

Just occasionally, you want to implement a delegate that doesn’t depend on its parameter values. You may wish to write an event handler whose behavior was only appropriate for one event and didn’t depend on the event arguments: saving the user’s work, for instance. Indeed, the event handlers from our original example in Listing 5.1 fit this criterion perfectly. In this case, you can leave out the parameter list entirely, just using the delegate keyword and then the block of code to use as the action for the method. listing 5.9 is equivalent to listing 5.1 but uses this syntax.

Button button = new Button();
button.Text = "Click me";
button.Click      += delegate { Console.WriteLine("LogPlain"); };
button.KeyPress   += delegate { Console.WriteLine("LogKey"); };
button.MouseClick += delegate { Console.WriteLine("LogMouse"); };

Form form = new Form();
form.AutoSize=true;
form.Controls.Add(button);
Application.Run(form);

Normally we’d have had to write each subscription as something like this:

button.Click += delegate (object sender, EventArgs e) { ... };

That wastes a lot of space for little reason—we don’t need the values of the parameters, so the compiler lets us get away with not specifying them at all. listing 5.9 also happens to be a perfect example of how consistency of formatting isn’t always a good thing—I played around with a few ways of laying out the code and decided this was the clearest form.

I’ve found this shortcut most useful when it comes to implementing my own events. I get sick of having to perform a nullity check before raising an event. One way of getting around this is to make sure that the event starts off with a handler, which is then never removed. As long as the handler doesn’t do anything, all you lose is a tiny bit of performance. Before C# 2, you had to explicitly create a method with the right signature, which usually wasn’t worth the benefit. Now, however, you can do this:

public event EventHandler Click = delegate {};

From then on, you can just call Click without any tests to see whether there are any handlers subscribed to the event.

You should be aware of one trap about this “parameter wildcarding” feature—if the anonymous method could be converted to multiple delegate types (for example, to call different method overloads) then the compiler needs more help. To show you what I mean, let’s look at how we start threads. There are four thread constructors in .NET 2.0:

public Thread (ParameterizedThreadStart start)
public Thread (ThreadStart start)
public Thread (ParameterizedThreadStart start, int maxStackSize)
public Thread (ThreadStart start, int maxStackSize)

The two delegate types involved are

public delegate void ThreadStart()
public delegate void ParameterizedThreadStart(object obj)

Now, consider the following three attempts to create a new thread:

new Thread(delegate()         { Console.WriteLine("t1"); } );

new Thread(delegate(object o) { Console.WriteLine("t2"); } );

new Thread(delegate           { Console.WriteLine("t3"); } );

The first and second lines contain parameter lists—the compiler knows that it can’t convert the anonymous method in the first line into a ParameterizedThreadStart, or convert the anonymous method in the second line into a ThreadStart. Those lines compile, because there’s only one applicable constructor overload in each case. The third line, however, is ambiguous—the anonymous method can be converted into either delegate type, so both of the constructor overloads taking just one parameter are applicable. In this situation, the compiler throws its hands up and issues an error. You can solve this either by specifying the parameter list explicitly or casting the anonymous method to the right delegate type.

Hopefully what you’ve seen of anonymous methods so far will have provoked some thought about your own code, and made you consider where you could use these techniques to good effect. Indeed, even if anonymous methods could only do what we’ve already seen, they’d still be very useful. However, there’s more to anonymous methods than just avoiding the inclusion of an extra method in your code. Anonymous methods are C# 2’s implementation of a feature known elsewhere as closures by way of captured variables. Our next section explains both of these terms and shows how anonymous methods can be extremely powerful—and confusing if you’re not careful.

The concept of closures is a very old one, first implemented in Scheme, but it’s been gaining more prominence in recent years as more mainstream languages have taken it on board. The basic idea is that a function^[5] is able to interact with an environment beyond the parameters provided to it. That’s all there is to it in abstract terms, but to understand how it applies to C#2, we need a couple more terms:

That’s all very dry and may be hard to imagine, but the main thrust is that an anonymous method can use local variables defined in the same method that declares it. This may not sound like a big deal, but in many situations it’s enormously handy—you can use contextual information that you have “on hand” rather than having to set up extra types just to store data you already know. We’ll see some useful concrete examples soon, I promise—but first it’s worth looking at some code to clarify these definitions. listing 5.10 provides an example with a number of local variables. It’s just a single method, so it can’t be run on its own. I’m not going to explain how it would work or what it would do yet, but just explain how the different variables are classified.

Example 5.10. Examples of different kinds of variables with respect to anonymous methods

Let’s go through all the variables from the simplest to the most complicated:

Okay, so we now understand the terminology, but we’re not a lot closer to seeing what captured variables do. I suspect you could guess the output if we ran the method from listing 5.10, but there are some other cases that would probably surprise you. We’ll start off with a simple example and gradually build up to more complex ones.

When a variable is captured, it really is the variable that’s captured by the anonymous method, not its value at the time the delegate instance was created. We’ll see later that this has far-reaching consequences, but first we’ll make sure we understand what that means for a relatively straightforward situation. listing 5.11 has a captured variable and an anonymous method that both prints out and changes the variable. We’ll see that changes to the variable from outside the anonymous method are visible within the anonymous method, and vice versa. We’re using the ThreadStart delegate type for simplicity as we don’t need a return type or any parameters—no extra threads are actually created, though.

string captured = "before x is created";

ThreadStart x = delegate
   {
      Console.WriteLine(captured);
      captured = "changed by x";
   };

captured = "directly before x is invoked";
x();

Console.WriteLine (captured);

captured = "before second invocation";
x();

The output of listing 5.11 is as follows:

directly before x is invoked
changed by x
before second invocation

Let’s look at how this happens. First, we declare the variable captured and set its value with a perfectly normal string literal. So far, there’s nothing special about the variable. We then declare x and set its value using an anonymous method that captures captured. The delegate instance will always print out the current value of captured, and then set it to “changed by x”.

Just to make it absolutely clear that just creating the delegate instance didn’t read the variable and stash its value away somewhere, we now change the value of captured to “directly before x is invoked”. We then invoke x for the first time. It reads the value of captured and prints it out—our first line of output. It sets the value of captured to “changed by x” and returns. When the delegate instance returns, the “normal” method continues in the usual way. It prints out the current value of captured, giving us our second line of output.

The normal method then changes the value of captured yet again (this time to before second invocation) and invokes x for the second time. The current value of captured is printed out, giving our last line of output. The delegate instance changes captured to changed by x and returns, at which point the normal method has run out of code and we’re done.

That’s a lot of detail about how a pretty short piece of code works, but there’s really only one crucial idea in it: the captured variable is the same one that the rest of the method uses. For some people, that’s hard to grasp; for others it comes naturally. Don’t worry if it’s tricky to start with—it’ll get easier over time. Even if you’ve understood everything easily so far, you may be wondering why you’d want to do any of this. It’s about time we had an example that was actually useful.

To put it simply, captured variables get rid of the need for you to write extra classes just to store the information a delegate needs to act on, beyond what it’s passed as parameters. Before ParameterizedThreadStart existed, if you wanted to start a new (non-threadpool) thread and give it some information—the URL of a page to fetch, for instance—you had to create an extra type to hold the URL and put the action of the ThreadStart delegate instance in that type. It was all a very ugly way of achieving something that should have been simple.

As another example, suppose you had a list of people and wanted to write a method that would return a second list containing all the people who were under a given age. We know about a method on List<T> that returns another list of everything matching a predicate: the FindAll method. Before anonymous methods and captured variables were around, it wouldn’t have made much sense for List<T>.FindAll to exist, because of all the hoops you’d have to go through in order to create the right delegate to start with. It would have been simpler to do all the iteration and copying manually. With C# 2, however, we can do it all very, very easily:

List<Person> FindAllYoungerThan(List<Person> people, int limit)
{
    return people.FindAll (delegate (Person person)
       { return person.Age < limit; }
    );
}

Here we’re capturing the limit parameter within the delegate instance—if we’d had anonymous methods but not captured variables, we could have performed a test against a hard-coded limit, but not one that was passed into the method as a parameter. I hope you’ll agree that this approach is very neat—it expresses exactly what we want to do with much less fuss about exactly how it should happen than you’d have seen in a C# 1 version. (It’s even neater in C#3, admittedly...^[7]) It’s relatively rare that you come across a situation where you need to write to a captured variable, but again that can certainly have its uses.

Still with me? Good. So far, we’ve only used the delegate instance within the method that creates it. That doesn’t raise many questions about the lifetime of the captured variables—but what would happen if the delegate instance escaped into the big bad world? How would it cope after the method that created it had finished?

The simplest way of tackling this topic is to state a rule, give an example, and then think about what would happen if the rule weren’t in place. Here we go:

Don’t worry if it doesn’t make a lot of sense yet—that’s what the example is for. Listing 5.12 shows a method that returns a delegate instance. That delegate instance is created using an anonymous method that captures an outer variable. So, what will happen when the delegate is invoked after the method has returned?

static ThreadStart CreateDelegateInstance()
{
   int counter = 5;

   ThreadStart ret = delegate
      {
         Console.WriteLine(counter);
         counter++;
      };

   ret();
   return ret;
}
...
ThreadStart x = CreateDelegateInstance();
x();
x();

The output of listing 5.12 consists of the numbers 5, 6, and 7 on separate lines. The first line of output comes from the invocation of the delegate instance within CreateDelegateInstance, so it makes sense that the value of i is available at that point. But what about after the method has returned? Normally we would consider counter to be on the stack, so when the stack frame for CreateDelegateInstance is destroyed we’d expect counter to effectively vanish... and yet subsequent invocations of the returned delegate instance seem to keep using it!

The secret is to challenge the assumption that counter is on the stack in the first place. It isn’t. The compiler has actually created an extra class to hold the variable. The CreateDelegateInstance method has a reference to an instance of that class so it can use counter, and the delegate has a reference to the same instance—which lives on the heap in the normal way. That instance isn’t eligible for garbage collection until the delegate is ready to be collected. Some aspects of anonymous methods are very compiler specific (in other words different compilers could achieve the same semantics in different ways), but it’s hard to see how the specified behavior could be achieved without using an extra class to hold the captured variable. Note that if you only capture this, no extra types are required—the compiler just creates an instance method to act as the delegate’s action.

OK, so local variables aren’t always local anymore. You may well be wondering what I could possibly throw at you next—let’s see now, how about multiple delegates capturing different instances of the same variable? It sounds crazy, so it’s just the kind of thing you should be expecting by now.

On a good day, captured variables act exactly the way I expect them to at a glance. On a bad day, I’m still surprised when I’m not taking a great deal of care. When there are problems, it’s almost always due to forgetting just how many “instances” of local variables I’m actually creating. A local variable is said to be instantiated each time execution enters the scope where it’s declared. Here’s a simple example comparing two very similar bits of code:

int single;
for (int i=0; i < 10; i++)
{
     single = 5;
     Console.WriteLine(single+i);
}

for (int i=0; i < 10; i++)
{
    int multiple = 5;
    Console.WriteLine(multiple+i);
}

In the good old days, it was reasonable to say that pieces of code like this were semantically identical. Indeed, they’d usually compile to the same IL. They still will, if there aren’t any anonymous methods involved. All the space for local variables is allocated on the stack at the start of the method, so there’s no cost to “redeclaring” the variable for each iteration of the loop. However, in our new terminology the single variable will be instantiated only once, but the multiple variable will be instantiated ten times—it’s as if there are ten local variables, all called multiple, which are created one after another.

I’m sure you can see where I’m going—when a variable is captured, it’s the relevant “instance” of the variable that is captured. If we captured multiple inside the loop, the variable captured in the first iteration would be different from the variable captured the second time round, and so on. Listing 5.13 shows exactly this effect.

Example 5.13. Capturing multiple variable instantiations with multiple delegates

Listing 5.13 creates five different delegate instances —one for each time we go around the loop. Invoking the delegate will print out the value of counter and then increment it. Now, because counter is declared inside the loop, it is instantiated for each iteration , and so each delegate captures a different variable. So, when we go through and invoke each delegate , we see the different values initially assigned to counter: 0, 10, 20, 30, 40. Just to hammer the point home, when we then go back to the first delegate instance and execute it three more times , it keeps going from where that instance’s counter variable had left off: 1, 2, 3. Finally we execute the second delegate instance , and that keeps going from where that instance’s counter variable had left off: 11.

So, each of the delegate instances has captured a different variable in this case. Before we leave this example, I should point out what would have happened if we’d captured index—the variable declared by the for loop—instead of counter. In this case, all the delegates would have shared the same variable. The output would have been the numbers 5 to 14; 5 first because the last assignment to index before the loop terminates would have set it to 5, and then incrementing the same variable regardless of which delegate was involved. We’d see the same behavior with a foreach loop: the variable declared by the initial part of the loop is only instantiated once. It’s easy to get this wrong! If you want to capture the value of a loop variable for that particular iteration of the loop, introduce another variable within the loop, copy the loop variable’s value into it, and capture that new variable—effectively what we’ve done in listing 5.13 with the counter variable.

For our final example, let’s look at something really nasty—sharing some captured variables but not others.

Let me just say before I show you this next example that it’s not code I’d recommend. In fact, the whole point of presenting it is to show how if you try to use captured variables in too complicated a fashion, things can get tricky really fast. Listing 5.14 creates two delegate instances that each capture “the same” two variables. However, the story gets more convoluted when we look at what’s actually captured.

Example 5.14. Capturing variables in different scopes. Warning: nasty code ahead!

How long would it take you to predict the output from listing 5.14 (even with the annotations)? Frankly it would take me a little while—longer than I like to spend understanding code. Just as an exercise, though, let’s look at what happens.

First let’s consider the outside variable . The scope it’s declared in is only entered once, so it’s a straightforward case—there’s only ever one of it, effectively. The inside variable is a different matter—each loop iteration instantiates a new one. That means that when we create the delegate instance the outside variable is shared between the two delegate instances, but each of them has its own inside variable.

After the loop has ended, we call the first delegate instance we created three times. Because it’s incrementing both of its captured variables each time, and we started off with them both as 0, we see (0,0), then (1,1), then (2,2). The difference between the two variables in terms of scope becomes apparent when we execute the second delegate instance. It has a different inside variable, so that still has its initial value of 0, but the outside variable is the one we’ve already incremented three times. The output from calling the second delegate twice is therefore (3,0), then (4,1).

Even after you understand this code fully, it’s still quite a good template for experimenting with other elements of captured variables. As we noted earlier, certain elements of variable capture are implementation specific, and it’s often useful to refer to the specification to see what’s guaranteed—but it’s also important to be able to just play with code to see what happens.

It’s possible that there are situations where code like listing 5.14 would be the simplest and clearest way of expressing the desired behavior—but I’d have to see it to believe it, and I’d certainly want comments in the code to explain what would happen. So, when is it appropriate to use captured variables, and what do you need to look out for?

Hopefully this section has convinced you to be very careful with captured variables. They make good logical sense (and any change to make them simpler would probably either make them less useful or less logical), but they make it quite easy to produce horribly complicated code.

Don’t let that discourage you from using them sensibly, though—they can save you masses of tedious code, and when they’re used appropriately they can be the most readable way of getting the job done. But what counts as “sensible”?