primary cumbia class where activities are registered and unregistered. Provides access to the cumbia service provider More...

#include <cumbia.h>

Public Types
enum	Type { CumbiaBaseType = 0 , CumbiaUserType = 10 , CumbiaMaxUserType = 256 }

Public Member Functions
	Cumbia ()
	Cumbia class constructor. More...

CuServiceProvider *	getServiceProvider () const

virtual	~Cumbia ()
	the class destructor More...

void	registerActivity (CuActivity activity, CuThreadListener dataListener, const std::string &thread_token, const CuThreadFactoryImplI &thread_factory_impl, const CuThreadsEventBridgeFactory_I &eventsBridgeFactoryImpl)
	registers (adds) an activity to cumbia, links it to a data listener, assigns its execution to an existing thread or a new one according to a thread token More...

void	unregisterActivity (CuActivity *activity)
	unregister an activity from cumbia More...

CuActivity *	findActivity (const CuData &token) const
	Finds an activity with the given token. More...

void	setActivityPeriod (CuActivity *a, int timeout)
	if a timer runs within an activity, change the timeout More...

unsigned long	getActivityPeriod (CuActivity *a) const

void	pauseActivity (CuActivity *a)
	if a timer runs within an activity, pause it More...

void	resumeActivity (CuActivity *a)
	if a timer runs within an activity, resume it More...

void	postEvent (CuActivity a, CuActivityEvent e)
	post an event to an activity More...

void	finish ()
	called from the class destructor, cleans up the Cumbia object More...

virtual int	getType () const
	returns the Cumbia::CumbiaBaseType type More...

void	setThreadTokenGenerator (CuThreadTokenGenI *tg)
	Cumbia::setThreadTokenGenerator install athread token generator that deals with grouping activities into separate threads according to the specific engine implementation. More...

void	removeThreadTokenGenerator ()
	Cumbia::removeThreadTokenGenerator remove the currently installed generator, if any. More...

CuThreadTokenGenI *	getThreadTokenGenerator () const
	Cumbia::getThreadTokenGenerator returns the installed token generator or nullptr if none is installed. More...

const std::string	threadToken (const std::string &in) const
	Cumbia::threadToken returns a thread token that can be used to group threads together. More...

std::vector< CuThreadInterface * > *	threads () const

Detailed Description

primary cumbia class where activities are registered and unregistered. Provides access to the cumbia service provider

A cumbia application will hold a reference to this central class throughout its lifetime, to register and unregister activities and to register and access services. This is achieved creating a Cumbia instance either in the main function, passing it around to objects that need access to it, or in the application's main class (as for example in the main widget of a Qt application). Activities (CuActivity objects) are the main actors of a cumbia application. They execute work in the background, publishing the results to the foreground thread when they are ready. Activities are registered to and unregistered from cumbia.

The cumbia-tango and cumbia-epics modules extend Cumbia to provide extra functionalities.

Functions

Cumbia::registerActivity: a new cumbia activity, CuActivity is registered and bound to a thread listener, CuThreadListener
Cumbia::unregisterActivity an activity is unregistered from cumbia
if an activity is executed periodically, the period can be changed and the timer can be paused and resumed
Cumbia::getServiceProvider returns a pointer to the CuServiceProvider created and managed by Cumbia itself. CuThreadService and CuActivityManager are the two services run by this class.

Example: Read md_src_tutorial_cuactivity for a simple example involving Cumbia and CuActivity

Other examples and tutorials can be found in the cumbia-qtcontrols and qumbia-tango-controls modules that depend on cumbia:

See also

Member Enumeration Documentation

◆ Type

enum Cumbia::Type

Enumerator
CumbiaBaseType	basic Cumbia type
CumbiaUserType	starting value for user defined Cumbia subclasses
CumbiaMaxUserType	upper bound for the Type enumeration

Constructor & Destructor Documentation

◆ Cumbia()

Cumbia::Cumbia ( )

Cumbia class constructor.

instantiates a cumbia service provider, namely CuServiceProvider
registers an instance of the cumbia thread service, CuThreadService, to the service provider
registers an instance of the cumbia activity manager, CuActivityManager, to the service provider

The cumbia service provider is a class member. A pointer to it can be obtained with Cumbia::getServiceProvider. The service provider remains the same throughout the whole application lifetime and is destroyed when the Cumbia object is destroyed (Cumbia::finish)

Please refer to CuServiceProvider, CuThreadService and CuActivityManager documentation for further information.

References CuServices::ActivityManager, CuServices::Thread, and CuServices::Timer.

