TThread provides a system-independent interface to threads. More...

#include <owl/thread.h>

Classes
class	TThreadError
	The error class that defines the objects that are thrown when an error occurs. More...

Public Types
enum	{ NoLimit = INFINITE }

enum	TCurrent { Current }

enum	TStatus { Created , Running , Suspended , Finished , Invalid }
	Identifies the states that the class can be in. More...

enum	TPriority { Idle = THREAD_PRIORITY_IDLE , Lowest = THREAD_PRIORITY_LOWEST , BelowNormal = THREAD_PRIORITY_BELOW_NORMAL , Normal = THREAD_PRIORITY_NORMAL , AboveNormal = THREAD_PRIORITY_ABOVE_NORMAL , Highest = THREAD_PRIORITY_HIGHEST , TimeCritical = THREAD_PRIORITY_TIME_CRITICAL }

typedef HANDLE	THandle

typedef TStatus	Status
	For compatibility with old T-less typenames.

typedef TThreadError	ThreadError

Public Member Functions
	TThread (TCurrent)
	Attach to a running thread.

THandle	Start ()
	Starts the thread executing.

ulong	Suspend ()
	Suspends execution of the thread.

ulong	Resume ()
	Resumes execution of a suspended thread.

bool	Sleep (long timeMS, bool alertable=false)
	Suspends execution of the current thread for the number of milliseconds specified by the timeMS parameter.

virtual void	Terminate ()
	Mark the thread for termination.

ulong	WaitForExit (ulong timeout=NoLimit)
	Blocks the calling thread until the internal thread exits or until the time specified by timeout, in milliseconds,expires.

ulong	TerminateAndWait (ulong timeout=NoLimit)
	Combines the behavior of Terminate() and WaitForExit().

TStatus	GetStatus () const
	Gets the current status of the thread.

uint32	GetExitCode () const

int	GetPriority () const
	Gets the thread priority.

int	SetPriority (int)
	Can pass a TPriority for simplicity.

Protected Member Functions
	TThread ()
	Create a thread. Derived class overrides Run()

	TThread (const TThread &)
	Puts the object into the Created state, just like the default constructor.

const TThread &	operator= (const TThread &)
	TThread assignment operator.

virtual	~TThread ()
	TThread destructor.

bool	ShouldTerminate () const
	Returns a bool value to indicate that Terminate() or TerminateAndWait() has been called.

void	Exit (ulong code)
	Alternative to returning from Run()

Detailed Description

TThread provides a system-independent interface to threads.

With suitable underlying implementations the same code can be used under OS/2 and Win32.

Example

class TimerThread : public TThread
{
  public:
    TimerThread() : Count(0) {}
  private:
    int Run();
    int Count;
};
 
int TimerThread::Run()
{
  // loop 10 times
  while (Count++ < 10) {
    Sleep(1000);    // delay 1 second
    cout << "Iteration " << Count << endl;
  }
  return 0;
}
 
int main()
{
  TimerThread timer;
  timer.Start();
  Sleep(20000);     // delay 20 seconds
  return 0;
}

Internal States

Created: the object has been created but its thread has not been started. The only valid transition from this state is to Running, which happens on a call to Start(). In particular, a call to Suspend() or Resume() when the object is in this state is an error and will throw an exception.
Running: the thread has been started successfully. There are two transitions from this state:
```
When the user calls Suspend() the object moves into
the Suspended state.

When the thread exits the object moves into the
Finished state.
```
Calling Resume() on an object that is in the Running state is an error and will throw an exception.
Suspended: the thread has been suspended by the user. Subsequent calls to Suspend() nest, so there must be as many calls to Resume() as there were to Suspend() before the thread actually resumes execution.
Finished: the thread has finished executing. There are no valid transitions out of this state. This is the only state from which it is legal to invoke the destructor for the object. Invoking the destructor when the object is in any other state is an error and will throw an exception.

Definition at line 600 of file thread.h.

