Walkthrough: Multithreading

Article
11/18/2006

This walkthrough demonstrates how to create a multithreaded application that searches a text file for occurrences of a word. It demonstrates:

Defining a class with a method that can be called by the BackgroundWorker component.
Handling events raised by the BackgroundWorker component.
Starting a BackgroundWorker component to run a method.
Implementing a Cancel button that stops the BackgroundWorker component.

To build the code example for this topic

Open a new Visual Basic Windows Application project, and create a form named Form1.
Add two buttons and four text boxes to Form1.

Name the objects as shown in the following table.

Object	Property	Setting
First button	Name, Text	Start, Start
Second button	Name, Text	Cancel, Cancel
First text box	Name, Text	SourceFile, ""
Second text box	Name, Text	CompareString, ""
Third text box	Name, Text	WordsCounted, "0"
Fourth text box	Name, Text	LinesCounted, "0"

Add a label next to each text box. Set the Text property for each label as shown in the following table.

Object Property Setting

First label

Text

Source File

Second label

Text

Compare String

Third label

Text

Matching Words

Fourth label

Text

Lines Counted
Add a BackgroundWorker component from the Components section of the ToolBox to your form. It will appear in the form's component tray.
Set the following properties for the BackgroundWorker1 object.

Property Setting

WorkerReportsProgress

True

WorkerSupportsCancellation

True

Object	Property	Setting
First label	Text	Source File
Second label	Text	Compare String
Third label	Text	Matching Words
Fourth label	Text	Lines Counted

Property	Setting
WorkerReportsProgress	True
WorkerSupportsCancellation	True

To define the method that will run on a separate thread

From the Project menu, choose Add Class to add a class to the project. The Add New Item dialog box is displayed.
Select Class from the templates window and type Words.vb in the name field.
Click Add. The Words class is displayed.

Add an Option Compare statement to the top of the Words class, above the Class statement:

Option Compare Text ' Case insensitive search.
' Use Option Compare Binary for case sensitive search.

Add the following code to the Words class:

Public Class Words
    ' Object to store the current state, for passing to the caller.
    Public Class CurrentState
        Public LinesCounted As Integer
        Public WordsMatched As Integer
    End Class

    Public SourceFile As String
    Public CompareString As String
    Private WordCount As Integer = 0
    Private LinesCounted As Integer = 0

    Public Sub CountWords( _
        ByVal worker As System.ComponentModel.BackgroundWorker, _
        ByVal e As System.ComponentModel.DoWorkEventArgs _
    )
        ' Initialize the variables.
        Dim mystream As System.IO.StreamReader = Nothing
        Dim line As String = ""

        If CompareString Is Nothing Or _
                CompareString = System.String.Empty Then
            Throw New Exception("CompareString not specified.")
        End If

        Try
            ' Open a new stream.
            mystream = My.Computer.FileSystem.OpenTextFileReader(SourceFile)
            ' Do until the stream returns Nothing at end of file.
            Do Until line Is Nothing
                If worker.CancellationPending Then
                    e.Cancel = True
                    Exit Do
                Else
                    line = mystream.ReadLine
                    WordCount += CountInString(line, CompareString)
                    LinesCounted += 1 ' Increment line count.

                    ' Raise an event so the form can monitor progress.
                    Dim state As New CurrentState
                    state.LinesCounted = LinesCounted
                    state.WordsMatched = WordCount
                    worker.ReportProgress(0, state)
                End If
            Loop
        Finally
            If mystream IsNot Nothing Then
                ' Close the file.
                mystream.Close()
            End If
        End Try
    End Sub

    Private Function CountInString( _
        ByVal SourceString As String, _
        ByVal CompareString As String _
    ) As Integer
        ' This function counts the number of times
        ' a word is found in a line.
        If SourceString Is Nothing Then
            Return 0
        End If

        Dim regex As New System.Text.RegularExpressions.Regex( _
            System.Text.RegularExpressions.Regex.Escape(CompareString))
        Dim matches As System.Text.RegularExpressions.MatchCollection
        matches = regex.Matches(SourceString)
        Return matches.Count
    End Function
