Accessing Controls from Worker Threads

[jmcilhinney]

C# version here.

While it is legal to access a control from threads other than the one it was created on, it is simply not a good idea. From VS 2005 onwards it is not allowed while debugging by default. Any call that accesses a control's Handle on a thread that does not own that handle will either fail or behave other than as expected. The way to safely access controls from worker threads is via delegation.

First you test the InvokeRequired property of the control, which will tell you whether or not you can safely access the control. InvokeRequired is one of the few members of the Control class that is thread-safe, so you can access it anywhere. If the property is True then an invocation is required to access the control because the current method is executing on a thread other than the one that owns the control's Handle.

The invocation is performed by calling the control's Invoke or BeginInvoke method. You create a delegate, which is an object that contains a reference to a method. It is good practice to make that a reference to the current method. You then pass that delegate to the Invoke or BeginInvoke method. That will essentially call the referenced method again, this time on the thread that owns the control's Handle.

So, the first step is to identify the control member you want to access. For a first example, let's use the ResetText method of a TextBox. That's nice and simple because there are no parameters and no return value. When starting out you can build up your solution in stages. The first stage is to write a simple method that accesses your control member as desired:

Private Sub ResetTextBoxText()
    Me.TextBox1.ResetText()
End Sub

Nice and easy. Ordinarily you could simply call that method and it would do what you wanted: reset the TextBox's Text property.

Now, the next stage is to test the control's InvokeRequired property and place the existing method body in the Else block:

Private Sub ResetTextBoxText()
    If Me.TextBox1.InvokeRequired Then
 
    Else
        Me.TextBox1.ResetText()
    End If
End Sub

That now says that if an invocation is NOT required we can access the control member directly.

The next stage is to create the delegate and use it to invoke the current method on the appropriate thread. As I said, our method has no parameters and no return value so it's nice and easy. In that case you can create an instance of the existing MethodInvoker delegate:

Private Sub ResetTextBoxText()
    If Me.TextBox1.InvokeRequired Then
        Me.TextBox1.Invoke(New MethodInvoker(AddressOf ResetTextBoxText))
    Else
        Me.TextBox1.ResetText()
    End If
End Sub

If an invocation is required, this creates a MethodInvoker delegate and passes it a reference to the current method. That delegate is then passed to the control's Invoke method, which carries it across the thread boundary to the thread that owns the control's Handle and invokes it. To invoke a delegate means to execute the method it has a reference to.

So now you can simply call that method from any thread you like and rest assured that if you're not on the correct thread that the method itself will handle it for you. To see this in action, try creating a new project and add a Button and a TextBox to the form along with a BackgroundWorker. Now add the following code:

Private Sub Form1_Load(ByVal sender As System.Object, _
                       ByVal e As System.EventArgs) Handles MyBase.Load
    Threading.Thread.CurrentThread.Name = "UI Thread"
End Sub

Private Sub Button1_Click(ByVal sender As System.Object, _
                          ByVal e As System.EventArgs) Handles Button1.Click
    Me.ResetTextBoxText()

    Me.BackgroundWorker1.RunWorkerAsync()
End Sub

Private Sub BackgroundWorker1_DoWork(ByVal sender As Object, _
                                     ByVal e As System.ComponentModel.DoWorkEventArgs) Handles BackgroundWorker1.DoWork
    Threading.Thread.CurrentThread.Name = "Worker Thread"

    Me.ResetTextBoxText()
End Sub

Private Sub ResetTextBoxText()
    Debug.WriteLine(Threading.Thread.CurrentThread.Name, "ResetTextBoxText")

    If Me.TextBox1.InvokeRequired Then
        Me.TextBox1.Invoke(New MethodInvoker(AddressOf ResetTextBoxText))
    Else
        Me.TextBox1.ResetText()
    End If
End Sub

