Enhanced C#
Language of your choice: library documentation
Nested classes | Properties | Public Member Functions | Static Public Member Functions | Protected Member Functions | Protected fields | Events | List of all members
Loyc.Threading.ThreadEx Class Reference

Creates and controls a thread, and fills in a gap in the .NET framework by propagating thread-local variables from parent to child threads, and by providing a ThreadStarting event. More...


Source file:

Remarks

Creates and controls a thread, and fills in a gap in the .NET framework by propagating thread-local variables from parent to child threads, and by providing a ThreadStarting event.

This class is a decorator for the Thread class and thus a drop-in replacement, except that only the most common methods and properties (both static and non-static) are provided.

.NET itself has no support whatsoever from inheriting thread-local variables. Not only are thread locals not inherited from the parent thread, .NET fires no event when a thread starts and a child thread cannot get the thread ID of the thread that created it.

ThreadEx helps work around this problem by automatically propagating ThreadLocalVariable<T> values, and providing the ThreadStarting event, which blocks the parent thread but is called in the child thread. This only works if you use ThreadEx to start the child thread; when using other mechanisms such as System.Threading.Tasks.Task, it is possible to copy thread- local variables from the parent thread using code like this:

int parentThreadId = Thread.CurrentThread.ManagedThreadId;
var task = System.Threading.Tasks.Task.Factory.StartNew(() => {
using (ThreadEx.PropagateVariables(parentThreadId))
DoSomethingOnChildThread();
});
task.Wait();

Be careful, however: you should guarantee that, while you copy the variables, the parent thread is blocked, or that the parent thread will not modify any of them (which may be difficult since variables might exist that you are unaware of, that you do not control).

TLV (thread-local variable) inheritance is needed to use the Ambient Service Pattern

Nested classes

struct  ThreadDestructor
 See PropagateVariables for more information. More...
 

Properties

static Thread CurrentThread [get]
 Gets the currently running thread. More...
 
bool IsBackground [get, set]
 Gets or sets a value indicating whether or not a thread is a background thread. More...
 
int ManagedThreadId [get]
 Gets a unique identifier for the current managed thread. More...
 
string Name [get, set]
 Gets or sets the name of the thread. More...
 
ThreadPriority Priority [get, set]
 Gets or sets a value indicating the scheduling priority of a thread. More...
 
System.Threading.ThreadState ThreadState [get]
 Gets a value containing the states of the current thread. More...
 
Thread Thread [get]
 
Thread ParentThread [get]
 
bool IsAlive [get]
 

Public Member Functions

 ThreadEx (ParameterizedThreadStart start)
 
 ThreadEx (ThreadStart start)
 
 ThreadEx (ParameterizedThreadStart start, int maxStackSize)
 
 ThreadEx (ThreadStart start, int maxStackSize)
 
void Start ()
 Causes the operating system to change the state of the current instance to System.Threading.ThreadState.Running. More...
 
virtual void Start (object parameter)
 Causes the operating system to change the state of the current instance to System.Threading.ThreadState.Running. Start() does not return until the ThreadStarted event is handled. More...
 
void Abort (object stateInfo)
 Raises a System.Threading.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. More...
 
void Abort ()
 
override int GetHashCode ()
 Returns a hash code for the current thread. More...
 
void Join ()
 Blocks the calling thread until a thread terminates, while continuing to perform standard COM and SendMessage pumping. More...
 
bool Join (int milliseconds)
 Blocks the calling thread until a thread terminates or the specified time elapses, while continuing to perform standard COM and SendMessage pumping. More...
 
bool Join (TimeSpan timeout)
 

Static Public Member Functions

static ThreadDestructor PropagateVariables (int parentThreadId)
 Manually initializes ThreadLocalVariable<T> objects in a thread that may not have been started via ThreadEx, propagating values from the parent thread. Returns an object for uninitializing the thread. More...
 
static AppDomain GetDomain ()
 Returns the current domain in which the current thread is running. More...
 
static void Sleep (int millisecondsTimeout)
 Suspends the current thread for a specified time. More...
 

Protected Member Functions

virtual void ThreadStart ()
 