End Class

To handle events from the thread

Add the following event handlers to your main form:

Private Sub BackgroundWorker1_RunWorkerCompleted( _
    ByVal sender As Object, _
    ByVal e As System.ComponentModel.RunWorkerCompletedEventArgs) _
    Handles BackgroundWorker1.RunWorkerCompleted

    ' This event handler is called when the background thread finishes.
    ' This method runs on the main thread.

    If e.Error IsNot Nothing Then
        MsgBox("Error: " & e.Error.Message)
    ElseIf e.Cancelled Then
        MsgBox("Word counting canceled.")
    Else
        MsgBox("Finished counting words.")
    End If
End Sub

Private Sub BackgroundWorker1_ProgressChanged( _
    ByVal sender As Object, _
    ByVal e As System.ComponentModel.ProgressChangedEventArgs) _
    Handles BackgroundWorker1.ProgressChanged

    ' This event handler is called after the background thread
    ' reads a line from the source file.
    ' This method runs on the main thread.

    Dim state As Words.CurrentState = _
        CType(e.UserState, Words.CurrentState)
    Me.LinesCounted.Text = state.LinesCounted.ToString
    Me.WordsCounted.Text = state.WordsMatched.ToString
End Sub

To start and call a new thread that runs the WordCount method

Add the following procedures to your program:

Private Sub BackgroundWorker1_DoWork( _
    ByVal sender As Object, _
    ByVal e As System.ComponentModel.DoWorkEventArgs) _
    Handles BackgroundWorker1.DoWork

    ' This event handler is where the actual work is done.
    ' This method runs on the background thread.

    ' Get the BackgroundWorker object that raised this event.
    Dim worker As System.ComponentModel.BackgroundWorker
    worker = CType(sender, System.ComponentModel.BackgroundWorker)

    ' Get the Works object and call the main method.
    Dim WC As Words = CType(e.Argument, Words)
    WC.CountWords(worker, e)
End Sub

Sub StartThread()
    ' This method runs on the main thread.

    Me.WordsCounted.Text = "0"

    ' Initialize the object that the background worker calls.
    Dim WC As New Words
    WC.CompareString = Me.CompareString.Text
    WC.SourceFile = Me.SourceFile.Text

    ' Start the asynchronous operation.
    BackgroundWorker1.RunWorkerAsync(WC)
End Sub

Call the StartThread method from the Start button on your form:

Private Sub Start_Click( _
    ByVal sender As System.Object, _
    ByVal e As System.EventArgs) _
    Handles Start.Click

    StartThread()
End Sub

To implement a Cancel button that stops the thread

Call the StopThread procedure from the Click event handler for the Cancel button.

Private Sub Cancel_Click( _
    ByVal sender As System.Object, _
    ByVal e As System.EventArgs) _
    Handles Cancel.Click

    ' Cancel the asynchronous operation.
    Me.BackgroundWorker1.CancelAsync()
End Sub

Testing

You can now test the application to make sure it works correctly.

To test the application

Press F5 to run the application.
When the form is displayed, enter the file path for the file you want to test in the sourceFile box. For example, assuming your test file is named Test.txt, enter C:\Test.txt.
In the second text box, enter a word or phrase for the application to search for in the text file.
Click the Start button. The LinesCounted button should begin incrementing immediately. The application displays the message "Finished Counting" when it is done.

To test the Cancel button

Press F5 to start the application, and enter the file name and search word as described in the previous procedure. Make sure that the file you choose is large enough to ensure you will have time to cancel the procedure before it is finished.
Click the Start button to start the application.
Click the Cancel button. The application should stop counting immediately.

Next Steps

This application contains some basic error handling. It detects blank search strings. You can make this program more robust by handling other errors, such as exceeding the maximum number of words or lines that can be counted.

Share via