Now run the program, click the Button and watch the Output window. You'll see that the ResetTextBoxText method is executed three times. The first time is in the UI thread when it's called from the Button's Click event handler. The second time is in the worker thread when it's called from the DoWork event handler. The third time is in the UI thread again, when it's invoked via the delegate.

EDIT: I should also point out the difference between Invoke and BeginInvoke. Invoke is a synchronous method. That means that when you call it the background thread will block until the method invoked on the UI thread completes. BeginInvoke is asynchronous, so it will return immediately and the background thread will continue on its way while the method invoked on the UI thread executes.

[jmcilhinney]

To invoke a method via a delegate, the delegate must have the same signature as the method. The example in the first post invokes a method that has no parameters and no return value. In that case you can use the existing MethodInvoker delegate. If you need to specify one or more parameters or get a return value though, you will have to declare your own delegate type.

Let's say that you want to set the Text property of a TextBox from a worker thread. From the first post we know the first step is to declare a method that does what we want:

Private Sub SetTextBoxText(ByVal text As String)
    Me.TextBox1.Text = text
End Sub

Now, that method has a parameter so we cannot use the MethodInvoker delegate. We must declare our own delegate type with the same signature. The signature is basically the parameter list and the return type. To create your delegate declaration you should copy the method declaration:

Private Sub SetTextBoxText(ByVal text As String)

then add the 'Delegate' key word:

Private Delegate Sub SetTextBoxText(ByVal text As String)

and finally change the name:

Private Delegate Sub SetTextBoxTextInvoker(ByVal text As String)

Now that we have declared our new delegate type we can create instances of it just as we did with the MethodInvoker.

The next step from above was to add a test for the InvokeRequired property of our control:

Private Sub SetTextBoxText(ByVal text As String)
    If Me.TextBox1.InvokeRequired Then
 
    Else
        Me.TextBox1.Text = text
    End If
End Sub

Finally we call the control's Invoke method and pass our delegate:

Private Sub SetTextBoxText(ByVal text As String)
    If Me.TextBox1.InvokeRequired Then
        Me.TextBox1.Invoke(New SetTextBoxTextInvoker(AddressOf SetTextBoxText), _
                           text)
    Else
        Me.TextBox1.Text = text
    End If
End Sub

Notice that, while last time the only parameter passed to the Invoke method was the delegate, this time we pass the 'text' value as well. Any parameters passed to Invoke after the delegate will then be passed again to the method that gets invoked by the delegate. Our delegate will be invoking the SetTextBoxText method, which requires a 'text' parameter. That code gets the 'text' value passed in to the first call and propagates it to the second call via the Invoke method and the delegate.

The above example passes a single parameter but the very same mechanism can be used to pass multiple parameters. Here's a similar example that can be used to set the Text property of any control:

Private Delegate Sub SetControlTextInvoker(ByVal ctl As Control, ByVal text As String)
 
Private Sub SetControlText(ByVal ctl As Control, ByVal text As String)
    If ctl.InvokeRequired Then
        ctl.Invoke(New SetControlTextInvoker(AddressOf SetControlText), _
                   ctl, _
                   text)
    Else
        ctl.Text = text
    End If
End Sub

Pass in the control and the text and the method handles the rest. It tests the InvokeRequired property and calls the Invoke method of the appropriate control, then sets the Text property of that same control.


EDIT: A note for those using .NET 1.x. The Control.Invoke method signature changed in .NET 2.0 to accept any number of individual parameters. Previous versions required any parameters to be passed within an array. That means that while this is fine in .NET 2.0 and above:

ctl.Invoke(New SetControlTextInvoker(AddressOf SetControlText), _
           ctl, _
           text)

you would have to do this in .NET 1.x:

ctl.Invoke(New SetControlTextInvoker(AddressOf SetControlText), _
           New Object() {ctl, _
                         text})

[jmcilhinney]

Getting a return value is no more difficult. One thing I haven't mentioned is that the Invoke method is a function. If the method invoked by the delegate returns a value then that is propagated by the Invoke method. Let's use an example of getting the Text property of a TextBox. Following the steps laid out already we first create a method to do the job:

