System::Thread Class Reference

A thread of execution in a program. More...

#include <B2BITS_Thread.h>

Public Types
enum	Priority {   DefaultPriority , IdlePriority , LowestPriority , LowPriority ,   NormalPriority , HighPriority , HighestPriority , RealtimePriority }
	Thread priority. More...
typedef void(*	ThreadListener) ()

Public Member Functions
virtual void	cancel ()
	Requests that thread to be canceled.
void	destroyOnExit (bool value) throw ()
	Set to true to destroy thread on exit.
bool	equals (ThreadId thrId)
ThreadId	getId () const
	Returns thread's id.
std::string const &	getName () const
	Returns the thread's name.
void	join ()
	Waits for this thread to terminate.
bool	join (unsigned int milliseconds)
	Waits for this thread to terminate.
void	setAffinity (const System::affinity256_t &mask) throw ()
	Sets CPU affinity.
void	setPriority (Priority p) throw ()
	Sets thread priority.
virtual void	start ()
	Causes this thread to begin execution.
	Thread (bool setExTranslator=true)
	Constructor.
	Thread (const char *pName, bool setExTranslator=true)
	Constructor.
	Thread (const std::string &aName, bool setExTranslator=true)
void	updateName (std::string const &name)
	Update thread name before starting.
virtual	~Thread ()
	Destructor.

Static Public Member Functions
static void	callThreadStartListener () throw ()
static void	callThreadStopListener () throw ()
static void	getSelfName (std::string &res)
	get name of the current thread
static ThreadListener	getThreadStartListener () throw ()
static ThreadListener	getThreadStopListener () throw ()
static u64	prepareUSleep (unsigned int delayUs) throw ()
	Calculates uSleepDelay value based on given microsecond time span.
static ThreadId	self ()
	Returns the thread ID of the calling thread.
static void	setCurrentThreadAffinity (const System::affinity256_t &mask)
	Sets CPU affinity for current thread.
static void	setCurrentThreadPriority (Priority p)
	Sets priority for current thread.
static void	setName (char const *name)
	Gives name to the current thread.
static void	setThreadStartListener (ThreadListener listener) throw ()
static void	setThreadStopListener (ThreadListener listener) throw ()
static bool	sleep (unsigned int aMillis)
	Causes the currently executing thread to sleep for the specified number of milliseconds.
static void	uSleep (u64 uSleepDelay) throw ()
	Performs busy wait using Thread::yield method.
static void	yield () throw ()
	Causes the currently executing thread object to temporarily pause and allow other threads to execute.

Protected Types
enum	CancellationType { DISABLED , DEFERRED , ASYNCHRONOUS }

Protected Member Functions
void	afterRun ()
void	beforeRun ()
virtual void	run ()=0
	Thread's start function.
void	setCancelMode (CancellationType aMode)
	Sets thread's cancellation mode.

Detailed Description

A thread of execution in a program.

Member Typedef Documentation

ThreadListener

typedef void(* System::Thread::ThreadListener) ()

Member Enumeration Documentation

CancellationType

enum System::Thread::CancellationType

protected

Enumerator
DISABLED
DEFERRED
ASYNCHRONOUS

Priority

enum System::Thread::Priority

Thread priority.

Enumerator
DefaultPriority
IdlePriority	not set, use OS default
LowestPriority	Idle thread priority.
LowPriority	Lower than LowPriority.
NormalPriority	Lower than NormalPriority.
HighPriority	Normal thread priority.
HighestPriority	Higher than NormalPriority.
RealtimePriority	Higher than HighPriority. Realtime thread priority

Constructor & Destructor Documentation

Thread() [1/3]

System::Thread::Thread ( bool setExTranslator = true )

explicit

Constructor.

When a new thread is created, it does not begin immediate execution.

Parameters

setExTranslator

- valid for the Windows platform only. When true SEH exceptions will be translated into the Utils::Exception.

Exceptions

SystemException

See also

start()

Thread() [2/3]

System::Thread::Thread ( const char * pName, bool setExTranslator = true )

explicit

Constructor.

When a new thread is created, it does not begin immediate execution.

Parameters

pName	- Thread name
setExTranslator	- valid for the Windows platform only. When true SEH exceptions will be translated into the Utils::Exception.

Exceptions

SystemException

See also

start()

Thread() [3/3]

System::Thread::Thread ( const std::string & aName, bool setExTranslator = true )

explicit

~Thread()

virtual System::Thread::~Thread ( )

virtual

Destructor.

Member Function Documentation

afterRun()

void System::Thread::afterRun ( )

protected

