Tag: events

Controlling a Myo Armband with C#

Controlling a Myo Armband with C#

Background

Thalmic Labs has started shipping their Myo armband that allows the wearer’s arm movements and gestures to control different pieces of integrated technology. How cool is that? My friend and I decided we wanted to give one a whirl and see what we could come up with. We’re both C# advocates, so we were a bit taken back when we saw the only C# support in the SDK was made for Unity. We decided to take things into our own hands and open source a Myo C# library. We’re excited to introduce the first version of MyoSharp!

The underlying Myo components are written in C++, and there’s only several functions that are exposed from the library that we can access. In order to do this, we need to leverage platform invocation (PInvokes) from C# to tap into this functionality. Once you have the PInvokes set up you can begin to play around!

The Workflow

Getting setup with the Myo is pretty straightforward, but it wasn’t obvious to us right away. We didn’t have anyone to walk us through how the different components were supposed to work together (just some good ol’ fashioned code) so we had to tinker around. Once we had everything mapped out, it was quite simple though.

  1. The first step is opening a communication channel with the Bluetooth module. You don’t need to worry about the implementation here since it’s all done in C++ by the Thalmic devs. Calling the correct methods using PInvokes from C# allows us to tap into a stream of “events” that come through the Bluetooth module.
  2. Now that we can intercept events, we need to be able to identify a Myo. After all, working with Myos is our main goal here! There’s a “pair” event that we can listen to from the Bluetooth module that notifies us of when a Myo has paired and provides us a handle to the device. This handle gets used for identifying events for a particular Myo or sending a particular Myo messages.
  3. There’s a connect event that will fire when a Myo connects after it’s been paired with the Bluetooth module. A Myo can be paired but disconnected.
  4. Now that we can uniquely identify a Myo, the only things we need to do are intercept events for a particular Myo and make sense of the data coming from the devices! Orientation change? Acceleration change? There’s a host of information that the device sends back, so we need to interpret it.
  5. When a Myo disconnects, there’s an event that’s sent back for that as well.

Getting Started with MyoSharp

I’m going to start this off with some simple code that should illustrate just how easy it is to get started with MyoSharp. I’ll describe what’s going on in the code immediately after.


using System;

using MyoSharp.Device;
using MyoSharp.ConsoleSample.Internal;

namespace MyoSharp.ConsoleSample
{
    /// <summary>
    /// This example will show you the basics for setting up and working with
    /// a Myo using MyoSharp. Primary communication with the device happens
    /// over Bluetooth, but this C# wrapper hooks into the unmanaged Myo SDK to
    /// listen on their "hub". The unmanaged hub feeds us information about
    /// events, so a channel within MyoSharp is responsible for publishing
    /// these events for other C# code to consume. A device listener uses a
    /// channel to listen for pairing events. When a Myo pairs up, a device
    /// listener publishes events for others to listen to. Once we have access
    /// to a channel and a Myo handle (from something like a Pair event), we
    /// can create our own Myo object. With a Myo object, we can do things like
    /// cause it to vibrate or monitor for poses changes.
    /// </summary>
    internal class BasicSetupExample
    {
        #region Methods
        private static void Main(string[] args)
        {
            // create a hub that will manage Myo devices for us
            using (var hub = Hub.Create())
            {
                // listen for when the Myo connects
                hub.MyoConnected += (sender, e) =>
                {
                    Console.WriteLine("Myo {0} has connected!", e.Myo.Handle);
                    e.Myo.Vibrate(VibrationType.Short);
                    e.Myo.PoseChanged += Myo_PoseChanged;
                };

                // listen for when the Myo disconnects
                hub.MyoDisconnected += (sender, e) =>
                {
                    Console.WriteLine("Oh no! It looks like {0} arm Myo has disconnected!", e.Myo.Arm);
                    e.Myo.PoseChanged -= Myo_PoseChanged;
                };

                // wait on user input
                ConsoleHelper.UserInputLoop(hub);
            }
        }
        #endregion

        #region Event Handlers
        private static void Myo_PoseChanged(object sender, PoseEventArgs e)
        {
            Console.WriteLine("{0} arm Myo detected {1} pose!", e.Myo.Arm, e.Myo.Pose);
        }
        #endregion
    }
}

In this example, we create a hub instance. A hub will manage a collection of Myos that come online and go offline and notify listeners that are interested. Behind the scenes, the hub creates a channel instance and passes this into a device listener instance. The channel and device listener combination allows for being notified when devices come online and is the core of the hub implementation. You can manage Myos on your own by completely bypassing the Hub class and creating your own channel and device listener if you’d like. It’s totally up to you.

In the code above, we’ve hooked up several event handlers. There’s an event handler to listen for when Myo devices connect, and a similar one for when the devices disconnect. We’ve also hooked up to an instance of a Myo device for when it changes poses. This will simply give us a console message every time the hardware determines that the user is making a different pose.

When devices go offline, the hub actually keeps the instance of the Myo object around. This means that if you have device A and you hook up to it’s PoseChanged event, if it goes offline and comes back online several times, your event will still be hooked up to the object that represents device A. This makes managing Myos much easier compared to trying to re-hook event handlers every time a device goes on and offline. Of course, you’re free to make your own implementation using our building blocks, so there’s no reason to feel forced into this paradigm.