Private Function GetTextBoxText() As String
    Return Me.TextBox1.Text
End Function

Next we declare a matching delegate:

Private Delegate Function GetTextBoxTextInvoker() As String
 
Private Function GetTextBoxText() As String
    Return Me.TextBox1.Text
End Function

After that we test the InvokeRequired property:

Private Delegate Function GetTextBoxTextInvoker() As String
 
Private Function GetTextBoxText() As String
    If Me.TextBox1.InvokeRequired Then
 
    Else
        Return Me.TextBox1.Text
    End If
End Function

Finally we call the Invoke method and pass an instance of our delegate:

Private Delegate Function GetTextBoxTextInvoker() As String
 
Private Function GetTextBoxText() As String
    If Me.TextBox1.InvokeRequired Then
        Return CStr(Me.TextBox1.Invoke(New GetTextBoxTextInvoker(AddressOf GetTextBoxText)))
    Else
        Return Me.TextBox1.Text
    End If
End Function

Let's clean that up a little so we only have one Return statement, which is widely considered to be best practice:

Private Delegate Function GetTextBoxTextInvoker() As String
 
Private Function GetTextBoxText() As String
    Dim text As String
 
    If Me.TextBox1.InvokeRequired Then
        text = CStr(Me.TextBox1.Invoke(New GetTextBoxTextInvoker(AddressOf GetTextBoxText)))
    Else
        text = Me.TextBox1.Text
    End If
 
    Return text
End Function

Notice that in this case we are actually returning the result of the Invoke method, which is the same value as was returned by the method that was invoked. This is how you get a value back onto your worker thread from the UI thread.

Notice also that the return value from the invoke method must be cast as the appropriate type. Invoke can be used to invoke any method at all, so it could return any value at all. That means that its actual return type is Object. You must therefore cast each returned object as its actual type.

Now to show that this method can be generalised to any control too, as well as combine the passing of parameters and returning a value, here's an extended example based on what we've already seen:

Private Delegate Function GetControlTextInvoker(ByVal ctl As Control) As String
 
Private Function GetControlText(ByVal ctl As Control) As String
    Dim text As String
 
    If ctl.InvokeRequired Then
        text = CStr(ctl.Invoke(New GetControlTextInvoker(AddressOf GetControlText), _
                               ctl))
    Else
        text = ctl.Text
    End If
 
    Return text
End Function

[JuggaloBrotha]

This is a far better explanation than anything else I've seen

Thanks JM

[TheUsed]

JM is, so far, the most detailed individual who offers help to those in need of something... so he's not only giving you the answer to your problem, but is in fact giving you the explanation of why it happened and what not..

thank you JM

note: all you other individuals who help, you all do a great job, keep it up.

[scootabug]

Are there any tricks in getting the Debug output?

I've got the output window open, tried enabling the other options than just 'Program Output' (which seems to be all i really need anyway) and 'Exception Messages'. I also tried changing the code from Debug.WriteLine to Debug.Write etc but didn't make any difference. *Sigh!*

Any tips?

[chris128]

I've always wondered how you were supposed to do this 'properly' ... now I know Thanks jmc

EDIT: to the person who posted above me - has that actually got anything at all to do with this thread? You would almost certainly be better off posting in the VB.NET forum.

[scootabug]

If you know that an invoke will always be required in accessing your control from a worker thread, suggesting that the function you're calling is only used by your worker thread, is it a 'safe option' to call the delegate directly without going via the 'real' function?

I'm not sure if that makes sense, so using the following code as an example:

Private Delegate Function GetTextBoxTextInvoker() As String
 
    Private Function GetTextBoxText() As String
        If Me.TextBox1.InvokeRequired Then
            Return CStr(Me.TextBox1.Invoke(New GetTextBoxTextInvoker(AddressOf GetTextBoxText)))
        Else
            Return Me.TextBox1.Text
        End If
    End Function