◆ ~Cumbia()

Cumbia::~Cumbia ( )

virtual

the class destructor

Cleanup is delegated to the Cumbia::finish method

References finish(), and pdelete.

Member Function Documentation

◆ findActivity()

CuActivity * Cumbia::findActivity ( const CuData & token ) const

Finds an activity with the given token.

@token CuData used to find an activity with the token

Returns: a non disposable CuActivity whose token matches token

Note: This is a convenience shortcut to CuActivityManager::find

References CuServices::ActivityManager, and CuActivityManager::find().

◆ finish()

void Cumbia::finish ( )

called from the class destructor, cleans up the Cumbia object

The method does the following:

through the CuThreadService, the list of threads is obtained and for every thread CuThreadInterface::exit and CuThread::wait are called. The thread is finally deleted.
for each thread, hrough the CuActivityManager, a list of activities linked to the thread is obtained and, for each CuActivity, CuActivityManager::removeConnection is called. This unbinds threads from activities and thread listeners (CuThreadListener) from activities (CuActivity). See CuActivityManager::removeConnection. At last, the activity is deleted.
each service from the list of CuServiceI fetched from CuServiceProvider is unregistered from the service provider through CuServiceProvider::unregisterService
if the service had not been registered with the shared option (see CuServiceProvider::registerService), the service is deleted.
the service provider is deleted.
deletes the token generator, if set

References CuActivityManager::activitiesForThread(), CuServices::ActivityManager, CuActivityManager::disconnect(), CuServiceI::getType(), and i.

Referenced by ~Cumbia().

◆ getActivityPeriod()

unsigned long Cumbia::getActivityPeriod ( CuActivity * a ) const

◆ getServiceProvider()

CuServiceProvider * Cumbia::getServiceProvider ( ) const

◆ getThreadTokenGenerator()

CuThreadTokenGenI * Cumbia::getThreadTokenGenerator ( ) const

Cumbia::getThreadTokenGenerator returns the installed token generator or nullptr if none is installed.

See also: setThreadTokenGenerator

Returns: the currently installed CuThreadTokenGenI implementation, null if none is installed.

See also: setThreadTokenGenerator

◆ getType()

int Cumbia::getType ( ) const

virtual

returns the Cumbia::CumbiaBaseType type

Returns: Cumbia::CumbiaBaseTyp

References CumbiaBaseType.

◆ pauseActivity()

void Cumbia::pauseActivity ( CuActivity * a )

if a timer runs within an activity, pause it

Parameters

a	the CuActivity which timer timeout has to be paused

References CuServices::ActivityManager, CuActivityManager::getThread(), and CuThreadInterface::postEvent().

◆ postEvent()

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

post an event to an activity

Parameters

a	a pointer to a CuActivity where the event is dispatched
e	a generic CuActivityEvent to be delivered to the activity

implementation: Through the activity manager service, the thread associated to the activity is fetched and CuThread::postEvent is called

References CuServices::ActivityManager, CuActivityManager::getThread(), and CuThreadInterface::postEvent().

◆ registerActivity()

void Cumbia::registerActivity	(	CuActivity *	activity,
		CuThreadListener *	dataListener,
		const std::string &	thread_token,
		const CuThreadFactoryImplI &	thread_factory_impl,
		const CuThreadsEventBridgeFactory_I &	eventsBridgeFactoryImpl
	)

registers (adds) an activity to cumbia, links it to a data listener, assigns its execution to an existing thread or a new one according to a thread token

Parameters

activity	the new activity to register
dataListener	an implementation of CuThreadListener that will receive updates through the CuThreadListener::onProgress and CuThreadListener::onResult callbacks
thread_token	a CuData used to decide whether the thread where the CuActivity is executed is a new one or it is picked from an existing one with the same token
thread_factory_impl	a const reference to a CuThreadFactoryImplI implementation, such as CuThreadFactoryImpl, that creates CuThread instances.
eventsBridgeFactoryImpl	a const reference to an implementation either of CuThreadsEventBridgeFactory_I, such as Qt's QThreadsEventBridgeFactory, that has to be used in Qt applications (couples CuThread with Qt event loop in QApplication), or CuThreadsEventBridgeFactory, that instantiates CuThreadsEventBridge bridges (for other cumbia, non Qt applications).

