[Home] [Prev] [Next] [Up]


XGThread class

Encapsulates multithreaded support.

Usage:

#include <XThread.h>

class XGThread;

Description

This class provides a mechanism for creating and supporting multiple threads.

Notes

When creating a thread, you should use the 'new' operator. That's because when the thread terminates and detached, the XThread object will be deleted by using the delete operator.

Constructor/Destructors

XGThread::XGThread(XGThreadProcPtr proc, long stack = 0, bool suspend = false)

This creates a thread to execute the procedure pointed to by proc.

proc: Points to a function to execute in this thread. The function itself is declared as:

void XGThreadProc(XGThread *id);

Where id identifies the thread being executed.

stack: optional argument gives the size (in bytes) of the default stack to use. If not provided (or if zero), this will use the system-default stack size.

suspend: if set to true, the thread is created suspended.

You can easily create a thread by firing and forgetting:

new XGThread(MyProc);

If you wish to create a thread and keep a pointer to it (for future status reporting purposes), you need to create the thread in it's suspended state, and attach a pointer to it. This is a three stage process:

XGThread *t = new XGThread(MyProc,0,true);
t->Attach();  // indicate someone else attached
t->Resume();  // start running thread.

Attach/Detach semantics

Normally, when a thread terminates, it deletes itself. This could be bad when a thread terminates but the application code maintains a pointer to that thread: the pointer will wind up being bad.

This implements an 'attach'/'detach' semantics to keep count of the number of owners of the thread object. When that thread count reaches zero (because no-one is attached and the thread termintaes), then the thread object is released to the heap.

void XGThread::Attach(void)

Increment the attach counter by one. When the thread is created, this count is set to 1 to indicate the thread procedure owns the thread.

void XGThread::Detach(void)

Decrement the attach counter by one. If this count reaches zero, the thread object is released to the heap.

long XGThread::GetAttach(void)

Get the current attach count.

Thread management

static XGThread *XGThread::CurrentThread(void)

This returns a pointer to the current thread object. The main thread (the first thread started up when the application is launched) is assigned a global thread object reference just for completeness. This can be used to compare thread pointers to determine (for example) if the current thread is the one I expect to be running.

static void XGThread::YieldThread(bool swap = false)

This yields execution to another thread. This must be called periodically on the Macintosh to implement the cooperative preempting that the Macintosh uses.

The optional parameter indicates to Microsoft Windows that this yield call is being used to help implement preemptive multitasking on the Macintosh. If the parameter is the default "false" value, this won't yield the thread on Windows. If the parameter is "true", the rest of this thread's timeslice on Windows will be yielded to another thread.

Scheduling management

void XGThread::Suspend(void)

Suspend the specified thread. You cannot suspend the main thread.

void XGThread::Resume(void)

Resume execution of the specified thread. Resuming the main thread is illegal.

bool XGThread::IsSuspended(void)

Returns 'true' if the thread specified is suspended.

void XGThread::Kill(void)

Kill the specified thread. Warning: this should only be done under extreme circumstances.

bool XGThread::IsAlive(void)

This returns 'true' if the thread is currently running, and 'false' if the thread has terminated.


[Home] [Prev] [Next] [Up]