#include <UThread.h>

Inheritance diagram for UThread:

[legend]

Public Types
enum	Priority { kPLow, kPBelowNormal, kPNormal, kPAboveNormal, kPRealTime }

Public Types inherited from UThreadC< void >
typedef THREAD_HANDLE	Handle

typedef THREAD_HANDLE	Handle

typedef void(*	Handler) ()

typedef void(*	Handler) ()

Public Member Functions
Handle	getThreadHandle () const

unsigned long	getThreadId () const

bool	isCreating () const

bool	isIdle () const

bool	isKilled () const

bool	isRunning () const

void	join (bool killFirst=false)

void	kill ()

void	setAffinity (int cpu=0)

void	setPriority (Priority priority)

void	start ()

	UThread (Priority priority=kPNormal)

virtual	~UThread ()

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 (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 (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

virtual	~UThreadC ()

virtual	~UThreadC ()

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	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	Detach (const Handle &H)

static int	Detach (Handle H)

static int	Join (const Handle &H)

static int	Join (Handle H)

static int	Kill (const Handle &H)

static int	Kill (Handle H)

Private Types
enum	State { kSIdle, kSCreating, kSRunning, kSKilled }

Private Member Functions
void	applyAffinity ()

void	applyPriority ()

int	Create (Handle *const &H=0, const bool &CreateDetached=false, const unsigned int &StackSize=0, const bool &CancelEnable=false, const bool &CancelAsync=false) const

virtual void	mainLoop ()=0

virtual void	mainLoopBegin ()

virtual void	mainLoopEnd ()

virtual void	mainLoopKill ()

void	operator= (UThread &)

void	ThreadMain ()

	UThread (const UThread &)

Static Private Member Functions
static int	Detach (Handle H)

static int	Join (Handle H)

static int	Kill (Handle H)

Private Attributes
int	cpuAffinity_

Handle	handle_

UMutex	killSafelyMutex_

Priority	priority_

UMutex	runningMutex_

State	state_

unsigned long	threadId_

Additional Inherited Members
Protected Member Functions inherited from UThreadC< void >
	UThreadC ()

	UThreadC ()

Static Protected Member Functions inherited from UThreadC< void >
static void	Exit ()

static void	Exit ()

static Handle	Self ()

static int	Self ()

static void	TestCancel ()

static void	TestCancel ()

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.

Enumerator
kPLow
kPBelowNormal
kPNormal
kPAboveNormal
kPRealTime

Definition at line 92 of file UThread.h.

◆ State

enum UThread::State

private

Enumerator
kSIdle
kSCreating
kSRunning
kSKilled

Definition at line 260 of file UThread.h.

Constructor & Destructor Documentation

◆ UThread() [1/2]

UThread::UThread ( Priority priority = kPNormal )

The constructor.

See also: Priority

Parameters

priority the thread priority

Definition at line 33 of file UThread.cpp.

◆ ~UThread()

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.

Definition at line 41 of file UThread.cpp.

◆ UThread() [2/2]

UThread::UThread ( const UThread & )

inlineprivate

Definition at line 257 of file UThread.h.

Member Function Documentation

◆ applyAffinity()

void UThread::applyAffinity ( )

private

Definition at line 208 of file UThread.cpp.

◆ applyPriority()

void UThread::applyPriority ( )

private

Definition at line 162 of file UThread.cpp.

◆ Create()

int UThread::Create	(	Handle *const &	H = `0`,
		const bool &	CreateDetached = `false`,
		const unsigned int &	StackSize = `0`,
		const bool &	CancelEnable = `false`,
		const bool &	CancelAsync = `false`
	)		const

private

◆ currentThreadId()

static unsigned long UThread::currentThreadId ( )

inlinestatic

Definition at line 96 of file UThread.h.

◆ Detach()

static int UThread::Detach ( Handle H )

inlinestaticprivate

Definition at line 252 of file UThread.h.

◆ 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.

◆ isCreating()

bool UThread::isCreating ( ) const

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

Definition at line 240 of file UThread.cpp.

◆ 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))).

Definition at line 250 of file UThread.cpp.

◆ 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).

