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.
public interface IEventChain
{
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.
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.
public static class EventChain
{
public static bool Fire(MulticastDelegate del, object sender, IEventChain arg)
{
bool handled = false;
if (del != null)
{
Delegate[] delegates = del.GetInvocationList();
for (int i=0; i<delegates.Length && !handled; i++)
{
delegates[i].DynamicInvoke(sender, arg);
handled = arg.Handled;
}
}
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