It’s worth mentioning that the UserInputLoop() method is only used to keep the program alive. The sample code on GitHub actually lets you use some debug commands to read some Myo statuses if you’re interested. Otherwise, you could just imagine this line is replaced by Console.ReadLine() to block waiting for the user to press enter.

Pose Sequences

Without even diving into the accelerometer, orientation, and gyroscope readings, we were looking for some quick wins to building up on the basic API that we created. One little improvement we wanted to make was the concept of pose sequences. The Myo will send events when a pose changes, but if you were interested in grouping some of these together there’s no way to do this out of the box. With a pose sequence, you can declare a series of poses and get an event triggered when the user has finished the sequence.

Here’s an example:


using System;

using MyoSharp.Device;
using MyoSharp.ConsoleSample.Internal;
using MyoSharp.Poses;

namespace MyoSharp.ConsoleSample
{
    /// <summary>
    /// Myo devices can notify you every time the device detects that the user 
    /// is performing a different pose. However, sometimes it's useful to know
    /// when a user has performed a series of poses. A 
    /// <see cref="PoseSequence"/> can monitor a Myo for a series of poses and
    /// notify you when that sequence has completed.
    /// </summary>
    internal class PoseSequenceExample
    {
        #region Methods
        private static void Main(string[] args)
        {
            // create a hub to manage Myos
            using (var hub = Hub.Create())
            {
                // listen for when a Myo connects
                hub.MyoConnected += (sender, e) =>
                {
                    Console.WriteLine("Myo {0} has connected!", e.Myo.Handle);

                    // for every Myo that connects, listen for special sequences
                    var sequence = PoseSequence.Create(
                        e.Myo, 
                        Pose.WaveOut, 
                        Pose.WaveIn);
                    sequence.PoseSequenceCompleted += Sequence_PoseSequenceCompleted;
                };

                ConsoleHelper.UserInputLoop(hub);
            }
        }
        #endregion

        #region Event Handlers
        private static void Sequence_PoseSequenceCompleted(object sender, PoseSequenceEventArgs e)
        {
            Console.WriteLine("{0} arm Myo has performed a pose sequence!", e.Myo.Arm);
            e.Myo.Vibrate(VibrationType.Medium);
        }
        #endregion
    }
}

The same basic setup occurs as the first example. We create a hub that listens for Myos, and when one connects, we hook a new PoseSequence instance to it. If you recall how the hub class works from the first example, this will hook up a new pose sequence each time the Myo connects (which, in this case, isn’t actually ideal). Just for demonstration purposes, we were opting for this shortcut though.

When creating a pose sequence, we only need to provide the Myo and the poses that create the sequence. In this example, a user will need to wave their hand out and then back in for the pose sequence to complete. There’s an event provided that will fire when the sequence has completed. If the user waves out and in several times, the event will fire for each time the sequence is completed. You’ll also notice in our event handler we actually send a vibrate command to the Myo! Most of the Myo interactions are reading values from Myo events, but in this case this is one of the commands we can actually send to it.

Held Poses

The event stream from the Myo device only sends events for poses when the device detects a change. When we were trying to make a test application with our initial API, we were getting frustrated with the fact that there was no way to trigger some action as long as a pose was being held. Some actions like zooming, panning, or adjusting levels for something are best suited to be linked to a pose being held by the user. Otherwise, if you wanted to make an application that would zoom in when the user makes a fist, the user would have to make a fist, relax, make a fist, relax, etc… until they zoomed in or out far enough. This obviously makes for poor usability, so we set out to make this an easy part of our API.

The code below has a similar setup to the previous examples, but introduces the HeldPose class:


using System;

using MyoSharp.Device;
using MyoSharp.ConsoleSample.Internal;
using MyoSharp.Poses;

namespace MyoSharp.ConsoleSample
{
    /// <summary>
    /// Myo devices can notify you every time the device detects that the user 
    /// is performing a different pose. However, sometimes it's useful to know
    /// when a user is still holding a pose and not just that they've 
    /// transitioned from one pose to another. The <see cref="HeldPose"/> class
    /// monitors a Myo and notifies you as long as a particular pose is held.
    /// </summary>
    internal class HeldPoseExample
    {
        #region Methods
        private static void Main(string[] args)
        {
            // create a hub to manage Myos
            using (var hub = Hub.Create())
            {
                // listen for when a Myo connects
                hub.MyoConnected += (sender, e) =>
                {
                    Console.WriteLine("Myo {0} has connected!", e.Myo.Handle);

                    // setup for the pose we want to watch for
                    var pose = HeldPose.Create(e.Myo, Pose.Fist, Pose.FingersSpread);

                    // set the interval for the event to be fired as long as 
                    // the pose is held by the user
                    pose.Interval = TimeSpan.FromSeconds(0.5);

                    pose.Start();
                    pose.Triggered += Pose_Triggered;
                };

                ConsoleHelper.UserInputLoop(hub);
            }
        }
        #endregion

        #region Event Handlers
        private static void Pose_Triggered(object sender, PoseEventArgs e)
        {
            Console.WriteLine("{0} arm Myo is holding pose {1}!", e.Myo.Arm, e.Pose);
        }
        #endregion
    }
}