Protected fields

Thread _parent
 
Thread _thread
 
ThreadStart _ts1
 
ParameterizedThreadStart _ts2
 
int _startState = 0
 

Events

static EventHandler< ThreadStartEventArgsThreadStarting
 This event is called in the context of a newly-started thread, provided that the thread is started by the Start() method of this class (rather than Thread.Start()). More...
 
static EventHandler< ThreadStartEventArgsThreadStopping
 This event is called when a thread is stopping, if the thread is stopping gracefully and provided that it was started by the Start() method of this class (rather than Thread.Start()). More...
 

Member Function Documentation

void Loyc.Threading.ThreadEx.Abort ( object  stateInfo)
inline

Raises a System.Threading.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.

static AppDomain Loyc.Threading.ThreadEx.GetDomain ( )
inlinestatic

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

override int Loyc.Threading.ThreadEx.GetHashCode ( )
inline

Returns a hash code for the current thread.

void Loyc.Threading.ThreadEx.Join ( )
inline

Blocks the calling thread until a thread terminates, while continuing to perform standard COM and SendMessage pumping.

bool Loyc.Threading.ThreadEx.Join ( int  milliseconds)
inline

Blocks the calling thread until a thread terminates or the specified time elapses, while continuing to perform standard COM and SendMessage pumping.

static ThreadDestructor Loyc.Threading.ThreadEx.PropagateVariables ( int  parentThreadId)
inlinestatic

Manually initializes ThreadLocalVariable<T> objects in a thread that may not have been started via ThreadEx, propagating values from the parent thread. Returns an object for uninitializing the thread.

Parameters
parentThreadIdId of parent thread. The .NET framework does not make this information available so you must somehow pass this value manually from the parent thread to the child thread.
Returns
An object to be disposed at the end of the thread. This method can be called in a using statement so that this happens automatically: using(ThreadEx.PropagateVariables(parentThreadId)) { ... }. It is important to dispose the returned object so that thread-local values can be released to prevent a memory leak.

It is safe to call this method if the thread has already been initialized. In that case, the thread will not be initialized a second time, and the returned value will do nothing when it is disposed.

Be careful with this method: you should guarantee that, while you copy the variables, the parent thread is blocked, or that the parent thread will not modify any of them during the copying process (which may be difficult since variables might exist that you are unaware of, that you do not control).

Referenced by LeMP.MacroProcessor.ProcessAsync().

static void Loyc.Threading.ThreadEx.Sleep ( int  millisecondsTimeout)
inlinestatic

Suspends the current thread for a specified time.

void Loyc.Threading.ThreadEx.Start ( )
inline

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

References Loyc.Threading.ThreadEx.Start().

Referenced by Loyc.Threading.ThreadEx.Start().

virtual void Loyc.Threading.ThreadEx.Start ( object  parameter)
inlinevirtual

Causes the operating system to change the state of the current instance to System.Threading.ThreadState.Running. Start() does not return until the ThreadStarted event is handled.

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

Property Documentation

Thread Loyc.Threading.ThreadEx.CurrentThread
staticget

Gets the currently running thread.

bool Loyc.Threading.ThreadEx.IsBackground
getset

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

int Loyc.Threading.ThreadEx.ManagedThreadId
get

Gets a unique identifier for the current managed thread.

string Loyc.Threading.ThreadEx.Name
getset

Gets or sets the name of the thread.

ThreadPriority Loyc.Threading.ThreadEx.Priority
getset

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

System.Threading.ThreadState Loyc.Threading.ThreadEx.ThreadState
get

Gets a value containing the states of the current thread.

Event Documentation

EventHandler<ThreadStartEventArgs> Loyc.Threading.ThreadEx.ThreadStarting
static

This event is called in the context of a newly-started thread, provided that the thread is started by the Start() method of this class (rather than Thread.Start()).

The Start() method blocks until this event completes.

EventHandler<ThreadStartEventArgs> Loyc.Threading.ThreadEx.ThreadStopping
static

This event is called when a thread is stopping, if the thread is stopping gracefully and provided that it was started by the Start() method of this class (rather than Thread.Start()).