[转]WinForms UI Thread Invokes: An In-Depth Review of Invoke/BeginInvoke/InvokeRequred

This blog comes from here:

http://weblogs.asp.net/justin_rogers/pages/126345.aspx

Abstract:
Marshalling the execution of your code
onto the UI thread in the Windows Forms environment is critical to
prevent cross-thread usage of UI code. Most people don't understand how
or when they'll need to use the marshalling behavior or under what
circumstances it is required and when it is not. Other users don't
understand what happens when you use the marshalling behavior but it
isn't needed. In actuality it has no negative effects on stability, and
instead reserves any negative side effects to performance only.

Understanding the semantics of when your callback methods will be
called, in what order, and how might be very important to your
application. In addition to the default marhalling behavior, I'll be
covering special considerations for enhancing the marhsalling behavior
once we fully understand how it works. We'll also cover all of the
normal scenarios and uses for code execution marhsalling to make this a
complete Windows Forms marshalling document.

TOC:

UCS 1: Using InvokeRequired and Invoke for Synchronous Marshalling, the default scenario

UCS 2: Using BeginInvoke for Asynchronous Marshalling

InvokeRequired and how it works

Invoke operation on the UI thread and from a different thread

InvokeMarshaledCallbacks and how it handles the callback queue

BeginInvoke operation on the UI thread and from a different thread

UCS 3: Using BeginInvoke to change a property after other events are processed, and why it can fail

Public and Internal Methods covered with a short description of what they do

Conclusion

1. UCS 1: Using InvokeRequired and Invoke for Synchronous Marshalling, the default scenario
I
call this the default scenario, because it identifies the most
prominent use of UI thread marshalling. In this scenario the user is
either on the UI thread or they are not, and most likely they aren't
sure. This can occur when you use common helper methods for acting on
the UI that are called from your main code (most likely on the UI
thread), and in code running on worker threads.

You can always tell if an Invoke is going to be required by calling
InvokeRequired. This method finds the thread the control's handle was
created on and compares it to the current thread. In doing so it can
tell you whether or not you'll need to marshal. This is extremely easy
to use since it is a basic property on Control. Just be aware that
there is some work going on inside the method and it should have
possibly been made a method instead.



If your code is running on a
thread that the control was not created on then InvokeRequired will
return true. In this case you should either call Invoke or BeginInvoke
on the control before you execute any code. Invoke can either be called
with just a delegate, or you can specify arguments in the form of an
object[]. This part can be confusing for a lot of users, because they
don't know what they should pass to the Invoke method in order to get
their code to run. For instance, let's say you are trying to do
something simple, like call a method like Focus(). Well, you could
write a method that calls Focus() and then pass that to Invoke.



Noticed I used MethodInvoker.
This is a special delegate that takes no parameters so it can be used to
call any methods that take 0 parameters. In this case Focus() takes no
arguments so things work. I'm telling the control to invoke the method
right off of myControl, so I don't need any additional information.
What happens if you need to call a bunch of methods on myControl? In
that case you'll need to define a method that contains all of the code
you need run and then Invoke it.



This solves one problem, but
leaves another. We just wrote code that only works only for myControl
because we hard coded the control instance into our method. We can
overcome this by using an EventHandler syntax instead. We'll cover the
semantics of this later, so I'll just write some code that works now.



EventArgs is always going to be
empty, while sender will always be the control that Invoke was called
on. There is also a generic helper method syntax you can use to
circumvent any of these issues that makes use of InvokeRequired. I'll
give you a version of that works with MethodInvoker and one that works
with EventHandler for completeness.



Once you've set up these helper
functions, you can just call them and they handle cross thread
marshalling for you if needed. Notice how each method simply calls back
into itself as the target of the Invoke call. This lets you put all of
the code in a single place. This is a great abstraction that you can
add to your application to automatically handle marshalling for you. We
haven't yet had to define any new delegates to handle strange method
signatures, so these techniques have low impact on the complexity of
your code. I'll wrap up the Invoke use case scenario there and move
into the BeginInvoke scenario.

