Access token for writing an entry in a UnifiedChannel. More...

#include <ChannelWriteToken.hxx>

Inheritance diagram for dueca::ChannelWriteToken:

[legend]

Collaboration diagram for dueca::ChannelWriteToken:

[legend]

Public Member Functions
	ChannelWriteToken (const GlobalId &owner, const NameSet &channelname, const std::string &dataclassname, const std::string &entrylabel=std::string(), Channel::EntryTimeAspect time_aspect=Channel::Continuous, Channel::EntryArity arity=Channel::OnlyOneEntry, Channel::PackingMode packmode=Channel::OnlyFullPacking, Channel::TransportClass tclass=Channel::Regular, const UCallbackOrActivity &when_valid=UCallbackOrActivity(), unsigned nreservations=0)
	Constructor, creates a token to write data in the channel, and if needed it creates the associated channel end.

	~ChannelWriteToken ()
	Destructor.

void	decodeAndWriteData (AmorphReStore &s, const DataTimeSpec &ts)
	Write channel data from a storage object.

bool	isValid ()
	Check the validity of the token.

entryid_type	getEntryId () const
	Get the entry number.

ChannelEntryInfo	getChannelEntryInfo () const
	Retrieve creation/entry information.

bool	applyFunctor (DCOFunctor *fnct, const DataTimeSpec &time)
	Apply a given functor to write channel data.

void	reWrite (const DataTimeSpec &time)
	Simply re-write the current (or default) data for a new time.

const std::string &	getDataClassName () const
	Return the data class.

Public Member Functions inherited from dueca::GenericToken
const GlobalId &	getTokenHolder () const
	Return the ID of the owner.

const GlobalId &	getChannelId () const
	Return the ID of the channel.

const NameSet &	getName () const
	Return the local name specified for the token.

const std::string &	getDataClassName () const
	Return the data class name.

uint32_t	getDataClassMagic () const
	Access the data class magic.

virtual	~GenericToken ()
	Destructor.

	GenericToken (const GlobalId &holder, const NameSet &name, const std::string &dataclassname)
	Constructor.

template<class MFT >
std::weak_ptr< MFT >	getMetaFunctor (const std::string &fname) const
	Obtain a specific metafunctor for interaction with channel data.

Public Member Functions inherited from dueca::TriggerPuller
const std::string &	getTriggerName () const
	Find a name.

Protected Member Functions
void *	getAccess (uint32_t magic)
	Return a void pointer to a new data location.

void	checkAccess (uint32_t magic)
	Check whether magic is good, and token is valid.

void	releaseAccess (const void *data_ptr, const DataTimeSpec &ts)
	Return the read access given previously, creating the effective write,.

void	discardAccess (const void *data_ptr)
	Discard the read access, abandoning an attempted write.

Protected Member Functions inherited from dueca::GenericToken
void	checkChannelEndPresent () const
	Check preconditions.

Protected Member Functions inherited from dueca::TriggerPuller
void	pull (const DataTimeSpec &ts)
	activate and notify the targets

	TriggerPuller (const std::string &name=std::string())
	Constructor.

virtual	~TriggerPuller ()
	Destructor.

virtual void	addTarget (const boost::intrusive_ptr< TriggerTarget > &target, unsigned id)
	Add a target to this puller, only called by TriggerTarget's setTrigger.

virtual void	removeTarget (const TriggerTarget *target)
	Remove a target from the puller, only called by destructor.

virtual void	setTriggerName ()
	Update the name, used by ConditionAnd and ConditionOr.

Friends
class	DataWriterBase

class	DCOWriter

void	_wrapSendEvent (ChannelWriteToken &t, const void *edata, const DataTimeSpec &tic)
	wrapper for the "old" sendEvent member call

Additional Inherited Members
Protected Types inherited from dueca::TriggerPuller
typedef list< TargetData >	targetlist_type
	Combination of a target, someone to pull if requested, and the index that target needs to identify this puller.

Protected Attributes inherited from dueca::GenericToken
std::string	dataclassname
	name of the data type

const DataSetConverter *	converter
	Converter for the data.

uint32_t	magic_number
	magic number for the data class name claimed here

UnifiedChannel *	channel
	pointer to the channel

Protected Attributes inherited from dueca::TriggerPuller
targetlist_type	targets
	List of targets and indices.

std::bitset< MAX_MANAGERS >	activitylevels
	Index of activitymanager levels.

std::string	name
	Name, for debugging purposes.

Detailed Description

Access token for writing an entry in a UnifiedChannel.

A UnifiedChannel is a channel that can contain multiple entries, of different data types. Older versions of DUECA had stream channels, for periodically updated data, or event channels, for point events. This channel holds both data types. It can also hold multiple "entries", and each entry may be of a different data class.

Different types of data may be written in the channel, and multiple entries may be present. For reading one supplies the data type (class) that one wants to read.

To get read or write access to the channel, components need to create a ChannelReadToken or a ChannelWriteToken.

This class defines the ChannelWriteToken. After creating a ChannelWriteToken, a local copy of the channel is created if it did not previously exist. Each ChannelWriteToken creates an entry in the channel, and this entry will be replicated on any channel ends on other nodes. With the destruction of the ChannelWriteToken the entry disappears again.

Each entry has an entry id, but that is valid only for its lifetime; entry id's may be recycled, and it is not possibly to "specify" an entry id.

Updating of the entries held by a module is done by producing a DataWriter on the ChannelWriteToken, and using this DataWriter to manipulate the data. Data types are created from .dco files by DUECA's code generator. Any members of a data type that are not changed through the DataWriter will be equal to the data from the previous time step. Reading is done by producing a DataReader on a ChannelReadToken.

