System.Threading.Thread Class

Summary

Creates and controls a thread, sets its priority, and gets its status.

C# Syntax:

public sealed class Thread

Public static (non-instance) members of this type are safe for multithreaded operations. Instance members are not guaranteed to be thread safe.

A process can create one or more threads to execute a portion of the program code associated with the process. Use a ThreadStart delegate to specify the program code executed by a thread.

For the duration of its existence, a thread is always in one or more of the states defined by ThreadState. A scheduling priority level, as defined by ThreadPriority, can be requested for a thread, but is not guaranteed to be honored by the operating system.

The following code example demonstrates simple threading functionality.

System.Threading Namespace

System.Threading.Thread Member List:

Public Constructors

ctor #1

Initializes a new instance of the Thread class.

Public Properties

CurrentContext	Read-only Gets the current context in which the thread is executing.
CurrentCulture	Read-write Gets or sets the culture for the current thread.
CurrentPrincipal	Read-write Gets or sets the thread's current principal (for role-based security).
CurrentThread	Read-only Gets the currently running thread.
CurrentUICulture	Read-write Gets or sets the current culture used by the Resource Manager to look up culture-specific resources at run time.
IsAlive	Read-only Gets a value indicating the execution status of the current thread.
IsBackground	Read-write Gets or sets a value indicating whether or not a thread is a background thread.
IsThreadPoolThread	Read-only
Name	Read-write Gets or sets the name of the thread.
Priority	Read-write Gets or sets a value indicating the scheduling priority of a thread.
ThreadState	Read-only Gets a value containing the states of the current thread.

Public Methods

Abort	Overloaded: Abort() Raises a ThreadAbortException in the thread on which it is invoked, to begin the process of terminating the thread. Calling this method usually terminates the thread.
Abort	Overloaded: Abort(object stateInfo) Raises a ThreadAbortException in the thread on which it is invoked, to begin the process of terminating the thread while also providing exception information about the thread termination. Calling this method usually terminates the thread.
AllocateDataSlot	Allocates an unnamed data slot on all the threads.
AllocateNamedDataSlot	Allocates a named data slot on all threads.
Equals (inherited from System.Object)	See base class member description: System.Object.Equals Derived from System.Object, the primary base class for all objects.
FreeNamedDataSlot	Frees a previously allocated named data slot.
GetData	Retrieves the value from the specified slot on the current thread, within the current thread's current domain.
GetDomain	Returns the current domain in which the current thread is running.
GetDomainID	Returns a unique application domain identifier.
GetHashCode (inherited from System.Object)	See base class member description: System.Object.GetHashCode Derived from System.Object, the primary base class for all objects.
GetNamedDataSlot	Looks up a named data slot.
GetType (inherited from System.Object)	See base class member description: System.Object.GetType Derived from System.Object, the primary base class for all objects.
Interrupt	Interrupts a thread that is in the WaitSleepJoin thread state.
Join	Overloaded: Join() Blocks the calling thread until a thread terminates.
Join	Overloaded: Join(int millisecondsTimeout) Blocks the calling thread until a thread terminates or the specified time elapses.
Join	Overloaded: Join(TimeSpan timeout) Blocks the calling thread until a thread terminates or the specified time elapses.
ResetAbort	Cancels an Thread.Abort requested for the current thread.
Resume	Resumes a thread that has been suspended.
SetData	Sets the data in the specified slot on the currently running thread, for that thread's current domain.
Sleep	Overloaded: Sleep(int millisecondsTimeout) Suspends the current thread for a specified time.
Sleep	Overloaded: Sleep(TimeSpan timeout) Blocks the current thread for a specified time.
SpinWait	Causes a thread to wait the number of times defined by the iterations parameter.
Start	Causes the operating system to change the state of the current instance to ThreadState.Running.
Suspend	Either suspends the thread, or if the thread is already suspended, has no effect.
ToString (inherited from System.Object)	See base class member description: System.Object.ToString Derived from System.Object, the primary base class for all objects.

