NGWS SDK Documentation  

This is preliminary documentation and subject to change.
To comment on this topic, please send us email at ngwssdk@microsoft.com. Thanks!

Thread Reference

Class for creating and managing a thread.

public class Thread
{   
  public Thread(ThreadStart start);
  public void Start();
  public void Stop();
  [SecurityPermissionAttribute(SecurityAction.LinkDemand, Flags=SecurityPermissionFlag.UnmanagedCode)]
  public void Abort(Object stateInfo)
  public extern void Abort();
  [SecurityPermissionAttribute(SecurityAction.Demand, Flags=SecurityPermissionFlag.UnmanagedCode)]
  public static  void ResetAbort()
  public void Suspend();
  public void Resume();
  public extern void Interrupt();
  public ThreadPriority Priority {get;set}
  public bool IsAlive {get;}
  public void Join();
  public bool Join(int millisecondsTimeout);
  public bool Join(TimeSpan timeout)
  public static void Sleep(int millisecondsTimeout);
  public static void Sleep(TimeSpan timeout)
  public static Thread CurrentThread {get;}
  public bool IsBackground {get;set}
  public ThreadState ThreadState {get;}
  public ApartmentState ApartmentState {get;set}
  public static LocalDataStoreSlot AllocateDataSlot();
  public static LocalDataStoreSlot AllocateNamedDataSlot(String name);
  public static LocalDataStoreSlot GetNamedDataSlot(String name);
  public static void FreeNamedDataSlot(String name);
  public static Object GetData(LocalDataStoreSlot slot);
  public static void SetData(LocalDataStoreSlot slot, Object data);
  public CultureInfo CurrentUICulture {get;set};
  public CultureInfo CurrentCulture {get;set}
  public static Context CurrentContext {get;}
  public static IPrincipal CurrentPrincipal
  {
    get {}
    [SecurityPermissionAttribute(SecurityAction.Demand, Flags=SecurityPermissionFlag.ControlPrincipal)]
    set {}       
  }
  public  String Name {get;set}

  internal Object ExceptionState 
  {
  get { return m_ExceptionStateInfo;}
  set { m_ExceptionStateInfo = value;}
  }
}

Thread Constructor

Creates a new Thread object which will begin execution at start.ThreadStart on a new thread when the Start method is called.

Exceptions: ArgumentNullException if start == null.

Start

Creates a new Thread object which will begin execution at start.ThreadStart on a new thread when the Start method is called.

Exceptions: ArgumentNullException if start == null.

Stop

Raises a ThreadStopException in the thread, which will usually results in the thread's death (unless it catches and ignores the exception). The thread is not stopped immediately--you must Join on the thread to guarantee it has stopped. If Stop is called on a thread that has not been started, the thread will stop when Start is called. If Stop is called on a dead thread, this method does nothing.

ThreadStopException will cause finally clauses of try statements to be executed before the thread's "state" is marked ThreadState.ThreadStopped, and it has totally stopped.

public class TX 
{
   public TX( )
   {
   }
   public void run( )
   {
      try
      {
         while (true)
         {
            StringBuilder   oSB   = new StringBuilder("AB");
            oSB.Append("C");
         }
      }
      finally
      {
         Console.WriteLine("Cleanup");
      }
   }
   public static void Main(String[] args)
   {
      TX   tx   = new TX( );
      Thread   t1   = new Thread(new ThreadStart(tx.run));
      t1.Start();
      Thread.Sleep(2000);
      t1.Stop();
      t1.Join();
   }

}

Abort

Raises a ThreadAbortException in the thread, which usually results in the thread's death. The ThreadAbortException is a special exception that is not catchable. The finally clauses of all try statements will be executed before the thread dies. This includes the finally that a thread might be executing at the moment the Abort is raised. The thread is not stopped immediately--you must Join on the thread to guarantee it has stopped. It is possible for a thread to do an unbounded amount of computation in the finally's and thus indefinitely delay the threads death. If Abort is called on a thread that has not been started, the thread will abort when Start is called. If Abort is called twice on the same thread, a DuplicateThreadAbort exception is thrown.

