class PThread

This class defines a thread of execution in the system.

Inheritance:


Public Methods

[more] Overrides from PObject
[more] Control functions
[more] Miscellaneous

Public Members

[more] Construction


Inherited from PObject:

Public Methods

Run Time Type functions

I/O functions

Miscellaneous functions

Public Members

Comparison functions


Documentation

This class defines a thread of execution in the system. A thread is an independent flow of processor instructions. This differs from a process which also embodies a program address space and resource allocation. So threads can share memory and resources as they run in the context of a given process. A process always contains at least one thread. This is reflected in this library by the PProcess class being descended from the PThread class.

The implementation of a thread is platform dependent. Not all platforms support concurrent threads within a process or even concurrent processes! For example, MS-DOS has no form of multi-threading or multi-processing, Microsoft Windows has a cooperative multi-processing but no multi-threading. Unix has full pre-emptive multi-processing but most cannot do multiple threads within that process while some Unix systems and Windows NT have full preemptive proceses and threads.

If a platform does not directly support multiple threads, the library will them using a cooperative co-routine technique. This requires that each thread of execution within a process, voluntarily yields control to other threads. This will occur if the thread is blocked inside an I/O function on a PChannel or when the PThread::Yield() function is explicitly called.

Note that this is cooperative. An endless loop will stop all threads in a process, possibly all processes on some platforms. If a lengthy operation is to take place that does not involve blocking I/O, eg pure computation or disk file I/O, then it is the responsiblity of the programmer to assure enough yielding for background threads to execute.

o Construction

oenum Priority
Codes for thread priorities

o LowestPriority
Will only run if all other threads are blocked

o LowPriority
Runs approximately half as often as normal

o NormalPriority
Normal priority for a thread

o HighPriority
Runs approximately twice as often as normal

o HighestPriority
Is only thread that will run, unless blocked

oenum AutoDeleteFlag
Codes for thread autodelete flag

o AutoDeleteThread
Automatically delete thread object on termination

o NoAutoDeleteThread
Don't delete thread as it may not be on heap

o PThread( PINDEX stackSize, AutoDeleteFlag deletion = AutoDeleteThread, Priority priorityLevel = NormalPriority, const PString & threadName = PString::Empty() )
Create a new thread instance. Unless the startSuspended parameter is TRUE, the threads Main() function is called to execute the code for the thread.

Note that the exact timing of the execution of code in threads can never be predicted. Thus you you can get a race condition on intialising a descendent class. To avoid this problem a thread is always started suspended. You must call the Resume() function after your descendent class construction is complete.

If synchronisation is required between threads then the use of semaphores is essential.

If the deletion is set to AutoDeleteThread then the PThread is assumed to be allocated with the new operator and may be freed using the delete operator as soon as the thread is terminated or executes to completion (usually the latter).

The stack size specified is not simply in bytes. It is a value that is multiplied by a factor into bytes depending on the target platform. For example a Unix system with a RISC processor may use significantly more stack than an MS-DOS platform. These sizes are normalised to the "stack factor" provided here. For some platforms, eg Windows NT, the stack size is only an initial size and the stack will automatically be increased as required.

Parameters:
stackSize - Size of stack to use for thread.
deletion - Automatically delete PThread instance on termination of thread.
priorityLevel - Initial priority of thread.
threadName - The name of the thread (for Debug/Trace)

o ~PThread()
Destroy the thread, this simply calls the Terminate() function with all its restrictions and penalties. See that function for more information.

Note that the correct way for a thread to terminate is to return from the Main() function.

o Overrides from PObject

ovoid PrintOn( ostream & strm ) const
Standard stream print function. The PObject class has a << operator defined that calls this function polymorphically.
Parameters:
- strm Stream to output text representation

o Control functions

ovirtual void Restart()
Restart a terminated thread using the same stack priority etc that was current when the thread terminated.

If the thread is still running then this function is ignored.

ovirtual void Terminate()
Terminate the thread. It is highly recommended that this is not used except in abnormal abort situations as not all clean up of resources allocated to the thread will be executed. This is especially true in C++ as the destructors of objects that are automatic variables are not called causing at the very least the possiblity of memory leaks.