2. UCS 2: Using BeginInvoke for Asynchronous Marshalling
Whenever
you call Invoke, you have to wait for the return call, so your current
thread hangs until the remote operation completes. This can take some
time since lots of things need to happen in order to schedule your code
on the UI thread and have it execute. While you don't really have to
worry that an Invoke might block indefinitely, you still can't determine
exactly how long it will take (unless it really wasn't required in the
first place, but we'll get to that later). In these cases you'll want
to call Invoke asynchronously.

Calling your code asynchronously
is simliar to calling it through Invoke. The only difference is that
BeginInvoke will return immediately. You can always check for the
results of your operation by calling EndInvoke, but you don't have to.
In general, you'll almost never use EndInvoke unless you actually want
the return value from the method which is fairly rare. The same
plumbing is in the back-end for BeginInvoke as for Invoke so all we'll
be doing is changing our code from UCS 1 to use BeginInvoke.



What happens if you do need the
return value? Well, then the use case changes quite a bit. You'll need
to wait until the IAsyncResult has been signalled complete and then
call EndInvoke on this object to get your value. The following code
will will grab the return value and then immediately call EndInvoke.
Note that since the result is probably not ready yet, EndInvoke will
hang. Using this combination of BeginInvoke/EndInvoke is the same as
just calling Invoke.



So we'll change our behavior to
check for completion status. We'll need to find some way to poll the
completion status value so we don't hang our current thread and can
continue doing work while we wait. Normally you'll just put places in
your code to check the result status and return. We don't have the time
nor space to make up such an elaborate sample here, so we'll just
pretend we are doing work.



The BeginInvoke use case
scenario isn't much different from the Invoke scenario. The underlying
reason behind using one over the other is simply how long you are
willing to wait for the result. There is also the matter of whether you
want the code to execute now or later. You see, if you are on the UI
thread already and issue an Invoke the code runs immediately. If you
instead issue a BeginInvoke you can continue executing your own code,
and then only during the next set of activity on the message pump will
the code be run. If you have some work to finish up before you yield
execution then BeginInvoke is the answer for you.

You have to be careful when
using BeginInvoke because you never know when your code will execute.
The only thing you are assured is that your code will be placed on the
queue and executed in the order it was placed there. This is the same
guarantee you get for Invoke as well, though Invoke places your code on
the queue and then exhausts it (running any queued operations). We'll
examine this in more detail in later sections. For now, let's take a
hard look at InvokeRequired.

3. InvokeRequired and how it works
This
is a read-only property that does quite a bit of work. You could say
it ran in determinate time in most cases, but there are degenerate cases
where it can take much longer. In fact the only time it is determinate
is if IsHandleCreated is true meaning the control you are using is
fully instantiated and has a windows handle associated with it.

If the handle is created then
control falls into the check logic to see if the windows thread process
id is the same as the current thread id. They use
GetWindowThreadProcessID, a Win32 API call, to check the handle and find
it's thread and process ID (note the process ID doesn't appear to be
used). Then they grab the current thread ID through none other than
GetCurrentThreadID. The result of InvokeRequired is nothing more than
(threadID != currentThreadID). Pretty basic eh?

Things get more difficult when
your control's handle is not created yet. In this case they have to
find what they call a marshalling control for your control. This
process can take some time. They walk the entire control hiearchy
trying to find out if any of your parent control's have been
instantiated yet and have a valid handle. Normally they'll find one.
As soon as they do they fall out and return that control as your
marshalling control. If they can't find any the have a fallback step.
They get the parking window. They make one of these parking windows on
every thread that has a message pump apparently, so no matter where you
create your controls (no matter what thread) there should be at least
one control that can be used as the marshalling control (unless maybe
you are running in the designer ;-).

