valerio.net

Not too long ago I created a type-safe implementation of the ThreadPool.QueueUserWorkItem method that has proved quite useful to spawn off a long-running process to a new thread. This works great if you have a method that takes an input argument and doesn’t return anything. However, what if your long-running process needs to return a value or complete an action when it’s finished? The situation usually arises whenever you need to run a long process on another thread and update the UI when that process is done.

The tricky part about doing the UI update is that you must update it using only the thread that created it. This usually involves checking the InvokeRequired property of the control, and then calling Invoke with a delegate to a method that gets called on the correct UI thread.

Thankfully .NET 2.0 has a BackgroundWorker class which does all of this behind the scenes. A typical scenario where the BackgroundWorker really shines would be to give a long-running computation an input argument, let it run, and then receive an output result that updates the UI. For example:

        private void button6_Click(object sender, EventArgs e)
        {
            // Runs on the UI thread
            BackgroundWorker bw = new BackgroundWorker();
            bw.WorkerReportsProgress = false;
            bw.WorkerSupportsCancellation = true;
            bw.DoWork += new DoWorkEventHandler(bw_DoWork);
            bw.RunWorkerCompleted += new RunWorkerCompletedEventHandler(bw_RunWorkerCompleted);

            string input = "Input argument";

            bw.RunWorkerAsync(input);
        }

        void bw_DoWork(object sender, DoWorkEventArgs e)
        {
            // Runs on different thread
            string input = (string)e.Argument;
            // Long-running computation
            e.Result = input.ToUpper();
        }

        void bw_RunWorkerCompleted(object sender, RunWorkerCompletedEventArgs e)
        {
            // Runs on the UI thread
            string result = (string)e.Result;
            txtOutput.AppendText(String.Format("Completed! Result={0}", result));
        }

This works great, though it has a few problems. First off, it is certainly not typesafe since the input argument to RunWorkerAsync is just an object. This means that in the DoWork event handler that e.Argument is also an object. Similarly, the e.Result property is an object, as well as the Result property in the RunWorkerCompleted event handler. We have objects flying around everywhere, and could easily write code that, for example, assumes that DoWork is returning a string when in fact it might be returning a DateTime. This could get ugly, not to mention that we can’t take advantage of anonymous types without type safety across these methods. This is where a generic wrapper for the BackgroundWorker really comes in handy:

So, for this situation we’re assuming that we have an input argument of type Tin that gets passed to the DoWork event handler on a different thread. That does an operation on the input argument and creates a return value of type Tout, and returns it (along with an Exception, if there was one). So we can write two generic helper classes to handle these types:

    public class DoWorkArgument
    {
        public DoWorkArgument(T argument)
        {
            this.Argument = argument;
        }

        public T Argument { get; private set; }
    }

    public class WorkerResult
    {
        public WorkerResult(T result, Exception error)
        {
            this.Result = result;
            this.Error = error;
        }

        public T Result { get; private set; }
        public Exception Error { get; private set; }
    }

This is fairly straightforward, and we’ve used the new “automatic properties” feature of C# 3.0 to make our code more readable.

