Creating Threads and Passing Data at Start Time

Article
11/03/2006

When an operating-system process is created, the operating system injects a thread to execute code in that process, including any original application domain. From that point on, application domains can be created and destroyed without any operating system threads necessarily being created or destroyed. If the code being executed is managed code, then a Thread object for the thread executing in the current application domain can be obtained by retrieving the static CurrentThread property of type Thread. This topic describes thread creation and discusses alternatives for passing data to the thread procedure.

Creating a Thread

Creating a new Thread object creates a new managed thread. The Thread class has constructors that take a ThreadStart delegate or a ParameterizedThreadStart delegate; the delegate wraps the method that is invoked by the new thread when you call the Start method. Calling Start more than once causes a ThreadStateException to be thrown.

The Start method returns immediately, often before the new thread has actually started. You can use the ThreadState and IsAlive properties to determine the state of the thread at any one moment, but these properties should never be used for synchronizing the activities of threads.

Note
Once a thread is started, it is not necessary to retain a reference to the Thread object. The thread continues to execute until the thread procedure ends.

The following code example creates two new threads to call instance and static methods on another object.

Imports System
Imports System.Threading

Public Class ServerClass

    ' The method that will be called when the thread is started.
    Public Sub InstanceMethod()
        Console.WriteLine( _
            "ServerClass.InstanceMethod is running on another thread.")

        ' Pause for a moment to provide a delay to make 
        ' threads more apparent.
        Thread.Sleep(3000) 
        Console.WriteLine( _
            "The instance method called by the worker thread has ended.")
    End Sub 'InstanceMethod

    Public Shared Sub StaticMethod()
        Console.WriteLine( _
            "ServerClass.StaticMethod is running on another thread.")

        ' Pause for a moment to provide a delay to make 
        ' threads more apparent.
        Thread.Sleep(5000) 
        Console.WriteLine( _
            "The static method called by the worker thread has ended.")
    End Sub 'StaticMethod
End Class 'ServerClass

Public Class Simple

    Public Shared Sub Main() 
        Console.WriteLine("Thread Simple Sample")

        Dim serverObject As New ServerClass()

        ' Create the thread object, passing in the 
        ' serverObject.InstanceMethod method using a
        ' ThreadStart delegate.
        Dim InstanceCaller As New Thread( _
            New ThreadStart(AddressOf serverObject.InstanceMethod))

        ' Start the thread.
        InstanceCaller.Start()

        Console.WriteLine("The Main() thread calls this after " _
            & "starting the new InstanceCaller thread.")

        ' Create the thread object, passing in the 
        ' serverObject.StaticMethod method using a 
        ' ThreadStart delegate.
        Dim StaticCaller As New Thread( _
            New ThreadStart(AddressOf ServerClass.StaticMethod))

        ' Start the thread.
        StaticCaller.Start()

        Console.WriteLine("The Main() thread calls this after " _
            & "starting the new StaticCaller thread.")

    End Sub 'Main
End Class 'Simple

using System;
using System.Threading;

public class ServerClass
{
    // The method that will be called when the thread is started.
    public void InstanceMethod()
    {
        Console.WriteLine(
            "ServerClass.InstanceMethod is running on another thread.");

        // Pause for a moment to provide a delay to make 
        // threads more apparent.
        Thread.Sleep(3000);
        Console.WriteLine(
            "The instance method called by the worker thread has ended.");
    }

    public static void StaticMethod()
    {
        Console.WriteLine(
            "ServerClass.StaticMethod is running on another thread.");

        // Pause for a moment to provide a delay to make 
        // threads more apparent.
        Thread.Sleep(5000);
        Console.WriteLine(
            "The static method called by the worker thread has ended.");
    }
}