Member Typedef Documentation

◆ Status

typedef TStatus owl::TThread::Status

For compatibility with old T-less typenames.

Definition at line 674 of file thread.h.

◆ THandle

typedef HANDLE owl::TThread::THandle

Definition at line 604 of file thread.h.

◆ ThreadError

typedef TThreadError owl::TThread::ThreadError

Definition at line 675 of file thread.h.

Member Enumeration Documentation

◆ anonymous enum

anonymous enum

Enumerator
NoLimit

Definition at line 603 of file thread.h.

◆ TCurrent

enum owl::TThread::TCurrent

Enumerator
Current

Definition at line 608 of file thread.h.

◆ TPriority

enum owl::TThread::TPriority

Enumerator
Idle	-15
Lowest	-2
BelowNormal	-1
Normal	0
AboveNormal	1
Highest	2
TimeCritical	15

Definition at line 633 of file thread.h.

◆ TStatus

enum owl::TThread::TStatus

Identifies the states that the class can be in.

Enumerator
Created	The class has been created but the thread has not been started.
Running	The thread is running.
Suspended	The thread has been suspended.
Finished	The thread has finished execution.
Invalid	The object is invalid. Currently this happens only when the operating system is unable to start the thread.

Definition at line 612 of file thread.h.

Constructor & Destructor Documentation

◆ TThread() [1/3]

owl::TThread::TThread ( TCurrent )

Attach to a running thread.

Definition at line 411 of file thread.cpp.

◆ TThread() [2/3]

owl::TThread::TThread ( )

protected

Create a thread. Derived class overrides Run()

Creates an object of type TThread.

Definition at line 398 of file thread.cpp.

◆ TThread() [3/3]

owl::TThread::TThread ( const TThread & )

protected

Puts the object into the Created state, just like the default constructor.

Does not copy any of the internal details of the thread being copied.

Definition at line 429 of file thread.cpp.

◆ ~TThread()

owl::TThread::~TThread ( )

protectedvirtual

TThread destructor.

If the thread hasn't finished, destroying its control object is an error.

Definition at line 482 of file thread.cpp.

References _T, owl::TThread::TThreadError::DestroyBeforeExit, GetStatus(), Running, Suspended, and WARN.

Member Function Documentation

◆ Exit()

void owl::TThread::Exit ( ulong code )

protected

Alternative to returning from Run()

Exit provides an alternative to returning from Run.

Called from within the thread that wants to exit early.

Definition at line 677 of file thread.cpp.

References Finished.

◆ GetExitCode()

uint32 owl::TThread::GetExitCode ( ) const

inline

Definition at line 1420 of file thread.h.

◆ GetPriority()

int owl::TThread::GetPriority ( ) const

inline

Gets the thread priority.

Under Win32, this is a direct call to the operating system. See the description of TPriority for possible values.

Definition at line 1431 of file thread.h.

◆ GetStatus()

TThread::TStatus owl::TThread::GetStatus ( ) const

inline

Gets the current status of the thread.

If the thread is marked as Running it may have terminated without our knowing it, so we have to check.

Definition at line 1412 of file thread.h.

◆ operator=()

const TThread & owl::TThread::operator= ( const TThread & thread )

protected

TThread assignment operator.

Used when assigning derived objects. Attempting to assign from a running object is an error, since the data fields in the running object can be changing asynchronously.

The target object must be in either the Created state or the Finished state. If so, puts the object into the Created state. If the object is not in either the Created state or the Finished state it is an error and an exception will be thrown.

Definition at line 454 of file thread.cpp.

References owl::TThread::TThreadError::AssignError, Created, Finished, GetStatus(), and Suspended.

◆ Resume()

ulong owl::TThread::Resume ( )

Resumes execution of a suspended thread.

It's an error to try to resume a thread that isn't suspended.

Definition at line 558 of file thread.cpp.

