Event Chain

• Download source - 11.45 KB

Introduction

Recently I needed a multicast delegate (an event, in other words) that was smart enough to stop calling the delegates in the invocation list when one of the delegates handled the event. In other words, I needed an event chain that stopped once a delegate in the chain indicated that it handled the event. I did some brief searching for this but didn't find anything, which surprises me for two reasons. First, I figured someone would have implemented this, and second, I thought this was implemented in C# 3.0. Perhaps I didn't look hard enough. Regardless, I needed this implementation for C# 2.0 and the .NET 2.0 Framework because that's what my code base currently requires.

The Code

As part of a previous article about an event pool, I had some code that was borrowed from Juval Lowy and Eric Gunnerson's best practices in defensive event firing mechanism, and Pete O'Hanlon upgraded this code to .NET 2.0 a while back. The code here is a modification of the safe event caller.

Note: You will be amused though that I removed the try-catch block because I now feel that the exception should not be caught by this code but rather by the caller, especially since, in the safe event caller implementation, the exception was re-thrown!

The IEventChain Interface

The critical aspect of this implementation is the IEventChain interface which the argument parameter to the event signature must implement. The event signature follows the .NET standard practice Handler(object sender, EventArgs args) where the "args" property is derived from EventArgs and implements IEventChain.

/// <summary>
/// The interface that the argument parameter must implement.
/// </summary>
public interface IEventChain
{
  /// <summary>
  /// The event sink sets this property to true if it handles the event.
  /// </summary>
  bool Handled { get; set; }
}

This interface has one property, Handled, which the event sink can set to true if it handles the event. The event invocation method inspects this property after invoking the delegate to see if the method set this property to true.

The EventChainHandlerDlgt Definition

The application uses this generic definition to specify the multicast delegate.

/// <summary>
/// A generic delegate for defining chained events.
/// </summary>
/// <typeparam name="T">The argument type, must implement IEventChain.</typeparam>
/// <param name="sender">The source instance of the event.</param>
/// <param name="args">The parameter.</param>
public delegate void EventChainHandlerDlgt<T>
    (object sender, T arg) where T : IEventChain;

The generic type <T> specifies the argument type. A very nifty feature that provides compile-time type validation is the where T : IEventChain clause, that imposes a restriction on the generic type <T> that it must implement IEventChain.

An Example Argument Class

The following illustrates the most basic implementation of an argument class suitable for the delegate described above:

public class SomeCustomArgs : EventArgs, IEventChain
{
  protected bool handled;

  public bool Handled
  {
    get { return handled; }
    set { handled = value; }
  }
}

In the code download, you'll see that I added another property and field simply for testing that the same argument instance is passed to all methods in the invocation list (as one would expect.)

Defining The Event Signature

A typical event signature looks like this:

public static event EventChainHandlerDlgt<SomeCustomArgs> ChainedEvent;

(The event is static only because in my test code, it is part of the Main method which is static.)

The event signature of course defines the method handler signature as well. So, when we say:

ChainedEvent += new EventChainHandlerDlgt<SomeCustomArgs>(Handler1);

The handler signature is expected to match the delegate as well (an example):

public static void Handler1(object sender, SomeCustomArgs args)
{
  Console.WriteLine("Handler1");
}

The EventChain Class

The EventChain class is a static class that implements one method: Fire. The code comments explain the operation of this method, which really is quite simple.

/// <summary>
/// This class invokes each event sink in the event's invocation list
/// until an event sink sets the Handled property to true.
/// </summary>
public static class EventChain
{
  /// <summary>
  /// Fires each event in the invocation list in the order in which
  /// the events were added until an event handler sets the handled
  /// property to true.
  /// Any exception that the event throws must be caught by the caller.
  /// </summary>
  /// <param name="del">The multicast delegate (event).</param>
  /// <param name="sender">The event source instance.</param>
  /// <param name="arg">The event argument.</param>
  /// <returns>Returns true if an event sink handled the event,
  /// false otherwise.</returns>
  public static bool Fire(MulticastDelegate del, object sender, IEventChain arg)
  {
    bool handled = false;

    // Assuming the multicast delegate is not null...
    if (del != null)
      {
      // Get the delegates in the invocation list.
      Delegate[] delegates = del.GetInvocationList();

      // Call the methods until one of them handles the event
      // or all the methods in the delegate list are processed.
      for (int i=0; i<delegates.Length && !handled; i++)
      {
        // There might be some optimization that is possible
        // by caching methods.
        delegates[i].DynamicInvoke(sender, arg);
        handled = arg.Handled;
      }
    }

    // Return a flag indicating whether an event sink handled
    // the event.
    return handled;
  }
}

Note that this method returns a boolean indicating whether one of the event sinks in the chain flagged that it handled the event.

Example

The screenshot above is the result of this code example (part of the download):

public static void Main()
{
  ChainedEvent += new EventChainHandlerDlgt<SomeCustomArgs>(Handler1);
  ChainedEvent += new EventChainHandlerDlgt<SomeCustomArgs>(Handler2);
  ChainedEvent += new EventChainHandlerDlgt<SomeCustomArgs>(Handler3);

  SomeCustomArgs args=new SomeCustomArgs();
  bool ret = EventChain.Fire(ChainedEvent, null, args);
  Console.WriteLine(args.N);
  Console.WriteLine(ret);
}

public static void Handler1(object sender, SomeCustomArgs args)
{
  ++args.N;
  Console.WriteLine("Handler1");
}

public static void Handler2(object sender, SomeCustomArgs args)
{
  ++args.N;
  Console.WriteLine("Handler2");
  args.Handled = true;
}

public static void Handler3(object sender, SomeCustomArgs args)
{
  ++args.N;
  Console.WriteLine("Handler3");
}

The point of this code is that Handler3 never gets called because Handler2 indicates that it handles the event.

Again, note that all these methods are static only because it was convenient to code this all in the Main method.

Conclusion

This code is simple enough that I felt it warrants being put in the "Beginner" section, yet illustrates a useful technique that extends the multicast delegate behavior. And as I mentioned in the introduction, it really does surprise me that someone hasn't done this before, and perhaps better, so if anyone has any other references to other implementations, please post the link in the comments for this article.

Afterthoughts

There are some interesting things one can do with this code. First off, it might be possible to optimize the invocation (how, I'm not sure right now). Also, one can change the order in which the invocation list is called. One can reverse the order, it can be based on some priority that is defined by the handler, and so forth. The handlers could be called as worker threads. All sorts of interesting possibilities are available when one has access to the invocation list!

History

• 1^st July, 2008: Initial post