public class Simple{
    public static int Main(String[] args)
    {
        Console.WriteLine("Thread Simple Sample");

        ServerClass serverObject = new ServerClass();

        // Create the thread object, passing in the 
        // serverObject.InstanceMethod method using a 
        // ThreadStart delegate.
        Thread InstanceCaller = new Thread(
            new ThreadStart(serverObject.InstanceMethod));

        // Start the thread.
        InstanceCaller.Start();

        Console.WriteLine("The Main() thread calls this after " 
            + "starting the new InstanceCaller thread.");

        // Create the thread object, passing in the 
        // serverObject.StaticMethod method using a 
        // ThreadStart delegate.
        Thread StaticCaller = new Thread(
            new ThreadStart(ServerClass.StaticMethod));

        // Start the thread.
        StaticCaller.Start();

        Console.WriteLine("The Main() thread calls this after "
            + "starting the new StaticCaller thread.");

        return 0;
    }
}

using namespace System;
using namespace System::Threading;

public ref class ServerClass
{
public:

    // The method that will be called when the thread is started.
    void InstanceMethod()
    {
        Console::WriteLine(
            "ServerClass->InstanceMethod is running on another thread.");

        // Pause for a moment to provide a delay to make 
        // threads more apparent.
        Thread::Sleep(3000);
        Console::WriteLine(
            "The instance method called by the worker thread has ended.");
    }

    static void StaticMethod()
    {
        Console::WriteLine(
            "ServerClass::StaticMethod is running on another thread.");

        // Pause for a moment to provide a delay to make 
        // threads more apparent.
        Thread::Sleep(5000);
        Console::WriteLine(
            "The static method called by the worker thread has ended.");
    }
};

void main()
{
    Console::WriteLine("Thread Simple Sample");

    ServerClass^ serverObject = gcnew ServerClass();

    // Create the thread object, passing in a ThreadStart delegate
    // representing an instance of ServerClass and the 
    // ServerClass::InstanceMethod method.
    Thread^ InstanceCaller = gcnew Thread(
        gcnew ThreadStart(serverObject, &ServerClass::InstanceMethod));

    // Start the thread.
    InstanceCaller->Start();

    Console::WriteLine("The main thread has " 
        + "started the new InstanceMethod thread.");

    // Create the thread object, passing in a ThreadStart delegate 
    // representing the static ServerClass::StaticMethod method.
    Thread^ StaticCaller = gcnew Thread(
        gcnew ThreadStart(&ServerClass::StaticMethod));

    // Start the thread.
    StaticCaller->Start();

    Console::WriteLine("The main thread has called "
        + "the new StaticMethod thread.");
}

Passing Data to Threads and Retrieving Data from Threads

In the .NET Framework version 2.0, the ParameterizedThreadStart delegate provides an easy way to pass an object containing data to a thread when you call the System.Threading.Thread.Start(System.Object) method overload. See ParameterizedThreadStart for a code example.

Using the ParameterizedThreadStart delegate is not a type-safe way to pass data, because the System.Threading.Thread.Start(System.Object) method overload accepts any object. An alternative is to encapsulate the thread procedure and the data in a helper class and use the ThreadStart delegate to execute the thread procedure. This technique is shown in the two code examples that follow.

Neither of these delegates has a return value, because there is no place to return the data from an asynchronous call. To retrieve the results of a thread method, you can use a callback method, as demonstrated in the second code example.

Imports System
Imports System.Threading

' The ThreadWithState class contains the information needed for
' a task, and the method that executes the task.
'
Public Class ThreadWithState
    ' State information used in the task.
    Private boilerplate As String
    Private value As Integer

    ' The constructor obtains the state information.
    Public Sub New(ByVal text As String, ByVal number As Integer)
        boilerplate = text
        value = number
    End Sub

    ' The thread procedure performs the task, such as formatting 
    ' and printing a document.
    Public Sub ThreadProc()
        Console.WriteLine(boilerplate, value) 
    End Sub
End Class

' Entry point for the example.
'
Public Class Example
    Public Shared Sub Main()

        ' Supply the state information required by the task.
        Dim tws As New ThreadWithState( _
            "This report displays the number {0}.", 42)

        ' Create a thread to execute the task, and then
        ' start the thread.
        Dim t As New Thread(AddressOf tws.ThreadProc)
        t.Start()
        Console.WriteLine("Main thread does some work, then waits.")
        t.Join()
        Console.WriteLine( _
            "Independent task has completed; main thread ends.")  
    End Sub
