cumbia thread implementation More...

#include <cuthread.h>

Inheritance diagram for CuThread:

[legend]

Public Types
enum	Type { CuThreadType = 0 }

Public Member Functions
	CuThread (const std::string &token, CuThreadsEventBridge_I threadEventsBridge, const CuServiceProvider sp, std::vector< CuThreadInterface * > *thv_p)
	builds a new CuThread More...

virtual	~CuThread ()
	the class destructor, deletes the thread and the event bridge More...

void	registerActivity (CuActivity l, CuThreadListener tl)
	Register a new activity on this thread. More...

void	unregisterActivity (CuActivity *l)
	unregister the activity passed as argument from this thread. More...

void	publishProgress (const CuActivity *activity, int step, int total, const CuData &data)
	invoked in CuThread's thread, posts a progress event to the main thread More...

void	publishResult (const CuActivity *activity, const CuData &data)
	invoked in CuThread's thread, posts a result event to main thread More...

void	publishResult (const CuActivity *activity, const std::vector< CuData > &data_list)
	post a result event from the background thread to the main thread More...

void	publishResult (const CuActivity activity, const CuUserData u)
	post a custom user event data to the specified activity More...

bool	matches (const std::string &other_thtok) const
	returns true if this thread token is equal to other_thread_token More...

std::string	getToken () const
	returns the thread token that was specified at construction time More...

void	cleanup ()

int	type () const
	returns 0 More...

void	start ()
	internally used, allocates a new std::thread More...

bool	isRunning ()
	returns true if the thread is running More...

void	onTimeout (CuTimer *sender)

void	wait ()
	wait for the thread to exit More...

void	exit ()
	exit the thread loop gracefully More...

void	postEvent (CuActivity a, CuActivityEvent e)
	sends the event e to the activity a from the main thread to the background More...

void	onEventPosted (CuEventI *event)
	implements onEventPosted from CuThreadsEventBridgeListener interface. Invokes onProgress or onResult on the registered CuThreadListener objects. More...

Public Member Functions inherited from CuThreadInterface
virtual	~CuThreadInterface ()
	interface virtual destructor More...

virtual void	registerActivity (CuActivity l, CuThreadListener tl)=0
	register and start a new activity More...

virtual void	unregisterActivity (CuActivity *l)=0
	unregister and, if required, automatically delete an activity More...

virtual void	publishProgress (const CuActivity *activity, int step, int total, const CuData &d)=0
	post a progress event from the background thread to the main thread More...

virtual void	publishResult (const CuActivity *activity, const CuData &d)=0
	post a result event from the background thread to the main thread More...

virtual void	publishResult (const CuActivity *activity, const std::vector< CuData > &data_list)=0
	post a result event from the background thread to the main thread More...

virtual void	publishResult (const CuActivity activity, const CuUserData u)=0
	post a custom user event data to the specified activity More...

virtual bool	matches (const std::string &other_thread_token) const =0
	Used by the thread factory, this function, given an input data, determines whether this thread is ecuivalent to another thread of the same class for the data. More...

virtual void	cleanup ()=0
	perform clean operations on the class members More...

virtual int	type () const =0
	return an integer to allow rtti More...

virtual void	start ()=0
	method to start the thread in the background More...

virtual bool	isRunning ()=0
	returns true if the thread is running, false otherwise More...

virtual void	wait ()=0
	wait for the thread to exit More...

virtual void	exit ()=0
	gracefully exit the thread More...

virtual void	postEvent (CuActivity , CuActivityEvent )=0
	forward an event to an activity More...

virtual void	onEventPosted (CuEventI *event)=0
	onEventPosted from CuThreadsEventBridgeListener interface. More...

Public Member Functions inherited from CuThreadsEventBridgeListener
virtual	~CuThreadsEventBridgeListener ()

virtual void	onEventPosted (CuEventI *e)=0
	callback on the main thread containing an event proceeding from the background thread More...

Protected Member Functions
virtual void	run ()

Detailed Description

cumbia thread implementation

CuThread offers a C++11 thread implementation that can be used with cumbia. Threads in cumbia applications are usually instantiated and managed by the CuThreadService cumbia service. Please read the introduction to CuThreadService documentation to understand how cumbia deals with them in an application (cuthread_service).

Registering and unregistering activities: One or more activities are registered to the thread with CuThread::registerActivity. Usually, CuThread::registerActivity is not called by the clients. Clients should rely on Cumbia::registerActivity instead. The same goes for CuThread::unregisterActivity and Cumbia::unregisterActivity.

Note: CuThreads are used internally by the library. Clients should not directly deal with them. They would rather write activities.

Publishing results from the background to the foreground: CuThread::publishProgress and CuThread::publishResult, invoked in CuThread's thread, post a progress event and a result event to the main thread, respectively. They are called by clients through CuActivity::publishProgress and CuActivity::publishResult, normally from the init, execute and onExit hooks (see CuActivity documentation)

