Click here to Skip to main content
Click here to Skip to main content

Event Chain

By , 1 Jul 2008
Rate this:
Please Sign up or sign in to vote.
EventChain

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.

/// <span class="code-SummaryComment"><summary></span>
/// The interface that the argument parameter must implement.
/// <span class="code-SummaryComment"></summary></span>
public interface IEventChain
{
  /// <span class="code-SummaryComment"><summary></span>
  /// The event sink sets this property to true if it handles the event.
  /// <span class="code-SummaryComment"></summary></span>
  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.

/// <span class="code-SummaryComment"><summary></span>
/// A generic delegate for defining chained events.
/// <span class="code-SummaryComment"></summary></span>
/// <span class="code-SummaryComment"><typeparam name="T">The argument type, must implement IEventChain.</typeparam></span>
/// <span class="code-SummaryComment"><param name="sender">The source instance of the event.</param></span>
/// <span class="code-SummaryComment"><param name="args">The parameter.</param></span>
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.

/// <span class="code-SummaryComment"><summary></span>
/// This class invokes each event sink in the event's invocation list
/// until an event sink sets the Handled property to true.
/// <span class="code-SummaryComment"></summary></span>
public static class EventChain
{
  /// <span class="code-SummaryComment"><summary></span>
  /// 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.
  /// <span class="code-SummaryComment"></summary></span>
  /// <span class="code-SummaryComment"><param name="del">The multicast delegate (event).</param></span>
  /// <span class="code-SummaryComment"><param name="sender">The event source instance.</param></span>
  /// <span class="code-SummaryComment"><param name="arg">The event argument.</param></span>
  /// <span class="code-SummaryComment"><returns>Returns true if an event sink handled the event,</span>
  /// false otherwise.<span class="code-SummaryComment"></returns></span>
  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

  • 1st July, 2008: Initial post

License

This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)

About the Author

Marc Clifton

United States United States
Marc is the creator of two open source projets, MyXaml, a declarative (XML) instantiation engine and the Advanced Unit Testing framework, and Interacx, a commercial n-tier RAD application suite.  Visit his website, www.marcclifton.com, where you will find many of his articles and his blog.
 
Marc lives in Philmont, NY.

Comments and Discussions

 
Questioncould u give me c#3.0's implement resource? PinmemberMember 34159511-Jul-08 21:45 
GeneralExcellent (and timely) Article PinmemberRFelts9-Jul-08 8:54 
GeneralGood one PinmemberN a v a n e e t h3-Jul-08 16:54 
GeneralRe: Good one PinprotectorMarc Clifton4-Jul-08 2:40 
GeneralRe: Good one PinmemberN a v a n e e t h4-Jul-08 16:15 
QuestionAm I missing something simple? Pinmembertonyt3-Jul-08 8:21 
AnswerRe: Am I missing something simple? PinprotectorMarc Clifton3-Jul-08 8:52 
GeneralReminds me of WPF RoutedEvents Pinmemberivolved2-Jul-08 16:53 
GeneralRe: Reminds me of WPF RoutedEvents Pinmemberivolved3-Jul-08 5:11 
GeneralGreat Job + My novel idea PinmvpJosh Smith2-Jul-08 12:16 
Marc,
 
Nice job! This is the kind of thing that .NET should have had all along. Luckily the world has a few people like yourself to help fill in the gaps.
 
Here's a novel idea that your article triggered in my head. I can see uses for having your EventChain class expose a FireUntil method, that takes in the same parameters as Fire(), but also takes a Predicate<T> parameter. Instead of using your IEventChain interface there could be an IEventArgWithOutput interface that has a read/write Output property of type T or Object. You could then have each event handler supply a resultant value, which is passed to the Predicate argument. If the predicate returns true, the event stops firing. What this would offer is the ability to isolate the event termination logic into an external source, and just have the event handlers supply a value that is analyzed by that logic.
 
:josh:
My WPF Blog[^]
All of life is just a big rambling blog post.

GeneralRe: Great Job + My novel idea Pinmemberivolved2-Jul-08 16:47 
GeneralRe: Great Job + My novel idea PinmvpJosh Smith2-Jul-08 23:59 
GeneralOptimization PinmemberDaniel Grunwald1-Jul-08 22:47 
GeneralRe: Optimization PinprotectorMarc Clifton2-Jul-08 4:40 
GeneralRe: Optimization PinprotectorMarc Clifton2-Jul-08 4:51 
GeneralRe: Optimization PinmemberDaniel Grunwald2-Jul-08 5:50 
GeneralRe: Optimization PinprotectorMarc Clifton2-Jul-08 5:59 
GeneralNice PinmemberBert delaVega1-Jul-08 17:44 
GeneralNot bad PinmemberGSerjo1-Jul-08 13:03 
GeneralRe: Not bad PinprotectorMarc Clifton2-Jul-08 4:38 
GeneralI like this Marc PinmvpSacha Barber1-Jul-08 11:46 
GeneralTres cool PinmemberMustafa Ismail Mustafa1-Jul-08 9:49 
GeneralRe: Tres PinmvpPete O'Hanlon1-Jul-08 10:03 
GeneralRe: Tres PinmemberMustafa Ismail Mustafa1-Jul-08 10:31 
GeneralRe: Tres PinprotectorMarc Clifton1-Jul-08 11:34 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

| Advertise | Privacy | Mobile
Web02 | 2.8.140421.2 | Last Updated 1 Jul 2008
Article Copyright 2008 by Marc Clifton
Everything else Copyright © CodeProject, 1999-2014
Terms of Use
Layout: fixed | fluid