Click here to Skip to main content
15,867,686 members
Articles / Programming Languages / C#
Article

Event Chain

Rate me:
Please Sign up or sign in to vote.
4.77/5 (36 votes)
1 Jul 2008CPOL4 min read 114.3K   363   63   33
Executing a multicast delegate to create an event chain that can be terminated by any handler in the chain
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.

C#
/// <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.

C#
/// <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:

C#
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:

C#
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:

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

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

C#
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.

C#
/// <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):

C#
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)


Written By
Architect Interacx
United States United States
Blog: https://marcclifton.wordpress.com/
Home Page: http://www.marcclifton.com
Research: http://www.higherorderprogramming.com/
GitHub: https://github.com/cliftonm

All my life I have been passionate about architecture / software design, as this is the cornerstone to a maintainable and extensible application. As such, I have enjoyed exploring some crazy ideas and discovering that they are not so crazy after all. I also love writing about my ideas and seeing the community response. As a consultant, I've enjoyed working in a wide range of industries such as aerospace, boatyard management, remote sensing, emergency services / data management, and casino operations. I've done a variety of pro-bono work non-profit organizations related to nature conservancy, drug recovery and women's health.

Comments and Discussions

 
Questioncould u give me c#3.0's implement resource? Pin
Member 34159511-Jul-08 21:45
Member 34159511-Jul-08 21:45 
GeneralExcellent (and timely) Article Pin
RFelts9-Jul-08 8:54
RFelts9-Jul-08 8:54 
GeneralGood one Pin
N a v a n e e t h3-Jul-08 16:54
N a v a n e e t h3-Jul-08 16:54 
GeneralRe: Good one Pin
Marc Clifton4-Jul-08 2:40
mvaMarc Clifton4-Jul-08 2:40 
GeneralRe: Good one Pin
N a v a n e e t h4-Jul-08 16:15
N a v a n e e t h4-Jul-08 16:15 
QuestionAm I missing something simple? Pin
tonyt3-Jul-08 8:21
tonyt3-Jul-08 8:21 
AnswerRe: Am I missing something simple? Pin
Marc Clifton3-Jul-08 8:52
mvaMarc Clifton3-Jul-08 8:52 
GeneralReminds me of WPF RoutedEvents Pin
BrowniePoints2-Jul-08 16:53
BrowniePoints2-Jul-08 16:53 
GeneralRe: Reminds me of WPF RoutedEvents Pin
BrowniePoints3-Jul-08 5:11
BrowniePoints3-Jul-08 5:11 
GeneralGreat Job + My novel idea Pin
Josh Smith2-Jul-08 12:16
Josh Smith2-Jul-08 12:16 
GeneralRe: Great Job + My novel idea Pin
BrowniePoints2-Jul-08 16:47
BrowniePoints2-Jul-08 16:47 
GeneralRe: Great Job + My novel idea Pin
Josh Smith2-Jul-08 23:59
Josh Smith2-Jul-08 23:59 
GeneralOptimization Pin
Daniel Grunwald1-Jul-08 22:47
Daniel Grunwald1-Jul-08 22:47 
GeneralRe: Optimization Pin
Marc Clifton2-Jul-08 4:40
mvaMarc Clifton2-Jul-08 4:40 
GeneralRe: Optimization Pin
Marc Clifton2-Jul-08 4:51
mvaMarc Clifton2-Jul-08 4:51 
GeneralRe: Optimization Pin
Daniel Grunwald2-Jul-08 5:50
Daniel Grunwald2-Jul-08 5:50 
GeneralRe: Optimization Pin
Marc Clifton2-Jul-08 5:59
mvaMarc Clifton2-Jul-08 5:59 
GeneralNice Pin
Bert delaVega1-Jul-08 17:44
Bert delaVega1-Jul-08 17:44 
GeneralNot bad Pin
Sergey Morenko1-Jul-08 13:03
professionalSergey Morenko1-Jul-08 13:03 
GeneralRe: Not bad Pin
Marc Clifton2-Jul-08 4:38
mvaMarc Clifton2-Jul-08 4:38 
GeneralI like this Marc Pin
Sacha Barber1-Jul-08 11:46
Sacha Barber1-Jul-08 11:46 
GeneralTres cool Pin
Mustafa Ismail Mustafa1-Jul-08 9:49
Mustafa Ismail Mustafa1-Jul-08 9:49 
GeneralRe: Tres Pin
Pete O'Hanlon1-Jul-08 10:03
subeditorPete O'Hanlon1-Jul-08 10:03 
GeneralRe: Tres Pin
Mustafa Ismail Mustafa1-Jul-08 10:31
Mustafa Ismail Mustafa1-Jul-08 10:31 
GeneralRe: Tres Pin
Marc Clifton1-Jul-08 11:34
mvaMarc Clifton1-Jul-08 11:34 

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

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