Main Page | Namespace List | Class Hierarchy | Class List | Directories | File List | Class Members | File Members

PThread Class Reference

#include <thread.h>

Inheritance diagram for PThread:

PObject PHTTPServiceThread PProcess PServiceProcess PHTTPServiceProcess PSecureHTTPServiceProcess List of all members.

Construction

enum  Priority {
  LowestPriority, LowPriority, NormalPriority, HighPriority,
  HighestPriority, NumPriorities
}
 Codes for thread priorities. More...
enum  AutoDeleteFlag { AutoDeleteThread, NoAutoDeleteThread }
 Codes for thread autodelete flag. More...
 PThread (PINDEX, AutoDeleteFlag deletion=AutoDeleteThread, Priority priorityLevel=NormalPriority, const PString &threadName=PString::Empty())
 ~PThread ()

Control functions

virtual void Restart ()
virtual void Terminate ()
virtual BOOL IsTerminated () const
void WaitForTermination () const
BOOL WaitForTermination (const PTimeInterval &maxWait) const
virtual void Suspend (BOOL susp=TRUE)
virtual void Resume ()
virtual BOOL IsSuspended () const
virtual void SetPriority (Priority priorityLevel)
virtual Priority GetPriority () const
virtual void SetAutoDelete (AutoDeleteFlag deletion=AutoDeleteThread)
void SetNoAutoDelete ()
virtual PString GetThreadName () const
virtual void SetThreadName (const PString &name)
static void Sleep (const PTimeInterval &delay)
 Suspend the current thread for the specified amount of time.

Miscellaneous

virtual PThreadIdentifier GetThreadId () const
virtual void Main ()=0
static PThreadIdentifier GetCurrentThreadId ()
static PThreadCurrent ()
static void Yield ()
static PThreadCreate (const PNotifier &notifier, INT parameter=0, AutoDeleteFlag deletion=AutoDeleteThread, Priority priorityLevel=NormalPriority, const PString &threadName=PString::Empty(), PINDEX stackSize=10000)

Public Member Functions

int PXBlockOnChildTerminate (int pid, const PTimeInterval &timeout)
int PXBlockOnIO (int handle, int type, const PTimeInterval &timeout)
void PXAbortBlock () const
Overrides from PObject
void PrintOn (ostream &strm) const

Protected Member Functions

void InitialiseProcessThread ()

Friends

class PProcess
class PTrace::Block

Detailed Description

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, but it is assumed that the platform has some support for native threads. Previous versions of PWLib has some support for co-operative threads, but this has been removed


Member Enumeration Documentation

enum PThread::AutoDeleteFlag
 

Codes for thread autodelete flag.

Enumeration values:
AutoDeleteThread  Automatically delete thread object on termination.
NoAutoDeleteThread  Don't delete thread as it may not be on heap.

enum PThread::Priority
 

Codes for thread priorities.

Enumeration values:
LowestPriority  Will only run if all other threads are blocked.
LowPriority  Runs approximately half as often as normal.
NormalPriority  Normal priority for a thread.
HighPriority  Runs approximately twice as often as normal.
HighestPriority  Is only thread that will run, unless blocked.
NumPriorities 


Constructor & Destructor Documentation

PThread::PThread PINDEX  ,
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 argument retained only for source code compatibility for previous implementations. It is not used in the current code and may be removed in subsequent versions.

Parameters:
deletion  Not used - previously stack size
priorityLevel  Automatically delete PThread instance on termination of thread.
threadName  Initial priority of thread. The name of the thread (for Debug/Trace)

PThread::~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.


Member Function Documentation

static PThread* PThread::Create const PNotifier notifier,
INT  parameter = 0,
AutoDeleteFlag  deletion = AutoDeleteThread,
Priority  priorityLevel = NormalPriority,
const PString threadName = PString::Empty(),
PINDEX  stackSize = 10000
[static]
 

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:
parameter  Function to execute in thread.
deletion  Parameter value to pass to notifier.
priorityLevel  Automatically delete PThread instance on termination of thread.
threadName  Initial priority of thread.
stackSize  The name of the thread (for Debug/Trace) Stack size on some platforms