Rather than calling GetTextBoxText() from your worker thread, and it invoking itself via the delegate function GetTextBoxTextInvoker()...can you safely call GetTextBoxTextInvoker() from your worker thread instead and 'cut out the middle man'?

To me it saves a few lines of code being executed for no apparent reason, and I say 'no apparent reason' because I'm not sure if there's another reason to do so...and this is the basis of my question.

I'm happy to be wrong, and I've tested this, and it works, but I'm just wondering if there's a 'gotcha' in here somewhere.

[jmcilhinney]

If you know that an invoke will always be required in accessing your control from a worker thread, suggesting that the function you're calling is only used by your worker thread, is it a 'safe option' to call the delegate directly without going via the 'real' function?

I'm not sure if that makes sense, so using the following code as an example:

Private Delegate Function GetTextBoxTextInvoker() As String
 
    Private Function GetTextBoxText() As String
        If Me.TextBox1.InvokeRequired Then
            Return CStr(Me.TextBox1.Invoke(New GetTextBoxTextInvoker(AddressOf GetTextBoxText)))
        Else
            Return Me.TextBox1.Text
        End If
    End Function

Rather than calling GetTextBoxText() from your worker thread, and it invoking itself via the delegate function GetTextBoxTextInvoker()...can you safely call GetTextBoxTextInvoker() from your worker thread instead and 'cut out the middle man'?

To me it saves a few lines of code being executed for no apparent reason, and I say 'no apparent reason' because I'm not sure if there's another reason to do so...and this is the basis of my question.

I'm happy to be wrong, and I've tested this, and it works, but I'm just wondering if there's a 'gotcha' in here somewhere.

Yes, you certainly can do that. For instance, if you wanted to append text to a TextBox then you could forgo the "middleman" and just create a delegate to invoke the AppendText method of the TextBox directly. If you are accessing a property rather than a method, or you're accessing multiple members, then you're still going to need to write a method that you can invoke on the UI thread though. I prefer to stick to the pattern I've demonstrated for clarity and consistency. If you always do this the same way and all the threading-specific code is always in the one method then it's always clear exactly what you're doing.

[scootabug]

Great, thanks!

[masfenix]

scoota, I dont seem to understand what your talking about. Mind to give an example where you cut out the 'middle' man?

Learning purposes only! Thanks

[jmcilhinney]

scoota, I dont seem to understand what your talking about. Mind to give an example where you cut out the 'middle' man?

Learning purposes only! Thanks

If you want to append text to a TextBox then, by my pattern, you'd do this:

Private Delegate Sub AppendTextToTextBoxInvoker(ByVal text As String)
 
Private Sub AppendTextToTextBox(ByVal text As String)
    If Me.TextBox1.InvokeRequired Then
        Me.TextBox1.Invoke(New AppendTextToTextBoxInvoker(AddressOf AppendTextToTextBox), text)
    Else
        Me.TextBox1.AppendText(text)
    End If
End Sub

and then somewhere in your background thread you'd do this:

Me.AppendTextToTextBox(someString)

By cutting out the middle man we mean removing the need for the AppendTextToTextBox method. Instead of that last line calling AppendTextToTextBox and it invoking itself, you can just invoke the TextBox's AppendText method directly:

Me.TextBox1.Invoke(New AppendTextToTextBoxInvoker(AddressOf Me.TextBox1.AppendText), someString)

I like the pattern I've described because, hopefully, it makes it clear to those who might not understand the process exactly what's happening. As you get more comfortable with multi-threading then it becomes easier to take "shortcuts". As is the case in so many situations, it's best to lay down and learn the rules first, then learn where and when it's OK to break the rules later.

[masfenix]

Thankyou! I cant even imagine doing this on something like C/C++. Hehe you'd have to code like 50 lines just to acomplish a single task.

[sebex]