When we create a HeldPose instance, we can pass in one or more poses that we want to monitor for being held. In the above example, we’re watching for when the user makes a fist or when they have their fingers spread. We can hook up to the Triggered event on the held pose instance, and the event arguments that we get in our event handler will tell us which pose the event is actually being triggered for.

If you take my zoom example that I started describing earlier, we could have a single event handler responsible for both zooming in and zooming out based on a pose being held. If we picked two poses, say fist and fingers spread, to mean zoom in and zoom out respectively, then we could check the pose on the event arguments in the event handler and adjust the zoom accordingly. Of course, you could always make two HeldPose instances (one for each pose) and hook up to the events separately if you’d like. This would end up creating two timer threads behind the scenes–one for each HeldPose instance.

The HeldPose class also has an interval setting. This allows the programmer to adjust the frequency that they want the Triggered event to fire, provided that a pose is being held by the user. For example, if the interval is set to be two seconds, as long as the pose is being held the Triggered event will fire every two seconds.

Roll, Pitch, and Yaw

The data that comes off the Myo can become overwhelming unless you’re well versed in vector math and trigonometry. Something that we’d like to build up and improve upon is the usability of data that comes off the Myo. We don’t want each programmer to have to write similar code to get the values from the Myo into a usable form for their application. Instead, if we can build that into MyoSharp, then everyone will benefit.

Roll, pitch, and yaw are values that we decided to bake into the API directly. So… what exactly are these things? Here’s a diagram to help illustrate:

Roll, Pitch, and Yaw - MyoSharp

Roll, pitch, and yaw describe rotation around one of three axes in 3D space.

The following code example shows hooking up to an event handler to get the roll, pitch, and yaw data:


using System;

using MyoSharp.Device;
using MyoSharp.ConsoleSample.Internal;

namespace MyoSharp.ConsoleSample
{
    /// <summary>
    /// This example will show you how to hook onto the orientation events on
    /// the Myo and pull roll, pitch and yaw values from it.
    /// </summary>
    internal class OrientationExample
    {
        #region Methods
        private static void Main(string[] args)
        {
            // create a hub that will manage Myo devices for us
            using (var hub = Hub.Create())
            {
                // listen for when the Myo connects
                hub.MyoConnected += (sender, e) =>
                {
                    Console.WriteLine("Myo {0} has connected!", e.Myo.Handle);
                    e.Myo.OrientationDataAcquired += Myo_OrientationDataAcquired;
                };

                // listen for when the Myo disconnects
                hub.MyoDisconnected += (sender, e) =>
                {
                    Console.WriteLine("Oh no! It looks like {0} arm Myo has disconnected!", e.Myo.Arm);
                    e.Myo.OrientationDataAcquired -= Myo_OrientationDataAcquired;
                };

                // wait on user input
                ConsoleHelper.UserInputLoop(hub);
            }
        }
        #endregion

        #region Event Handlers
        private static void Myo_OrientationDataAcquired(object sender, OrientationDataEventArgs e)
        {
            Console.Clear();
            Console.WriteLine(@"Roll: {0}", e.Roll);
            Console.WriteLine(@"Pitch: {0}", e.Pitch);
            Console.WriteLine(@"Yaw: {0}", e.Yaw);
        }
        #endregion
    }
}

Of course, if we know of more common use cases that people will be using the orientation data for, then we’d love to bake this kind of stuff right into MyoSharp to make it easier for everyone.

Closing Comments

That’s just a quick look at how you can leverage MyoSharp to make your own C# application to work with a Myo! As I said, MyoSharp is open source so we’d love to see contributions or ideas for suggestions. We’re aiming to provide as much base functionality as we can into our framework but designing it in a way that developers can extend upon each of the individual building blocks.


Hack The North

Hack The North

Hack The North… What The Hack Is That?

Hack The North is Canada’s largest international hackathon. It’s big. It’s bad. It’s awesome. Okay, but what does that even mean?

The idea is that 1000 people get together from all over the world in an event where they’re given 36 hours to create amazing technology hacks. There’s a lack of sleep but no lack of amazing ideas and hacked together proof of concepts that show incredible innovation. Sponsors are present to hand out prizes for best usage of their product or API to competitors as well as mentor them and provide help with problem solving. This year, Hack The North was hosted at The University of Waterloo.

Bro, Do You Even Hack?!

This was my first time ever at a hackathon. I’ve participated in the Ontario Engineering Competition (OEC) which is much smaller scale event with a similar structure–A bunch of students get together and have to come up with a design to solve a problem. I even ran OEC in 2010 with some schoolmates (you might know them at Thalmic Labs) which was a blast. However, this weekend I was sitting on the other side of the table.

I got to hang out with a group of my colleagues at Hack The North at the Magnet Forensics booth. We had a great time representing our company and meeting tons of incredible students from all over the world. We provided assistance where we could with some of the challenges that students were facing, and spoke to them about the important role that our software plays in the life of a forensic examiner/investigator.

What’d You See There?

When I first showed up at Hack The North, it was around 9:00 on Friday night. I got there just in time for the opening ceremonies, which I thought were great. They had live Q&A with a former Facebook employee who has “made it” in the software industry and intros from some of the major sponsors at the event.

Hack The North - Opening Ceremonies

Everyone getting settled for the opening ceremonies at Hack The North.