Note that the correct way for a thread to terminate is to return from the Main() function or self terminate by calling Terminate() within the context of the thread which can then assure that all resources are cleaned up.

ovirtual BOOL IsTerminated() const
Determine if the thread has been terminated or ran to completion.

Returns:
TRUE if the thread has been terminated.

ovoid WaitForTermination() const
Block and wait for the thread to terminate.

Returns:
FALSE if the thread has not terminated and the timeout has expired.

ovirtual void Suspend( BOOL susp = TRUE )
Suspend or resume the thread.

If susp is TRUE this increments an internal count of suspensions that must be matched by an equal number of calls to Resume() or Suspend(FALSE) before the thread actually executes again.

If susp is FALSE then this decrements the internal count of suspensions. If the count is <= 0 then the thread will run. Note that the thread will not be suspended until an equal number of Suspend(TRUE) calls are made.

Parameters:
susp - Flag to suspend or resume a thread.

ovirtual void Resume()
Resume thread execution, this is identical to Suspend(FALSE)

ovirtual BOOL IsSuspended() const
Determine if the thread is currently suspended. This checks the suspension count and if greater than zero returns TRUE for a suspended thread.

Returns:
TRUE if thread is suspended.

ostatic void Sleep( const PTimeInterval & delay )
Suspend the current thread for the specified amount of time.
Parameters:
- delay Time interval to sleep for.

ovirtual void SetPriority( Priority priorityLevel )
Set the priority of the thread relative to other threads in the current process.
Parameters:
priorityLevel - New priority for thread.

ovirtual Priority GetPriority() const
Get the current priority of the thread in the current process.

Returns:
current thread priority.

ovirtual void SetAutoDelete( AutoDeleteFlag deletion = AutoDeleteThread )
Set the flag indicating thread object is to be automatically deleted when the thread ends.
Parameters:
deletion - New auto delete setting.

ovoid SetNoAutoDelete()
Reet the flag indicating thread object is to be automatically deleted when the thread ends

ovirtual PString GetThreadName() const
Get the name of the thread. Thread names are a optional debugging aid.

Returns:
current thread name.

ovirtual void SetThreadName( const PString & name )
Change the name of the thread. Thread names are a optional debugging aid.

Parameters:
name - New name for the thread.
Returns:
current thread name.

o Miscellaneous

ovirtual PThreadIdentifer GetThreadId() const
Get operating system specific thread identifier for this thread

ostatic PThreadIdentifer GetCurrentThreadId()
Get operating system specific thread identifier for current thread

ovirtual void Main() = 0
User override function for the main execution routine of the thread. A descendent class must provide the code that will be executed in the thread within this function.

Note that the correct way for a thread to terminate is to return from this function.

ostatic PThread* Current()
Get the currently running thread object instance. It is possible, even likely, that the smae code may be executed in the context of differenct threads. Under some circumstances it may be necessary to know what the current codes thread is and this static function provides that information.

Returns:
pointer to current thread.

ostatic void Yield()
Yield to another thread. If there are no other threads then this function does nothing. Note that on most platforms the threading is cooperative and this function must be called for other threads to run at all. There may be an implicit call to Yield within the I/O functions of PChannel classes. This is so when a thread is I/O blocked then other threads can, as far as possible, continue to run.

If the platform directly supports multiple threads then this function will do nothing.

ostatic PThread* Create( const PNotifier & notifier, INT parameter = 0, AutoDeleteFlag deletion = AutoDeleteThread, Priority priorityLevel = NormalPriority, const PString & threadName = PString::Empty(), PINDEX stackSize = 10000 )
Create a simple thread executing the specified notifier. This creates a simple PThread class that automatically executes the function defined by the PNotifier in the context of a new thread.
Parameters:
notifier - Function to execute in thread.
parameter - Parameter value to pass to notifier.
deletion - Automatically delete PThread instance on termination of thread.
priorityLevel - Initial priority of thread.
threadName - The name of the thread (for Debug/Trace)
stackSize - Stack size on some platforms


Direct child classes:
PProcess
Friends:
class PProcess
class PSemaphore
class PTrace::Block

Alphabetic index HTML hierarchy of classes or Java



This page was generated with the help of DOC++.