It is possible for a thread to do an unbounded amount of computation in the finally's and thus indefinitely delay the threads death. It is also possible for a thread to swallow the ThreadAbort in unmanaged code. The runtime will detect this and will re-throw the ThreadAbort exception when the thread returns back to managed code.

If Abort is called on a thread that has not been started, the thread will abort when 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 two aborts come at the same time, it is possible that the state info gets set by one, and the actual abort gets delivered by another. But this is not distinguishable by an application.

To call Abort, code needs to have the UnmanagedCode permission.

ResetAbort

Resets a thread abort. Should be called by trusted code only.

Code needs to have the UnmanagedCode permission to call ResetAbort.

AllocateDataSlot

Allocates an un-named data slot. The slot is allocated on ALL the threads.

AllocateNamedDataSlot

Allocates a named data slot. The slot is allocated on ALL the threads. Named data slots are "public" and can be manipulated by anyone.

GetNamedDataSlot

Looks up a named data slot. If the name has not been used, a new slot is allocated. Named data slots are "public" and can be manipulated by anyone.

FreeNamedDataSlot

Frees a named data slot. The slot is allocated on ALL the threads. Named data slots are "public" and can be manipulated by anyone.

GetData

Retrieves the value from the specified slot on the current thread.

SetData

Sets the data in the specified slot on the currently running thread.

CurrentContext

Returns the current content the thread is executing in.

CurrentPrincipal

Get and set thread's current principal (for role based security).

Name

Retrieves the name of the thread. If the component does not have a name, null is returned.

ApartmentState

An unstarted thread can be marked to indicate that it will host a single-threaded or multi-threaded apartment.

Exceptions:

ArgumentException if state is not a valid apartment state (STA or MTA).

Enum to represent the different threading models.

public enum ApartmentState
{
        STA = 0,
        MTA = 1,
        Unknown = 2,
};

IsAlive

Returns true if the thread has been started and is not dead.

Priority

Returns the priority of the thread.

Exceptions: ThreadStateException if the thread is dead.

Constants for thread priorities.

public enum ThreadPriority
{
        Lowest = 0,
        BelowNormal = 1,
        Normal = 2,
        AboveNormal = 3,
        Highest = 4,
};    

CurrentThread

Returns the current thread the code is executing on.

IsBackground

If the thread is marked as background the Execution Engine will not wait until the thread has stopped when shutting down.

ThreadState

Return the thread state as a consistent set of bits. This is more general then IsAlive or IsBackground.

Constants for thread states.

public enum ThreadState
{
  Running = 0,
  StopRequested = 1,
  SuspendRequested = 2,
  Background = 4,
  Unstarted = 8,
  Stopped = 16,
  WaitSleepJoin = 32,
  Suspended = 64,
  AbortRequested = 128,
  Aborted = 256
};

Suspend

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

Exceptions: ThreadStateException if the thread has not been started or it is dead.

Resume

Resumes a thread that has been suspended.

Exceptions: ThreadStateException if the thread has not been started or it is dead or it isn't in the suspended state.

Interrupt

Interrupts a thread that is inside a Wait, Sleep or Join. If that thread is not currently blocked in that manner, it will be interrupted when it next begins to block.

Sleep.

Suspends the current thread for timeout milliseconds / timespan. If timeout == 0, forces the thread to give up the remainer of its timeslice. If timeout == Timeout.Infinite, no timeout will occur.

Exceptions:

ArgumentException if timeout < 0.

ThreadInterruptedException if the thread is interrupted while sleeping.

Join

Waits for the thread to die or for timeout milliseconds to elapse. Returns true if the thread died, or false if the wait timed out. If Timeout.Infinite is given as the parameter, no timeout will occur.

Exceptions:

ArgumentException if timeout < 0.

ThreadInterruptedException if the thread is interrupted while waiting.

ThreadStateException if the thread has not been started yet.