As an alternative, the ChannelWriteToken or ChannelReadToken can be read in a generic, type-agnostic manner by creating a CommObjectWriter respectively a CommObjectReader, and using that object to traverse the data. Note that reading/writing of a channel in that manner incurs significant overhead.

Constructor & Destructor Documentation

◆ ChannelWriteToken()

dueca::ChannelWriteToken::ChannelWriteToken	(	const GlobalId &	owner,
		const NameSet &	channelname,
		const std::string &	dataclassname,
		const std::string &	entrylabel = std::string(),
		Channel::EntryTimeAspect	time_aspect = Channel::Continuous,
		Channel::EntryArity	arity = Channel::OnlyOneEntry,
		Channel::PackingMode	packmode = Channel::OnlyFullPacking,
		Channel::TransportClass	tclass = Channel::Regular,
		const UCallbackOrActivity &	when_valid = UCallbackOrActivity(),
		unsigned	nreservations = 0 )

Constructor, creates a token to write data in the channel, and if needed it creates the associated channel end.

Parameters

owner	Identification of the owner.
channelname	Name of the channel end, for the connecting publish-subscribe mechanism.
dataclassname	Name of the data type to be written. This must match an existing DUECA Channel Object (DCO) type.
entrylabel	Fixed identifying label to be given to this entry.
time_aspect	The data in the entry may represent a continuous time approximation (EntryTimeAspect::Continuous, "stream") data, which has a contiguous time span associated with it, or it may represent individual data items (EntryTimeAspect::Events, "event"), which are marked with a time point.
arity	If OnlyOneEntry, the channel is limited to one entry only. If another entry is already present, the token will not become valid. If OneOrMoreEntries, multiple entries may be written to the channel.
packmode	Indicate whether differential packing should be used or the default full packing is used. Differential packing packs only the difference with respect to the previous data point.
tclass	Transportation priority for the channel. Must match the priority specified by other write tokens.
when_valid	Optional callback, to be invoked when the token becomes valid. You can use a GenericCallback pointer here, or an AcitivityCallback pointer.
nreservations	Please do not attempt to use this; no support for user code! A specific counter for channels used in start-up code for DUECA that need to guarantee transmission of all inital data to a known number of clients.

Member Function Documentation

◆ decodeAndWriteData()

void dueca::ChannelWriteToken::decodeAndWriteData	(	AmorphReStore &	s,
		const DataTimeSpec &	ts )

Write channel data from a storage object.

Parameters

s	Amorphous storage object.
ts	Time for which to write

Exceptions

AmorphReStoreEmpty if not enough data in s

◆ isValid()

bool dueca::ChannelWriteToken::isValid ( )

virtual

Check the validity of the token.

Implements dueca::GenericToken.

◆ applyFunctor()

bool dueca::ChannelWriteToken::applyFunctor	(	DCOFunctor *	fnct,
		const DataTimeSpec &	time )

Apply a given functor to write channel data.

If successful, this has the same effect as writing the data.

Parameters

fnct	Functor to be applied (created from a getMetaFunctor). The operator()(void* pointer) method will be called.
time	Time for writing

Returns: True if data was obtained from the functor and written to the channel, false if the operation failed (e.g., due to lack of data).

◆ reWrite()

void dueca::ChannelWriteToken::reWrite ( const DataTimeSpec & time )

Simply re-write the current (or default) data for a new time.

Parameters

time	Time for re-writing

◆ getAccess()

void * dueca::ChannelWriteToken::getAccess ( uint32_t magic )

protected

Return a void pointer to a new data location.

The data location is filled with the latest written data in this entry.

Parameters

magic magic number, must match the data type magic number

Exceptions

InvalidChannelAccessReturn,if the magic is not correct or the token is not valid.

◆ checkAccess()

void dueca::ChannelWriteToken::checkAccess ( uint32_t magic )

protected

Check whether magic is good, and token is valid.

Parameters

magic magic number, must match the data type magic number

Exceptions

InvalidChannelAccessReturn,if the magic is not correct or the token is not valid.

◆ releaseAccess()

void dueca::ChannelWriteToken::releaseAccess	(	const void *	data_ptr,
		const DataTimeSpec &	ts )

protected

Return the read access given previously, creating the effective write,.

Parameters

data_ptr	Must match the previously obtained pointer.
ts	Time specification for the write. Must be a range (end > start) for continuous data, and a time point (end == start) for event data.

◆ discardAccess()

void dueca::ChannelWriteToken::discardAccess ( const void * data_ptr )

protected

Discard the read access, abandoning an attempted write.

Parameters

data_ptr Must match previously obtained pointer, data access is returned.

Friends And Related Symbol Documentation

◆ _wrapSendEvent

void _wrapSendEvent	(	ChannelWriteToken &	t,
		const void *	edata,
		const DataTimeSpec &	tic )

friend

wrapper for the "old" sendEvent member call

Parameters

t	Channel write token
edata	Pointer to the data; deallocation will be done by the channel
tic	Time for the event

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

/home/abuild/rpmbuild/BUILD/dueca-4.1.3/dueca/ChannelWriteToken.hxx

Public Member Functions

Protected Member Functions

Friends

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ ChannelWriteToken()

Member Function Documentation

◆ decodeAndWriteData()

◆ isValid()

◆ applyFunctor()

◆ reWrite()

◆ getAccess()

◆ checkAccess()

◆ releaseAccess()

◆ discardAccess()

Friends And Related Symbol Documentation

◆ _wrapSendEvent