All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
PThread Class Referenceabstract

This class defines a thread of execution in the system. More...

`#include <thread.h>`

Inheritance diagram for PThread:

## Classes

struct | Times
| Times for execution of the thread. More...

## Public Member Functions

bool | IsAutoDelete () const
int | PXBlockOnChildTerminate (int pid, const PTimeInterval &timeout)
int | PXBlockOnIO (int handle, int type, const PTimeInterval &timeout)
void | PXAbortBlock () const
Overrides from <code>PObject</code>
void | PrintOn (ostream &strm) const
| Standard stream print function. More...
Public Member Functions inherited from PObject
virtual | ~PObject ()
virtual PObject * | Clone () const
| Create a copy of the class on the heap. More...
virtual PINDEX | HashFunction () const
| This function yields a hash value required by the `PDictionary` class. More...
virtual const char * | GetClass (unsigned ancestor=0) const
| Get the current dynamic type of the object instance. More...
PBoolean | IsClass (const char *cls) const
virtual PBoolean | InternalIsDescendant (const char *clsName) const
| Determine if the dynamic type of the current instance is a descendent of the specified class. More...
virtual Comparison | Compare (const PObject &obj) const
| Compare the two objects and return their relative rank. More...
virtual Comparison | CompareObjectMemoryDirect (const PObject &obj) const
| Determine the byte wise comparison of two objects. More...
bool | operator== (const PObject &obj) const
| Compare the two objects. More...
bool | operator!= (const PObject &obj) const
| Compare the two objects. More...
bool | operator< (const PObject &obj) const
| Compare the two objects. More...
bool | operator> (const PObject &obj) const
| Compare the two objects. More...
bool | operator<= (const PObject &obj) const
| Compare the two objects. More...
bool | operator>= (const PObject &obj) const
| Compare the two objects. More...
virtual void | ReadFrom (istream &strm)
| Input the contents of the object from the stream. More...

## Protected Attributes

bool | m_isProcess
bool | m_autoDelete
PINDEX | m_originalStackSize
PString | m_threadName
PMutex | m_threadNameMutex
PThreadIdentifier | m_threadId

## 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())
| Create a new thread instance. More...
| ~PThread ()
| Destroy the thread, this simply calls the `Terminate()` function with all its restrictions and penalties. More...

## Control functions

virtual void | Restart ()
| Restart a terminated thread using the same stack priority etc that was current when the thread terminated. More...
virtual void | Terminate ()
| Terminate the thread. More...
virtual PBoolean | IsTerminated () const
| Determine if the thread has been terminated or ran to completion. More...
void | WaitForTermination () const
| Block and wait for the thread to terminate. More...
PBoolean | WaitForTermination (const PTimeInterval &maxWait) const
| Block and wait for the thread to terminate. More...
virtual void | Suspend (PBoolean susp=true)
| Suspend or resume the thread. More...
virtual void | Resume ()
| Resume thread execution, this is identical to `Suspend(false)`. More...
virtual PBoolean | IsSuspended () const
| Determine if the thread is currently suspended. More...
virtual void | SetPriority (Priority priorityLevel)
| Set the priority of the thread relative to other threads in the current process. More...
virtual Priority | GetPriority () const
| Get the current priority of the thread in the current process. More...
virtual void | SetAutoDelete (AutoDeleteFlag deletion=AutoDeleteThread)
| Set the flag indicating thread object is to be automatically deleted when the thread ends. More...
void | SetNoAutoDelete ()
| Reet the flag indicating thread object is to be automatically deleted when the thread ends. More...
virtual PString | GetThreadName () const
| Get the name of the thread. More...
virtual void | SetThreadName (const PString &name)
| Change the name of the thread. More...
static void | Sleep (const PTimeInterval &delay)
| Suspend the current thread for the specified amount of time. More...

## Miscellaneous

virtual PThreadIdentifier | GetThreadId () const
| Get operating system specific thread identifier for this thread. More...
bool | GetTimes (Times &times)
| Get the thread execution times. More...
virtual void | Main ()=0
| User override function for the main execution routine of the thread. More...
static PThreadIdentifier | GetCurrentThreadId ()
static PThread * | Current ()
| Get the currently running thread object instance. More...
static void | Yield ()
| Yield to another thread without blocking. More...
static PThread * | Create (const PNotifier &notifier, INT parameter=0, AutoDeleteFlag deletion=AutoDeleteThread, Priority priorityLevel=NormalPriority, const PString &threadName=PString::Empty(), PINDEX stackSize=65536)
| Create a simple thread executing the specified notifier. More...
static PThread * | Create (const PNotifier &notifier, const PString &threadName)