This doesn't work for LIstboxes or Comboxes because it doesn't pass the selected index. How can I accomplish that?

[jmcilhinney]

This doesn't work for LIstboxes or Comboxes because it doesn't pass the selected index. How can I accomplish that?

Um, yes it does. The SelectedIndex is just a number and I've shown you how to pass data in both directions using this technique. Post #2 shows you how to pass data from the background thread to the UI thread. Post #3 shows you how to return data from the UI thread to the background thread. Think about it. Post #3 uses a method named GetTextBoxText to get the Text of a TextBox. Does that really sound all that different to getting the SelectedIndex of a ListBox or ComboBox? You use the exact same pattern and just change the detail. A logical name for the method would be GetListControlSelectedIndex. That should make it obvious what needs changing.

Note that ListControl is the base class of both the ListBox and the ComboBox from which they both inherit the SelectedIndex property, so you can create a single method that will work for both, or you can write specific methods if you prefer.

[jmcilhinney]

Here's the last example from post #1 redone for WPF:

Private WithEvents worker As New BackgroundWorker
 
Private Sub Window1_Loaded(ByVal sender As Object, _
                           ByVal e As RoutedEventArgs) Handles MyBase.Loaded
    Thread.CurrentThread.Name = "UI Thread"
End Sub
 
Private Sub Button1_Click(ByVal sender As Object, _
                          ByVal e As RoutedEventArgs) Handles Button1.Click
    Me.ResetTextBoxText()
 
    Me.worker.RunWorkerAsync()
End Sub
 
Private Sub BackgroundWorker1_DoWork(ByVal sender As Object, _
                                     ByVal e As DoWorkEventArgs) Handles worker.DoWork
    Thread.CurrentThread.Name = "Worker Thread"
 
    Me.ResetTextBoxText()
End Sub
 
Private Sub ResetTextBoxText()
    Debug.WriteLine(Thread.CurrentThread.Name, "ResetTextBoxText")
 
    If Me.TextBox1.Dispatcher.CheckAccess() Then
        Me.TextBox1.Clear()
    Else
        Me.TextBox1.Dispatcher.Invoke(New Action(AddressOf ResetTextBoxText))
    End If
End Sub

[jmcilhinney]

Here's the last example from post #1 reworked to use a SynchronizationContext:

Private context As Threading.SynchronizationContext = Threading.SynchronizationContext.Current
 
Private Sub Form1_Load(ByVal sender As System.Object, _
                       ByVal e As System.EventArgs) Handles MyBase.Load
    Threading.Thread.CurrentThread.Name = "UI Thread"
End Sub
 
Private Sub Button1_Click(ByVal sender As System.Object, _
                          ByVal e As System.EventArgs) Handles Button1.Click
    Me.context.Send(AddressOf Me.ResetTextBoxText, Nothing)
 
    Me.BackgroundWorker1.RunWorkerAsync()
End Sub
 
Private Sub BackgroundWorker1_DoWork(ByVal sender As Object, _
                                     ByVal e As System.ComponentModel.DoWorkEventArgs) Handles BackgroundWorker1.DoWork
    Threading.Thread.CurrentThread.Name = "Worker Thread"
 
    Me.context.Send(AddressOf Me.ResetTextBoxText, Nothing)
End Sub
 
Private Sub ResetTextBoxText(ByVal userState As Object)
    Debug.WriteLine(Threading.Thread.CurrentThread.Name, "ResetTextBoxText")
 
    Me.TextBox1.ResetText()
End Sub

Notice that, in this case, there's no need to check which thread you're on. If in doubt, you simply tell the SynchronizationContext to Send the method call to the appropriate thread, no matter what thread you're currently on. Note that Send is to Invoke as Post is to BeginInvoke, i.e. one is synchronous and one is asynchronous.

[weirddemon]

JMC, in regards to post #17, if you use that example as is, it isn't multi-threaded. Not from what I can tell. When it tries to reset the TextBox, I quickly try to press a different blank button and I can't because the UI thread is busy.