Next we take a look at the BackgroundWorker implementation. I put everything in a static class named BackgroundWorkerHelper that contains a few static helper methods. The first method is:

    public static class BackgroundWorkerHelper
    {
        public static void DoWork(
            Tin inputArgument,
            Func, Tout> doWork,
            Action> workerCompleted)
        {
            BackgroundWorker bw = new BackgroundWorker();
            bw.WorkerReportsProgress = false;
            bw.WorkerSupportsCancellation = false;
            bw.DoWork += (sender, args) =>
            {
                if (doWork != null)
                {
                    args.Result = doWork(new DoWorkArgument((Tin)args.Argument));
                }
            };
            bw.RunWorkerCompleted += (sender, args) =>
            {
                if (workerCompleted != null)
                {
                    workerCompleted(new WorkerResult((Tout)args.Result, args.Error));
                }
            };
            bw.RunWorkerAsync(inputArgument);
        }

This defines a method called DoWork which takes three input arguments. The first argument is the input argument and is of type Tin. The second argument is a generic delegate, specifically a Func, Tout> delegate. This means that a delegate to a method must be given which takes one input parameter, a DoWorkArgument object, and returns an object of type Tout. The third input argument is another generic delegate which must have a method specified that accepts one input object of type WorkerResult and does not return anything.

The rest of the implementation creates a BackgroundWorker and hooks up to its DoWork and RunWorkerCompleted events. Note that we’ve made the simplification that we won’t be supporting cancellation or reporting of progress. A more sophisticated wrapper could be implemented that takes advantage of these features if they are needed. I chose to stick with this for simplicity.

The DoWork event has code attached to it through the use of a lambda expression which attempts to invoke the doWork delegate that was passed in (if it’s not null). The args.Argument object is cast to type Tin before a new DoWorkArgument is passed to the delegate invocation, and its result assigned to args.Result. A similar approach is taken on the RunWorkerCompleted event, though no return value is specified.

We can use this BackgroundWorkerHelper to reduce our example above to:

       private void button7_Click(object sender, EventArgs e)
        {
            string input = "Input argument";
            BackgroundWorkerHelper.DoWork(
                input,
                (args) =>
                {
                    // Runs on different thread
                    string input = args.Argument;
                    // Long-running computation
                    return input.ToUpper();
                },
                (args) =>
                {
                    // Runs on the UI thread
                    string result = args.Result;
                    txtOutput.AppendText(String.Format("Completed! Result={0}", result));
                });
        }

Notice that the C# 3.0 compiler can infer the types on everything (in this case Tin=string and Tout=string) and requires no casting. It’s also much less code, and really gets the point across that an input is given to the long-running operation, which then calls the last piece of code to update the UI. It flows naturally from top to bottom without jumping around between methods.

This covers the situation where you have a long-running method that takes an input and returns an output, but I’ve run into two other similar situations where this can be simplified. For example, if you have a long-running method that doesn’t take any input parameters, but needs to update the UI when it’s done. In this case, we can simplify the DoWork method to:

        public static void DoWork(
            Func doWork,
            Action> workerCompleted)
        {
            BackgroundWorker bw = new BackgroundWorker();
            bw.WorkerReportsProgress = false;
            bw.WorkerSupportsCancellation = false;
            bw.DoWork += (sender, args) =>
            {
                if (doWork != null)
                {
                    args.Result = doWork();
                }
            };
            bw.RunWorkerCompleted += (sender, args) =>
            {
                if (workerCompleted != null)
                {
                    workerCompleted(new WorkerResult((Tout)args.Result, args.Error));
                }
            };
            bw.RunWorkerAsync();
        }

Similarly, if you encounter a situation where the long-running method takes no input and returns no output, but it would be useful to update the UI (or check for an error, etc) when the method is complete, it can be further simplified to:

        public delegate void Func();

        public static void DoWork(
            Func doWork,
            Action workerCompleted)
        {
            BackgroundWorker bw = new BackgroundWorker();
            bw.WorkerReportsProgress = false;
            bw.WorkerSupportsCancellation = false;
            bw.DoWork += (sender, args) =>
            {
                if (doWork != null)
                {
                    doWork();
                }
            };
            bw.RunWorkerCompleted += (sender, args) =>
            {
                if (workerCompleted != null)
                {
                    workerCompleted(args.Error);
                }
            };
            bw.RunWorkerAsync();
        }

Hope somebody finds that useful! It’s helped me write the tricky multi-threaded code that usually results when trying to create a responsive user interface by spawning long-running processes out to the thread pool while still retaining thread affinity for the UI controls.

If there’s enough interest I can make the BackgroundWorkerHelper.cs file available for download so you don’t need to copy/paste everything in this post.

EDIT: I also created a “Queued BackgroundWorker” that only starts the next long-running process after the first one finishes.

You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.