G3D::GThread Class Reference

#include <GThread.h>

Public Types
enum	{ NUM_CORES = -100 }
typedef shared_ptr< class GThread >	Ref

Public Member Functions
	GThread (const std::string &name)
virtual	~GThread ()
bool	start (SpawnBehavior behavior=USE_NEW_THREAD)
void	terminate ()
bool	running () const
bool	started () const
bool	completed () const
void	waitForCompletion ()
const std::string &	name ()
Public Member Functions inherited from G3D::ReferenceCountedObject
virtual	~ReferenceCountedObject ()

Static Public Member Functions
static int	numCores ()
static GThreadRef	create (const std::string &name, void(*proc)(void *), void *param=NULL)
template<class Class >
static void	runConcurrently2D (const Vector2int32 &start, const Vector2int32 &upTo, Class *object, void(Class::*method)(int x, int y), int maxThreads=NUM_CORES)
	Iterates over a 2D region using multiple threads and blocks until all threads have completed. More...
template<class Class >
static void	runConcurrently2D (const Vector2int32 &start, const Vector2int32 &upTo, Class *object, void(Class::*method)(int x, int y, int threadID), int maxThreads=NUM_CORES)

Static Public Attributes
static const SpawnBehavior	USE_CURRENT_THREAD = G3D::USE_CURRENT_THREAD
static const SpawnBehavior	USE_NEW_THREAD = G3D::USE_NEW_THREAD

Protected Member Functions
virtual void	threadMain ()=0

Private Types
enum	GStatus { STATUS_CREATED, STATUS_STARTED, STATUS_RUNNING, STATUS_COMPLETED }

Private Member Functions
	GThread (const GThread &)
GThread &	operator= (const GThread &)
bool	operator== (const GThread &)

Static Private Member Functions
static void *	internalThreadProc (void *param)

Private Attributes
volatile GStatus	m_status
pthread_t	m_handle
std::string	m_name

Detailed Description

Platform independent thread implementation. You can either subclass and override GThread::threadMain or call the create method with a method.

Beware of reference counting and threads. If circular references exist between GThread subclasses then neither class will ever be deallocated. Also, dropping all pointers (and causing deallocation) of a GThread does NOT stop the underlying process.

See also

G3D::GMutex, G3D::Spinlock, G3D::AtomicInt32, G3D::ThreadSet

Member Typedef Documentation

typedef shared_ptr<class GThread> G3D::GThread::Ref

Member Enumeration Documentation

anonymous enum

Enumerator
NUM_CORES	Tells GThread::runConcurrently() and GThread::runConcurrently2D() to use System::numCores() threads.

 {
 NUM_CORES = -100
 };

enum G3D::GThread::GStatus

private

Enumerator
STATUS_CREATED
STATUS_STARTED
STATUS_RUNNING
STATUS_COMPLETED

{STATUS_CREATED, STATUS_STARTED, STATUS_RUNNING, STATUS_COMPLETED};

Constructor & Destructor Documentation

G3D::GThread::GThread ( const GThread &  )

private

G3D::GThread::GThread

(

const std::string &

name

)

 :
 m_status(STATUS_CREATED),
 m_name(name) {

#ifdef G3D_WINDOWS
 m_event = NULL;
#endif

 // system-independent clear of handle
 System::memset(&m_handle, 0, sizeof(m_handle));
}

Here is the call graph for this function:

G3D::GThread::~GThread ( )

virtual

 {
#ifdef _MSC_VER
# pragma warning( push )
# pragma warning( disable : 4127 )
#endif
 alwaysAssertM(m_status != STATUS_RUNNING, "Deleting thread while running.");
#ifdef _MSC_VER
# pragma warning( pop )
#endif

#ifdef G3D_WINDOWS
 if (m_event) {
 ::CloseHandle(m_event);
 }
#endif
}

Member Function Documentation

bool G3D::GThread::completed

(

)

const

Returns true if the thread has exited.

 {
 return (m_status == STATUS_COMPLETED);
}

GThreadRef G3D::GThread::create ( const std::string &  name, void(*)(void *)  proc, void *  param = NULL  )

static

Constructs a basic GThread without requiring a subclass.

Parameters

proc	The global or static function for the threadMain()

 {
 return shared_ptr<GThread>(new _internal::BasicThread(name, proc, param));
}

void * G3D::GThread::internalThreadProc ( void *  param )

staticprivate

 {
 GThread* current = reinterpret_cast<GThread*>(param);
 current->m_status = STATUS_RUNNING;
 current->threadMain();
 current->m_status = STATUS_COMPLETED;
 return (void*)NULL;
}

Here is the call graph for this function:

Here is the caller graph for this function:

const std::string& G3D::GThread::name ( )

inline

Returns thread name

 {
 return m_name;
 }

int G3D::GThread::numCores ( )

static

Returns System::numCores(); put here to break a dependence on System.h

 {
 return System::numCores();
}

Here is the call graph for this function:

Here is the caller graph for this function:

GThread& G3D::GThread::operator= ( const GThread &  )

private

bool G3D::GThread::operator== ( const GThread &  )

private

template<class Class >

