#include <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 }
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
typedef TThreadError	ThreadError
Public Member Functions
	TThread (TCurrent)
THandle	Start ()
ulong	Suspend ()
ulong	Resume ()
bool	Sleep (long timeMS, bool alertable=false)
virtual void	Terminate ()
ulong	WaitForExit (ulong timeout=NoLimit)
ulong	TerminateAndWait (ulong timeout=NoLimit)
TStatus	GetStatus () const
uint32	GetExitCode () const
int	GetPriority () const
int	SetPriority (int)
Protected Member Functions
	TThread ()
	TThread (const TThread &)
const TThread &	operator= (const TThread &)
virtual	~TThread ()
bool	ShouldTerminate () const
void	Exit (ulong code)

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.

Member Typedef Documentation

typedef TStatus owl::TThread::Status

For compatibility with old T-less typenames.

Member Enumeration Documentation

enum owl::TThread::TPriority

Enumerator:

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

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.

Constructor & Destructor Documentation

owl::TThread::TThread ( TCurrent )

Attach to a running thread.

owl::TThread::TThread ( ) [protected]

Create a thread. Derived class overrides Run()

Creates an object of type TThread.

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.

owl::TThread::~TThread ( ) [protected, virtual]

TThread destructor.

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

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

Member Function Documentation

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.

References Finished.

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.

bool owl::TFile::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.

Fills status with the status for name. Returns nonzero if successful, 0 otherwise.

Note:: This is only available when OWL has been compiled with OWL5_COMPAT defined. The TFileName class should be used instead.

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.

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

ulong owl::TThread::Resume ( )

Resumes execution of a suspended thread.

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

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

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

Can pass a TPriority for simplicity.

Sets the priority of the thread.

bool owl::TThread::ShouldTerminate ( ) const [inline, protected]

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.

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.

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.

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

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.

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

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().

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.

References Terminate(), and 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.

References Running.

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

D:/Work/OWLNext/Subversion/branches/632/include/owl/thread.h
D:/Work/OWLNext/Subversion/branches/632/source/owlcore/file.cpp
D:/Work/OWLNext/Subversion/branches/632/source/owlcore/thread.cpp

Classes

Public Types

Public Member Functions

Protected Member Functions

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation