Issue:
Add site S1 (http://localhost:30000/S1 ) to the sharepoint (http://localhost:30000), it appears in the top navigation, now add another site S2 (http://localhost:30000/S2 ) to the sharepoint, click on S1, S2 is not visible in the top navigation
Resolution:
// objSubWeb is the object of the SPWeb pointing to the sub site
objSubWeb.Navigation.UseShare = true;
Thread Safe Multithreading in Windows Forms using .NET 2.0
This document details how to create high performance multithread Application using Event based Asynchronous pattern.
Difficult Level: Beginner Intermediate Advanced
Author: Mohammad Hamed Akhter
Document Revision History
Author(s): Mohammad Hamed Akhter
Reviewers: Naga Sudhir Muttireddy
Remarks:
Date: 1/30/2008
Table of Contents
Introduction.. 4
Windows Messages. 4
Processing Messages. 4
Windows Forms and Message Queue.. 5
Leveraging the Message Loop.. 6
Execution Order. 6
Multithreading.. 8
Multithreading Basics. 8
The Goals of Multithreading.. 8
Options for Asynchronous Programming.. 9
Asynchronous Delegates. 9
Polling and Callbacks. 10
Multithreading in Windows Applications. 12
The Asynchronous Call 13
Marshalling Calls to the Right Thread.. 15
Implementation.. 17
The Thread Class. 17
Creating a ThreadWrapper. 18
Creating the Derived Task Class. 19
Improving the Thread Wrapper. 20
Reference:. 22
Bibliography.. 22
Complete Code Listing (Trusted Source). 22
Introduction
The idea of creating this document is to help in rapid development of the multithreaded application. Applications that perform many tasks simultaneously, yet remain responsive to user interaction, often require a design that uses multiple threads. The System.Threading namespace provides all the tools necessary to create high-performance multithreaded applications, but using these tools effectively requires significant experience with multithreaded software engineering. For relatively simple multithreaded applications, the BackgroundWorker component provides a straightforward solution. For more sophisticated asynchronous applications, consider implementing a class that adheres to the Event-based Asynchronous Pattern.
The Event-based Asynchronous Pattern makes available the advantages of multithreaded applications while hiding many of the complex issues inherent in multithreaded design. Using a class that supports this pattern can allow you to:
1. Perform time-consuming tasks, such as downloads and database operations, "in the background," without interrupting your application.
2. Execute multiple operations simultaneously, receiving notifications when each completes.
3. Wait for resources to become available without stopping ("hanging") your application.
4. Communicate with pending asynchronous operations using the familiar events-and-delegates model. For more information on using event handlers
and delegates, see Events and Delegates.
Before we jump into these, we would first brush-up the basics of Windows Forms, Multithreading and Asynchronous Delegates
Windows Messages
We would see how to take full advantage of the message loop - possibly combination with the multithreads - to perform asynchronous and background processing in a way that keeps our code simple without sacrificing application responsiveness.
Windows itself has no awareness of .NET and so cannot have any awareness of the .NET event architecture. Clearly, under the hood Windows must be doing something else to make the control aware of the need to raise, for example, the Paint Event. And similarly for every other event you might encounter. In fact, Windows informs the control of the need to do painting by sending it something called a Windows Message.
Processing Messages
The message queue is a data area in windows that is used to store any messages that need to be sent to a window. The Windows procedure and the message loop are both functions that must be implemented by the application that wants to display windows.
The Windows procedure has the task of processing messages sent to a window. It is the function that comes closest in concept to a .NET event handler. However, where a .NET event handler is specifically geared to one event and is normally only called when that event is raised, the windows procedure is much more general purpose in nature.
Running the Message loop is what the main thread of an application normally spends most of its time doing. The message loop normally does the following:
1. Checks to see if there is a message on the queue waiting to be processed. If there isn't then it goes to sleep and wakes up when a message appears
2. When a message is on the queue, it reads it (pops off the queue), then calls the appropriate windows procedure, passing it the details of that message. This step is known as dispatching the message
3. Goes back to step 1.
There are different windows procedures for each type of window (form or control) in the application. When a message is dispatched, Windows is automatically able to make sure the correct procedure is invoked. This all happens on the same thread. A thread that is executing a message loop is normally termed a user interface thread.
Windows Forms and Message Queue
In CLR, System.Windows.Forms.Control class there is some code that implements a windows procedure. That windows procedure will be implemented to invoke the various methods in control and its derived classes which perform default processing. That accounts for the windows procedures.
How about the message loop? That comes from the Application Object. The static Application.Run() method takes the form that it has been supplied, locates its windows procedure, and registers it with Windows. Then it enters a message loop
Leveraging the Message Loop
Now we have the basic principles under our belt let's see what implications this knowledge has for our Windows Application.
Execution Order
If you've done a lot of Windows Forms programming then the chances are that at one time or another, you've called some methods which should display something on the screen, only you find that the data has only been displayed later on, not at the time that you called the method. If you don't understand how the message loop works, then this type of bug can be quite puzzling, but with our knowledge of the message loop we can now see the explanation.
In general, most painting is done because the system has posted a WM_PAINT message and allowing the windows procedure to deal with the message. Now suppose you have a list box call listBox1, and you execute this code:
Void MyMethod()
{
// some processing
listBox1.Items.Add("My New Item");
// some more intensive processing
}
The Add() method does not do the painting, instead it posts a WM_PAINT message to the queue. Then the Add() method returns the control back to MyMethod(), if MyMethod is processing something which lasts for several seconds, you won't see the new item appear in the list box for several seconds, because the required drawing to the screen won't take place until the WM_PAINT message is processed. In Windows Forms application, if MyMethod() is being executed on the main thread, it must have been invoked by some event handler - that's the only way that main thread in
Windows Forms application ever normally executes any methods. The main thread won't get to look at the message queue until the current event handler has completely finished. Once that happens, execution flow will transfer back into the message loop and the list box will be updated on the screen.
The second consequence of this architecture is more subtle - the message loop is being executed by the main UI thread, which means that it is always the main UI thread which gets to handle the messages. So even if, in the above example, MyMethod() was actually being executed on some other worker thread, the actual painting will end up taking place on the main application thread, in the Paint event handler(s). Clearly, if you are writing multithreaded applications, that information is rather important for writing correct thread synchronization code! Incidentally, that the painting takes place on the main thread is normally regarded as a good thing since its good practice to only allow one thread to deal with the user interface. The Windows Forms classes have been designed with this principle in mind, which means most of their methods are not thread safe.
One of the neatest things about message loop is the way that is allows threads to communicate with each other in a multithreaded application. When the main UI thread picks up a message from the queue, it doesn't know or care which thread originally left the message there. All it cares about is that there's a message with some data that needs to be processes. This provides a convenient alternative way of communicating between threads that does not involve the thread synchronization primitives. If you want to use this technique to pass data to the main thread (or if you want to get some method called on the main thread), then you will need to use the Control.BeginInvoke()/EndInvoke() methods.
Multithreading
In a Windows client application, running multithreaded code is as easy as instantiating an object and calling a method. However, multithreading safely isn’t as clear-cut. Several issues can trip you up, including passing data from one thread to another, updating controls from the proper thread, and properly cleaning up when the work is finished
Multithreading Basics
A thread is an independent unit of execution. A complex application can have dozens of threads executing simultaneously. When you program with threads, you write your code as though each thread were running independently. Behind the scenes, the Windows operating system gives each thread a brief unit of time (called a time slice) to perform some work, and then it freezes the thread in a state of suspended animation. A little bit later (perhaps only a few milliseconds); the operating system unfreezes the thread and allows it to perform a little more work. This model of constant interruption is known as preemptive multitasking. It takes place completely outside the control of your program.
Your application acts (for the most part), as if all its threads were running simultaneously, and each thread carries on as though it’s an independent program performing some task.
The Goals of Multithreading
Multithreading increases complexity. If you decide to use multithreading, you’ll need to code carefully to avoid minor mistakes that can lead to mysterious errors later on. Before you split your application into separate threads, carefully consider whether the additional work is warranted.
There are essentially three reasons for using multiple threads in a program:
• Making the client more responsive. If you run a time-consuming task on a separate thread, the user can still interact with your application’s user interface to perform other tasks. You can even give the user the ability to cancel the background work before it’s complete.
• Completing several tasks at once. On its own, multithreading doesn’t improve performance for the typical single-CPU computer. (In fact, the additional overhead needed to track the new threads decreases it slightly.) However, certain tasks can involve a high degree of latency, such as fetching data from an external source (Web page, database, or a file on a network) or communicating with a remote component. While these tasks are underway, the CPU is essentially idle. Although you can’t reduce the wait time, you can use the time to perform other work. For example, you might send requests to three Web services at the same time to reduce the total time taken, or you might perform CPU intensive work while waiting for a call to complete.
• Making a server application scalable. A server-side application needs to be able to handle an arbitrary number of clients. Depending on the technology you’re using, this might be handled for you (as it is if you’re creating an ASP.NET Web application). In other cases, you might need to create this infrastructure on your own—for example, if you’re building a peer-to-peer file sharer with the .NET networking classes.
Options for Asynchronous Programming
As all programmers know, there are several ways to solve most problems. In keeping with this principle, .NET provides several tools for multithreaded programming. Each approach has its own strengths and weaknesses.
Your options include the following:
• Asynchronous delegate calls. The delegate type has built-in support for asynchronous use. That means you can launch any method on a separate thread. The code runs on one of the free threads that the common language runtime (CLR) reserves in a handy thread pool. This approach is straightforward and convenient.
• The BackgroundWorker component. It’s easy enough to get code to run on a separate thread, but it’s not as easy to manage threading issues such as synchronization. To help you avoid these challenges, .NET 2.0 introduces a new higher-level model with the BackgroundWorker component, which allows you to write multithreaded code just by responding to a couple of events that fire when the task starts and when it finishes. This approach is the simplest, but also the least flexible. • The System.Threading.Thread class. For more control, you can spawn a new thread at will by creating a Thread object. The Thread object is tied to a single method, which it launches when you call Thread.Start(). When the method ends, the thread is destroyed. This approach is the most powerful, but it also requires the most work to implement.
These three approaches differ in how they are implemented by the CLR, how you write your code, and what features are available. A serious .NET programmer needs to be familiar with all three.
Asynchronous Delegates
As you already know, delegates are type-safe function pointers that form the basis for .NET events. You create a delegate that references a specific method, and then you can call that method through the delegate. The first step is to define the delegate at the namespace level (if it’s not already present in the .NET class library). Here’s a delegate that can point to any method that accepts a single integer parameter and returns an integer:
//Declaring a delegate
public delegate int DoSomethingDelegate(int input);
Now consider a class that has a method that matches this delegate:
public class MyObject
{
public int DoubleNumber(int input)
{
return input * 2;
}
}
You can create a delegate variable that points to a method with the same signature. Here’s the code:
MyObject myObj = new MyObject();
// Create a delegate that points to the myObj.DoubleNumber() method.
DoSomethingDelegate doSomething = new DoSomethingDelegate(myObj.DoubleNumber);
// Call the myObj.DoubleNumber() method through the delegate.
int doubleValue = doSomething(12);
What you may not realize is that delegates also have built-in threading smarts. Every time you define a delegate (such as DoSomethingDelegate in the above example), a custom delegate class is generated and added to your assembly. (A custom delegate class is needed because the code for each delegate is different, depending on the signature of the method you’ve defined.) When you call a method through the delegate, you are actually relying on the Invoke() method of the delegate class.
The Invoke() method executes the linked method synchronously. However, the delegate class also includes methods for asynchronous invocation—BeginInvoke() and EndInvoke(). When you use BeginInvoke(), the call returns immediately, but it doesn’t provide the return value. Instead, the method is simply queued to start on another thread. When calling BeginInvoke(), you supply all the parameters of the original method, plus two additional parameters for an optional callback and state object. If you don’t need these details (described later), simply pass a null reference.
//Begin Invoke with parameters o original method and optionals
IAsyncResult async = doSomething.BeginInvoke(12, null, null);
BeginInvoke() doesn’t return the return value of the underlying method. Instead, it returns an IAsyncResult object that you can examine to determine when the asynchronous operation is complete. To pick up the results later on, you submit the IAsyncResult object to the matching EndInvoke() method of the delegate. EndInvoke() waits for the operation to complete if it hasn’t already finished and then provides the real return value. If any unhandled errors occurred in the method that you executed asynchronously, they’ll bubble up to the rest of your code when you call EndInvoke().
Here’s the previous example rewritten to call the delegate asynchronously:
MyObject myObj = new MyObject();
// Create a delegate that points to the myObj.DoubleNumber() method.
DoSomethingDelegate doSomething = new DoSomethingDelegate(myObj.DoubleNumber);
// Start the myObj.DoubleNumber() method on another thread.
IAsyncResult async = doSomething.BeginInvoke(originalValue, null, null);
// (Do something else here while myObj.DoubleNumber() is executing.)
// Retrieve the results, and wait (synchronously) if they're still not ready.
int doubleValue = doSomething.EndInvoke(async);
Polling and Callbacks
When you call EndInvoke(), the call becomes synchronous. That means that if the underlying method hasn’t returned by the time you call EndInvoke(), your code simply waits for it to finish, as it would if you called Invoke(). If you want to check whether the method is actually complete before you call EndInvoke(), you can check the IsCompleted property of the IAsyncResult object that’s returned from the BeginInvoke() method. You can check this information repeatedly (for example, in a loop while you do some other work in bite-sized pieces). This approach is known as polling, and it’s usually not terribly efficient. Here’s an example that uses it:
IAsyncResult async = doSomething.BeginInvoke(12, null, null);
// Loop until the method is complete.
while (!async.IsCompleted)
{
// Do a small piece of work here.
}
int doubleValue = doSomething.EndInvoke(async);
A better approach is to use a callback to react immediately when an asynchronous task is complete. Callbacks allow you to separate the code for different tasks, and they can simplify your application significantly. To use a callback, you must first create a method that accepts a single parameter of type IAsyncResult, as shown here:
private void MyCallback(IAsyncResult async)
{ ... }
The IAsyncResult object is the same object you receive when you call BeginInvoke(). It’s provided to your callback so that you can easily complete the call—just call EndInvoke() and submit the IAsyncResult object. To use a callback, you need to pass a delegate that points to your callback method as the second-to-last parameter when you call BeginInvoke():
doSomething.BeginInvoke(12, new AsyncCallback(this.MyCallback), null);
In this case, the BeginInvoke() will still return the same IAsyncResult object, but the code doesn’t need to use it to monitor progress because the CLR will automatically call the callback method as soon as the asynchronous operation is complete. Callbacks don’t provide any information about why they were triggered. They don’t even provide the delegate object that you used to start the asynchronous processing. That means that if you’re handling several asynchronous tasks with the same callback, you can’t easily tell which operation has completed when the callback fires. To get around this limitation, you can send an additional object using the last parameter of the BeginInvoke() method. This object is then provided through the IAsyncResult.AsyncState parameter in the callback method. You can use any object, including an instance of a custom class that records the details of the original operation. One useful trick is to provide the original delegate object (in this case, the doSomething delegate) as part of that custom class. This way, you can easily complete the call in the callback by calling EndInvoke() on the provided delegate. Otherwise, it’s up to you to keep the delegate reference around for later.
Here’s an example that starts an asynchronous task with a callback and sends an additional state parameter. In this example, the state object is simply the delegate that made the call:
doSomething.BeginInvoke(originalValue,
new AsyncCallback(this.MyCallback), doSomething);
And here’s how you can retrieve the result in the callback:
private void MyCallback(IAsyncResult async)
{
// Retrieve the delegate.
DoSomethingDelegate doSomething = (DoSomethingDelegate)async.AsyncState;
// Use it to retrieve the result.
int doubleValue = doSomething.EndInvoke(async);
// (Do something with the retrieved information.)
}
It’s important to realize that callbacks are actually executed on the same thread as the asynchronous delegate, not the main thread of your application. This fact can cause a host of problems if you don’t take it into account. For example, if you try to update an existing object, you could run into synchronization problems (where two threads try to update the same data at once). Similarly, you can’t modify the properties of an existing UI control from a separate thread, or you may introduce other obscure errors and trigger unexpected exceptions. The only solution to these problems is to marshal your call to the right user interface thread, or use some type of synchronization. You’ll see examples of both these techniques in the following section, as you apply the delegate approach to a more realistic example.
Multithreading in Windows Applications
The asynchronous delegate example demonstrates how to execute code on a separate thread. However, this example is wide open to some of the nastier problems of multithreading. The worst part about all these problems is they usually don’t appear immediately. Instead, they occur only sporadically under certain conditions, making them difficult to diagnose and solve. To tackle these problems, it helps to consider a sample application. The basic ingredient for any test is a time-consuming process.
public class Worker
{
public static int[] FindPrimes()
{
// Find the primes
}
}
When you click Find Primes, the following code runs:
private void cmdFind_Click(object sender, EventArgs e)
{
this.UseWaitCursor = true;
txtResults.Text = "";
lblTimeTaken.Text = "";
}
// Start the search for primes and wait.
DateTime startTime = DateTime.Now;
int[] primes = Worker.FindPrimes();
// Display the time for the call to complete.
lblTimeTaken.Text =
DateTime.Now.Subtract(startTime).TotalSeconds.ToString();
// Paste the list of primes together into one long string.
StringBuilder sb = new StringBuilder();
foreach (int prime in primes)
{
sb.Append(prime.ToString());
sb.Append(" ");
}
txtResults.Text = sb.ToString();
this.UseWaitCursor = false;
}
This code runs without a hitch, but it also locks the user out while the work is in progress. If you start dragging the form around the screen while the Worker is searching for primes, you may see some erratic behavior. For example, the window may become a blank surface, indicating that the form hasn’t yet responded to the Windows message asking it to repaint itself or it may display the “Not Responding” message in the caption (see Figure below). To improve on this situation, you need multithreading.
The Asynchronous Call
There are several ways to translate this example into a multithreaded application. Using asynchronous delegates, you can launch the Worker.FindPrimes() method on another thread. However, a much better approach is to wrap the call to Worker.FindPrimes() with another method in the form. This allows you to separate the code for updating the user interface from the code that actually performs the prime-number search, which is a key design goal. It also provides you with an extra layer of flexibility. This extra layer comes in handy if the signature of the FindPrimes() method changes. The below figure shows this design.
Here’s the form method that you need. It simply calls the Worker.FindPrimes() method (synchronously), and then updates the user interface with the results.
private void CallAsyncWorker()
{
// Start the search for primes and wait.
DateTime startTime = DateTime.Now;
int[] primes = Worker.FindPrimes();
// (Update the user interface.)
}
Because you’re calling the CallAsyncWorker() method asynchronously, you need to create a delegate for it that has the same signature:
private delegate void CallAsyncWorkerDelegate(int from, int to);
Now you can invoke the CallAsyncWorker() method on another thread when the user clicks the Find Primes button. Here’s the code you need:
private void cmdFind_Click(object sender, EventArgs e)
{
// Disable the button.
cmdFind.Enabled = false;
txtResults.Text = "";
lblTimeTaken.Text = "";
// Start the search for primes on another thread.
CallAsyncWorkerDelegate doWork = new
CallAsyncWorkerDelegate(CallAsyncWorker);
doWork.BeginInvoke(null, null, null);
}
Notice that this example disables the button so that only one asynchronous operation can be performed at a time. The button will be re-enabled when the asynchronous task is completed.
Marshalling Calls to the Right Thread
This example leaves out one detail—the code for updating the user interface. The problem is that .NET controls exhibit thread affinity, which means that their properties and methods can be called only by code running on the same thread that created the control. As a result, you can’t modify the lblTimeTaken or txtResults controls from the CallAsyncWorker() method. A new debugging feature in .NET 2.0 helps you spot threading errors. By default, every Windows control included with .NET throws an InvalidOperationException when it’s accessed from the wrong thread. (You can disable this behavior by setting the static Control.CheckForIllegalCrossThreadCalls to false.) However, it’s important to realize that this is a debugging convenience, and these checks aren’t made in a release-mode build. Furthermore, third-party controls are unlikely to provide the same nicety. As a result, you need to be conscious of when you cross a thread boundary. If you do access a control from another thread, you will run into unpredictable errors that can crash your application or freeze your user interface. Worst of all, these types of errors happen sporadically, which makes them very difficult to diagnose. Fortunately, all .NET controls provide two members that you can access from other threads.
These include:
• InvokeRequired. This property returns true if the current code is running on a thread other than the one that created the control, in which case you can’t directly manipulate the control.
• Invoke(). This method allows you to fire a method on the correct user interface thread, so you can manipulate the control without causing an error. You can use the Invoke() method to solve the problem in the current example. You just need to break your code down so that the user interface update happens in a separate method.
Here’s an UpdateForm() method you could use for updating the interface (with the corresponding delegate):
private delegate void UpdateFormDelegate(TimeSpan timeTaken, string primeList);
private void UpdateForm(TimeSpan timeTaken, string primeList)
{
lblTimeTaken.Text = timeTaken.TotalSeconds.ToString();
txtResults.Text = primeList;
cmdFind.Enabled = true;
}
Now you can call the UpdateForm() method from the CallAsyncWorker() method using Control.Invoke(). Here’s how you need to revise the code:
private void CallAsyncWorker()
{
// Start the search for primes and wait.
DateTime startTime = DateTime.Now;
int[] primes = Worker.FindPrimes();
// Calculate the time for the call to complete.
TimeSpan timeTaken = DateTime.Now.Subtract(startTime);
// Paste the list of primes together into one long string.
StringBuilder sb = new StringBuilder();
foreach (int prime in primes)
{
sb.Append(prime.ToString());
sb.Append(" ");
}
// Use the Control.Invoke() method of the current form,
// which is owned by the same thread as the rest of the controls.
this.Invoke(new UpdateFormDelegate(UpdateForm),
new object[] {timeTaken, sb.ToString()} );
}
The nice part about the Invoke() method is that it supports methods with any signature. All you need to do is pass a delegate and supply an object array with all the parameter values. Notice that the CallAsyncWorker() method also performs the work of building the string of primes. That’s because the UpdateForm() method fires on the user interface thread (when it’s idle), temporarily interrupting your application. To ensure that the application remains responsive, you need to reduce the amount of work you perform here as much as possible. This completes the example. Figure below shows the three steps. First the button is clicked, launching the event handler (step 1). Next, the CallAsyncWorker() is invoked asynchronously
(step 2), and it calls the FindPrimes() method (step 3). Finally, CallAsyncWorker() retrieves the result and calls the UpdateForm() method on the user interface thread (step 4). Steps 1 and 4 are on the user interface thread, while the shaded portion (steps 2 and 3) execute on a single thread borrowed from the CLR’s thread pool.
To test this example, run the application and start a prime search. While it’s underway, you still can click on other controls, and drag the form around the screen. Of course, to prevent synchronization problems or unintended side effects, you need to make sure your user interface is in a state where only the supported commands are available. For example, the Find Primes button is disabled in this example because we’ve chosen to allow only one search at a time. If you like, you can rewrite UpdateForm() method to make it self-sufficient, so that it automatically marshals itself to the user interface thread as needed. This is a common pattern in Windows Forms applications that’s easy to implement.
private void UpdateForm(TimeSpan timeTaken, string primeList)
{
if (this.InvokeRequired)
{
this.Invoke(new UpdateFormDelegate(UpdateForm),
new object[] {timeTaken, primeList} );
}
else
{
lblTimeTaken.Text = timeTaken.TotalSeconds.ToString();
txtResults.Text = primeList;
cmdFind.Enabled = true;
}
}
Now you can call UpdateFormDelegate() directly. If you call UpdateFormDelegate() from the user interface thread, the code will run ordinarily. If you call it from another thread, the method will call itself on the correct thread, taking care of the marshalling automatically.
Implementation
The Thread Class
At first, the BackgroundWorker component seems like the perfect solution to building multithreaded applications, and in many cases it is. The BackgroundWorker component makes particularly good sense when you have a single long-running task that executes in the background. But the BackgroundWorker doesn’t provide some features, such as the following:
• The ability to manage multiple asynchronous tasks at once. For example, you can’t run multiple prime-number queries at once (at least not without some ugly workarounds).
• The ability to communicate in ways other than sending a progress report or cancellation request. For example, you can’t pause an in-progress task or supply new information. You’re limited to the features baked into the BackgroundWorker.
• The ability to directly access and manipulate details about the background thread (such as its priority).
If you’re creating an application that needs these features, you need to step up to the System.Threading.Thread class. The Thread class represents a new thread of execution. To use the Thread class, you begin by creating a new Thread object, at which point you supply a delegate to the method you want to invoke asynchronously. As with the delegate examples and the BackgroundWorker, a Thread object can point to only a single method. However, there’s one basic limitation—this method must accept no parameters and have no return value. In other words, it must match the signature of the System.Threading.ThreadStart delegate.
ThreadStart asyncMethod = new ThreadStart(myMethod);
Thread thread = new Thread(asyncMethod);
Once you’ve created the Thread object, you can start it on its way by calling the Thread.Start() method. This method returns immediately, and your code begins executing asynchronously on a new thread (not one of the threads in the CLR thread pool).
thread.Start();
When the method ends, the thread is destroyed and cannot be reused.
Creating a ThreadWrapper
In the next example, you’ll see how to build a threading system for performing an arbitrary number of simultaneous prime-number searches. Creating a ThreadWrapper Because the Thread class supports only methods with no parameters and no return value, it’s common to put the code you want to execute in a separate class. You can then add properties to that class for the input and output information. A common design in .NET applications is to create a Worker class that encapsulates the code for performing your specific task and the thread object. That way, you don’t need to track both the worker and the thread objects separately. Before you create your thread wrapper, it makes good sense to factor out all the threading essentials into a base class. That way you can use the same pattern to create multiple asynchronous tasks without recoding it each time. This approach also gives you the benefit of defining a standard interface. We’ll examine the ThreadWrapper base class piece by piece. First of all, the ThreadWrapper is declared abstract so that it can’t be instantiated on its own. Instead, you need to create a derived class.
public abstract class ThreadWrapper
{ ... }
The ThreadWrapper defines two public properties. Status returns one of three values from an enumeration (Unstarted, InProgress, or Completed). ID returns an automatically generated unique ID, which is useful for tracking the task when several are underway at once.
// Track the status of the task.
private StatusState status = StatusState.Unstarted;
public StatusState Status
{
get { return status; }
}
// Use a unique ID to track the task later, if needed.
private Guid id = Guid.NewGuid();
public Guid ID
{
get { return id; }
}
The ThreadWrapper wraps a Thread object. It exposes a public Start() method which, when called, creates the thread and starts it off:
// This is the thread where the task is carried out.
private Thread thread;
// Start the new operation.
public void Start()
{
if (status == StatusState.InProgress)
{
throw new InvalidOperationException("Already in progress.");
}
else
{
// Initialize the new task.
status = StatusState.InProgress;
// Create the thread and run it in the background,
// so it will terminate automatically if the application ends.
thread = new Thread(StartTaskAsync);
thread.IsBackground = true;
// Start the thread.
thread.Start();
}
}
The thread executes a private method named StartTaskAsync(). This method farms the work out to two other methods—DoTask() and OnCompleted(). DoTask() performs the actual work (calculating the prime-numbers). OnCompleted() fires a completion event or triggers a callback to notify the client. Both of these details are specific to the particular task at hand, so they’re implemented as abstract methods that the derived class will override:
private void StartTaskAsync()
{
DoTask();
status = StatusState.Completed;
OnCompleted();
}
// Override this class to supply the task logic.
protected abstract void DoTask();
// Override this class to supply the callback logic.
protected abstract void OnCompleted();
This completes the ThreadWrapper.
Creating the Derived Task Class
Now that you have the thread wrapper in place, you can derive a new class that overrides DoTask() and OnCompleted() to perform the prime-number calculation
public class CTask : ThreadWrapper
{ ... }
The first order of business is getting the input information into the CTask class.
The easiest approach is to require that the from and to numbers be supplied as constructor arguments:
private int fromNumber, toNumber;
public CTask()
{
}
This solves the problem of getting the input information into the class. But how do you get the result out? The thread wrapper needs to fire some sort of completion event. You could require the client to supply a callback as a constructor argument. However, this example uses an event instead:
public event FindPrimesCompletedEventHandler Completed;
The event signature defines two parameters—the sender and a FindPrimesCompletedEventArgs object that wraps the information about the search range and final prime-number result list.
public delegate void FindPrimesCompletedEventHandler(object sender, FindPrimesCompletedEventArgs e);
Now, you simply need to override the DoTask() and OnCompleted() methods to fill in the blanks. The DoTask() method performs the search and stores the prime list in a variable:
private string primeList;
protected override void DoTask()
{
// Start the search for primes and wait.
int[] primes = Worker.FindPrimes();
// Paste the list of primes together into one long string.
StringBuilder sb = new StringBuilder();
foreach (int prime in primes)
{
sb.Append(prime.ToString());
sb.Append(" ");
}
// Store the result.
string primeList = sb.ToString();
}
Notice that in this example, the work is farmed out to the Worker component. This makes for a more streamlined design and simpler coding. However, you might want to change this design to put the prime search code into the DoTask() method. This way, you can add support for progress reporting and cancellation. (The downloadable samples for this chapter [in the Source Code area of the Apress Web site] use this approach.) The OnCompleted() method fires the event:
protected override void OnCompleted()
{
if (Completed != null)
Completed(this,
new FindPrimesCompletedEventArgs(primeList));
}
The next ingredient is to create the form that lets the user launch the prime-number searches.
Improving the Thread Wrapper
This example sketched out the bare skeleton you need to create a respectable solution. You can add a lot more functionality to the thread wrapper implementation. For example, the base ThreadWrapper class could be enhanced to support task stopping, either politely (through a cancel request message that you must heed in the DoTask() method), or impolitely (by aborting the thread). Here’s the rough outline for a stop feature. Simply add this code to the ThreadWrapper base class and customize the protected variables in the CTask class as required.
// Flag that indicates a stop is requested.
private bool requestCancel = false;
protected bool RequestCancel
{
get { return requestCancel; }
}
// How long the thread will wait (in total) before aborting a thread
// that hasn't responded to the cancellation message.
// TimeSpan.Zero means polite stops are not enabled.
private TimeSpan cancelWaitTime = TimeSpan.Zero;
protected TimeSpan CancelWaitTime
{
get { return cancelWaitTime; }
set { cancelWaitTime = value; }
}
// How often the thread checks to see if a cancellation
// message has been heeded.
private int cancelCheckInterval = 5;
protected int CancelCheckInterval
{
get { return cancelCheckInterval; }
set { cancelCheckInterval = value; }
}
public void StopTask()
{
// Perform no operation if task isn't running.
if (status != StatusState.InProgress) return;
// Try the polite approach.
if (cancelWaitTime != TimeSpan.Zero)
{
DateTime startTime = DateTime.Now;
while (DateTime.Now.Subtract(startTime).TotalSeconds > cancelWaitTime)
{
// Still waiting for the time limit to pass.
// Allow other threads to do some work.
Thread.Sleep(TimeSpan.FromSeconds(cancelCheckInterval));
}
}
// Use the forced approach.
thread.Abort();
}
You could use a similar approach to implement the Pause() and Resume() methods. The next refinement is progress tracking. If your derived class supports progress reporting, it should set the SupportsProgress property to true. It can then supply the percentage complete through the protected progress variable.
private bool supportsProgress = false;
protected bool SupportsProgress
{
get { return supportsProgress; }
set { supportsProgress = value; }
}
protected int progress;
public int Progress
{
get
{
if (!supportsProgress)
throw new InvalidOperationException(
"This worker does not report progess.");
else
return progress;
}
}
Reference:
· .NET Delegates: A C# Bedtime Story
· Safe, Simple Multithreading in Windows Forms
· How to: Make Thread-Safe Calls to Windows Forms Controls
· Event-based Asynchronous Pattern Overview
Bibliography
· .NET 2.0 Windows Forms and Custom Controls
Complete Code Listing (Trusted Source)