static PThread* PThread::Current  )  [static]
 

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.

Reimplemented in PProcess, PServiceProcess, and PHTTPServiceProcess.

static PThreadIdentifier PThread::GetCurrentThreadId  )  [static]
 

Get operating system specific thread identifier for current thread.

virtual Priority PThread::GetPriority  )  const [virtual]
 

Get the current priority of the thread in the current process.

Returns:
current thread priority.

virtual PThreadIdentifier PThread::GetThreadId  )  const [virtual]
 

Get operating system specific thread identifier for this thread.

virtual PString PThread::GetThreadName  )  const [virtual]
 

Get the name of the thread. Thread names are a optional debugging aid.

Returns:
current thread name.

Reimplemented in PProcess.

void PThread::InitialiseProcessThread  )  [protected]
 

virtual BOOL PThread::IsSuspended  )  const [virtual]
 

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.

virtual BOOL PThread::IsTerminated  )  const [virtual]
 

Determine if the thread has been terminated or ran to completion.

Returns:
TRUE if the thread has been terminated.

virtual void PThread::Main  )  [pure virtual]
 

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.

Implemented in PHTTPServiceThread.

void PThread::PrintOn ostream &  strm  )  const [virtual]
 

Standard stream print function. The PObject class has a << operator defined that calls this function polymorphically.

Parameters:
strm  Stream to output text representation

Reimplemented from PObject.

void PThread::PXAbortBlock  )  const
 

int PThread::PXBlockOnChildTerminate int  pid,
const PTimeInterval timeout
 

int PThread::PXBlockOnIO int  handle,
int  type,
const PTimeInterval timeout
 

virtual void PThread::Restart  )  [virtual]
 

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.

virtual void PThread::Resume  )  [virtual]
 

Resume thread execution, this is identical to #Suspend(FALSE)#.

virtual void PThread::SetAutoDelete AutoDeleteFlag  deletion = AutoDeleteThread  )  [virtual]
 

Set the flag indicating thread object is to be automatically deleted when the thread ends.

Parameters:
deletion  New auto delete setting.

void PThread::SetNoAutoDelete  )  [inline]
 

Reet the flag indicating thread object is to be automatically deleted when the thread ends.

virtual void PThread::SetPriority Priority  priorityLevel  )  [virtual]
 

Set the priority of the thread relative to other threads in the current process.

Parameters:
priorityLevel  New priority for thread.

virtual void PThread::SetThreadName const PString name  )  [virtual]
 

Change the name of the thread. Thread names are a optional debugging aid.

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

Reimplemented in PProcess.

static void PThread::Sleep const PTimeInterval delay  )  [static]
 

Suspend the current thread for the specified amount of time.

Parameters:
delay  Time interval to sleep for.

virtual void PThread::Suspend BOOL  susp = TRUE  )  [virtual]
 

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.

virtual void PThread::Terminate  )  [virtual]
 

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.

Reimplemented in PProcess, and PServiceProcess.

BOOL PThread::WaitForTermination const PTimeInterval maxWait  )  const
 

Parameters:
maxWait  Maximum time to wait for termination.

void PThread::WaitForTermination  )  const
 

Block and wait for the thread to terminate.

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

static void PThread::Yield  )  [static]
 

Yield to another thread without blocking. This duplicates the implicit thread yield that may occur on some I/O operations or system calls.

This may not be implemented on all platforms.


Friends And Related Function Documentation

friend class PProcess [friend]
 

friend class PTrace::Block [friend]
 


The documentation for this class was generated from the following file:
Generated on Mon Feb 21 20:43:17 2005 for PWLib by  doxygen 1.4.1