ArThread Class Reference

POSIX/WIN32 thread wrapper class. More...

#include <ArThread.h>

Inherited by ArASyncTask.

Public Types
typedef std::map< ThreadType, ArThread * >	MapType
enum	Status {   STATUS_FAILED =1, STATUS_NORESOURCE, STATUS_NO_SUCH_THREAD, STATUS_INVALID,   STATUS_JOIN_SELF, STATUS_ALREADY_DETATCHED }
typedef pthread_t	ThreadType

Public Member Functions
	ArThread (bool blockAllSignals=true)
	Constructor.
	ArThread (ThreadType thread, bool joinable, bool blockAllSignals=true)
	Constructor - starts the thread.
	ArThread (ArFunctor *func, bool joinable=true, bool blockAllSignals=true)
	Constructor - starts the thread.
virtual void	cancel (void)
	Cancel the thread.
virtual int	create (ArFunctor *func, bool joinable=true, bool lowerPriority=true)
	Create and start the thread.
virtual int	detach (void)
	Detatch the thread so it cant be joined.
bool	getBlockAllSignals (void)
	Do we block all process signals at startup?
virtual ArFunctor *	getFunc (void) const
	Get the functor that the thread runs.
virtual bool	getJoinable (void) const
	Get the joinable status of the thread.
virtual ThreadType	getOSThread (void) const
	Get the underlying os thread type.
pid_t	getPID (void)
virtual bool	getRunning (void) const
	Get the running status of the thread.
virtual bool	getRunningWithLock (void)
	Get the running status of the thread, locking around the variable.
virtual const ThreadType *	getThread (void) const
	Get the underlying thread type.
virtual const char *	getThreadActivity (void)
	Gets a string that describes what the thread is doing NULL if it doesn't know.
virtual const char *	getThreadName (void)
	Gets the name of the thread.
pid_t	getTID (void)
virtual bool	isThreadFinished () const
	Returns whether the thread has been completed and can be deleted. More...
virtual bool	isThreadStarted () const
	Returns whether the thread has been started. More...
virtual int	join (void **ret=NULL)
	Join on the thread.
int	lock (void)
	Lock the thread instance. More...
virtual void	logThreadInfo (void)
	Logs the information about this thread.
virtual void	setRunning (bool running)
	Set the running value on the thread.
virtual void	setThreadName (const char *name)
	Sets the name of the thread.
virtual void	stopRunning (void)
	Stop the thread.
virtual void	threadFinished (void)
	Marks the thread as finished and logs useful debugging information. More...
virtual void	threadStarted (void)
	Marks the thread as started and logs useful debugging information. More...
int	tryLock (void)
	Try to lock the thread instance without blocking. More...
int	unlock (void)
	Unlock the thread instance. More...
virtual	~ArThread ()
	Destructor.

Static Public Member Functions
static void	cancelAll (void)
	Cancel all threads.
static ArLog::LogLevel	getLogLevel (void)
	Gets the logging level for thread information.
static ThreadType	getThisOSThread (void)
	Get the underlying os thread type of this thread.
static const ThreadType *	getThisThread (void)
	Get the underlying thread type of this thread.
static const char *	getThisThreadName (void)
	Gets the name of the this thread.
static void	init (void)
	Initialize the internal book keeping structures. More...
static void	joinAll (void)
	Join on all threads.
static ThreadType	osSelf (void)
	Returns the os self of the current thread. More...
static ArThread *	self (void)
	Returns the instance of your own thread (the current one) More...
static void	setLogLevel (ArLog::LogLevel level)
	Sets the logging level for thread information.
static void	shutdown ()
	Shuts down and deletes the last remaining thread; call after joinAll.
static void	stopAll ()
	Stop all threads.
static void	yieldProcessor (void)
	Yield the processor to another thread.

Protected Member Functions
virtual int	doJoin (void **ret=NULL)

Static Protected Member Functions
static void	addThreadToMap (ThreadType pt, ArThread *at)
static ArThread *	findThreadInMap (ThreadType t)
static void	removeThreadFromMap (ThreadType t)