From that point on, I spent the rest of the time hanging around the Magnet booth… But that doesn’t mean I didn’t see anything awesome. We had people from all over the place coming by to talk to us and pick up some Magnet swag. We handed out an incredible amount of stress balls and couldn’t seem to keep a sufficient supply of them coming. We had our stickers showing up on everything from fuzzy viking hats to laptops to shirts to megaphones. You name it, our stickers made it onto it.

Hack The North - Magnet Viking

Akshay Joshi decorated his hat with Magnet stickers!

Hack The North - Magnet Megaphone

One of the Hack The North organizers was sporting a Magnet sticker on his megaphone.

On the last day of Hack The North, we had participants coming up to our booth to demonstrate some of their awesome hacks. We got to see how Thalmic’s Myo was being incorporated or how other vendors’ APIs were being leveraged to do some really awesome things. We were really impressed with some of the things we saw.

What’s Next?

I think even after the first night of being at Hack The North I was trying to think of what we could do next time or if we even wanted to come back… The answer to the latter was quickly an “absolutely yes!”, so I’m pretty confident we’ll be making an appearance at Hack The North again. There were so many great people at this even that we spoke with that it would be silly not to go back.

I think next year we’d like to participate even more. We learned a lot about the different ways that we could get involved, so things like speaking sessions or workshops would be awesome to get people involved with. We’ll definitely have more stress balls and unique giveaways to please the masses!

Thanks to everyone who made it out to Hack The North. Stay in touch with us! We’d love to hear more from you.

Hack The North - Kelly and Nick

Kelly and I with our #Truth T-shirts and other Magnet gear on at our booth!


Cameron Sapp – Recognizing The New Guy

 

 

Cameron Sapp (Rocking awesome handlebars for Movember)

Cameron Sapp and a Little Background

A couple weeks ago I mentioned that I wanted to start publicly acknowledging some of my teammates. While this is the first one, it certainly won’t be the last. At Magnet Forensics, I’m surrounded by many individuals that bring a lot to the table. There’s certainly no reason and no way I’d only be able to pick one person to write about. Now there wasn’t a particular reason I picked this individual first, but I think I had some concrete things fresh in my head that I wanted to share. Without too much more rambling, I’d like to introduce Cameron Sapp!

New Kid on the Block

Cameron joined our team earlier this year. I don’t think any of us doubted his technical abilities and we were all excited to bring him on board. After all, we have a ton of stuff to work on and we need more great minds working with us! We were getting pretty impatient waiting for him to start, but it was definitely worth the wait.

Cam fit in to the work culture really well and really quickly too. Heck, he’s one of Team Magnet’s awesome volleyball players! Something people may not pay attention to is how much a work culture fit is important in a small organization. Being able to get along with all of your teammates and share a common vision is absolutely crucial for being successful. Luckily for us, Cameron fits in well with the team and definitely embraces the Magnet culture!

I was recently told by a bright individual, Dan Silivestru of tinyHippos, that there will be a time where someone younger is going to show up and surprise me with what they know. Of course, it’s not that I walk around doubting the ability of people, but unfortunately it’s pretty common for age and/or experience to bring about big assumptions for people’s abilities. I’m still young and early in my career, so I don’t think age is something I’m concerned with–but I might be guilty of thinking highly of my technical abilities. While Cameron isn’t the first, and certainly won’t be the last, he definitely was able to pull some tricks from his sleeves to impress me. For that, I would like to applaud him and recognize him here on The Internetz.

Whatcha Gonna Do With All Them Lambdas?

I’ve been programming in Microsoft’s C# for quite a few years now. I’m certainly not a master by any stretch of the imagination, but I’d say I’m pretty well versed. I’ve also written in the past about how I like to use events a lot when I’m programming (like here, here, and here) and almost always try to find an event-driven approach to things. But what does this have to do with Mr Cameron Sapp?

Well, you see… In C# it’s often the case where you hook up events like this:


someObject.DidSomething += SomeObject_DidSomething;

private void SomeObject_DidSomething(Object sender, EventArgs e)
{
    // do some awesome stuff.
}

That’s not so bad, right? Well, except if you’re making these suckers everywhere… And when you don’t want to have to type out a big ugly signature… Or when the type of your event arguments is obnoxiously long… Well, you get the point. If you’re not a C# programmer, take my word for it: if you use events a lot, having these event handlers all over the place sometimes just sucks to have to look at.

Enter… The lambda.

So once upon a time, Cameron stuck up a code review. Things were looking pretty good (as per usual with Cam’s code), but I noticed something right before I was going to give it the stamp of approval.


// Some code...

someClass.SomeEvent += (s, e) =>
{
    // event handler logic
}

// Some more code...

What the heck is that?! My alarms for event handler memory leaks weren’t going off (since this handler needed to exist for the entire lifetime of the objects in question), but I had no idea what I was looking at. Cameron’s a pretty smart guy, I remember thinking, so this code definitely had to compile on his machine before he pushed it up for me to review. Still… What was I looking at?

This was my first real shocker where someone caught me off guard for something I always felt really comfortable with. I mean… C# and events are my bread and butter. How was this guy showing me something I hadn’t seen before regarding events? How can he know something about them I don’t?! Well, he did it. And I’m sure that he’s got a lot more up there in that head of his that I don’t know. And I can’t wait for him to teach me it!