References _T, Created, Finished, GetStatus(), owl::TThread::TThreadError::ResumeAfterExit, owl::TThread::TThreadError::ResumeBeforeRun, owl::TThread::TThreadError::ResumeDuringRun, Running, and TRACEX.

◆ SetPriority()

int owl::TThread::SetPriority ( int pri )

Can pass a TPriority for simplicity.

Sets the priority of the thread.

Definition at line 625 of file thread.cpp.

References _T, and TRACEX.

◆ ShouldTerminate()

bool owl::TThread::ShouldTerminate ( ) const

inlineprotected

Returns a bool value to indicate that Terminate() or TerminateAndWait() has been called.

If this capability is being used, the thread should call ShouldTerminate() regularly, and if it returns a non-zero value the thread finish its processing and exit.

Definition at line 1442 of file thread.h.

◆ Sleep()

bool owl::TThread::Sleep	(	long	timeMS,
		bool	alertable = false )

inline

Suspends execution of the current thread for the number of milliseconds specified by the timeMS parameter.

If the alertable parameter is set to true, the function resumes execution upon I/O completion.

The function returns true if its wakeup is due to I/O completion.

Definition at line 1401 of file thread.h.

◆ Start()

TThread::THandle owl::TThread::Start ( )

Starts the thread executing.

The actual call depends on the operating system. Returns the handle of the thread. After the system call we check status.

Definition at line 502 of file thread.cpp.

References _T, Created, owl::TThread::TThreadError::CreationFailure, GetStatus(), Invalid, Running, and TRACEX.

◆ Suspend()

ulong owl::TThread::Suspend ( )

Suspends execution of the thread.

It's an error to try to suspend a thread that hasn't been started or that has already terminated.

Definition at line 535 of file thread.cpp.

References _T, Created, Finished, GetStatus(), owl::TThread::TThreadError::SuspendAfterExit, owl::TThread::TThreadError::SuspendBeforeRun, Suspended, and TRACEX.

◆ Terminate()

void owl::TThread::Terminate ( )

virtual

Mark the thread for termination.

Sets an internal flag that indicates that the thread should exit. The derived class can check the state of this flag by calling ShouldTerminate().

Definition at line 586 of file thread.cpp.

References _T, and TRACEX.

◆ TerminateAndWait()

ulong owl::TThread::TerminateAndWait ( ulong timeout = NoLimit )

Combines the behavior of Terminate() and WaitForExit().

Sets an internal flag that indicates that the thread should exit and blocks the calling thread until the internal thread exits or until the time specified by timeout, in milliseconds, expires. A timeout of NoLimit says to wait indefinitely.

Definition at line 616 of file thread.cpp.

References Terminate(), and WaitForExit().

◆ WaitForExit()

ulong owl::TThread::WaitForExit ( ulong timeout = NoLimit )

Blocks the calling thread until the internal thread exits or until the time specified by timeout, in milliseconds,expires.

A timeout of NoLimit says to wait indefinitely.

Definition at line 598 of file thread.cpp.

References _T, Running, and TRACEX.

The documentation for this class was generated from the following files:

include/owl/thread.h
source/owlcore/thread.cpp

Classes

Public Types

Public Member Functions

Protected Member Functions

Detailed Description

Member Typedef Documentation

◆ Status

◆ THandle

◆ ThreadError

Member Enumeration Documentation

◆ anonymous enum

◆ TCurrent

◆ TPriority

◆ TStatus

Constructor & Destructor Documentation

◆ TThread() [1/3]

◆ TThread() [2/3]

◆ TThread() [3/3]

◆ ~TThread()

Member Function Documentation

◆ Exit()

◆ GetExitCode()

◆ GetPriority()

◆ GetStatus()

◆ operator=()

◆ Resume()

◆ SetPriority()

◆ ShouldTerminate()

◆ Sleep()

◆ Start()

◆ Suspend()

◆ Terminate()

◆ TerminateAndWait()

◆ WaitForExit()