End Class

using System;
using System.Threading;

// The ThreadWithState class contains the information needed for
// a task, and the method that executes the task.
//
public class ThreadWithState {
    // State information used in the task.
    private string boilerplate;
    private int value;

    // The constructor obtains the state information.
    public ThreadWithState(string text, int number) 
    {
        boilerplate = text;
        value = number;
    }

    // The thread procedure performs the task, such as formatting 
    // and printing a document.
    public void ThreadProc() 
    {
        Console.WriteLine(boilerplate, value); 
    }
}

// Entry point for the example.
//
public class Example {
    public static void Main() 
    {
        // Supply the state information required by the task.
        ThreadWithState tws = new ThreadWithState(
            "This report displays the number {0}.", 42);

        // Create a thread to execute the task, and then
        // start the thread.
        Thread t = new Thread(new ThreadStart(tws.ThreadProc));
        t.Start();
        Console.WriteLine("Main thread does some work, then waits.");
        t.Join();
        Console.WriteLine(
            "Independent task has completed; main thread ends.");  
    }
}

using namespace System;
using namespace System::Threading;

// The ThreadWithState class contains the information needed for
// a task, and the method that executes the task.
//
public ref class ThreadWithState 
{
private:
    // State information used in the task.
    String^ boilerplate;
    int value;

public:
    // The constructor obtains the state information.
    ThreadWithState(String^ text, int number) 
    {
        boilerplate = text;
        value = number;
    }

    // The thread procedure performs the task, such as formatting 
    // and printing a document.
    void ThreadProc() 
    {
        Console::WriteLine(boilerplate, value); 
    }
};

// Entry point for the example.
//
void main() 
{
    // Supply the state information required by the task.
    ThreadWithState^ tws = gcnew ThreadWithState(
        "This report displays the number {0}.", 42);

    // Create a thread to execute the task, and then
    // start the thread.
    Thread^ t = gcnew Thread(
        gcnew ThreadStart(tws, &ThreadWithState::ThreadProc));
    t->Start();
    Console::WriteLine("Main thread does some work, then waits.");
    t->Join();
    Console::WriteLine(
        "Independent task has completed; main thread ends.");  
}

Retrieving Data with Callback Methods

The following example demonstrates a callback method that retrieves data from a thread. The constructor for the class that contains the data and the thread method also accepts a delegate representing the callback method; before the thread method ends, it invokes the callback delegate.

Imports System
Imports System.Threading

' The ThreadWithState class contains the information needed for
' a task, the method that executes the task, and a delegate
' to call when the task is complete.
'
Public Class ThreadWithState
    ' State information used in the task.
    Private boilerplate As String
    Private value As Integer

    ' Delegate used to execute the callback method when the
    ' task is complete.
    Private callback As ExampleCallback

    ' The constructor obtains the state information and the
    ' callback delegate.
    Public Sub New(ByVal text As String, ByVal number As Integer, _
                   ByVal callbackDelegate As ExampleCallback)
        boilerplate = text
        value = number
        callback = callbackDelegate
    End Sub

    ' The thread procedure performs the task, such as
    ' formatting and printing a document, and then invokes
    ' the callback delegate with the number of lines printed.
    Public Sub ThreadProc()
        Console.WriteLine(boilerplate, value) 
        If Not callback Is Nothing Then callback(1)
    End Sub
End Class

' Delegate that defines the signature for the callback method.
'
Public Delegate Sub ExampleCallback(ByVal lineCount As Integer)

' Entry point for the example.
'
Public Class Example
    Public Shared Sub Main()
        ' Supply the state information required by the task.
        Dim tws As New ThreadWithState( _
            "This report displays the number {0}.", _
            42, _
            New ExampleCallback(AddressOf ResultCallback) _
        )

        Dim t As New Thread(AddressOf tws.ThreadProc)
        t.Start()
        Console.WriteLine("Main thread does some work, then waits.")
        t.Join()
        Console.WriteLine( _
            "Independent task has completed; main thread ends.")  
    End Sub

    ' The callback method must match the signature of the
    ' callback delegate.
    '
    Public Shared Sub ResultCallback(ByVal lineCount As Integer)
        Console.WriteLine("Independent task printed {0} lines.", _
            lineCount)  
    End Sub