Summary

So this was pretty quick, and it probably doesn’t do Cameron enough justice, but I think it’s a start. We’re really fortunate to have Cameron as part of our team–both from a culture fit and a technical perspective. He’s a rock solid developer that is not only willing to adapt to our coding environment, but he’s also got lots of insight to bring to the table.

It’s important that we never put ourselves in a position where we think we know it all. As soon as you get comfortable with what you know, you stop learning. When you stop learning, you have people like Cameron show up and send you a wake up call. There isn’t a single person out there who knows everything, and you might be surprised who can teach you a thing or two.

Thanks for being part of our team, Cam. Let’s show ’em how it’s done.

More team member recognition to come! Stay tuned.


Events: Demystifying Common Memory Leaks

Events: Demystifying Common Memory Leaks

Background

If you’ve poked through my previous postings, you’ll probably notice that I love using events when I program. If I can find a reason to use an event, I probably will. I think they’re a great tool that can really help you with designing your architectures, but there are certainly some common problems people run into when they use events. The one I want to address today has to do with memory leaks. That’s right. I said it. Memory leaks in your .NET application. Just because it’s a managed language doesn’t mean your code can’t be leaking memory! And now that I’ve got your attention, let’s see how events might be causing some leakage in your application.

(There is source that you can download and run. Check the summary section at the end!)

Instance-Scope Event Handlers

One of the most common ways to set up an EventHandler in C# is by having them defined for the entire scope of the instance. Consider for a moment the form designer in Visual Studio. When you double click on controls you get some handler created for the default event on that control. See how the EventHandler was declared though? You get a method declared that has a sender and some type of EventArgs. Pretty standard stuff here and there’s nothing ground-breaking about it. So what’s the problem with this method?

Well, there’s nothing wrong with it as long as you know how to clean up after yourself. Consider the following two classes:


private class ObjectWithEvent
{
    ~ObjectWithEvent()
    {
        Console.WriteLine(this + " is being finalized.");
    }

    public event EventHandler<EventArgs> Event;

    public void UnhookAll()
    {
        Event = null;
    }
}

private class ObjectThatHooksEvent
{
    public ObjectThatHooksEvent(ObjectWithEvent objectWithEvent)
    {
        objectWithEvent.Event += ObjectWithEvent_Event;
    }

    ~ObjectThatHooksEvent()
    {
        Console.WriteLine(this + " is being finalized.");
    }

    private void ObjectWithEvent_Event(object sender, EventArgs e)
    {
        // some fancy event
    }
}

The first class has an event that our second class can hook onto. You’ll notice in the second class that I’ve defined an instance-scope handler that we can hook up. This is the exact same syntax for declaring an event handler that you’d get from the form designer if you’re doing GUI programming.

The danger with this setup is that until you unhook the event, the object that hooks onto the event will not be freed. “Well, no problem!” is what you might be thinking. You know how to solve that. You can just unhook the event in the second class’s finalizer/deconstructor.

…Except that won’t work. The finalizer will not get called on the instance of the second class until the event has been unhooked! It’s a bit of a chicken-or-the-egg problem, but it makes sense. A finalizer will only be called when the reference is being cleaned up, but the instance can’t be marked for cleaning because something is still using its event handler. See why this can get a bit dangerous?

Anonymous Delegate (No Parent Reference)

So this is an example of hooking events where you won’t get a leak. Why am I showing it? Well, in the next section I’ll make a small tweak to it which will make it behave just like the first scenario I described.

Let’s assume we have two classes again. I’ll use the first class from my first example (the object with the event) and this new class here that we’ll use to hook onto the event:

private class HookWithAnonymousDelegate
{
    public HookWithAnonymousDelegate(ObjectWithEvent objectWithEvent)
    {
        objectWithEvent.Event += (sender, args) =>
        {
            // handle your event
            // (this one is special because it doesn't use anything related to the instance)
            Console.WriteLine("Event being called!");
        };
    }

    ~HookWithAnonymousDelegate()
    {
        Console.WriteLine(this + " is being finalized.");
    }
}

Notice the difference from the first example? I’ve hooked up an anonymous method (using a lambda expression) to our event instead of declaring an instance-scope event handler. It’s a small change, and for the most part, I might argue that this is just a stylistic thing. If you don’t ever plan on unhooking the event then it’s not such a big deal to go with anonymous methods, but if your method body grows pretty big the code can definitely get unsightly.

Anyway… sweet! We just hooked up to our event and we don’t have the scary leak situation that we did in the first scenario. How cool is that? Well…

Anonymous Delegate (With Parent Reference)

The second method I described works great… until you go to put it into practice. It’s clearly not an impossible situation, but it’s pretty unlikely that you’ll write event handlers within an object that don’t use any of that object’s state (or even other methods on the object). Again, not impossible but just not the common use case. And since it’s not the common use case, you need to be concerned with the potentially problematic common use case 🙂

Let’s consider two classes (yes, again, two classes). We’ll use the first class I described above in both examples that has an event that we can hook onto, and a second class that looks similar to the class I introduced in the second example:

private class HookWithAnonymousDelegate2
{
    public HookWithAnonymousDelegate2(ObjectWithEvent objectWithEvent)
    {
        objectWithEvent.Event += (sender, args) =>
        {
            // handle your event and use something that's part of this instance
            SomeInnocentLittleMethod();
        };
    }

