UThreadNode Class Reference

#include <UThreadNode.h>

Inherited by UAudioPlayerTone, UAudioRecorder, UEventDispatcher, UEventsManager, and UObjDeletionThread< T >.

List of all members.

Public Types
enum	Priority
Public Member Functions
	UThreadNode (Priority priority=kPNormal)
virtual	~UThreadNode ()
void	start ()
void	kill ()
void	join (bool killFirst=false)
void	setPriority (Priority priority)
void	setAffinity (int cpu=0)
bool	isCreating () const
bool	isRunning () const
bool	isIdle () const
bool	isKilled () const
Private Member Functions
	DEPRECATED (virtual void startInit())
virtual void	mainLoopBegin ()
virtual void	mainLoop ()=0
	DEPRECATED (virtual void killCleanup())
virtual void	mainLoopKill ()
virtual void	mainLoopEnd ()

---

Detailed Description

The class UThreadNode is an abstract class for creating thread objects. A UThreadNode provides methods to create threads as an object-style fashion.

For most of inherited classes, only mainLoop() needs to be implemented, then only start() needs to be called from the outside. The main loop is called until the thread itself calls kill() or another thread calls kill() or join() (with parameter to true) on this thread. Unlike kill(), join() is a blocking call: the calling thread will wait until this thread has finished, thus join() must not be called inside the mainLoop().

If inside the mainLoop(), at some time, the thread needs to wait on a mutex/semaphore (like for the acquisition of a resource), the function mainLoopKill() should be implemented to release the mutex/semaphore when the thread is killed, to avoid a deadlock. The function killCleanup() is called after the thread's state is set to kSKilled. After the mutex/semaphore is released in killCleanup(), on wake up, the thread can know if it needs to stop by calling isKilled().

To do an initialization process (executed by the worker thread) just one time before entering the mainLoop(), mainLoopBegin() can be implemented.

Example:

 #include "utilite/UThreadNode.h"
 class SimpleThread : public UThreadNode
 {
 public:
        SimpleThread() {}
        virtual ~SimpleThread() {
                // The calling thread will wait until this thread has finished.
                this->join(true);
        }

 protected:
        virtual void mainLoop() {
                // Do some works...

                // This will stop the thread, otherwise the mainLoop() is recalled.
                this->kill();
        }
 };

 int main(int argc, char * argv[])
 {
        SimpleThread t;
        t.start();
        t.join(); // Wait until the thread has finished.
        return 0;
 }

See also:

start()

kill()

join()

mainLoopBegin()

mainLoopKill()

mainLoop()

---

Member Enumeration Documentation

enum UThreadNode::Priority

Enum of priorities : kPLow, kPBelowNormal, kPNormal, kPAboveNormal, kPRealTime.

---

Constructor & Destructor Documentation

UThreadNode::UThreadNode

(

Priority

priority = kPNormal

)

The constructor.

See also:

Priority

Parameters:

priority

the thread priority

UThreadNode::~UThreadNode

(

)

[virtual]

The destructor. Inherited classes must call join(true) inside their destructor to avoid memory leaks where the underlying c-thread is still running.

Note: not safe to delete a thread while other threads are joining it.

---

Member Function Documentation

UThreadNode::DEPRECATED

(

virtual void

startInit()

)

[inline, private]

Virtual method startInit(). User can implement this function to add a behavior before the main loop is started. It is called once.

Deprecated:

implement mainLoopInit() instead.

UThreadNode::DEPRECATED

(

virtual void

killCleanup()

)

[inline, private]

Virtual method killCleanup(). User can implement this function to add a behavior before the thread is killed. When this function is called, the state of the thread is set to kSKilled. It is useful to wake up a sleeping thread to finish his loop and to avoid a deadlock.

Deprecated:

implement mainLoopKill() instead.

bool UThreadNode::isCreating

(

)

const

Returns:

if the state of the thread is kSCreating (after start() is called but before entering the mainLoop()).

bool UThreadNode::isIdle

(

)

const

Returns:

if the state of the thread is kSIdle (before start() is called and after the thread is totally killed (or after join(true))).

bool UThreadNode::isKilled

(

)

const

Returns:

if the state of the thread is kSKilled (after kill() is called and before the thread is totally killed).

bool UThreadNode::isRunning

(

)

const

Returns:

if the state of the thread is kSRunning (it is executing the mainLoop()) or kSCreating.

void UThreadNode::join

(

bool

killFirst = false

)

The caller thread will wait until the thread has finished.

Note : blocking call

Parameters:

killFirst

if you want kill() to be called before joining (default false), otherwise not.

void UThreadNode::kill

(

)

Kill the thread. This functions does nothing if the thread is not started or is killed.

Note : not a blocking call

virtual void UThreadNode::mainLoop

(

)

[private, pure virtual]

Pure virtual method mainLoop(). The inner loop of the thread. This method is called repetitively until the thread is killed. Note that if kill() is called in mainLoopBegin(), mainLoop() is not called, terminating immediately the thread.

See also:

mainLoop()

kill()

Implemented in UEventsManager, UObjDeletionThread< T >, UAudioRecorderMic, UAudioPlayerTone, UAudioRecorderFile, and UEventDispatcher.

void UThreadNode::mainLoopBegin

(

)

[private, virtual]

Virtual method mainLoopBegin(). User can implement this function to add a behavior before the main loop is started. It is called once (before entering mainLoop()).

Reimplemented in UAudioRecorderMic, UAudioPlayerTone, and UAudioRecorderFile.

virtual void UThreadNode::mainLoopEnd

(

)

[inline, private, virtual]

Virtual method mainLoopEnd(). User can implement this function to add a behavior after the thread is killed (after exiting the mainLoop(), work is still done in the thread before exiting).

Reimplemented in UAudioRecorder, UAudioRecorderMic, and UAudioRecorderFile.

void UThreadNode::mainLoopKill

(

)

[private, virtual]

Virtual method mainLoopKill(). User can implement this function to add a behavior before the thread is killed. When this function is called, the state of the thread is set to kSKilled. It is useful to wake up a sleeping thread to finish his loop and to avoid a deadlock.

Reimplemented in UAudioPlayerTone.

void UThreadNode::setAffinity

(

int

cpu = 0

)

Set the thread affinity. This is applied during start of the thread.

MAC OS X : http://developer.apple.com/library/mac/#releasenotes/Performance/RN-AffinityAPI/_index.html.

Parameters:

cpu	the cpu id (start at 1), 0 means no affinity (default).

void UThreadNode::setPriority

(

Priority

priority

)

Set the thread priority.

Parameters:

priority

the priority

void UThreadNode::start

(

)

Start the thread. Once the thread is started, subsequent calls to start() are ignored until the thread is killed.

See also:

kill()

---

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

• include/utilite/UThreadNode.h
• src/UThreadNode.cpp