Application.GetParkingWindow is
nasty. After all, this is the final fallback and the last ditch effort
to find some control that can accept your windows message. The funny
thing here is that GetParkingWindow is extremely determinant if your
control is already created. They have some code that basically gets the
ThreadContext given the thread ID of your control. That is what we've
been looking for this entire time, so that code-path must be used
somewhere else (darn IL is getting muddied, thank god these are small
methods).

Then they start doing the
magic. They assume the control is on the current thread. This is just
an assumption, and it might not be true, but they make it for the sake
of running the method. They get the parking window off of this current
TheadContext and return that. If it hasn't been created yet, we are
really screwed because that was our last chance to find a marshalling
control. At this point, if we still don't have a marshalling control,
they return the original control you passed in.

At the end of this entire
process, if we find a marshalling control, that is used with
GetWindowThreadProcessID. If not, we simply return false, indicating
that an Invoke is not required. This is important. It basically means
if the handle isn't created, it doesn't matter WHAT thread you are on
when you call into the control. Reason being, is that there isn't any
Handle, which means no real control exists yet, and all of the method
calls will probably fail anyway (some won't, but those that require a
HWND or Windows Handle will). This also means you don't always have to
call control methods on the UI thread, only those that aren't thread
safe. With InvokeRequired to the side, it is time to talk about Invoke
and what it goes through.

4. Invoke operation on the UI thread and from a different thread
Time
to examine the Invoke operation and what is involed. To start with,
we'll examine what happens when the Invoke operation is happening on the
same thread as the UI thread for the control. This is a special case,
since it means we don't have to marshal across a thread boundary in
order to call the delegate in question.

All of the real work happens in
MarshaledInvoke. This call is made on the marshalling control, so the
first step is to get the marshaling control through
FindMarshalingControl. The first Invoke method, without arguments,
calls the Invoke method with a null argument set. The overriden Invoke
in turn calls MarshaledInvoke on the marshaling control passing in the
current caller (note we need this because the marshalling control might
be different from the control we called Invoke on), the delegate we are
marshalling, the arguments, and whether or not we want synchronous
marshaling. That second parameter is there so we can use the same
method for asynchronous invokes later.



If the handle on the marhaling
control is invalid, you get the classic exception telling you the handle
isn't created and that the Invoke or what not failed. There is also
some gook about ActiveX controls in there that I don't quite understand,
but they appear to be demanding some permissions. Then comes the
important part for calling Invoke on the UI thread. They again check
the handle's thread id against the current thread id, and if we are
running synchronously, they set a special bool indicating we are running
synchronously and are operating on the same thread. This is the
short-circuit code that gets run only when you call Invoke and are on
the same thread.

Since the special case is
enabled, we'll immediately call the InvokeMarshaledCallbacks method
rather than posting a message to the queue. Note all other entries into
this method, and all other conditions will cause a windows message to
be posted and InvokeMarshaledCallbacks will later be called from the
WndProc of the control once the message is received.

There is some more code before
this point. Basically, they make a copy of the arguments you pass in.
This is pretty smart, since I'm guessing you could try changing the
arguments in the original array and thus the arguments to your delegate
if they didn't make the copy. It also means, once Invoke or BeginInvoke
is called, you can change your object array of parameters, aka you can
reuse the array, which is pretty nice for some scenarios.

After they copy your parameters
into a newly allocated array they take the liberty of grabbing the
current stack so they can reattach it to the UI thread. This is for
security purposes so you can't try to Invoke code on the UI thread that
you wouldn't have been able to run on your own thread. They use
CompressedStack for this operation and the GetCompressedStack method.
While this is a public class inside of mscorlib.dll, there is NO
documentation for it. It seems to me that this might be a very
interesting security mechanism for API developers, but they don't give
you any info on it. Maybe I'll write something about how to use it
later.

With this in place, they
construct a new ThreadMethodEntry. These guys are the work horse. They
get queued into a collection, and are later used to execute your
delegate. It appears the only additional parameter used to create this
class over calling MarshaledInvoke is the CompressedStack. They also
used the copied arguments array instead of the original.