beforeRun()

void System::Thread::beforeRun ( )

protected

callThreadStartListener()

static void System::Thread::callThreadStartListener ( ) throw (  )

inlinestatic

callThreadStopListener()

static void System::Thread::callThreadStopListener ( ) throw (  )

inlinestatic

cancel()

virtual void System::Thread::cancel ( )

virtual

Requests that thread to be canceled.

Cancellation is asynchronous. Use join() to wait for termination of thread if necessary. You should never use cancellation unless you really want the target thread to go away. This is a termination mechanism.

Exceptions

SystemException

See also

"cancellation (3THR)"

destroyOnExit()

void System::Thread::destroyOnExit ( bool value ) throw (  )

inline

Set to true to destroy thread on exit.

equals()

bool System::Thread::equals

(

ThreadId

thrId

)

Returns

True if thread IDs equals, false otherwise.

getId()

ThreadId System::Thread::getId ( ) const

inline

Returns thread's id.

getName()

std::string const & System::Thread::getName ( ) const

inline

Returns the thread's name.

getSelfName()

static void System::Thread::getSelfName ( std::string & res )

static

get name of the current thread

getThreadStartListener()

static ThreadListener System::Thread::getThreadStartListener ( ) throw (  )

static

getThreadStopListener()

static ThreadListener System::Thread::getThreadStopListener ( ) throw (  )

static

join() [1/2]

void System::Thread::join

(

)

Waits for this thread to terminate.

Exceptions

SystemException

join() [2/2]

bool System::Thread::join

(

unsigned int

milliseconds

)

Waits for this thread to terminate.

Parameters

milliseconds

- timeout in milliseconds

Exceptions

SystemException

prepareUSleep()

static u64 System::Thread::prepareUSleep ( unsigned int delayUs ) throw (  )

static

Calculates uSleepDelay value based on given microsecond time span.

Value should be passed to Thread::uSleep method. This method was intended to minimize overhead of Thread::uSleep.

Parameters

delayUs

Delay. Microseconds. Can be zero.

run()

virtual void System::Thread::run ( )

protectedpure virtual

Thread's start function.

Subclasses of Thread should override this method.

self()

static ThreadId System::Thread::self ( )

static

Returns the thread ID of the calling thread.

setAffinity()

void System::Thread::setAffinity	(	const System::affinity256_t &	mask	)
throw	(	)

Sets CPU affinity.

There is no waranty for this method.

setCancelMode()

void System::Thread::setCancelMode ( CancellationType aMode )

protected

Sets thread's cancellation mode.

Exceptions

SystemException

setCurrentThreadAffinity()

static void System::Thread::setCurrentThreadAffinity ( const System::affinity256_t & mask )

static

Sets CPU affinity for current thread.

Parameters

mask	Affinity mask for calling thread.

setCurrentThreadPriority()

static void System::Thread::setCurrentThreadPriority ( Priority p )

static

Sets priority for current thread.

Parameters

p	priority for calling thread.

setName()

static void System::Thread::setName ( char const * name )

static

Gives name to the current thread.

Parameters

name

New name

setPriority()

void System::Thread::setPriority	(	Priority	p	)
throw	(	)

Sets thread priority.

There is no waranty for this method.

setThreadStartListener()

static void System::Thread::setThreadStartListener ( ThreadListener listener ) throw (  )

static

setThreadStopListener()

static void System::Thread::setThreadStopListener ( ThreadListener listener ) throw (  )

static

sleep()

static bool System::Thread::sleep ( unsigned int aMillis )

static

Causes the currently executing thread to sleep for the specified number of milliseconds.

It is a cancellation point.

Returns

true if the method was interrupted by a signal, false otherwise.

Exceptions

SystemException

start()

virtual void System::Thread::start ( )

virtual

Causes this thread to begin execution.

Exceptions

SystemException

updateName()

void System::Thread::updateName ( std::string const & name )

inline

Update thread name before starting.

Parameters

name	- new name to be assigned to the thread

uSleep()

static void System::Thread::uSleep ( u64 uSleepDelay ) throw (  )

static

Performs busy wait using Thread::yield method.

Methods blocks execution on given uSleepDelay time, which is calculated by Thread::prepareUSleep method.

Parameters

uSleepDelay

Delay value which is calculated by Thread::prepareUSleep method.

yield()

static void System::Thread::yield ( ) throw (  )

static

Causes the currently executing thread object to temporarily pause and allow other threads to execute.

Warning

This function can cause 100% CPU usage. If it your case, you can replace it with System::Thread::sleep(1).

Exceptions

SystemException