    ~HookWithAnonymousDelegate2()
    {
        Console.WriteLine(this + " is being finalized.");
    }

    private void SomeInnocentLittleMethod()
    {
        Console.WriteLine("... Not so innocent after all!");
    }
}

See the difference compared to example 2? The event handler in this class calls an instance method. This would be a pretty common thing to do (unless you like to duplicate all of your code and not use methods ever :P) and it doesn’t look like it should cause problems. And really, it won’t if you understand the implications of hooking an event handler up to an event. So once you’re done handling your events, make sure you clean up and remove your handlers!

In my opinion, the really interesting part of this example is that the event handler is only calling an instance method. It’s not even using any variables or properties of the instance. Still, the .NET framework is going to hold onto this second instance until we unhook.

Summary

Well, hopefully I haven’t scared you away from using events. The take-away point here is that you need to be mindful of hooking up your events and when/where you unhook them. Personally, unless you always plan to have two objects exist for the same lifetime, I wouldn’t hook up events in the constructors like I’ve done in my examples. Some closing tips:

  • Try only hooking onto events when you need to. If you don’t need to hook up all your events when initializing something, then don’t!
  • Be mindful of how you’re going to clean up your event hooking. Whenever you add an event handler, try to think of where you’ll be cleaning it up.
  • Hooking events onto singletons or global instances can make this problem a lot worse. Since your singleton will be around for the lifetime of your application, if you forget to unhook from your event then you’ll start accumulating a lot of garbage.

I’ve written up a little sample application that uses the example classes and walks you through the three examples I’ve outlined. All of them involve instantiating the classes, hooking up the events, and then how they behave differently when you try to clean them up. You can grab the source code from:

Hope you enjoyed! Remember to follow Dev Leader:


Dependency Injected Singletons… What?

Background

Previously I wrote a bit about singletons. I’m not afraid to say that I think singletons have a time and a place… Okay, I’m afraid to say it, but it’s actually how I feel 🙂 After learning more and more about inversion of control design patterns and programming by interfaces, I started to notice just how inflexible singletons are. When you consider using a singleton, you should be considering both the pros and cons without jumping right into it. Here’s an example of my approach for mixing singletons, programming by interfaces, and a bit of inversion of control.

The Setup

I’m actually surprised you got this far. I’m sure you’re probably just sticking around to see how messed up this could possibly be. I’m actually proud that this little pattern has worked out so well when I’ve used it, so it can’t possibly be that bad.

One major drawback to singletons is that they are often implemented as concrete classes. That is, you ask some class X for it’s instance (via a static property/method) and it provides you it. This doesn’t mix very well with programming by interfaces. So, the first step is to have your singleton return an interface instead of a concrete class. Unfortunately, this on it’s own only provides a few benefits, and it’s really only a minor abstraction layer. You can change your singleton class around all you want, but the only dependencies people are going to see are what’s exposed on the interface. As long as your interface isn’t changing, you’re in a good position. With this change alone, we’ve managed to tackle a bit on programming by interfaces, which makes me just a bit happier.

So, what’s the problem now then? Well, now that I have my singleton returning an interface, the unfortunate truth is it’s always going to be the same class backing that interface. It’s incredibly risky if I start putting some sort of logic in my singleton’s property to get the instance that will return different references that could implement the interface. I mean, once your code is running, you want to make sure you’re always getting the same reference back… or else you’re not using a singleton! The drawback to this is that it completely ruins inversion of control and dependency injection!

 

An Example

Consider that I have a singleton that has information about my application. (If you don’t like my example, then you’ll surely hate using WinForms, because Microsoft does it with their Application class. So, it’s a fair example!) Okay, so if we pretend that we need something just like the Application class in our project, we might create some interface IApplication and create a singleton that returns an instance of an IApplication.

Suppose in one implementation we have, we really want to be using reflection and the assembly information to figure out our application’s information. Our concrete class would implement the IApplication interface but the methods would revolve around using reflection and querying the assembly for what it wants. If we built up a whole framework that used this singleton… We’d be tied to that implementation!

What happens if we go to make another application that wants to use this same framework, but it needs to be able to provide the application information through a configuration file? Well… We’d be pooched! Our singleton that’s used everywhere (and yes, please continue crying about the use of the singleton… Just remember Microsoft’s Application class) and we can’t really do anything about it!

Or can we?

The “Solution”

Okay, so here we are. I’ve demonstrated the problem with a scenario that isn’t too far fetched. How do we fix this crappy situation we’ve got ourselves in by using the dreaded singleton pattern? We use my other best friend: events. Except we use them in a way that makes me cringe. Static events.

Here’s my solution the the above problem:

The Interface:

    public interface IApplication
    {
        string Name { get; }

        string Version { get; }
    }