They then grab the queue for
these guys off of the property bag. You could never do this yourself,
because they index the properties collection using object instances that
you can't get access to. This is a very interesting concept, to create
an object used to index a hashtable or other collection that nobody
else has access to. They store all of the WinForms properties this way,
as well as the events.

Finally, they queue the
ThreadMethodEntry onto the queue and continue. They appear to do a
bunch of locking to make all of this thread-safe. While the Invoke
structure is a pain in the rear, I'm glad they reserve all of this
locking to a few select methods that handle all of the thread safe
operations.

Since this is an Invoke there is
additional code required to make sure the operation happens
synchronously. The ThreadMethodEntry implements IAsyncResult directly,
so on Invoke calls, we check to make sure it isn't already completed (a
call to IsCompleted), and if it isn't, we grab the AsyncWaitHandle and
do a WaitOne call. This will block our thread until the operation
completes and we can return our value. Why did we make a call to
IsCompleted first? Well, remember that call we made to
InvokeMarshaledCallbacks? Well, when we do that our operation will
already be complete once we get to that portion of the code. If we
didn't make this check and instead just started a WaitOne on the handle,
we'd hang indefinitely.

Once the operation either
completes or was already completed, we look for any exceptions. If
there are exceptions, we throw them. Here have some exceptions they say
;-) If no exceptions were thrown then we return a special return value
property stored on the ThreadMethodEntry. This value is set in
InvokeMarshaledCallbacks when we invoke the delegate.

If you are running off the UI
thread, how do things change? Well, we don't have the special same
thread operation involved this time, so instead we post a message to the
marshaling control. This is a special message that is constructed
using some internal properties and then registered using
RegisterWindowMessage. This ensures that all controls will use the same
message for this callback preventing us from register a bunch of custom
windows messages.

InvokeMarshaledCallbacks is an
important method since it gets called both synchronously if we are on
the same thread as the UI and from the WndProc in the case we aren't.
This is where all of the action of calling our delegate happens and so
it is where we'll be next.

5. InvokeMarshaledCallbacks and how it handles the callback queue
This
method is deep. Since it has to be thread safe, we get lots of locking
(even though we should only call this method from the UI thread, we
have to make sure we don't step on others that are accessing the queue
to add items, while we remove them). Note that this method will
continue processing the entire queue of delegates, and not just one.
Calling this method is very expensive, especially if you have a large
number of delegates queued up. You can start to better understand the
performance possibilities of asynchronous programming and how you should
avoid queuing up multiple delegates that are going to do the same thing
(hum, maybe that IAsyncResult will come in handy after all ;-)

We start by grabbing the
delegate queue and grabbing a start entry. Then we start up a loop to
process all of the entries. Each time through the loop the current
delegate entry gets updated and as soon as we run out of elements, the
loop exits. If you were to start an asynchronous delegate from inside
of another asynchronous delegate, you could probably hang your system
because of the way this queue works. So you should be careful.

The top of the loop does work
with the stack. We grab the current stack so we can restore it later,
then set the compressed stack that was saved onto the
ThreadMethodEntry. That'll ensure our security model is in place. Then
we run the delegate. There are some defaults. For instance, if the
type is MethodInvoker, we cast it and call it using a method that yields
better performance. If the method is of type EventHandler, then we
automatically set the parameters used to call the EventHandler. In this
case the sender will be the original caller, and the EventArgs will be
EventArgs.Empty. This is pretty sweet, since it simplifies calling
EventHandler definitions. It also means we can't change the sender or
target of an EventHandler definition, so you have to be careful.

If the delegate isn't of one of
the two special types then we do a DynamicInvoke on it. This is a
special method on all delegates and we simply pass in our argument
array. The return value is stored on our ThreadMethodEntry and we
continue. The only special case is that of an exception. If an
exception is thrown, we store the exception on the ThreadMethodEntry and
continue.