End Class

using System;
using System.Threading;

// The ThreadWithState class contains the information needed for
// a task, the method that executes the task, and a delegate
// to call when the task is complete.
//
public class ThreadWithState {
    // State information used in the task.
    private string boilerplate;
    private int value;

    // Delegate used to execute the callback method when the
    // task is complete.
    private ExampleCallback callback;

    // The constructor obtains the state information and the
    // callback delegate.
    public ThreadWithState(string text, int number, 
        ExampleCallback callbackDelegate) 
    {
        boilerplate = text;
        value = number;
        callback = callbackDelegate;
    }
    
    // The thread procedure performs the task, such as
    // formatting and printing a document, and then invokes
    // the callback delegate with the number of lines printed.
    public void ThreadProc() 
    {
        Console.WriteLine(boilerplate, value);
        if (callback != null)
            callback(1);
    }
}

// Delegate that defines the signature for the callback method.
//
public delegate void ExampleCallback(int lineCount);

// Entry point for the example.
//
public class Example 
{
    public static void Main() 
    {
        // Supply the state information required by the task.
        ThreadWithState tws = new ThreadWithState(
            "This report displays the number {0}.",
            42,
            new ExampleCallback(ResultCallback)
        );

        Thread t = new Thread(new ThreadStart(tws.ThreadProc));
        t.Start();
        Console.WriteLine("Main thread does some work, then waits.");
        t.Join();
        Console.WriteLine(
            "Independent task has completed; main thread ends."); 
    }

    // The callback method must match the signature of the
    // callback delegate.
    //
    public static void ResultCallback(int lineCount) 
    {
        Console.WriteLine(
            "Independent task printed {0} lines.", lineCount);
    }
}

using namespace System;
using namespace System::Threading;

// Delegate that defines the signature for the callback method.
//
public delegate void ExampleCallback(int lineCount);

// The ThreadWithState class contains the information needed for
// a task, the method that executes the task, and a delegate
// to call when the task is complete.
//
public ref class ThreadWithState 
{
private:
    // State information used in the task.
    String^ boilerplate;
    int value;

    // Delegate used to execute the callback method when the
    // task is complete.
    ExampleCallback^ callback;

public:
    // The constructor obtains the state information and the
    // callback delegate.
    ThreadWithState(String^ text, int number, 
        ExampleCallback^ callbackDelegate)  
    {
        boilerplate = text;
        value = number;
        callback = callbackDelegate;
    }

    // The thread procedure performs the task, such as
    // formatting and printing a document, and then invokes
    // the callback delegate with the number of lines printed.
    void ThreadProc() 
    {
        Console::WriteLine(boilerplate, value); 
        if (callback != nullptr)
            callback(1);
    }
};

public ref class Example
{
public:
    static void Demo()
    {
        // Supply the state information required by the task.
        ThreadWithState^ tws = gcnew ThreadWithState(
            "This report displays the number {0}.",
            42,
            gcnew ExampleCallback(&Example::ResultCallback)
        );

        // Create a thread to execute the task, and then
        // start the thread.
        Thread^ t = gcnew Thread(
            gcnew ThreadStart(tws, &ThreadWithState::ThreadProc));
        t->Start();
        Console::WriteLine("Main thread does some work, then waits.");
        t->Join();
        Console::WriteLine(
            "Independent task has completed; main thread ends.");  
    }

private:
    // The callback method must match the signature of the
    // callback delegate.
    //
    static void ResultCallback(int lineCount) 
    {
        Console::WriteLine(
            "Independent task printed {0} lines.", lineCount);
    }
};

// Entry point for the example.
//
void main() 
{
    Example::Demo();
}

Creating Threads and Passing Data at Start Time

Creating a Thread

Passing Data to Threads and Retrieving Data from Threads

Retrieving Data with Callback Methods

See Also

Reference

Other Resources

Additional resources