I launched a process and called waitforexit in the ResetTextBoxTest method to be definitive, and the UI was still not responsive.

Am I missing something?

[jmcilhinney]

JMC, in regards to post #17, if you use that example as is, it isn't multi-threaded. Not from what I can tell. When it tries to reset the TextBox, I quickly try to press a different blank button and I can't because the UI thread is busy.

I launched a process and called waitforexit in the ResetTextBoxTest method to be definitive, and the UI was still not responsive.

Am I missing something?

ResetTextBoxText is executed on the UI thread. It must be, because it's accessing a control directly. The whole purpose of this thread is how to deal with the fact that you can't access controls directly on anything but the UI thread.

In that example, it's the DoWork event handler of the BackgroundWorker that is executed on the background thread. That's the whole point of the BackgroundWorker: you call RunWorkerAsync and the DoWork event is raised on a background thread, where you do the work. It's the Send method of the SynchronizationContext that marshals the method call to the UI thread, instead of calling Invoke.

The BackgroundWorker also exists so that you don't have to worry about doing things like using a SynchronizationContext or ISynchronizeInvoke, but I just used it for simplicity in this example. Normally, if you need to update the UI when using a BackgroundWorker, you would use the ReportProgress method and ProgressChanged event and/or the RunWorkerCompleted event. I have another CodeBank thread that deals with that subject though.

[Starf0x]

Thank You Jim.

This/These examples are really great and explained nicely.
But what bothers me that VB doesn't have a delegate to do a lot controls in one go.
If you have/collect a lot of data from an bgworker, you have to split it all up to do each and every control in single steps.
Forces you to rethink everything.

Kind Regards, Starf0x

[jmcilhinney]

Thank You Jim.

This/These examples are really great and explained nicely.
But what bothers me that VB doesn't have a delegate to do a lot controls in one go.
If you have/collect a lot of data from an bgworker, you have to split it all up to do each and every control in single steps.
Forces you to rethink everything.

Kind Regards, Starf0x

You are looking at this in completely the wrong way. Delegates have nothing specific to do with controls. A delegate is simply a reference to a method. That's it, that's all. In these examples, I'm using the Invoke method of a control to marshal a delegate onto the UI thread. Once you are on the UI thread, you you can do anything you want. If you want to update a thousand controls then update a thousand controls. The delegate has nothing whatsoever to do with that.

Private Sub EnableEveryControl()
    If Me.InvokeRequired Then
        Me.Invoke(New MethodInvoker(AddressOf EnableEveryControl))
    Else
        For Each ctl In Me.Controls
            ctl.Enabled = True
        Next
    End If
End Sub

As you can see, this code uses the very same MethodInvoker delegate as I used in previous examples, yet the code is able to affect every control on the form, whether that is one or one million. The delegate has NOTHING to do with the controls. It is merely a means to invoke a method on the UI thread. What you do in that method is COMPLETELY up to you, as it always is.

[stateofidleness]

Wow JMC, I know i've posted a lot of "threading" questions recently, and this thread actually makes is so much clearer. Thanks for taking the time to write it up with such clarity!

[teguh123]

Also because the invoke happens on Main UI thread anyway, we don't need to do synclock right?>

[jmcilhinney]

Also because the invoke happens on Main UI thread anyway, we don't need to do synclock right?>

When using my pattern, whatever you execute inside the Else block is executed on the UI thread. As such, only one instance of that code can be executed at a time. That means that you don't need to synchronise that specific block of code to protect it from itself, but you may still have to protect against undesirable interactions with other blocks of code that may be executed on other threads.

[NickThissen]

Just wanted to mention I made an extension method that you can use to get and set properties from any control via this same method (except you don't have to type the delegate and invocation each time).
It can be found here:
http://www.vbforums.com/showthread.php?t=646484

[rkinci]

Very helpful. Thanks.