MThreadWorker Class Reference

Abstract worker thread, the one optimized for doing work outside of the currently running thread. More...

Inheritance diagram for MThreadWorker:

Public Types
typedef void(*	StaticRunFunctionType) (MThreadWorker *)
	Global user redefined function for thread execution. More...

Public Member Functions
virtual void	Start ()
	Create and start the thread by execution of Run virtual function. More...
bool	WaitUntilFinished (bool throwIfError=true, long timeout=-1)
	A request of the thread client to wait until the thread finishes execution. More...
bool	IsRunning () const
	Tells if the background thread is currently running. More...
bool	IsFinished () const
	Legacy method that tells if the thread is not running. More...
MException *	GetExitException ()
	Get the exception with which the thread was finished. More...
const MException *	GetExitException () const
	Get the constant return exception after the thread is finished. More...
virtual void	Run ()=0
	Worker thread abstract running function. More...
Public Member Functions inherited from MThread
virtual	~MThread ()
	Destructor, destroys the thread object.
unsigned long	GetThreadId () const
	Get thread identifier, a number that is guaranteed to be unique per thread.
InternalHandleType	GetInternalHandle () const volatile
	Get thread handle, operating system dependent thread object manipulator.

Static Public Member Functions
static void	StaticRun (MThreadWorker *thread)
	Static runner of the thread that is called for thread execution. More...
static StaticRunFunctionType	GetStaticRunFunction ()
static void	SetStaticRunFunction (StaticRunFunctionType func)
Static Public Member Functions inherited from MThread
static void	Relinquish ()
	Release the rest of our time slice letting the other threads run.

Protected Member Functions
	MThreadWorker ()
	Worker thread constructor. More...
virtual	~MThreadWorker ()
	Destructor, destroys the thread object. More...
Protected Member Functions inherited from MThread
	MThread (InternalHandleType thread=0)
	Operating system dependent internal handle type. More...

Additional Inherited Members
Protected Attributes inherited from MThread
volatile InternalHandleType	m_thread
	Thread handle.

Detailed Description

Abstract worker thread, the one optimized for doing work outside of the currently running thread.

Every thread, child of this class will have to overload the function Run() to specify what exactly the thread should be doing.

For every thread, standard C random number generator is seeded once. On Windows, and when COM support is enabled, COM is initialized. Also, there is a way of statically adding a user defined function to be called at every thread creation, see SetThreadStartFunction().

Member Typedef Documentation

typedef void(* MThreadWorker::StaticRunFunctionType) (MThreadWorker *)

Global user redefined function for thread execution.

This is a hook that can be used in place of default StaticRun function for executing any code that is specific to all threads created by the library. As an example, it can be used to set a per thread crash handler.

Typically, the user defined function will do some custom initialization and then call MThreadWorker::StaticRun, which is the default implementation. It is not recommended to completely replace StaticRun.

Constructor & Destructor Documentation

MThreadWorker::MThreadWorker ( )

protected

Worker thread constructor.

The real worker threads will derive from MThreadWorker, this is why the constructor is protected.

virtual MThreadWorker::~MThreadWorker ( )

protectedvirtual

Destructor, destroys the thread object.

Precondition

There should be no thread running (the thread function should be exited). Otherwise the behavior is undefined, as the function might want to continue using its worker thread object.

Member Function Documentation

MException* MThreadWorker::GetExitException

(

)

Get the exception with which the thread was finished.

If the thread was finished normally with return from Run, this is NULL. Note that the clients should not attempt to delete the returned exception.

Precondition

IsFinished is true, otherwise the exception will notify about improper usage.

const MException* MThreadWorker::GetExitException ( ) const

inline

Get the constant return exception after the thread is finished.

Note that the clients should not attempt to delete the returned exception.

Precondition

IsFinished is true, otherwise the exception will notify about improper usage.

static StaticRunFunctionType MThreadWorker::GetStaticRunFunction ( )

inlinestatic

Statically defined function to call at thread execution.

By default, it is MThreadWorker::StaticRun.

Having it global and static allows applications to employ a hook that alters all threads created by MeteringSDK, which is a convenience for cases such as installing per thread crash handlers.

There is no synchronization available for getting and setting of this function, therefore, the best place to call this method is prior to creation of any thread, such as the first few lines of main function.

Typically, the user defined function will do some custom initialization and then call MThreadWorker::StaticRun, the default implementation. It is not recommended to completely replace StaticRun with the custom code.

bool MThreadWorker::IsFinished ( ) const

inline

Legacy method that tells if the thread is not running.

The name is somewhat misleading as it will return true even if the thread had not run at all. Because of it, use IsRunning instead.

This service can be called by both the worker thread, and its client.

bool MThreadWorker::IsRunning

(

)

const

Tells if the background thread is currently running.

The service can be called by both the worker thread, and its client.

Possible values:

• False : the thread has not run yet, or it has finished.
• True : the worker thread is running

virtual void MThreadWorker::Run ( )

pure virtual

Worker thread abstract running function.

User shall redefine this method to perform desired actions in a separate thread. This is called from StaticRun, or from a custom user defined global thread function in order to perform actions specific to thread.

static void MThreadWorker::SetStaticRunFunction ( StaticRunFunctionType  func )

inlinestatic

Statically defined function to call at thread execution.

By default, it is MThreadWorker::StaticRun.

Having it global and static allows applications to employ a hook that alters all threads created by MeteringSDK, which is a convenience for cases such as installing per thread crash handlers.

There is no synchronization available for getting and setting of this function, therefore, the best place to call this method is prior to creation of any thread, such as the first few lines of main function.

Typically, the user defined function will do some custom initialization and then call MThreadWorker::StaticRun, the default implementation. It is not recommended to completely replace StaticRun with the custom code.

virtual void MThreadWorker::Start ( )

virtual

Create and start the thread by execution of Run virtual function.

This is a client thread call.

Precondition

There is enough resources to create and start a thread, otherwise a system error is thrown.

static void MThreadWorker::StaticRun ( MThreadWorker *  thread )

static

Static runner of the thread that is called for thread execution.

There is a way of overriding this function globally by calling SetCustomStaticRunFunction(). The custom call will typically eventually call StaticRun.

Parameters

thread

Pointer to thread object, self.

bool MThreadWorker::WaitUntilFinished	(	bool	throwIfError = true,
		long	timeout = -1
	)

A request of the thread client to wait until the thread finishes execution.

If the thread finished already, return immediately. If there was no thread created, or it was destroyed, WaitUntilFinished returns true immediately, a success.

This call should be made by the thread client, as it does not make any sense to be called by the worker thread itself.

Parameters

throwIfError	If true, and the worker raised an exception, this exception will be rethrown in the context of the caller of WaitUntilFinished. If the parameter is false, but the error is raised by the worker thread it will be available with GetExitException()/
timeout	Timeout in milliseconds to wait for the thread to finish. NOTE: Some operating systems such as Android does not support timeout parameter, the value will be ignored and the thread will be waited for possibly an unlimited time.