The Singleton:

    public static class Application
    {
        private static readonly object _instanceLock = new object();
        private static IApplication _instance;

        public static event EventHandler<QueryTypeEventArgs> QueryType;

        public static IApplication Instance
        {
            get
            {
                if (_instance == null)
                {
                    lock (_instanceLock)
                    {
                        if (_instance == null)
                        {
                            _instance = CreateInstance();
                        }
                    }
                }

                return _instance;
            }
        }

        private static IApplication CreateInstance()
        {
            var handler = QueryType;
            if (handler == null)
            {
                throw new InvalidOperationException(
                    "Cannot create an instance because the QueryType event " +
                    "handler was never set.");
            }

            var args = new QueryTypeEventArgs();
            handler.Invoke(null, args);

            if (args.Type == null)
            {
                throw new InvalidOperationException(
                    "Cannot create an instance because the type has not been " +
                    "provided.");
            }

            // NOTE: here's where things get weird. you need to define your own
            // sort of "contract" for what type of constructor you will allow.
            // you might not even use a constructor here... but you need to
            // define what mechanism the provided type must have to provide
            // you with a singleton instance. i'm a fan of providing a type
            // with a private parameterless constructor, so i'll demonstrate
            // with that. your requirements will change what this section of
            // code looks like.
            if (!typeof(IApplication).IsAssignableFrom(args.Type))
            {
                throw new InvalidOperationException(
                    "Cannot create an instance because the provided type does " +
                    "not implement the IApplication interface.");
            }

            const BindingFlags FLAGS = 
                BindingFlags.CreateInstance | 
                BindingFlags.Instance | 
                BindingFlags.NonPublic;

            var constructors = args.Type.GetConstructors(FLAGS);
            if (constructors.Length != 1)
            {
                throw new InvalidOperationException(
                    "Cannot create an instance because a single private " +
                    "parameterless constructor was expected.");
            }

            return (IApplication)constructors[0].Invoke(null);
        }
    }

The Program (With two types to inject!)

    internal class Program
    {
        private static void Main(string[] args)
        {
            Application.QueryType += (sender, e) =>
            {
                e.Type = typeof(ApplicationB);
            };

            Console.WriteLine(string.Format(
                "Application Name: {0}rnVersion: {1}",
                Application.Instance.Name,
                Application.Instance.Version));

            Console.WriteLine("Press enter to exit.");
            Console.ReadLine();
        }
    }

    internal class ApplicationA : IApplication
    {
        private ApplicationA()
        {
        }

        public string Name
        {
            get
            {
                return "Application A (Pretend this was from the assembly info)";
            }
        }

        public string Version
        {
            get { return "1234"; }
        }
    }

    internal class ApplicationB : IApplication
    {
        private ApplicationB()
        {
        }

        public string Name
        {
            get
            {
                return "Application B (Pretend this was from an XML file)";
            }
        }

        public string Version
        {
            get { return "9876"; }
        }
    }

So, if you were to run the program, what outputs would you expect in either case? What happens when you forget to set your event handler? What happens when you set your event handler and don’t provide a type? What if it’s a bad type?

 

Summary


I’m not claiming this is the best approach to solve this problem, and I’m not even encouraging that everyone go ahead and use it. Some of the pros of this are:

  • Advantages of programming by interfaces! You’re only exposing interface definitions to others.
  • Dependency injection capabilities. Inject your “singleton” into other applications.
  • All the goodies related to singletons
  • Easy to use. Just hook up your type to a event handler when your program initializes.

Some of the cons are:

  • All the things people hate about singletons. All of them.
  • Static events are absolutely hideous.
  • You’re giving some other class control of creating your singleton instance.
  • There is no compile time checking or contracts for how your singleton needs to be created.

And now that you know some of the good and some of the bad, can you leverage a design like this? You can check out a working solution I put together for the code and example I described above over at Google Code. Hope you were able to learn something (either good or bad)!


Why Events? Decoupling.

Background

Previously, I wrote about how events provide you with flexibility in your code. If you take on an event-based paradigm, you can view your system as a group of components that have events execute when certain conditions are met, and less of a procedural view where X always must occur after Y. But what else do events let us do? Decouple your architecture! We all know decoupling is a beautiful thing, so let’s see how it’s done.

 

How Events Decouple Your Code

So the big question then is, how? I’d like to start by providing framing an example architecture. If we assume that we have code that is decoupled by major functionality, we might have some sort of layered architecture. This could mean that we have three layers: presentation, application, and data. These layers would be responsible for user interaction, core business logic, and data storage/retrieval respectively. Let us also assume that the knowledge of layers flows from the top down. In our example, the data layer knows only of itself, the application layer knows about itself and the data layer, and the presentation layer has access to all three. It’s essentially just the flow of dependencies. Great. So where is this going?

If you’ve structured the various components in your system to take advantage of events, C# events provide us with a pretty awesome signature: you get the sender of the event, and a little magical parcel of data called EventArgs. Now let’s recall that in my previous posting, I mention that an event is really just a type of delegate. What does it mean to delegate? Literally, what does it mean? The great Google tells me: “Entrust (a task or responsibility) to another person, typically one who is less senior than oneself”. There. The secret of decoupling. My code can’t take responsibility for doing something, so I should tell whoever is interested that now might be a great time to do something.

 

Let’s See An Example!

Let’s continue off of the sample architecture that I already started off with. So we have our three layers. Let’s pretend we have some sort of import process where we read in lines of a file. Every line in the file is supposed to have two values, separated by a comma. This is all done by an importer class in our data later. Sounds easy.