## Additional Inherited Members

Public Types inherited from PObject
enum | Comparison { LessThan = -1, EqualTo = 0, GreaterThan = 1 }
| Result of the comparison operation performed by the `Compare()` function. More...
Static Public Member Functions inherited from PObject
static const char * | Class ()
| Get the name of the class as a C string. More...
static Comparison | InternalCompareObjectMemoryDirect (const PObject *obj1, const PObject *obj2, PINDEX size)
| Internal function caled from CompareObjectMemoryDirect() More...
Protected Member Functions inherited from PObject
| PObject ()
| Constructor for PObject, made protected so cannot ever create one on its own. More...

## 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 PTLib/PWLib have some support for co-operative threads, but this has been removed.

## Member Enumeration Documentation

enum PThread::AutoDeleteFlag

Codes for thread autodelete flag.

Enumerator
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.

Enumerator
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 | Automatically delete PThread instance on termination of thread.
  priorityLevel | Initial priority of thread.
  threadName | 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 = `65536`
| ) |  |

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

  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

Referenced by Create().

static PThread* PThread::Create | ( | const PNotifier & | notifier,
|  | const PString & | threadName
| ) |  |

inline static

Parameters

  notifier | Function to execute in thread.
  threadName | The name of the thread (for Debug/Trace)

References Create(), NoAutoDeleteThread, and NormalPriority.

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.

static PThreadIdentifier PThread::GetCurrentThreadId | ( |  | ) |

static

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

inline virtual

Get operating system specific thread identifier for this thread.

Note that the return value from these functions is only valid if called by the owning thread. Calling this function for another thread that may be terminating is a very bad idea.

References m_threadId.

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.

bool PThread::GetTimes | ( | Times & | times | ) |

Get the thread execution times.

Parameters

  times | Times for thread execution.

bool PThread::IsAutoDelete | ( |  | ) | const

inline

References m_autoDelete.

virtual PBoolean 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 PBoolean 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 PLibraryProcess, PThreadObj2Arg< ObjType, Arg1Type, Arg2Type >, PThreadObj1Arg< ObjType, Arg1Type >, PThreadObj< ObjType >, PThreadObj< PSNMPServer >, PThread3Arg< Arg1Type, Arg2Type, Arg3Type >, PThread2Arg< Arg1Type, Arg2Type >, PThread1Arg< Arg1Type >, PThreadMain, XMPP::BaseStreamHandler, and 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)`.

The Resume() method may be called from within the constructor of a PThread descendant. However, the `Resume()` should be in the constructor of the most descendant class. So, if you have a class B (which is descended of PThread), and a class C (which is descended of B), placing the call to `Resume()` in the constructor of B is unwise.

If you do place a call to `Resume()` in the constructor, it should be at the end of the constructor, after all the other initialisation in the constructor.

The reason the call to `Resume()` should be at the end of the construction process is simple - you want the thread to start when all the variables in the class have been correctly initialised.

Referenced by PThread1Arg< Arg1Type >::PThread1Arg(), PThread2Arg< Arg1Type, Arg2Type >::PThread2Arg(), PThread3Arg< Arg1Type, Arg2Type, Arg3Type >::PThread3Arg(), PThreadMain::PThreadMain(), PThreadObj< PSNMPServer >::PThreadObj(), PThreadObj1Arg< ObjType, Arg1Type >::PThreadObj1Arg(), and PThreadObj2Arg< ObjType, Arg1Type, Arg2Type >::PThreadObj2Arg().

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.

Referenced by SetNoAutoDelete().

void PThread::SetNoAutoDelete | ( |  | ) |

inline

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

References NoAutoDeleteThread, and SetAutoDelete().

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

void PThread::WaitForTermination | ( |  | ) | const

Block and wait for the thread to terminate.

PBoolean PThread::WaitForTermination | ( | const PTimeInterval & | maxWait | ) | const

Block and wait for the thread to terminate.

Returns
  `false` if the thread has not terminated and the timeout has expired, `true` otherwise.

Parameters

  maxWait | Maximum time to wait for termination.

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.

## Member Data Documentation

bool PThread::m_autoDelete

protected

Referenced by IsAutoDelete().

bool PThread::m_isProcess

protected

PINDEX PThread::m_originalStackSize

protected

PThreadIdentifier PThread::m_threadId

protected

Referenced by GetThreadId().

PString PThread::m_threadName

protected

PMutex PThread::m_threadNameMutex

protected

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

- thread.h