The PThread Class


Overview

This class is used to create and handle threads. It's very easy to use, and you only need about 2 lines of code to create and start a thread using this class. To use it, you need to know at least the basic of what threads is.


PThread

Derived from: None

Declared in: PThread.h


PThread Constructor and Destructor


PThread()

          PThread(void);

The constructor initialize the class variables to default values.


~PThread()

          virtual ~PThread(void);

Does nothing.


PThread Member Functions


GetExitCode()

          int32 GetExitCode(void) const;

Do only call this function, when your thread has exited. It will return the number you returned in your thread function with the return keyword.


GetPriority()

          PPriority GetPriority(void) const;

This function will return the threads current priority. See the SetPriority() function for more information.


IsAlive()

          bool IsAlive(void);

This function tests if the thread is alive - that is running. It returns true if the thread is running, or false otherwise.


Kill()

          void Kill(void);
             throw(PSystemException);

If you don't want to be "Mr. Nice Guy", use this function. It will kill your thread the hard way. Notice that there is possiblity of memory loss, if you allocate something in your thread. It won't be deallocated then.


Resume()

          void Resume();
             throw(PSystemException);

If you have suspended your thread with the Suspend() function, you can start it again with this function. Note that you need to call this function the same number of times you called the Suspend() function before your thread will continue to run. Let's take an example: If you called Suspend() 3 times, you need to call Resume() 3 times, before the thread starts to run again.


SetHookFunc()

          void SetHookFunc(PThreadFunc func, void *userData);

You need to call this function before you can start your thread. It tells the class where your new thread has to start. The arguments is a pointer to your function and the argument that will be given to your function. The userData argument can be anything you like. PThread won't touch it. It will just pass it through your own function.

Your thread function has to be with the following prototype:

int32 MyThread(void *userData);

The number you return in your function, can be retrieved later on with the GetExitCode() function.


SetName()

          void SetName(PString name);

If you want to call your new thread something special, call this function before you call the StartThread() function. The argument is the name you want to give your thread. If you don't call this function, your thread will get a default name.


SetPriority()

          void SetPriority(PPriority pri);
             throw(PSystemException);

This function will change your thread priority. If you call this function before you start your thread, your thread will be initialized with the priority you give. If your thread is already running, this function will change the priority of your thread immediately. The priority can be any of the following:

 pIdle  This is the lowest priority of a thread.
 pLow  Low priority.
 pBelowNormal  Almost normal priority.
 pNormal  Normal priority.
 pAboveNormal  A little bit above the normal priority.
 pHigh  High priority.
 pRealTime  Real time priority.

If you don't call this function, your thread will be run in normal priority.


StartThread()

          void StartThread(void);
             throw(PSystemException);

Call this function to start the thread. When this function exit, your new thread will be running at the same time. Before you call this function, you need to tell the class where the new thread has to start with the SetHookFunc() function.


Suspend()

          void Suspend(void);
             throw(PSystemException);

This function will pause your thread. It won't run until you call the Resume() function. It's possible to call Suspend() x number of times without any errors. You just need to call the Resume() an equal number of times before the thread continue to run.


WaitOnThread()

          void WaitOnThread(void) const;
             throw(PSystemException);

This function will first return when your thread exit. If the thread has already existed when you call this function, it will return immediately. If your thread is suspended, this function will wait until it starts to run and then wait until the thread exits. It will be a good idea to call this function, before you destroy the object.


The PolyKit developer documentation.
This documentation was written by Thomas Neumann.
© Copyright 1998-1999 by PolyCode.