static void G3D::GThread::runConcurrently2D ( const Vector2int32 &  start, const Vector2int32 &  upTo, Class *  object, void(Class::*)(int x, int y)  method, int  maxThreads = NUM_CORES  )

inlinestatic

Iterates over a 2D region using multiple threads and blocks until all threads have completed.

Evaluates object->method(x, y) for every start.x <= x < upTo.x and start.y <= y < upTo.y. Iteration is row major, so each thread can expect to see successive x values.

Parameters

maxThreads

Maximum number of threads to use. By default at most one thread per processor core will be used.

Example:

class RayTracer {
public:
 void trace(const Vector2int32& pixel) {
 ...
 }

 void traceAll() {
 GThread::runConcurrently2D(Point2int32(0,0), Point2int32(w,h), this, &RayTracer::trace);
 }
};

 {
 _internal_runConcurrently2DHelper(start, upTo, object, method, static_cast<void (Class::*)(int, int, int)>(NULL), maxThreads);
 }

Here is the call graph for this function:

template<class Class >

static void G3D::GThread::runConcurrently2D ( const Vector2int32 &  start, const Vector2int32 &  upTo, Class *  object, void(Class::*)(int x, int y, int threadID)  method, int  maxThreads = NUM_CORES  )

inlinestatic

Like the other version of runConcurrently2D, but tells the method the thread index that it is running on. That enables the caller to manage per-thread state.

 {
 _internal_runConcurrently2DHelper(start, upTo, object, static_cast<void (Class::*)(int, int)>(NULL), method, maxThreads);
 }

Here is the call graph for this function:

bool G3D::GThread::running

(

)

const

Returns true if threadMain is currently executing. This will only be set when the thread is actually running and might not be set when start() returns.

 {
 return (m_status == STATUS_RUNNING);
}

bool G3D::GThread::start

(

SpawnBehavior

behavior = USE_NEW_THREAD

)

Starts the thread and executes threadMain(). Returns false if the thread failed to start (either because it was already started or because the OS refused).

Parameters

behavior

If USE_CURRENT_THREAD, rather than spawning a new thread, this routine runs threadMain on the current thread.

 {
 
 debugAssertM(! started(), "Thread has already executed.");
 if (started()) {
 return false;
 }

 m_status = STATUS_STARTED;

 if (behavior == USE_CURRENT_THREAD) {
 // Run on this thread
 m_status = STATUS_RUNNING;
 threadMain();
 m_status = STATUS_COMPLETED;
 return true;
 }

# ifdef G3D_WINDOWS
 DWORD threadId;

 m_event = ::CreateEvent(NULL, TRUE, FALSE, NULL);
 debugAssert(m_event);

 m_handle = ::CreateThread(NULL, 0, &internalThreadProc, this, 0, &threadId);

 if (m_handle == NULL) {
 ::CloseHandle(m_event);
 m_event = NULL;
 }

 SetThreadName(threadId, m_name.c_str());

 return (m_handle != NULL);
# else
 if (!pthread_create(&m_handle, NULL, &internalThreadProc, this)) {
 return true;
 } else {
 // system-independent clear of handle
 System::memset(&m_handle, 0, sizeof(m_handle));

 return false;
 }
# endif
}

Here is the call graph for this function:

bool G3D::GThread::started

(

)

const

True after start() has been called, even through the thread may have already completed(), or be currently running().

 {
 return m_status != STATUS_CREATED;
}

Here is the caller graph for this function:

void G3D::GThread::terminate

(

)

Terminates the thread without notifying or waiting for a cancelation point.

 {
 if (m_handle) {
# ifdef G3D_WINDOWS
 ::TerminateThread(m_handle, 0);
# else
 pthread_kill(m_handle, SIGSTOP);
# endif
 // system-independent clear of handle
 System::memset(&m_handle, 0, sizeof(m_handle));
 }
}

Here is the call graph for this function:

virtual void G3D::GThread::threadMain ( )

protectedpure virtual

Overriden by the thread implementor

Implemented in G3D::_internalGThreadWorker< Class >, and G3D::_internal::BasicThread.

Here is the caller graph for this function:

void G3D::GThread::waitForCompletion

(

)

Waits for the thread to finish executing.

 {
 if (m_status == STATUS_COMPLETED) {
 // Must be done
 return;
 }

# ifdef G3D_WINDOWS
 debugAssert(m_event);
 ::WaitForSingleObject(m_event, INFINITE);
# else
 debugAssert(m_handle);
 pthread_join(m_handle, NULL);
# endif
}

Member Data Documentation

pthread_t G3D::GThread::m_handle

private

std::string G3D::GThread::m_name

private

volatile GStatus G3D::GThread::m_status

private

const SpawnBehavior G3D::GThread::USE_CURRENT_THREAD = G3D::USE_CURRENT_THREAD

static

For backwards compatibility to G3D 8.xx

const SpawnBehavior G3D::GThread::USE_NEW_THREAD = G3D::USE_NEW_THREAD

static

For backwards compatibility to G3D 8.xx

---

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

• dep/g3dlite/include/G3D/GThread.h
• dep/g3dlite/source/GThread.cpp