Thread management: The CuThread::isEquivalent method decides whether this thread's token is equivalent to another token. If so, Cumbia assigns a new activity to this thread, otherwise a new thread is created for the new activity (see also Cumbia::registerActivity, cuthread_service and CuThreadService::getThread ). The thread token can be obtained by CuThread::getToken. A token is assigned in the CuThread constructor and cannot be changed later. The CuThread::start method instantiates a new C++11 std::thread. To gracefully terminate a CuThread, CuThread::exit must be called, followed by CuThread::wait, as done inside Cumbia::finish method.

Thread disposal: When the last activity exits (there are no more activities registered with this thread), the thread leaves its run loop, joins and auto destroys itself.

See also: Please read the documentation of the CuThreadInterface for more details.

Member Enumeration Documentation

◆ Type

enum CuThread::Type

Enumerator
CuThreadType

Constructor & Destructor Documentation

◆ CuThread()

CuThread::CuThread	(	const std::string &	token,
		CuThreadsEventBridge_I *	teb,
		const CuServiceProvider *	sp,
		std::vector< CuThreadInterface * > *	thv_p
	)

builds a new CuThread

Parameters

thread_token	the token associated to the thread
eventsBridge	a CuThreadsEventBridge_I implementation, for example CuThreadsEventBridge (see CuThreadsEventBridgeFactory::createEventBridge) or QThreadsEventBridge, recommended for Qt applications (see QThreadsEventBridgeFactory::createEventBridge)
service_provider	the CuServiceProvider of the application

Thread token: The thread token is used as an id for the thread. When Cumbia::registerActivity is called, the thread token passed as argument is compared to all tokens of all the running CuThreadInterface threads. If two tokens match, the thread with that token is reused for the new activity, otherwise a new thread is dedicated to run the new activity.

◆ ~CuThread()

CuThread::~CuThread ( )

virtual

the class destructor, deletes the thread and the event bridge

The CuThread destructor deletes the thread (std::thread) and the event bridge

References perr.

Member Function Documentation

◆ cleanup()

void CuThread::cleanup ( )

virtual

does nothing

Implements CuThreadInterface.

◆ exit()

void CuThread::exit ( )

virtual

exit the thread loop gracefully

an ExitThreadEvent is queued to the event queue to exit the thread

Implements CuThreadInterface.

◆ getToken()

std::string CuThread::getToken ( ) const

returns the thread token that was specified at construction time

Returns: the CuData specified in the class constructor at creation time

See also: CuThread::CuThread

◆ isRunning()

bool CuThread::isRunning ( )

virtual

returns true if the thread is running

Returns: true if the thread is running

Implements CuThreadInterface.

◆ matches()

bool CuThread::matches ( const std::string & other_thtok ) const

virtual

returns true if this thread token is equal to other_thread_token

Parameters

other_thread_token a CuData that's the token of another thread

Returns: true if this thread was created with a token that equals other_thread_token, false otherwise.

Note: The CuData::operator== is used to perform the comparison between the tokens

Usage: CuThreadService::getThread calls this method to decide wheter to reuse the current thread (if the tokens are equivalent) or create a new one to run a new activity (if this method returns false).

When Cumbia::registerActivity is used to execute a new activity, the thread token passed as input argument is relevant to decide whether the new registered activity must be run in a running thread (if one is found with the same token) or in a new one (no threads found with the token given to CuActivity::registerActivity).

◆ onEventPosted()

void CuThread::onEventPosted ( CuEventI * event )

virtual

implements onEventPosted from CuThreadsEventBridgeListener interface. Invokes onProgress or onResult on the registered CuThreadListener objects.

This method gets a reference to a CuActivityManager through the service provider.

if either a CuEventI::Result or CuEventI::Progress is received, then the addressed CuActivity is extracted by the CuResultEvent and the list of CuThreadListener objects is obtained through CuActivityManager::getThreadListeners. At last either CuThreadListener::onProgress or CuThreadListener::onResult is called.
if CuEventI::CuA_ExitEv event type is received, CuThread becomes aware that a CuActivity has finished, and deletes it if its CuActivity::CuADeleteOnExit flag is set to true.

note: The association between activities, threads and CuThreadListener objects is defined by Cumbia::registerActivity. Please read Cumbia::registerActivity documentation for more details.

Implements CuThreadInterface.

References CuEventI::CuA_ExitEvent, CuEventI::CuA_UnregisterEv, CuEventI::CuProgressEv, CuEventI::CuResultEv, CuEventI::CuThAutoDestroyEv, CuResultEvent::data, CuResultEvent::datalist, CuResultEvent::getActivity(), CuResultEvent::getStep(), CuResultEvent::getTotal(), CuResultEvent::getType(), CuResultEvent::isList(), CuResultEvent::u_data, and wait().

◆ onTimeout()

void CuThread::onTimeout ( CuTimer * sender )

◆ postEvent()