Now, I’m not suggesting this is something you’d actually want in your application, it’s simply to demonstrate my point. So let’s pretend that the source of our data could sometimes be poorly formatted. Our import function can easily know about this (i.e. it splits the line on a comma, and finds out that there are not exactly two values). But does it know how to resolve it? Is it supposed to skip it? Is it supposed to magically figure out how fix it? Does it crash and burn? Wait… Maybe it’s not responsible for making that decision… So who is?

Invoke that event! If your importer class has an event, let’s say, LineFormatError, then someone on the outside can subscribe to it. Maybe my presentation layer can subscribe to it and, through event args, tell the invoker of the event (my importer class reference, of course) how to handle it. The flow could look something like this:

  1. Hook your necessary events up, so something in the presentation layer hooks on to my importer’s event for line format errors.
  2. Start your import.
  3. Upon hitting a poorly formatted line, invoke the LineFormatError event.
  4. The presentation layer receives the event (so now we’re in the “event handler”).
  5. The presentation layer could use information provided in the event args to ask the user if they want to skip the line.
  6. Based on the user’s decision, the presentation layer sets some information on the event arguments that says whether or not to skip it.
  7. The control goes back to the data layer where it checks the event args for what to do–skip or abort.
How is this decoupled? Well, quite simply, you don’t have your data layer directly showing message boxes to the user to decide what to do. It has absolutely no idea that there’s even a message box being shown… it doesn’t care! It simply agrees that it’s not responsible for making the decision of whether or not to skip or abort, but let’s someone else handle it. It delegates the decision through an event.

 

Summary

Events are beautiful things. Leverage them, and you can take advantage of some really decoupled code. Your various components often can’t be responsible for certain tasks, but using events, these components can delegate the decisions to other parts of your code that are certainly responsible for making the decision.


Why Events? Flexibility.

Background

There are many different approaches to developing software, but in my opinion, the opposite ends of the spectrum end up being:

  • Knowing how the whole system looks, feels, and operates before coding a single line.
  • Having an idea of what the user wants and coding to make it happen.

Although I’m generalizing a lot here, it’s sort of like the battle between Waterfall and Agile. Okay, great. So what am I rambling on about here?

Well, in the first case, you know all the ins and outs of the system. You can structure your system so that almost no matter how complex it is, you can ensure that method A is always run immediately after method B which is etc… The design is completely controlled. You have a spec for how all the components work together. The problem? Well, most of this will be reserved for another write-up, but in our case there’s no flexibility. If that spec changes after your complicated system is already in place, how much code do you have to go change?

 

Enter: Events

Okay, so I hinted at why something like Waterfall might cause some headaches, but you don’t need to develop your software in an agile fashion to have flexibility. Events can help you with that!

If you’re not already familiar with what an event is, it’s simply a delegate that one would call when some particular criteria is met. In C#, which is what I’ll be assuming for this write-up, you add event handlers to an event so that when the event is invoked, the event handlers get called (and they get called in the order that they were “hooked” onto the event). Splendid.

So what’s great about events? How are they going to fix your brittle code? Well, if you approach software design in terms of components in a system and how they interact, it’s really beneficial to think about how certain things react to each other. If you’re planning your whole system out ahead of time, you could just always call method A, then method B, and then method C in order every time you want something in particular to happen. But is that flexible? What happens when method B now calls an additional method, let’s say method D, due to some architectural changes that had to be made. Well… That’s all fine and dandy unless you have scenarios where you don’t want to run D in your A,B,C method calls you have everywhere.

So, what if you had thought about it this way:

  • I want B to run once A is run.
  • I need an event for A
  • I need to call method B in my event handler for event A
  • I want C to be run once B is run.
  • I need an event for B
  • I need to call method C in my event handler for event B
And then someone comes along and throws method D into the mix. Well, you know that there is at least one particular case where you want D to be run after B is run… So make another event handler! Your listing now changes to:
  • I want B to run once A is run.
  • I need an event for A
  • I need to call method B in my event handler for event A
  • I want C to be run once B is run.
  • I need an event for B
  • I need to call method C in my event handler for event B
  • I want D to be run when condition X is met after B is run
  • I need an event for B (which I already have!)
  • I need to call method C in my event handler for event B
    • I can add a whole second event handler for event B (so I get C then D called)
    • OR I can modify the existing event handler that calls method C to conditionally call method D when necessary

And now how do you check the condition? Pass in some fancy event args with your state.

 

Summary

Events can help you keep your code flexible when your structure is changing because they provide hooks into the code when certain conditions are met. You don’t need to rely on a firmed-up design for how methods are required to be called in some particular order. If your design changes because you want something to execute under different conditions, just hook up to the event that meets those conditions instead and re-write minimal code.

I’m huge on using events in my architectures, so I’ll try to write up a few more posts on events and why I like them. The flexibility I just described is only one very small part of it, and it certainly requires that you shift your perspective on how components in a system interact.


  • Nick Cosentino

    Nick Cosentino

    I work as a team lead of software engineering at Magnet Forensics (http://www.magnetforensics.com). I'm into powerlifting, bodybuilding, and blogging about leadership/development topics over at http://www.devleader.ca.

    Verified Services

    View Full Profile →

  • Copyright © 1996-2010 Dev Leader. All rights reserved.
    Jarrah theme by Templates Next | Powered by WordPress