This method exploits the CuThreadService to get a thread for the given thread_token. If the thread_token matches the token of a running thread, that thread is used for the activity. Otherwise, CuThreadService will return a new thread that is instantiated through the CuThreadFactoryImplI factory. The new thread will be bridged to the event loop (Qt's or cumbia CuEventLoopService) through the threads event bridge instantiated by the CuThreadsEventBridgeFactory_I passed to registerActivity. Please refer to CuThreadService::getThread documentation for further reading.

The CuActivityManager, another cumbia service (implements CuServiceI and is registered to the CuServiceProvider), will bind together the thread, the activity and the CuThreadListener, by means of CuActivityManager::addConnection.

At last, the thread is started (if not reused and already running) and the new activity is registered to the thread itself (through CuThread::registerActivity). CuThread::registerActivity starts immediately the activity in the background thread.

see Cumbia::unregisterActivity see CuActivity::Flags

References CuServices::ActivityManager, CuActivityManager::connect(), CuThreadService::getThread(), CuThreadInterface::isRunning(), CuThreadInterface::registerActivity(), CuActivity::setThread(), CuThreadInterface::start(), CuServices::Thread, and threadToken().

◆ removeThreadTokenGenerator()

void Cumbia::removeThreadTokenGenerator ( )

Cumbia::removeThreadTokenGenerator remove the currently installed generator, if any.

Note: The currently installed generator is deleted

Referenced by setThreadTokenGenerator().

◆ resumeActivity()

void Cumbia::resumeActivity ( CuActivity * a )

if a timer runs within an activity, resume it

Parameters

a	the CuActivity which timer timeout has to be resumed

References CuServices::ActivityManager, CuActivityManager::getThread(), and CuThreadInterface::postEvent().

◆ setActivityPeriod()

void Cumbia::setActivityPeriod	(	CuActivity *	a,
		int	timeout
	)

if a timer runs within an activity, change the timeout

Parameters

a	the CuActivity which timer has to be changed
timeout	the number of milliseconds of the new timeout

Implementation: Through the activity manager service, the thread associated to the activity is fetched and a CuTimeoutChangeEvent is posted.

References CuServices::ActivityManager, CuActivityManager::getThread(), and CuThreadInterface::postEvent().

◆ setThreadTokenGenerator()

void Cumbia::setThreadTokenGenerator ( CuThreadTokenGenI * tg )

Cumbia::setThreadTokenGenerator install athread token generator that deals with grouping activities into separate threads according to the specific engine implementation.

Parameters

tg	an implementation of the CuThreadTokenGenI interface

Note: Once you install a thread token generator with this method, the ownership of the object is handed to Cumbia. The generator will either be destroyed by Cumbia or by the removeThreadTokenGenerator method. Subsequent calls to setThreadTokenGenerator will also delete a previously installed generator.

References removeThreadTokenGenerator().

◆ threads()

std::vector< CuThreadInterface * > * Cumbia::threads ( ) const

◆ threadToken()

const std::string Cumbia::threadToken ( const std::string & in ) const

Cumbia::threadToken returns a thread token that can be used to group threads together.

If a thread token generator (CuThreadTokenGenI) implementation has been registered with setThreadTokenGenerator, it is used to provide the thread token.

If the option contains the thread_token with a given value, that value will be used to group threads with the same token

If there is no thread_token key in the input options, the return value is the same as the input argument.

Parameters

options configuration options to customize thread grouping

Returns: a thread token (CuData)

Referenced by registerActivity().

◆ unregisterActivity()

void Cumbia::unregisterActivity ( CuActivity * a )

unregister an activity from cumbia

Parameters

activity the CuActivity to unregister

Disconnect the activity from its listeners and remove it from cumbia. If the associated thread activity count is zero, the thread is removed from the CuThreadService and its resources released.

A CuActivity can automatically unregister after execution and be deleted if appropriate flags are set (CuActivity::CuAUnregisterAfterExec and CuActivity::CuADeleteOnExit)

References CuServices::ActivityManager, CuActivityManager::countActivitiesForThread(), CuActivityManager::disconnect(), CuActivityManager::getThread(), CuThreadService::removeThread(), CuServices::Thread, and CuThreadInterface::unregisterActivity().

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

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ Type

Constructor & Destructor Documentation

◆ Cumbia()

◆ ~Cumbia()

Member Function Documentation

◆ findActivity()

◆ finish()

◆ getActivityPeriod()

◆ getServiceProvider()

◆ getThreadTokenGenerator()

◆ getType()

◆ pauseActivity()

◆ postEvent()

◆ registerActivity()

◆ removeThreadTokenGenerator()

◆ resumeActivity()

◆ setActivityPeriod()

◆ setThreadTokenGenerator()

◆ threads()

◆ threadToken()

◆ unregisterActivity()