Public Types | Public Member Functions | Private Types | Private Member Functions | Static Private Member Functions | Private Attributes
UThread Class Reference

#include <UThread.h>

Inheritance diagram for UThread:
Inheritance graph
[legend]

List of all members.

Public Types

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

Public Member Functions

Handle getThreadHandle () 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 ()

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 &t)
void ThreadMain ()
 UThread (const UThread &t)

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_

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

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

Enumerator:
kPLow 
kPBelowNormal 
kPNormal 
kPAboveNormal 
kPRealTime 

Definition at line 92 of file UThread.h.

enum UThread::State [private]
Enumerator:
kSIdle 
kSCreating 
kSRunning 
kSKilled 

Reimplemented in rtabmap::RtabmapThread.

Definition at line 254 of file UThread.h.


Constructor & Destructor Documentation

The constructor.

See also:
Priority
Parameters:
prioritythe thread priority

Definition at line 33 of file UThread.cpp.

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::UThread ( const UThread t) [inline, private]

Definition at line 251 of file UThread.h.


Member Function Documentation

void UThread::applyAffinity ( ) [private]

Definition at line 208 of file UThread.cpp.

void UThread::applyPriority ( ) [private]

Definition at line 162 of file UThread.cpp.

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]

Reimplemented from UThreadC< void >.

static int UThread::Detach ( Handle  H) [inline, static, private]

Reimplemented from UThreadC< void >.

Definition at line 246 of file UThread.h.

Handle UThread::getThreadHandle ( ) const [inline]

Definition at line 167 of file UThread.h.

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.

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.

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.

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.

void UThread::join ( bool  killFirst = false)

The caller thread will wait until the thread has finished.

Note : blocking call

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

Definition at line 85 of file UThread.cpp.

static int UThread::Join ( Handle  H) [inline, static, private]

Reimplemented from UThreadC< void >.

Definition at line 242 of file UThread.h.

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.

static int UThread::Kill ( Handle  H) [inline, static, private]

Reimplemented from UThreadC< void >.

Definition at line 244 of file UThread.h.

virtual void UThread::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 rtabmap::PreUpdateThread, UCvMat2QImageThread, UEventsManager, rtabmap::DBDriver, UObjDeletionThread< T >, rtabmap::RtabmapThread, WifiThread, rtabmap::CameraThread, rtabmap::DBReader, rtabmap::CompressionThread, rtabmap::OdometryThread, and UEventDispatcher.

virtual void UThread::mainLoopBegin ( ) [inline, 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 rtabmap::DBReader.

Definition at line 179 of file UThread.h.

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

Definition at line 207 of file UThread.h.

virtual void UThread::mainLoopKill ( ) [inline, 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 UEventsManager, rtabmap::RtabmapThread, and rtabmap::OdometryThread.

Definition at line 199 of file UThread.h.

void UThread::operator= ( UThread t) [inline, private]

Definition at line 250 of file UThread.h.

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:
cputhe cpu id (start at 1), 0 means no affinity (default).

Definition at line 198 of file UThread.cpp.

void UThread::setPriority ( Priority  priority)

Set the thread priority.

Parameters:
prioritythe priority

Definition at line 156 of file UThread.cpp.

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.

void UThread::ThreadMain ( ) [private, virtual]

Implements UThreadC< void >.

Definition at line 264 of file UThread.cpp.


Member Data Documentation

int UThread::cpuAffinity_ [private]

Definition at line 263 of file UThread.h.

Definition at line 257 of file UThread.h.

Definition at line 264 of file UThread.h.

Definition at line 256 of file UThread.h.

Definition at line 265 of file UThread.h.

Definition at line 255 of file UThread.h.

unsigned long UThread::threadId_ [private]

Definition at line 261 of file UThread.h.


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


rtabmap
Author(s): Mathieu Labbe
autogenerated on Fri Aug 28 2015 12:51:43