Definition at line 255 of file UThread.cpp.

◆ isRunning()

bool UThread::isRunning ( ) const

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

Definition at line 245 of file UThread.cpp.

◆ 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.

Definition at line 85 of file UThread.cpp.

◆ Join()

static int UThread::Join ( Handle H )

inlinestaticprivate

Definition at line 246 of file UThread.h.

◆ 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

Definition at line 48 of file UThread.cpp.

◆ Kill()

static int UThread::Kill ( Handle H )

inlinestaticprivate

Definition at line 249 of file UThread.h.

◆ mainLoop()

virtual void UThread::mainLoop ( )

privatepure 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 rtabmap::PreUpdateThread, rtabmap::DBDriver, UCvMat2QImageThread, rtabmap::SensorCaptureThread, UEventsManager, UObjDeletionThread< T >, rtabmap::RtabmapThread, WifiThread, rtabmap::CompressionThread, rtabmap::IMUThread, rtabmap::OdometryThread, and UEventDispatcher.

◆ mainLoopBegin()

virtual void UThread::mainLoopBegin ( )

inlineprivatevirtual

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 rtabmap::SensorCaptureThread, rtabmap::RtabmapThread, rtabmap::IMUThread, and rtabmap::OdometryThread.

Definition at line 183 of file UThread.h.

◆ mainLoopEnd()

virtual void UThread::mainLoopEnd ( )

inlineprivatevirtual

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).

Definition at line 211 of file UThread.h.

◆ mainLoopKill()

virtual void UThread::mainLoopKill ( )

inlineprivatevirtual

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 rtabmap::SensorCaptureThread, UEventsManager, rtabmap::RtabmapThread, and rtabmap::OdometryThread.

Definition at line 203 of file UThread.h.

◆ operator=()

void UThread::operator= ( UThread & )

inlineprivate

Definition at line 256 of file UThread.h.

◆ 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).

Definition at line 198 of file UThread.cpp.

◆ setPriority()

void UThread::setPriority ( Priority priority )

Set the thread priority.

Parameters

priority the priority

Definition at line 156 of file UThread.cpp.

◆ 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()

Definition at line 122 of file UThread.cpp.

◆ ThreadMain()

void UThread::ThreadMain ( )

privatevirtual

Implements UThreadC< void >.

Definition at line 264 of file UThread.cpp.

Member Data Documentation

◆ cpuAffinity_

int UThread::cpuAffinity_

private

Definition at line 265 of file UThread.h.

◆ handle_

Handle UThread::handle_

private

Definition at line 263 of file UThread.h.

◆ killSafelyMutex_

UMutex UThread::killSafelyMutex_

private

Definition at line 266 of file UThread.h.

◆ priority_

Priority UThread::priority_

private

Definition at line 262 of file UThread.h.

◆ runningMutex_

UMutex UThread::runningMutex_

private

Definition at line 267 of file UThread.h.

◆ state_

State UThread::state_

private

Definition at line 261 of file UThread.h.

◆ threadId_

unsigned long UThread::threadId_

private

Definition at line 264 of file UThread.h.

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

Public Types

Public Member Functions

Static Public Member Functions

Private Types

Private Member Functions

Static Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ Priority

◆ State

Constructor & Destructor Documentation

◆ UThread() [1/2]

◆ ~UThread()

◆ UThread() [2/2]

Member Function Documentation

◆ applyAffinity()

◆ applyPriority()

◆ Create()

◆ currentThreadId()

◆ Detach()

◆ getThreadHandle()

◆ getThreadId()

◆ isCreating()

◆ isIdle()

◆ isKilled()

◆ isRunning()

◆ join()

◆ Join()

◆ kill()

◆ Kill()

◆ mainLoop()

◆ mainLoopBegin()

◆ mainLoopEnd()

◆ mainLoopKill()

◆ operator=()

◆ setAffinity()

◆ setPriority()

◆ start()

◆ ThreadMain()

Member Data Documentation

◆ cpuAffinity_

◆ handle_

◆ killSafelyMutex_

◆ priority_

◆ runningMutex_

◆ state_

◆ threadId_