CuEventActivity Class Reference

an activity to subscribe and receive events from Tango. Implements CuActivity and Tango::Callback interfaces More...

#include <cueventactivity.h>

Inheritance diagram for CuEventActivity:

Public Types
enum	Type { CuEventActivityType = CuActivity::UserAType + 2 }

Public Member Functions
	CuEventActivity (const TSource &tso, CuDeviceFactory_I *df, const std::string &refreshmo, const CuData &tag, int update_policy)
	the class constructor that configures the activity event flags More...
	~CuEventActivity ()
	the class destructor More...
int	getType () const
	returns the CuEventActivityType value More...
void	event (CuActivityEvent *e)
	Receive events from the main thread to the CuActivity thread. More...
bool	matches (const CuData &token) const
	returns true if the passed token's src and activity values matche this activity token's src and activity values. More...
int	repeat () const
	returns 0. CuEventActivity's execute is called only once. More...

Protected Member Functions
void	init ()
	the implementation of the CuActivity::init hook More...
void	execute ()
	the implementation of the CuActivity::execute hook More...
void	onExit ()
	the implementation of the CuActivity::onExit hook More...
void	push_event (Tango::EventData *)
	receive events from Tango, extract data and post the result on the main thread through publishResult More...

Detailed Description

an activity to subscribe and receive events from Tango. Implements CuActivity and Tango::Callback interfaces

Implementing CuActivity, the work is done in the background by the three methods

• init
• execute
• onExit

They are called from a separate thread. In cumbia-tango, threads are grouped by device. As an implementor of Tango::Callback, events are received through the push_event callback

Apart from the three execution hooks listed above, some other methods have been written to comply with the CuActivityInterface:

• getType, returning CuEventActivityType
• event, to receive CuActivityEvent events
• matches, that returns true if the input token represents an activity like this
• repeat, that in this case always returns false

note

To solve a known Tango issue that prevents events from working if the client application subscribes to sources across different devices, an instance of omni_thread::ensure_self is kept alive as long as the CuEventActivity lives.

Member Enumeration Documentation

Type

enum CuEventActivity::Type

Enumerator
CuEventActivityType

Constructor & Destructor Documentation

CuEventActivity()

CuEventActivity::CuEventActivity	(	const TSource &	tso,
		CuDeviceFactory_I *	df,
		const std::string &	refreshmo,
		const CuData &	tag,
		int	update_policy
	)

the class constructor that configures the activity event flags

Parameters

token	a CuData that will identify this activity
df	a pointer to a CuDeviceFactoryService that is used by init and onExit to create/obtain and later get rid of a Tango device, respectively.

Default activity flags

The default activity flags set by the CuEventActivity constructor are

• CuActivity::CuAUnregisterAfterExec: false: the activity is not unregistered after exec. Instead, it keeps living within an event loop that delivers Tango events over time
• CuActivity::CuADeleteOnExit: true lets the activity be deleted after onExit

~CuEventActivity()

CuEventActivity::~CuEventActivity

(

)

the class destructor

Member Function Documentation

event()

void CuEventActivity::event

(

CuActivityEvent *

e

)

Receive events from the main thread to the CuActivity thread.

Parameters

e	the event. Do not delete e after use. Cumbia will delete it after this method invocation.

See also

CuActivity::event

Note

the body of this method is currently empty

execute()

void CuEventActivity::execute ( )

protected

the implementation of the CuActivity::execute hook

This is called in the CuActivity's thread of execution.

Notes

• subscribe_event for the attribute to read is called on the TangoDevice and the desired event subscription type is requested according to the "rmode" (refresh mode) value in the activity token obtained by getToken

If subscribe_event is successful, the client will start receiving events through the Tango::Callback push_event function. If an error occurs here, publishResult is called in order to deliver the error message to the main thread, where a CuDataListener will deal with it.

note

Typically, if subscribe_event fails, a CuPollingActivity is started as a fallback mode for the reader.

To learn about the contents of the CuData delivered as result, please see the CuEventActivity::push_event documentation.

See also CuActivity::execute

note

In the CuEventActivity::push_event callback, CuData "E" value is copied from Tango::EventData::event. Here data["E"] is set to "subscribe" to identify the subscribe_event phase (CuTReader looks for this not to issue an error if subscription fails).

References CuTangoWorld::strerror().

getType()

int CuEventActivity::getType

(

)

const

returns the CuEventActivityType value

Returns

the constant value CuEventActivityType defined in CuEventActivity::Type

References CuEventActivityType.

init()

void CuEventActivity::init ( )

protected

the implementation of the CuActivity::init hook

This is called in the CuActivity's thread of execution.

Notes

• in cumbia-tango, threads are grouped by device
• a new omni_thread::ensure_self is created and lives across the entire CuEventActivity lifetime to work around a known Tango issue that breaks the event reception when the client application subscribes to attributes across different devices
• CuDeviceFactoryService::getDevice is called to obtain a reference to a Tango device (in the form of TDevice)
• TDevice's user refrence count is incremented with TDevice::addRef

See also CuActivity::init, execute and onExit

References CuTThread::CuTThreadType.

matches()

bool CuEventActivity::matches

(

const CuData &

token

)

const

returns true if the passed token's src and activity values matche this activity token's src and activity values.

Parameters

token

a CuData containg key/value pairs of another activity's token

Returns

true if the input token's "src" and "activity" values match this token's "src" and "activity" values

Two CuEventActivities match if the "src" and the "activity" names match. CuEventActivity "activity" key is set to the "E" value by CuTReader, so two activities match if they are both CuEventActivity and share the same source name.

onExit()

void CuEventActivity::onExit ( )

protected

the implementation of the CuActivity::onExit hook

This is called in the CuActivity's thread of execution.

• unsubscribe_event is called for the Tango attribute
• client reference counter is decreased on the TDevice (TDevice::removeRef)
• CuDeviceFactoryService::removeDevice is called to remove the device from the device factory if the reference count is zero
• publishResult is not called (it's likely that all listeners have been removed)
• the omni_thread::ensure_self instance is deleted

See also CuActivity::onExit

References CuTangoWorld::strerror().

push_event()

void CuEventActivity::push_event ( Tango::EventData *  e )

protected

receive events from Tango, extract data and post the result on the main thread through publishResult

Parameters

e	the Tango::EventData passed by the tango callback

• receive the event
• extract data exploiting CuTangoWorld utility methods
• publishResult with the data extracted and packed in a CuData

contents of the CuData delivered by publishResult ("key": value)

• "is_command": bool: true if the source is a command, false if it is an attribute (CuVariant::toBool)
• "err": bool: true if an error occurred, false otherwise
• "mode": string: the read mode: "E" or "P" ("E" in this case)
• "msg": string: in case of error, the error message is reported
• "E": string: a copy of the value of Tango::EventData::event string (documented as the event name in lib/cpp/client/event.h)
• refer to md_lib_cudata_for_tango for a complete description of the CuData key/value pairs that result from attribute or command read operations.

References CuTangoWorld::error(), CuTangoWorld::extractData(), CuTangoWorld::getLastMessage(), and CuTangoWorld::strerror().

repeat()

int CuEventActivity::repeat

(

)

const

returns 0. CuEventActivity's execute is called only once.

Returns

the integer -1

See also

CuActivity::repeat

---

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

• cueventactivity.h
• cueventactivity.cpp