UThread Class Reference

#include <UThread.h>

Inheritance diagram for UThread:

Collaboration diagram for UThread:

Public Types
enum	Priority {   kPLow , kPBelowNormal , kPNormal , kPAboveNormal ,   kPRealTime }
Public Types inherited from UThreadC< void >
typedef THREAD_HANDLE	Handle
typedef void(*	Handler) ()
typedef THREAD_HANDLE	Handle
typedef void(*	Handler) ()

Public Member Functions
	UThread (Priority priority=kPNormal)
virtual	~UThread ()
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
Handle	getThreadHandle () const
unsigned long	getThreadId () const
Public Member Functions inherited from UThreadC< void >
int	Create (Handle *const &H=0, const bool &CreateDetached=false, const unsigned int &StackSize=0, const bool &CancelEnable=false, const bool &CancelAsync=false) const
int	Create (unsigned long &ThreadId, Handle *const &H=0, const bool &CreateDetached=false, const unsigned int &StackSize=0, const bool &CancelEnable=false, const bool &CancelAsync=false) const
int	Create (Handle *const &H=0, const bool &CreateDetached=false, const unsigned int &StackSize=0, const bool &CancelEnable=false, const bool &CancelAsync=false) const
int	Create (unsigned long &ThreadId, Handle *const &H=0, const bool &CreateDetached=false, const unsigned int &StackSize=0, const bool &CancelEnable=false, const bool &CancelAsync=false) const

Static Public Member Functions
static unsigned long	currentThreadId ()
Static Public Member Functions inherited from UThreadC< void >
static int	Create (const Handler &Function, Handle *const &H=0, const bool &CreateDetached=false, const unsigned int &StackSize=0, const bool &CancelEnable=false, const bool &CancelAsync=false)
static int	Join (Handle H)
static int	Kill (Handle H)
static int	Detach (Handle H)
static int	Create (const Handler &Function, Handle *const &H=0, const bool &CreateDetached=false, const unsigned int &StackSize=0, const bool &CancelEnable=false, const bool &CancelAsync=false)
static int	Join (const Handle &H)
static int	Kill (const Handle &H)
static int	Detach (const Handle &H)

Additional Inherited Members
Static Protected Member Functions inherited from UThreadC< void >
static void	Exit ()
static void	TestCancel ()
static Handle	Self ()
static void	Exit ()
static void	TestCancel ()
static int	Self ()

Detailed Description

The class UThread is an abstract class for creating thread objects. A UThread 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/UThread.h"
class SimpleThread : public UThread
{
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()

Definition at line 86 of file UThread.h.

Member Enumeration Documentation

Priority

enum UThread::Priority

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

Definition at line 92 of file UThread.h.

Constructor & Destructor Documentation

UThread()

UThread::UThread

(

Priority

priority = kPNormal

)

The constructor.

See also

Priority

Parameters

priority

the thread priority

~UThread()

virtual UThread::~UThread ( )

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

currentThreadId()

static unsigned long UThread::currentThreadId ( )

inlinestatic

Definition at line 96 of file UThread.h.

start()

void UThread::start

(

)

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

See also

kill()

kill()

void UThread::kill

(

)

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

Note : not a blocking call

join()

void UThread::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.

setPriority()

void UThread::setPriority

(

Priority

priority

)

Set the thread priority.

Parameters

priority

the priority

setAffinity()

void UThread::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).

isCreating()

bool UThread::isCreating

(

)

const

Returns

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

isRunning()

bool UThread::isRunning

(

)

const

Returns

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

isIdle()

bool UThread::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))).

isKilled()

bool UThread::isKilled

(

)

const

Returns

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

getThreadHandle()

Handle UThread::getThreadHandle ( ) const

inline

Definition at line 171 of file UThread.h.

getThreadId()

unsigned long UThread::getThreadId ( ) const

inline

Definition at line 172 of file UThread.h.

---

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

• utilite/include/rtabmap/utilite/UThread.h