Exiting our delegate calling
code, we reset the stack frame to the saved stack frame. We then call
Complete on our ThreadMethodEntry to signal anybody waiting for it to
finish. If we are running asynchronously and there were exceptions we
call Application.OnThreadException(). You may have noticed these
exceptions happening in the background when you call BeginInvoke in your
application, and this is where they come from. With all of that
complete, we are done. That concludes all of the code required to
understand an Invoke call, but we still have some other cases for
BeginInvoke, so let's look at those.

6. BeginInvoke operation on the UI thread and from a different thread
How
much different is BeginInvoke from the basic Invoke paradigm? Well,
not much. There are only a couple of notes, so I don't take a bunch of
your time redefining all of the logic we already discussed. The first
change is how we call MarshaledInvoke. Instead of specifying true for
running synchronously we instead specify false. There is also no
special case for running synchronously on the UI thread, instead we
always post a message to the windows pump. Finally, rather than having
synchronization code on the ThreadMethodEntry, we return it immediately
as an IAsyncResult that can be used to determine when the method has
completed later or with EndInvoke.

That is where all of the new
logic is, EndInvoke. You see, we need additional logic for retrieving
the result of the operation and making sure it is completed. EndInvoke
can be a blocking operation if IsCompleted is not already true on the
IAsyncResult. So basically, we do a bunch of checks to make sure the
IAsyncResult passed in really is a ThreadMethodEntry. If it is, and it
hasn't completed, we do the same synchronization logic we did on the
Invoke version, with some small changes. First, we try to do an
InvokeMarshaledCallbacks if we are on the same thread. This is similar
to the same thread synchronization we did in the first case. If we
aren't on the same thread, then we wait on the AsyncWaitHandle. They
have some code that is dangerously close to looking like a race
condition here, but I think they've properly instrumented everything to
prevent that scenario.

As we fall through all of the
synchronization we again check for exceptions. Just like with Invoke we
throw them if we have them. A lot of people don't catch these
exceptions or assume they won't happen, so a lot of asynchronous code
tends to fail. Catch your exceptions people ;-) If no exceptions were
thrown then we return the value from the delegate and everything is
done.

You see, not many changes are
required in order to implement BeginInvoke over top of the same code we
used in Invoke. We've already covered the changes in
InvokeMarshaledCallbacks, so we appear to be complete. Time for a
sample.

7. UCS 3: Using BeginInvoke to change a property after other events are processed, and why it can fail
Sometimes
events in Windows Forms can transpire against you. The classic example
I use to explain this process is the AfterNodeSelect event of the
TreeView control. I generally use this event in order to update a
ListBox or other control somewhere on the form, and often you want to
transfer focus to a new control, probably the ListBox. If you try to
set the Focus within the event handler, then later on when the TreeView
gets control back after the event, it sets the Focus right back to
itself. You feel like nothing happened, even though it did.

You can easily fix this by using
a BeginInvoke to set focus instead. We'll call Focus directly so we
need to define a new delegate. We'll call it a BoolMethodInvoker since
Focus() returns a bool, we can't just use the basic MethodInvoker
delegate (what a shame eh?)



Now, knowing a bit about how the BeginInvoke stuff works,
there is a way to screw yourself over. First, your method may get
executed VERY soon. As a matter of fact, the next message on the pump
might be a marshalling message, and then other messages in the pump that
you wanted to go after might still be executed after you. In many
cases your method calls will still generate even more messages so this
can be circumvented a bit, but possibly not.

There is a second issue as well. If another code source
calls an Invoke and you are on the UI thread, then your method may get
processed even before the event handlers are done executing and the
TreeView gets control back to make it's focus call. This is an edge
case, but you can imagine you might run into scenarios where you want
some asynchronous operations and some synchronous. You need to be aware
than any synchronous call can possibly affect your asynchronous calls
and cause them to be processed.

8. Public and Internal Methods covered with a short description of what they do
These
are all of the public and internal methods that we covered and what
they do. Kind of a quick reference. I'll probably find this very
helpful later when I'm trying to derive some new functionality and I
don't want to have to read my entire article.