void CuThread::postEvent	(	CuActivity *	a,
		CuActivityEvent *	e
	)

virtual

sends the event e to the activity a from the main thread to the background

Note: This method is used to send an event from the main thread to the background Events from the background are posted to the main thread through the thread event bridge (CuThreadsEventBridge_I)

Parameters

a	the CuActivity that sends the event
e	the CuActivityEvent

Examples: Cumbia calls CuThread::postEvent several times:

Cumbia::setActivityPeriod sends a CuTimeoutChangeEvent event
Cumbia::pauseActivity sends a CuPauseEvent
Cumbia::resumeActivity sends a CuResumeEvent
Cumbia::postEvent barely forwards a user defined CuActivityEvent to the specified activity

There can be situations where clients can call the above listed Cumbia methods. On the other hand, CuThread::postEvent is not normally intended for direct use by clients of this library.

Implements CuThreadInterface.

◆ publishProgress()

void CuThread::publishProgress	(	const CuActivity *	activity,
		int	step,
		int	total,
		const CuData &	data
	)

virtual

invoked in CuThread's thread, posts a progress event to the main thread

Parameters

activity	the addressee of the event
step	the current step of the progress
total	the total number of steps making up the whole work
data	the data to be delivered with the progress event

CuResultEvent is used in conjunction with CuThreadsEventBridge_I::postEvent

Implements CuThreadInterface.

◆ publishResult() [1/3]

void CuThread::publishResult	(	const CuActivity *	a,
		const CuData &	da
	)

virtual

invoked in CuThread's thread, posts a result event to main thread

Parameters

a	the recepient of the event
data	the data to be delivered with the result

CuResultEvent is used in conjunction with CuThreadsEventBridge_I::postEvent

Implements CuThreadInterface.

◆ publishResult() [2/3]

void CuThread::publishResult	(	const CuActivity *	activity,
		const CuUserData *	u
	)

virtual

post a custom user event data to the specified activity

Parameters

activity	the recipient
u	a custom CuUserData derived data

Implements CuThreadInterface.

◆ publishResult() [3/3]

void CuThread::publishResult	(	const CuActivity *	activity,
		const std::vector< CuData > &	data_list
	)

virtual

post a result event from the background thread to the main thread

This lets you send events to the main thread that account for a list of results computed in the background

See CuThread::publishProgress for details

Implements CuThreadInterface.

◆ registerActivity()

void CuThread::registerActivity	(	CuActivity *	l,
		CuThreadListener *	tl
	)

virtual

Register a new activity on this thread.

This is invoked from the main thread. As soon as registerActivity is called, a RegisterActivityEvent is added to the thread event queue and the CuActivity will be soon initialised and executed in the background. (CuActivity::init and CuActivity::execute)

Parameters

l	a CuActivity that is the worker, whose methods are invoked in this background thread.

Implements CuThreadInterface.

References CuActivity::setThreadToken().

◆ run()

void CuThread::run ( )

protectedvirtual

Thread loop

References datos, CuActivity::doExecute(), CuActivity::event(), CuTimeoutChangeEvent::getTimeout(), CuActivityEvent::getType(), i, perr, CuActivity::repeat(), CuTimer::timeout(), and CuActivityEvent::TimeoutChange.

Referenced by start().

◆ start()

void CuThread::start ( )

virtual

internally used, allocates a new std::thread

Note: used internally

return a new instance of std::thread

Implements CuThreadInterface.

References perr, and run().

◆ type()

int CuThread::type ( ) const

virtual

returns 0

Implements CuThreadInterface.

References CuThreadType.

◆ unregisterActivity()

void CuThread::unregisterActivity ( CuActivity * l )

virtual

unregister the activity passed as argument from this thread.

Parameters

l	the CuActivity to unregister from this thread.

An UnRegisterActivityEvent is queued to the thread event queue. When processed, CuActivity::doOnExit is called which in turn calls CuActivity::onExit (in the CuActivity background thread). If the flag CuActivity::CuADeleteOnExit is true, the activity is later deleted (back in the main thread)

Thread: main

Implements CuThreadInterface.

◆ wait()

void CuThread::wait ( )

virtual

wait for the thread to exit

call join on the thread

Implements CuThreadInterface.

Referenced by onEventPosted().

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

Public Types

Public Member Functions

Protected Member Functions

Detailed Description

Member Enumeration Documentation

◆ Type

Constructor & Destructor Documentation

◆ CuThread()

◆ ~CuThread()

Member Function Documentation

◆ cleanup()

◆ exit()

◆ getToken()

◆ isRunning()

◆ matches()

◆ onEventPosted()

◆ onTimeout()

◆ postEvent()

◆ publishProgress()

◆ publishResult() [1/3]

◆ publishResult() [2/3]

◆ publishResult() [3/3]

◆ registerActivity()

◆ run()

◆ start()

◆ type()

◆ unregisterActivity()

◆ wait()