Protected Methods

Finalize	Overridden: Releases the resources held by this instance.
MemberwiseClone (inherited from System.Object)	See base class member description: System.Object.MemberwiseClone Derived from System.Object, the primary base class for all objects.

Hierarchy:

• System.Object
• System.Threading.Thread

System.Threading.Thread Member Details

Summary

Initializes a new instance of the Thread class.

C# Syntax:

public Thread(Thread(    ThreadStart start );

start

A ThreadStart delegate that references the methods to be invoked when this thread begins executing.

Exceptions

Exception Type	Condition
ArgumentNullException	The start parameter is null.

To schedule the thread for execution, call the Thread.Start method.

Return to top

Summary

Gets the current context in which the thread is executing.

C# Syntax:

public static Context CurrentContext {get;}

Return to top

Summary

Gets or sets the culture for the current thread.

C# Syntax:

public CultureInfo CurrentCulture {get; set;}

Return to top

Summary

Gets or sets the thread's current principal (for role-based security).

C# Syntax:

public static IPrincipal CurrentPrincipal {get; set;}

Exceptions

Exception Type	Condition
SecurityException	The caller does not have the required permission.

SecurityPermission to manipulate the principal object. Associated enumeration: SecurityPermissionFlag.ControlPrincipal.

Return to top

Summary

Gets the currently running thread.

C# Syntax:

public static Thread CurrentThread {get;}

Return to top

Summary

Gets or sets the current culture used by the Resource Manager to look up culture-specific resources at run time.

C# Syntax:

public CultureInfo CurrentUICulture {get; set;}

Exceptions

Exception Type	Condition
ArgumentNullException	The property value is null.

Return to top

Summary

Gets a value indicating the execution status of the current thread.

C# Syntax:

public bool IsAlive {get;}

This property returns true unless the Thread.ThreadState of the current thread contains ThreadState.Unstarted, ThreadState.Stopped, or ThreadState.Aborted.

Return to top

Summary

Gets or sets a value indicating whether or not a thread is a background thread.

C# Syntax:

public bool IsBackground {get; set;}

Exceptions

Exception Type	Condition
ThreadStateException	The thread has not been started, is dead, or is not in the suspended state.

A thread is either a background thread or a foreground thread. Background threads are identical to foreground threads except for the fact that background threads do not prevent a process from terminating. Once all foreground threads belonging to a process have terminated, the common language runtime ends the process by invoking Thread.Abort on any background threads that are still alive.

Return to top

C# Syntax:

public bool IsThreadPoolThread {get;}

Return to top

Summary

Gets or sets the name of the thread.

C# Syntax:

public string Name {get; set;}

Exceptions

Exception Type	Condition
InvalidOperationException	A set operation was requested, and the Name property has already been set.

This property is write-once.

Return to top

Summary

Gets or sets a value indicating the scheduling priority of a thread.

C# Syntax:

public ThreadPriority Priority {get; set;}

Exceptions

Exception Type	Condition
ThreadStateException	The thread has reached a final state, such as ThreadState.Aborted.
ArgumentException	The value specified for a set operation is not a valid ThreadPriority value.

A thread can be assigned any one of the following priority values:

• Highest
• AboveNormal
• Normal
• BelowNormal
• Lowest

Operating systems are not required to honor the priority of a thread.

Return to top

Summary

Gets a value containing the states of the current thread.

C# Syntax:

public ThreadState ThreadState {get;}

The ThreadState property is more general than the Thread.IsAlive property or the Thread.IsBackground property.

Return to top

Summary

Raises a ThreadAbortException in the thread on which it is invoked, to begin the process of terminating the thread. Calling this method usually terminates the thread.

C# Syntax:

public void Abort();

Exceptions

Exception Type	Condition
SecurityException	The caller does not have the required permission for this thread.

When this method is invoked on a thread, the system throws a ThreadAbortException in the thread to abort it.ThreadAbortException is a special exception that can be caught by application code, but is re-thrown at the end of the catch block unless Thread.ResetAbort is called.ResetAbort cancels the request to abort, and prevents the ThreadAbortException from terminating the thread. Unexecuted finally blocks are executed before the thread is aborted; this includes any finally block that is executing when the exception is thrown.

The thread is not guaranteed to abort immediately, or at all. This situation can occur if a thread does an unbounded amount of computation in the finally blocks that are called as part of the abort procedure, thereby indefinitely delaying the abort. To ensure a thread has aborted, invoke a Thread.Join method on the thread after calling Abort.

If Abort is called on a thread that has not been started, the thread will abort when Thread.Start is called. If Abort is called on a thread that has been suspended, the thread is resumed and then aborted. If Abort is called on a thread that is blocked or is sleeping, the thread is interrupted and then aborted. If, while executing unmanaged code, a thread ignores a ThreadAbortException, the system re-throws the ThreadAbortException when the thread begins executing managed code.

If two calls to Abort come at the same time, it is possible that one call set the state information and the other call executes the Abort. However, an application cannot distinguish this.

After Abort is invoked on a thread, the state of the thread includes ThreadState.AbortRequested. After the thread has terminated as a result of a successful call to Abort, the state of the thread is changed to ThreadState.Stopped. With sufficient permissions, a thread that is the target of an Abort can cancel the abort using the ResetAbort method. For an example that demonstrates calling the ResetAbort method, see the ThreadAbortException class.

SecurityPermissionAttribute for advanced operations on threads. Associated enumeration: SecurityPermissionFlag.ControlThread.

Return to top

Summary

Raises a ThreadAbortException in the thread on which it is invoked, to begin the process of terminating the thread while also providing exception information about the thread termination. Calling this method usually terminates the thread.

C# Syntax:

public void Abort(    object stateInfo );

stateInfo

An object that contains application-specific information, such as state, which can be used by the thread being aborted.

Exceptions

Exception Type	Condition
SecurityException	The caller does not have the required permission for this thread.

When this method is invoked on a thread, the system throws a ThreadAbortException in the thread to abort it.ThreadAbortException is a special exception that can be caught by application code, but is re-thrown at the end of the catch block unless Thread.ResetAbort is called.ResetAbort cancels the request to abort, and prevents the ThreadAbortException from terminating the thread. Unexecuted finally blocks are executed before the thread is aborted; this includes any finally block that is executing when the exception is thrown.

The thread is not guaranteed to abort immediately, or at all. This situation can occur if a thread does an unbounded amount of computation in the finally blocks that are called as part of the abort procedure, thereby indefinitely delaying the abort. To ensure a thread has aborted, invoke a Thread.Join method on the thread after calling Abort.

If Abort is called on a thread that has not been started, the thread will abort when Thread.Start is called. If Abort is called on a thread that has been suspended, the thread is resumed and then aborted. If Abort is called on a thread that is blocked or is sleeping, the thread is interrupted and then aborted. If, while executing unmanaged code, a thread ignores a ThreadAbortException, the system re-throws the ThreadAbortException when the thread begins executing managed code.

If two calls to Abort come at the same time, it is possible that one call sets the state information, and the other call executes the Abort. However, an application cannot distinguish this.

After Abort is invoked on a thread, the state of the thread includes ThreadState.AbortRequested. After the thread has terminated as a result of a successful call to Abort, the state of the thread is changed to ThreadState.Stopped. With sufficient permissions, a thread that is the target of an Abort can cancel the abort using the ResetAbort method. For an example that demonstrates calling the ResetAbort method, see the ThreadAbortException class.

SecurityPermissionAttribute for advanced operations on threads. Associated enumeration: SecurityPermissionFlag.ControlThread.

Return to top

Summary

Allocates an unnamed data slot on all the threads.

C# Syntax:

public static LocalDataStoreSlot AllocateDataSlot();

Return Value:

A LocalDataStoreSlot.

The slot is allocated on all threads.

Threads use a local store memory mechanism to store thread-specific data. The common language runtime allocates a multi-slot data store array to each process when it is created. The thread can allocate a data slot in the data store, store and retrieve a data value in the slot, and free the slot for reuse after the thread expires. Data slots are unique per thread. No other thread (not even a child thread) can get that data.

Return to top

Summary

Allocates a named data slot on all threads.

C# Syntax:

public static LocalDataStoreSlot AllocateNamedDataSlot(    string name );

name

The name of the data slot to be allocated.

Return Value:

A LocalDataStoreSlot.

Threads use a local store memory mechanism to store thread-specific data. The common language runtime allocates a multi-slot data store array to each process when it is created. The thread can allocate a data slot in the data store, store and retrieve a data value in the slot, and free the slot for reuse after the thread expires. Data slots are unique per thread. No other thread (not even a child thread) can get that data.

Slots allocated with this method must be freed with Thread.FreeNamedDataSlot.

Return to top

Inherited
See base class member description: System.Object.Equals

C# Syntax:

public virtual bool Equals(    object obj );

For more information on members inherited from System.Object click on the link above.

Return to top

Summary

Releases the resources held by this instance.

C# Syntax:

~Thread();

Application code does not call this method; it is automatically invoked during garbage collection.

See the conceptual topic at MSDN: programmingessentialsforgarbagecollection for more information.

Return to top

Summary

Frees a previously allocated named data slot.

C# Syntax:

public static void FreeNamedDataSlot(    string name );

name

The name of the data slot to be freed.

The slot is freed on all threads.

Threads use a local store memory mechanism to store thread-specific data. The common language runtime allocates a multi-slot data store array to each process when it is created. The thread can allocate a data slot in the data store, store and retrieve a data value in the slot, and free the slot for reuse after the thread expires. Data slots are unique per thread. No other thread (not even a child thread) can get that data.

Return to top

Summary

Retrieves the value from the specified slot on the current thread, within the current thread's current domain.

C# Syntax:

public static object GetData(    LocalDataStoreSlot slot );

slot

The LocalDataStoreSlot from which to get the value.

Return Value:

The retrieved value.

Threads use a local store memory mechanism to store thread-specific data. The common language runtime allocates a multi-slot data store array to each process when it is created. The thread can allocate a data slot in the data store, store and retrieve a data value in the slot, and free the slot for reuse after the thread expires. Data slots are unique per thread. No other thread (not even a child thread) can get that data.

Return to top

Summary

Returns the current domain in which the current thread is running.

C# Syntax:

public static AppDomain GetDomain();

Return Value:

An AppDomain representing the current application domain of the running thread.

The get and set accessors work on the hard thread, not the logical thread. Therefore, they are package-protected and should not be available for general consumption.

Return to top

Summary

Returns a unique application domain identifier.

C# Syntax:

public static int GetDomainID();

Return Value:

A 32-bit signed integer uniquely identifying the application domain.

Return to top

Inherited
See base class member description: System.Object.GetHashCode

C# Syntax:

public virtual int GetHashCode();

For more information on members inherited from System.Object click on the link above.

Return to top

Summary

Looks up a named data slot.

C# Syntax:

public static LocalDataStoreSlot GetNamedDataSlot(    string name );

name

The name of the local data slot.

Return Value:

A LocalDataStoreSlot allocated for this thread.

Threads use a local store memory mechanism to store thread-specific data. The common language runtime allocates a multi-slot data store array to each process when it is created. The thread can allocate a data slot in the data store, store and retrieve a data value in the slot, and free the slot for reuse after the thread expires. Data slots are unique per thread. No other thread (not even a child thread) can get that data.

If the named slot does not exist, a new slot is allocated. Named data slots are public and can be manipulated by anyone.

Return to top

Inherited
See base class member description: System.Object.GetType

C# Syntax:

public Type GetType();

For more information on members inherited from System.Object click on the link above.

Return to top

Summary

Interrupts a thread that is in the WaitSleepJoin thread state.

C# Syntax:

public void Interrupt();

Exceptions

Exception Type	Condition
SecurityException	The caller does not have the appropriate SecurityPermission.

If this thread is not currently blocked in a wait, sleep, or join state, it will be interrupted when it next begins to block.

SecurityPermissionAttribute for advanced operations on threads. Associated enumeration: SecurityPermissionFlag.ControlThread.

Return to top

Summary

Blocks the calling thread until a thread terminates.

C# Syntax:

public void Join();

Exceptions

Exception Type	Condition
ThreadStateException	The caller attempted to join a thread that is in the ThreadState.Unstarted state.
ThreadInterruptedException	The thread is interrupted while waiting.

Use this method to ensure a thread has terminated. The caller will block indefinitely if the thread does not terminate.

This method changes the state of the calling thread to include ThreadState.WaitSleepJoin. You cannot invoke Join on a thread that is in the ThreadState.Unstarted state.

Return to top

Summary

Blocks the calling thread until a thread terminates or the specified time elapses.

C# Syntax:

public bool Join(    int millisecondsTimeout );

millisecondsTimeout

The number of milliseconds to wait for the thread to terminate.

Return Value:

true if the thread has terminated; false if the thread has not terminated after the amount of time specified by the millisecondsTimeout parameter has elapsed.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	The value of millisecondsTimeout is negative and is not equal to Timeout.Infinite in milliseconds.
ThreadStateException	The thread has not been started.

If Timeout.Infinite is specified for the millisecondsTimeout parameter, this method behaves identically to Join, except for the return value.

This method changes the state of the calling thread to include ThreadState.WaitSleepJoin. You cannot invoke Join on a thread that is in the ThreadState.Unstarted state.

Return to top

Summary

Blocks the calling thread until a thread terminates or the specified time elapses.

C# Syntax:

public bool Join(    TimeSpan timeout );

timeout

A TimeSpan set to the amount of time to wait for the thread to terminate.

Return Value:

true if the thread terminated; false if the thread has not terminated after the amount of time specified by the timeout parameter has elapsed.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	The value of timeout is negative and is not equal to Timeout.Infinite in milliseconds, or is greater than Int32.MaxValue milliseconds.
ThreadStateException	The caller attempted to join a thread that is in the ThreadState.Unstarted state.

If Timeout.Infinite is specified for timeout, this method behaves identically to Join, except for the return value.

This method changes the state of the current thread to include ThreadState.WaitSleepJoin. You cannot invoke Join on a thread that is in the ThreadState.Unstarted state.

Return to top

Inherited
See base class member description: System.Object.MemberwiseClone

C# Syntax:

protected object MemberwiseClone();

For more information on members inherited from System.Object click on the link above.

Return to top

Summary

Cancels an Thread.Abort requested for the current thread.

C# Syntax:

public static void ResetAbort();

Exceptions

Exception Type	Condition
ThreadStateException	Abort was not invoked on the current thread.
SecurityException	The caller does not have the required security permission for the current thread.

This method can only be called by code with the proper permissions. For more information see .

When a call is made to Abort to terminate a thread, the system throws a ThreadAbortException.ThreadAbortException is a special exception that can be caught by application code, but is rethrown at the end of the catch block unless ResetAbort is called.ResetAbort cancels the request to abort, and prevents the ThreadAbortException from terminating the thread.

See ThreadAbortException for an example that demonstrates calling the ResetAbort method.

SecurityPermissionAttribute for advanced operations on threads. Associated enumeration: SecurityPermissionFlag.ControlThread.

Return to top

Summary

Resumes a thread that has been suspended.

C# Syntax:

public void Resume();

Exceptions

Exception Type	Condition
ThreadStateException	The thread has not been started, is dead, or is not in the suspended state.
SecurityException	The caller does not have the appropriate SecurityPermission.

SecurityPermissionAttribute for advanced operations on threads. Associated enumeration: SecurityPermissionFlag.ControlThread.

Return to top

Summary

Sets the data in the specified slot on the currently running thread, for that thread's current domain.

C# Syntax:

public static void SetData(    LocalDataStoreSlot slot,    object data );

slot

The LocalDataStoreSlot in which to set the value.

data

The value to be set.

Threads use a local store memory mechanism to store thread-specific data. The common language runtime allocates a multi-slot data store array to each process when it is created. The thread can allocate a data slot in the data store, store and retrieve a data value in the slot, and free the slot for reuse after the thread expires. Data slots are unique per thread. No other thread (not even a child thread) can get that data.

Return to top

Summary

Suspends the current thread for a specified time.

C# Syntax:

public static void Sleep(    int millisecondsTimeout );

millisecondsTimeout

The number of milliseconds for which the thread is blocked. Specify zero (0) to indicate that this thread should be suspended to allow other waiting threads to execute. Specify Timeout.Infinite to block the thread indefinitely.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	The timeout value is negative and is not equal to Timeout.Infinite.

The thread will not be scheduled for execution by the operating system for the amount of time specified. This method changes the state of the thread to include ThreadState.WaitSleepJoin.

Return to top

Summary

Blocks the current thread for a specified time.

C# Syntax:

public static void Sleep(    TimeSpan timeout );

timeout

A TimeSpan set to the amount of time for which the thread is blocked. Specify zero to indicate that this thread should be suspended to allow other waiting threads to execute. Specify Timeout.Infinite to block the thread indefinitely.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	The value of timeout is negative and is not equal to Timeout.Infinite in milliseconds, or is greater than Int32.MaxValue milliseconds.

The thread will not be scheduled for execution by the operating system for the amount of time specified. This method changes the state of the thread to include ThreadState.WaitSleepJoin.

Return to top

Summary

Causes a thread to wait the number of times defined by the iterations parameter.

C# Syntax:

public static void SpinWait(    int iterations );

iterations

A 32-bit signed integer that defines how long a thread is to wait.

Return to top

Summary

Causes the operating system to change the state of the current instance to ThreadState.Running.

C# Syntax:

public void Start();

Exceptions

Exception Type	Condition
ThreadStateException	The thread has already been started.
SecurityException	The caller does not have the appropriate SecurityPermission.
OutOfMemoryException	There is not enough memory available to start this thread.
NullReferenceException	This method was invoked on a thread reference that is null.

Once a thread is in the Running state, the operating system can schedule it for execution. When the thread begins executing, the ThreadStart delegate supplied to the constructor for the thread invokes its methods.

Once the thread terminates, it cannot be restarted with another call to Start.

The following example demonstrates creating a thread and starting it.

This code produces the following output:

using System;
using System.Threading;

public class ThreadWork 
{
   public static void DoWork()
   {
      for(int i = 0; i<3;i++)
      {
         Console.WriteLine("Working thread...");
            Thread.Sleep(100);
      }
   }
}
class ThreadTest
{
   public static void Main()
   {
      ThreadStart myThreadDelegate = new ThreadStart(ThreadWork.DoWork);
      Thread myThread = new Thread(myThreadDelegate);
      myThread.Start();
         for(int i = 0; i<3; i++)
         {
         Console.WriteLine("In main.");
            Thread.Sleep(100);
         }
   }
}

    

              				In main.
              				Working thread...
              				In main. Working thread...
              				In main.
              				Working thread...
              			
            

Note that the sequence of the output statements is typical, but is not guaranteed to be identical across systems.

Return to top

Summary

Either suspends the thread, or if the thread is already suspended, has no effect.

C# Syntax:

public void Suspend();

Exceptions

Exception Type	Condition
ThreadStateException	The thread has not been started or is dead.
SecurityException	The caller does not have the appropriate SecurityPermission.

If the thread is already suspended, this method has no effect.

SecurityPermissionAttribute for advanced operations on threads. Associated enumeration: SecurityPermissionFlag.ControlThread.

Return to top

Inherited
See base class member description: System.Object.ToString

C# Syntax:

public virtual string ToString();

For more information on members inherited from System.Object click on the link above.

Return to top

Top of page