InvokeRequired - Finds the most
appropriate control and uses the handle of that control to get the
thread id that created it. If this thread id is different than the
thread id of the current thread then an invoke is required, else it is
not. This method uses a number of internal methods to solve the issue
of the most appropriate control.

Invoke - This method sets up a brand new
synchronous marshalled delegate. The delegate is marshalled to the UI
thread while your thread waits for the return value.

BeginInvoke - This method sets up a
brand new asynchronous marshalled delegate. The delegate is marshalled
to the UI thread while your thread continues to operate. An extended
usage of this method allows you to continue working on the UI thread and
then yield execution to the message pump allowing the delegate to be
called.

EndInvoke - This method allows you to
retrieve the return value of a delegate run by the BeginInvoke call. If
the delegate hasn't returned yet, EndInvoke will hang until it does.
If the delegate is alread complete, then the return value is retrieved
immediately.

MarshaledInvoke - This method queues up
marshaling actions for both the Invoke and BeginInvoke layers.
Depending on the circumstances this method can either immediately
execute the delegates (running on the same thread) or send a message
into the message pump. It also handles wait actions during the Invoke
process or returns an IAsyncResult for use in BeginInvoke.

InvokeMarshaledCallbacks - This method
is where all of your delegates get run. This method is either called
from MarshaledInvoke or WndProc depending on the circumstances. Once
inside of this method, the entire queue of delegates is run through and
all events are signalled allowing any blocking calls to operate (Invoke
or EndInvoke calls) and setting all IAsyncResult objects to the
IsCompleted = true state. This method also handles exception logic
allowing exceptions to be thrown back on the original thread for Invoke
calls or tossed into the applications thread exception layer if you are
using BeginInvoke and were running asynchronous delegates.

FindMarshallingControl - Walks the
control tree from current back up the control hierarchy until a valid
control is found for purposes of finding the UI thread id. If the
control hierarchy doesn't contain a control with a valid handle, then a
special parking window is retrieved. This method is used by many of the
other methods since a marshalling control is the first step in
marshalling a delegate to the UI thread.

Application.GetParkingWindow - This
method takes a control and finds the marking window for it. If the
control has a valid handle then the thread id of the control is found,
the ThreadContext for that thread is retreived, and the parking window
is returned. If the control does not have a valid handle then the
ThreadContext of the current thread is retrieved and the parking window
is returned. If no context is found (really shouldn't happen) null is
returned.

ThreadContext.FromId - This method takes
a thread id and indexes a special hash to find the context for the
given thread. If one doesn't exist then a new ThreadContext is created
and returned in it's place.

ThreadContext.FromCurrent - This method
grabs the current ThreadContext out of thread local storage. I'm
guessing this must be faster than getting the current thread id and
indexing the context hash, else why would they use thread local storage
at all?

ThreadContext..ctor() - This is the most
confusing IL to examine, but it appears the constructor does some self
registration into a context hash that the other methods use to get the
context for a given thread. They wind up using some of the Thread
methods, namely SetData, to register things into thread local storage.
Why they use thread local storage and a context hash indexed by thread
ID, I'm just not sure.

9. Conclusion
You've
learned quite a bit about the Windows Forms marshalling pump today and
how it handles all of the various methods of cross thread marshalling.
You've also gotten a peak deeper into the Windows Forms source through a
very detailed IL inspection. I've come up with some derived concepts
based on this whole process, so maybe these will lead into some even
more compelling articles. Even more importantly, we've learned how the
process can break down if we are expecting a specific order of events.

I had never fully examined this code
before, so even I was surprised at some of what I found. For instance,
the performance implications of calling the same method multiple times
asynchronously might be something that should be considered. Knowing
that all delegates will be processed in a tight loop is pretty huge and
that items can be queued while others are being dequeued (aka you can
hang yourself). Finally, the realization that if you use an
EventHandler type, you can't pass in the sender explicitly might lead to
confusion for some folks. After all, if you mock up an arguments array
and pass it to Invoke or BeginInvoke you would expect it to be used.