Protected Attributes
bool	myBlockAllSignals
bool	myFinished
ArFunctor *	myFunc
bool	myJoinable
ArMutex	myMutex
std::string	myName
pid_t	myPID
bool	myRunning
	State variable to denote when the thread should continue or exit.
bool	myStarted
ArStrMap	myStrMap
ThreadType	myThread
pid_t	myTID

Static Protected Attributes
static ArLog::LogLevel	ourLogLevel = ArLog::Verbose
static MapType	ourThreads
static ArMutex	ourThreadsMutex
static std::string	ourUnknownThreadName = "unknown"

Detailed Description

POSIX/WIN32 thread wrapper class.

create() will create the thread. That thread will run the given Functor.

A thread can either be in a detached state or a joinable state. If the thread is in a detached state, that thread can not be join()'ed upon. The thread will simply run until the program exits, or its function exits. A joinable thread means that another thread and call join() upon it. If this function is called, the caller will block until the thread exits its function. This gives a way to synchronize upon the lifespan of threads.

Calling cancel() will cancel the thread.

The static function self() will return a thread

See also

ArASyncTask which provides a different approach with a simpler interface.

Member Enumeration Documentation

Status

enum ArThread::Status

Enumerator
STATUS_FAILED	Failed to create the thread.
STATUS_NORESOURCE	Not enough system resources to create the thread.
STATUS_NO_SUCH_THREAD	The thread can no longer be found.
STATUS_INVALID	Thread is detached or another thread is joining on it.
STATUS_JOIN_SELF	Thread is your own thread. Can't join on self.
STATUS_ALREADY_DETATCHED	Thread is already detatched.

Member Function Documentation

init()

void ArThread::init ( void  )

static

Initialize the internal book keeping structures.

Initializes the internal structures which keep track of what thread is what.

This is called by Aria::init(), so the user will not normaly need to call this function themselves. This funtion must be called from the main thread of the application. In otherwords, it should be called by main().

isThreadFinished()

bool ArThread::isThreadFinished ( ) const

virtual

Returns whether the thread has been completed and can be deleted.

This is dependent on the thread implementation calling the threadFinished() method.

isThreadStarted()

bool ArThread::isThreadStarted ( ) const

virtual

Returns whether the thread has been started.

This is dependent on the thread implementation calling the threadStarted() method.

lock()

int ArThread::lock ( void  )

inline

Lock the thread instance.

Java and Python Wrappers: Not available in Java or Python wrapper libraries.

osSelf()

ArThread::ThreadType ArThread::osSelf ( void  )

static

Returns the os self of the current thread.

This returns the OS thread, and should be used in place of self if its being used a lot.

self()

ArThread * ArThread::self ( void  )

static

Returns the instance of your own thread (the current one)

If a newly created thread calls self() on itself too soon, this will return NULL.

This is due to the fact that the thread is first created and started. Then the operating system returns the thread ID and thread that called create() then updates the list of threads with the new thread ID. There is just not much that can be done about that. The use should be aware of this caveat.

Note that this does a lookup on the thread map, so it might be a little slow, if you need to use this a lot you should probably use osSelf instead.

threadFinished()

void ArThread::threadFinished ( void  )

virtual

Marks the thread as finished and logs useful debugging information.

This method should be called after the main thread loop ends. It enables the creator of the thread to determine that the thread has actually been completed and can be deleted.

12/3/2012 MPL Taking this out since it should be set already

threadStarted()

void ArThread::threadStarted ( void  )

virtual

Marks the thread as started and logs useful debugging information.

If you call this function in your functor (ie runThread) it'll then call some things for logging (to make debugging easier) This method should be called before the main thread loop begins.

tryLock()

int ArThread::tryLock ( void  )

inline

Try to lock the thread instance without blocking.

Java and Python Wrappers: Not available in Java or Python wrapper libraries.

unlock()

int ArThread::unlock ( void  )

inline

Unlock the thread instance.

Java and Python Wrappers: Not available in Java or Python wrapper libraries.

---

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

• ArThread.h
• ArThread.cpp
• ArThread_LIN.cpp
• ArThread_WIN.cpp