Access token used to read data from a UnifiedChannel. More...

#include <ChannelReadToken.hxx>

Inheritance diagram for dueca::ChannelReadToken:

[legend]

Collaboration diagram for dueca::ChannelReadToken:

[legend]

Public Types
enum	AccessResult { NoData , TimeSkip , DataSuccess }
	Different type of access result. More...

Public Member Functions
	ChannelReadToken (const GlobalId &owner, const NameSet &channelname, const std::string &dataclassname, entryid_type entryhandle=0, Channel::EntryTimeAspect time_aspect=Channel::Continuous, Channel::EntryArity arity=Channel::OnlyOneEntry, Channel::ReadingMode rmode=Channel::AdaptEventStream, double requested_span=0.2, const UCallbackOrActivity &when_valid=UCallbackOrActivity())
	Constructor, creates a token and if needed creates the associated channel end.

	ChannelReadToken (const GlobalId &owner, const NameSet &channelname, const std::string &dataclassname, entryid_type entryhandle, Channel::EntryTimeAspect time_aspect, Channel::EntryArity arity, Channel::ReadingMode rmode, double requested_span, Channel::TransportClass tclass, GenericCallback *when_valid=NULL)
	ChannelReadToken constructor, deprecated version.

	ChannelReadToken (const GlobalId &owner, const NameSet &channelname, const std::string &dataclassname, const std::string &entrylabel, Channel::EntryTimeAspect time_aspect=Channel::Continuous, Channel::EntryArity arity=Channel::OnlyOneEntry, Channel::ReadingMode rmode=Channel::AdaptEventStream, double requested_span=0.2, const UCallbackOrActivity &when_valid=UCallbackOrActivity())
	Constructor, creates a token and if needed creates the associated channel end.

	ChannelReadToken (const GlobalId &owner, const NameSet &channelname, const std::string &dataclassname, const std::string &entrylabel, Channel::EntryTimeAspect time_aspect, Channel::EntryArity arity, Channel::ReadingMode rmode, double requested_span, Channel::TransportClass tclass, GenericCallback *when_valid=NULL)
	ChannelReadToken constructor, deprecated version.

	ChannelReadToken (const GlobalId &owner, const NameSet &channelname, const std::string &dataclassname, entryid_type entryhandle, Channel::EntryTimeAspect time_aspect, Channel::EntryArity arity, Channel::ReadingMode rmode, const UCallbackOrActivity &when_valid, unsigned requested_depth)
	Constructor, creates a token and if needed creates the associated channel end.

bool	isValid ()
	Check the validity of the token.

const GlobalId &	getClientId () const
	Return the client ID.

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

bool	isSequential () const
	Data access type, sequential?

Channel::EntryTimeAspect	getTimeAspect () const
	Time aspect of read data.

DataTimeSpec	getOldestDataTime () const
	Return the span of the oldest data in the current entry.

DataTimeSpec	getLatestDataTime () const
	Return the span of the latest data in the current entry.

void	selectFirstEntry ()
	Instruct the token to start dealing with the first entry in the channel.

void	selectNextEntry ()
	Instruct the token to start dealing with the next entry.

bool	haveEntry () const
	Check that there is a valid entry to read.

const entryid_type	getEntryId () const
	Get the entry handle id.

const std::string &	getEntryLabel () const
	Get the current entry's label, if available.

unsigned int	getNumVisibleSets (const TimeTickType ts=MAX_TIMETICK) const
	Returns the number of data points older than the given time.

unsigned int	getNumVisibleSets (const DataTimeSpec ts) const
	Returns the number of data points older than the given, for any of the entries read by this token.

unsigned int	getNumVisibleSetsInEntry (const TimeTickType ts=MAX_TIMETICK) const
	Returns the number of data points older than the given time for the currently selected entry read by this token.

unsigned int	getNumVisibleSetsInEntry (const DataTimeSpec ts) const
	Returns the number of data points older than the given time, for the currently selected entry read by this token.

bool	haveVisibleSets (const TimeTickType ts=MAX_TIMETICK) const
	Returns true if there are data points visible at the given time, for any of the entries read by this token.

bool	haveVisibleSets (const DataTimeSpec ts) const
	Returns true if there are data points visible at the given time.

bool	haveVisibleSetsInEntry (const TimeTickType ts=MAX_TIMETICK) const
	Returns true if there are data points visible at the given time, for the current entry read by this token.

bool	haveVisibleSetsInEntry (const DataTimeSpec ts) const
	Returns true if there are data points visible at the given time, for the current entry read by this token.

unsigned int	flushTotalAvailableSets () const
	Flush all data in a channel for this reader.

unsigned int	flushOlderSets () const
	Flush almost all data in a channel for this reader, but leave one dataset in.

unsigned int	flushOlderSets (const TimeTickType ts) const
	Flush almost all data in a channel for this reader, but leave datasets newer than ts.

unsigned int	flushOne () const
	Flush a single dataset for this reader.

ChannelEntryInfo	getChannelEntryInfo () const
	Retrieve creation/entry information.

AccessResult	readAndStoreData (AmorphStore &s, TimeTickType &tsprev)
	Read channel data into an amorph store object.

bool	readAndPack (AmorphStore &s, DataTimeSpec &ts, const TimeSpec &tsreq=TimeSpec(0U, MAX_TIMETICK))
	Read channel data into an amorph store object.

	~ChannelReadToken ()
	Destructor.

bool	applyFunctor (DCOFunctor *fnct, TimeTickType time=MAX_TIMETICK)
	Apply a given functor to channel data.

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
const void *	getAccess (TimeTickType t_request, DataTimeSpec &ts, GlobalId &origin, uint32_t magic)
	Return a void pointer to the data in the current entry.

void	releaseAccess (const void *data_ptr)
	Return the read access given previously.

void	releaseAccessKeepData (const void *data_ptr)
	Return the read access given previously, but keep the data.

void	addTarget (const boost::intrusive_ptr< TriggerTarget > &t, unsigned id)
	Override the addTarget method from the TriggerPuller class.

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	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	DataReaderBaseAccess

class	DCOReader

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 used to read data from a UnifiedChannel.

A UnifiedChannel is a channel that can contain multiple entries. Each entry can have a different data type(class). This ChannelReadToken gives access to one of the data types in a UnifiedChannel. At construction of the access token one can specify that the token can iterate over all entries of that data type in the channel, or that the token is limited to a single entry. See the dueca::ChannelWriteToken for information on writing entries in a channel.

Note that in many cases, a channel has only one entry. This of course simplifies handling the channel. It is possible to read all entries matching a specify data type. Only in that case it is necessary to use the ChannelReadToken::selectFirstEntry(), ChannelReadToken::selectFirstEntry() and ChannelReadToken::haveEntry() calls. For channels with multiple entries (e.g., to read all the traffic in a simulation), it is more efficient, both computationally and from the view of the programmer, to use a ChannelWatcher to detect changes in the channel, and add ChannelReadToken(s) that read just specific entries.

Older versions of DUECA had stream channels, for periodically updated data, where the data is valid for a specific time span, or event channels, representing events happening at specific times. Present versions of DUECA have a single channel type, dueca::UnifiedChannel. This channel holds both data variants, and replaces both old channel types. Compatibility with older dueca is maintained, with the UnifiedChannel objects implementing the functionality of the previous channels. See dueca::EventAccessToken, dueca::StreamAccessToken, dueca::MultiStreamReadToken, dueca::EventWriteToken, dueca::StreamWriteToken and dueca::MultiStreamWriteToken if you find old code still using this.

Either a specific entry, identified by its entry ID, or by label, is selected when the token is created. To select only a specific entry, use the Channel::OnlyOneEntry specification. In this case the channel may still have multiple entries, but access is to a single specific entry. Alternatively, with Channel::OneOrMoreEntries or Channel::ZeroOrMoreEntries, the token can be used to traverse all entries of the given data class. Note that the entry multiplicity is defined slightly differently for a write* token; there OnlyOneEntry means that a channel will be restricted to only that single entry.

The data class can display inheritance. You may compare this with the HLA-style publish-subscribe mechanism, without the data management. The interface is drastically different from HLA implementation, in the sense that data is internally kept and managed by the channel, and easy reading and writing is provided.

When creating a dueca::ChannelReadToken or a dueca::ChannelWriteToken, a local copy of the channel (a "channel end") is created in a node if it did not previously exist.

To declare a ChannelReadToken:

ChannelReadToken r_mytoken;

dueca::ChannelReadToken

Access token used to read data from a UnifiedChannel.

Definition ChannelReadToken.hxx:202

dueca::StreamReaderLatest

This is a "light weight object" that enables you to read the latest set of data on a StreamChannelEnd...

Definition StreamReaderLatest.hxx:43

To initialize it, typically in a class constructor list:

r_mytoken(this->getId(), NameSet("MyDataClass://myentity/channelname"),

"MyDataClass"),

dueca::NameSet

Name tuple as used in DUECA.

Definition NameSet.hxx:65

In this case, an entry number is not selected and by default only the first (0) entry is selected. This entry must match the data type, otherwise the token will not become valid. This entry must have data of class MyDataClass, or data of a class that derives from MyDataClass. Note that, by convention, the class part of the channel name is often also set to "MyDataClass", but that this is not strictly necessary; another name could be chosen there. The defaults are to treat the data in the channel as stream data; data defined for contiguous time intervals.

A default time span of 0.2 seconds is supplied, meaning that data is kept available for at least a 0.2 second time span. When reading, the data corresponding to the specified time is looked up and returned.

Here is another example:

r_mytoken(this->getId(), NameSet("MyDataClass://myentity/channelname"),

"MyDataClass", 0, Channel::Events, Channel::ReadAllData),

dueca::Channel::Events

@ Events

Event-like data, time is a point stamp, multiple events may share the same time.

Definition ChannelDef.hxx:35

dueca::Channel::ReadAllData

@ ReadAllData

Sequentially read all data, from oldest to newest, all data is read once, and reading fails when no m...

Definition ChannelDef.hxx:61

In this case, only entry 0 (the first) is selected. The data class must match that entry's data class for the token to become valid. Requested reading mode is ReadAllData, meaning that data will be discarded only after it has been accessed by this token. Note that this carries an obligation to access and read all data; otherwise the channel clogs up, leading to error messages and forced discarding of data. The time access is now Channel::Events. Event data is tagged with a single time point only, and multiple data sets may be tagged with the same time. There may also be times that there is no (new) data.

Before using the token for further access, it needs to be checked for validity. You can repeat this check if the first check does not succeed.

bool v = r_mytoken.isValid();

Note that this check is commonly done in the Module::isPrepared() call. It is so common, that a macro has been defined, e.g.:

bool res = true;

CHECK_TOKEN(r_mytoken);

A token may also be used as a trigger. Note that in some cases this does not make sense; if you have multiple stream entries in a channel, the triggering may become erratic (repeating itself) as the different entries are updated with data for new times. The most sensible cases for triggering are channels with stream data with one entry only, or event channels. You can also create a token that focuses on one entry in a channel with multiple entries, and trigger on that single entry.

If you need to, and selected multiple entries when creating the token, a typical reading application for multiple entries might do:

// for when all entries have read all the entries
for (my_token.selectFirstEntry(); my_token.haveEntry();
     my_token.selectNextEntry()) {
 
  // use a DataReader to access the data from the currently
  // selected entry in the channel
  DataReader<MyDataClass> r(my_token, ts);
 
  // read, by accessing the MyDataClass object with r.data()
 
  // closing off this block, so reader is destroyed and read
  // access is released.
}

Note that the order in which the entries appear does not need to be the order in which the write tokens were made.

A more rapid option for reading the data from channels with multiple entries is by using a dueca::ChannelWatcher . The ChannelWatcher monitors creation and deletion of entries in a channel, and upon creation of an entry you can create a read token specifically for that entry.

Check the different dueca::DataReader template specializations to see the different types of accessing data.

If you specified the entry ID at token creation, you cannot recurse over the entries in the channel. On the other hand in that case you can use the token as a trigger for activities. The associated activity will be scheduled when data arrives for the specified entry.

Member Enumeration Documentation

◆ AccessResult

enum dueca::ChannelReadToken::AccessResult

Different type of access result.

Enumerator
NoData	cannot find data for requested access (sequential exhausted).
TimeSkip	stream data, and there is a gap in the time.
DataSuccess	packed as requested

Constructor & Destructor Documentation

◆ ChannelReadToken() [1/5]

dueca::ChannelReadToken::ChannelReadToken	(	const GlobalId &	owner,
		const NameSet &	channelname,
		const std::string &	dataclassname,
		entryid_type	entryhandle = 0,
		Channel::EntryTimeAspect	time_aspect = Channel::Continuous,
		Channel::EntryArity	arity = Channel::OnlyOneEntry,
		Channel::ReadingMode	rmode = Channel::AdaptEventStream,
		double	requested_span = 0.2,
		const UCallbackOrActivity &	when_valid = UCallbackOrActivity() )

Constructor, creates a token and if needed creates the associated channel end.

First variant, with entry handle as selection.

Parameters

owner	Identification of the owner
channelname	Name of the channel end
dataclassname	Name of the data type to be read
entryhandle	Selecting handle for the entry. If equal to `entry_any`, the token will be connected to all entries of the specified data class, otherwise a specific entry will be selected. Entryhandle 0 (default) is the first entry.
time_aspect	The data in the entry may represent a continuous time approximation ("stream") data, which has a contiguous time span associated with it, or it may represent individual data items ("event"), which are marked with a time point. This must match the mode in which this entry was written, or specify Channel::AnyTimeAspect to not be selective.
arity	Indicate the desired number of entries you want to access with this token, multiple or just one. If you indicate Channel::ZeroOrMoreEntries, the token will become valid also if there are no entries written in the channel.
rmode	Reading mode, when Channel::JumpToMatchTime, the reading may skip older data in the channel, when Channel::ReadAllData, the data is read sequentially, no data is skipped. Using Channel::AdaptEventStream uses JumpToMatchTime for stream, and ReadAllData for event channels.
requested_span	How long should data be kept available, in seconds. Relevant only for Channel::JumpToMatchTime.
when_valid	Optional callback, to invoked when the token becomes valid.

◆ ChannelReadToken() [2/5]

dueca::ChannelReadToken::ChannelReadToken	(	const GlobalId &	owner,
		const NameSet &	channelname,
		const std::string &	dataclassname,
		entryid_type	entryhandle,
		Channel::EntryTimeAspect	time_aspect,
		Channel::EntryArity	arity,
		Channel::ReadingMode	rmode,
		double	requested_span,
		Channel::TransportClass	tclass,
		GenericCallback *	when_valid = NULL )

ChannelReadToken constructor, deprecated version.

Deprecated: Use a version without Channel::TransportClass, since transport class is already determined by writing tokens

Parameters

owner	Identification of the owner
channelname	Name of the channel end
dataclassname	Name of the data type to be read
entryhandle	Selecting handle for the entry. If equal to `entry_any`, the token will be connected to all entries of the specified data class, otherwise a specific entry will be selected. Entryhandle 0 is the first entry, etc.
time_aspect	The data in the entry may represent a continuous time approximation ("stream") data, which has a contiguous time span associated with it, or it may represent individual data items ("event"), which are marked with a time point. This must match the mode in which this entry was written, or specify Channel::AnyTimeAspect to not be selective.
arity	Indicate the desired number of entries you want to access with this token, multiple or just one.
rmode	Reading mode, when Channel::JumpToMatchTime, the reading may skip older data in the channel, when Channel::ReadAllData, the data is read sequentially, no data is skipped. Using Channel::AdaptEventStream uses JumpToMatchTime for stream, and ReadAllData for event channels.
requested_span	How long should data be kept available, in seconds.
tclass	Transport class, ignored and obsolete!
when_valid	Optional callback, to invoked when the token becomes valid.

◆ ChannelReadToken() [3/5]

dueca::ChannelReadToken::ChannelReadToken	(	const GlobalId &	owner,
		const NameSet &	channelname,
		const std::string &	dataclassname,
		const std::string &	entrylabel,
		Channel::EntryTimeAspect	time_aspect = Channel::Continuous,
		Channel::EntryArity	arity = Channel::OnlyOneEntry,
		Channel::ReadingMode	rmode = Channel::AdaptEventStream,
		double	requested_span = 0.2,
		const UCallbackOrActivity &	when_valid = UCallbackOrActivity() )

Constructor, creates a token and if needed creates the associated channel end.

Second variant, with entry label as selection. Note that duplicate entry names are possible, and this token will only select the first one matching the label.

Parameters

owner	Identification of the owner
channelname	Name of the channel end
dataclassname	Name of the data type to be read
entrylabel	Fixed identifying label to be given to this entry. If arity==Channel::OnlyOneEntry, the token will be attached to the first entry which matches this label. If no such entry is present, the token will not become valid.
time_aspect	The data in the entry may represent a continuous time approximation ("stream") data, which has a contiguous time span associated with it, or it may represent individual data items ("event"), which are marked with a time point. This must match the mode in which this entry was written, or specify Channel::AnyTimeAspect to not be selective.
arity	If Channel::OnlyOneEntry, the token is attached to one entry only. The entry's label must match the entrylabel name. When this has been selected, the token can be used as a trigger.
rmode	Reading mode, when Channel::JumpToMatchTime, the reading may skip older data in the channel, when Channel::ReadAllData, the data is read sequentially, no data is skipped. Note that Channel::ReadAllData also involves an obligation to actually read (or flush) all the data, to prevent excessive memory use. Using Channel::AdaptEventStream uses JumpToMatchTime for stream, and ReadAllData for event channels.
requested_span	How long should data be kept available, in seconds. The actual availability is determined by the longest span requested.
when_valid	Optional callback, to invoked when the token becomes valid.

◆ ChannelReadToken() [4/5]

dueca::ChannelReadToken::ChannelReadToken	(	const GlobalId &	owner,
		const NameSet &	channelname,
		const std::string &	dataclassname,
		const std::string &	entrylabel,
		Channel::EntryTimeAspect	time_aspect,
		Channel::EntryArity	arity,
		Channel::ReadingMode	rmode,
		double	requested_span,
		Channel::TransportClass	tclass,
		GenericCallback *	when_valid = NULL )

ChannelReadToken constructor, deprecated version.

Deprecated: Use a version without Channel::TransportClass, transport class is actually determined by writing tokens

◆ ChannelReadToken() [5/5]

dueca::ChannelReadToken::ChannelReadToken	(	const GlobalId &	owner,
		const NameSet &	channelname,
		const std::string &	dataclassname,
		entryid_type	entryhandle,
		Channel::EntryTimeAspect	time_aspect,
		Channel::EntryArity	arity,
		Channel::ReadingMode	rmode,
		const UCallbackOrActivity &	when_valid,
		unsigned	requested_depth )

Constructor, creates a token and if needed creates the associated channel end.

Third variant, with entry handle as selection and using a channel depth in copies count, instead of time. Mainly for compatibility with older DUECA versions.

Parameters

owner	Identification of the owner
channelname	Name of the channel end
dataclassname	Name of the data type to be read
entryhandle	Selecting handle for the entry. If equal to `entry_any`, the token will be connected to all entries of the specified data class, otherwise a specific entry will be selected. Entryhandle 0 is the first entry.
time_aspect	The data in the entry may represent a continuous time approximation ("stream") data, which has a contiguous time span associated with it, or it may represent individual data items ("event"), which are marked with a time point. This must match the mode in which this entry was written, or specify Channel::AnyTimeAspect to not be selective.
arity	Indicate the desired number of entries in the channel.
rmode	Reading mode, when Channel::JumpToMatchTime, the reading may skip older data in the channel, when Channel::ReadAllData, the data is read sequentially, no data is skipped. Using Channel::AdaptEventStream uses JumpToMatchTime for stream, and ReadAllData for event channels.
when_valid	Optional callback, to invoked when the token becomes valid.
requested_depth	How many copies should be kept in the channel.

Member Function Documentation

◆ isValid()

bool dueca::ChannelReadToken::isValid ( )

virtual

Check the validity of the token.

Returns: true if the token is valid to be used.

Implements dueca::GenericToken.

◆ getClientId()

const GlobalId & dueca::ChannelReadToken::getClientId ( ) const

inline

Return the client ID.

Returns: An object id referring to the client.

◆ getChannelId()

const GlobalId & dueca::ChannelReadToken::getChannelId ( ) const

Return the channel ID.

Returns: Id given to the channel.

◆ isSequential()

bool dueca::ChannelReadToken::isSequential ( ) const

Data access type, sequential?

Returns: true if the data is read sequentially, oldest first, with ChannelDef::ReadAllData or ChannelDef::ReadReservation.

◆ getOldestDataTime()

DataTimeSpec dueca::ChannelReadToken::getOldestDataTime ( ) const

Return the span of the oldest data in the current entry.

Note that you cannot count on this if reading mode is JumpToMatchTime, since the channel may be cleaned in the meantime.

Returns: Time span (or tick) of the oldest accessible data point. If there is no data, it returns the improbable DataTimeSpec(0,0)

◆ getLatestDataTime()

DataTimeSpec dueca::ChannelReadToken::getLatestDataTime ( ) const

Return the span of the latest data in the current entry.

Note that you cannot always count on this, since the channel may receive new data in the meantime.

Returns: Time span (or tick) of the newest data point. If there is no data, it returns the improbable DataTimeSpec(0,0)

◆ selectFirstEntry()

void dueca::ChannelReadToken::selectFirstEntry ( )

Instruct the token to start dealing with the first entry in the channel.

Only use this if the token has not been tied to a specific entry

Exceptions

AccessNotReleased If you have still a read access open on this channel.

◆ selectNextEntry()

void dueca::ChannelReadToken::selectNextEntry ( )

Instruct the token to start dealing with the next entry.

Exceptions

AccessNotReleased If you have still a read access open on this channel.

◆ haveEntry()

bool dueca::ChannelReadToken::haveEntry ( ) const

Check that there is a valid entry to read.

Returns: True if there is an entry to deal with, false if no entries available.

◆ getEntryId()

const entryid_type dueca::ChannelReadToken::getEntryId ( ) const

Get the entry handle id.

Note that the returned entry id depends on which the currently selected entry is. The selectFirstEntry and selectNextEntry calls influence this. Note that such calls will be used by a dueca::DataReader with VirtualJoin template.

Returns: An entryid number.

◆ getEntryLabel()

const std::string & dueca::ChannelReadToken::getEntryLabel ( ) const

Get the current entry's label, if available.

Note that the returned entry label depends on which the currently selected entry is. The selectFirstEntry and selectNextEntry calls influence this. Note that such calls will be used by a dueca::DataReader with VirtualJoin template.

Returns: The label of the entry.

◆ getNumVisibleSets() [1/2]

unsigned int dueca::ChannelReadToken::getNumVisibleSets ( const TimeTickType ts = MAX_TIMETICK ) const

Returns the number of data points older than the given time.

Note that this number may differ per entry, and thus change after a call to getNextEntry().

The returned number of sets may be imprecise, i.e. sets may be may be added while reading or between calls.

Parameters

ts	Latest time to look for

Returns: Number of data points

◆ getNumVisibleSets() [2/2]

unsigned int dueca::ChannelReadToken::getNumVisibleSets ( const DataTimeSpec ts ) const

inline

Returns the number of data points older than the given, for any of the entries read by this token.

The returned number of sets may be imprecise, i.e. sets may have been added while reading or between calls.

If you created the read access with the Channel::JumpToMatchTime (either directly, or indirectly because you specified Channel::Continuous and Channel::AdaptEventStream), the returned number of sets may also reduce, because older data automatically gets cleaned. In that case, use a try/catch block when reading.

Parameters

ts	Latest time to look for.

Returns: Number of data points

◆ getNumVisibleSetsInEntry() [1/2]

unsigned int dueca::ChannelReadToken::getNumVisibleSetsInEntry ( const TimeTickType ts = MAX_TIMETICK ) const

Returns the number of data points older than the given time for the currently selected entry read by this token.

The returned number of sets may be imprecise, i.e. sets may be may be added while reading or between calls.

Parameters

ts	Latest time to look for

Returns: Number of data points

◆ getNumVisibleSetsInEntry() [2/2]

unsigned int dueca::ChannelReadToken::getNumVisibleSetsInEntry ( const DataTimeSpec ts ) const

inline

Returns the number of data points older than the given time, for the currently selected entry read by this token.

The returned number of sets may be imprecise, i.e. sets may have been added while reading or between calls.

If you created the read access with the Channel::JumpToMatchTime (either directly, or indirectly because you specified Channel::Continuous and Channel::AdaptEventStream), the returned number of sets may also reduce, because older data automatically gets cleaned. In that case, use a try/catch block when reading.

Parameters

ts	Latest time to look for.

Returns: Number of data points

◆ haveVisibleSets() [1/2]

bool dueca::ChannelReadToken::haveVisibleSets ( const TimeTickType ts = MAX_TIMETICK ) const

Returns true if there are data points visible at the given time, for any of the entries read by this token.

This is more efficient than getNumVisibleSets; the same considerations apply.

Parameters

ts	Latest time to look for

Returns: true if there is at least one datapoint visible

◆ haveVisibleSets() [2/2]

bool dueca::ChannelReadToken::haveVisibleSets ( const DataTimeSpec ts ) const

inline

Returns true if there are data points visible at the given time.

This works well with sequential reading. It might still result in a NoDataAvailable exception if you try non-sequential read after testing this.

This is more efficient than getNumVisibleSets.

Parameters

ts	Latest time to look for

Returns: true if there is at least one datapoint visible

◆ haveVisibleSetsInEntry() [1/2]

bool dueca::ChannelReadToken::haveVisibleSetsInEntry ( const TimeTickType ts = MAX_TIMETICK ) const

Returns true if there are data points visible at the given time, for the current entry read by this token.

This is more efficient than getNumVisibleSetsInEntry; the same considerations apply.

Parameters

ts	Latest time to look for

Returns: true if there is at least one datapoint visible

◆ haveVisibleSetsInEntry() [2/2]

bool dueca::ChannelReadToken::haveVisibleSetsInEntry ( const DataTimeSpec ts ) const

inline

Returns true if there are data points visible at the given time, for the current entry read by this token.

This works well with sequential reading. It might still result in a NoDataAvailable exception if you try non-sequential read after testing this, or you try to read for a specific time that has no data present.

This is more efficient than getNumVisibleSetsInEntry.

Parameters

ts	Latest time to look for

Returns: true if there is at least one datapoint visible

◆ flushTotalAvailableSets()

unsigned int dueca::ChannelReadToken::flushTotalAvailableSets ( ) const

Flush all data in a channel for this reader.

Note that this is only relevant for tokens that do sequential reads.

For read tokens accessing multiple entries, this will leave the first entry selected after completion.

Returns: Number of data sets flushed

◆ flushOlderSets() [1/2]

unsigned int dueca::ChannelReadToken::flushOlderSets ( ) const

Flush almost all data in a channel for this reader, but leave one dataset in.

For read tokens accessing multiple entries, this will leave the first entry selected after completion.

Returns: Number of data sets flushed

◆ flushOlderSets() [2/2]

unsigned int dueca::ChannelReadToken::flushOlderSets ( const TimeTickType ts ) const

Flush almost all data in a channel for this reader, but leave datasets newer than ts.

For read tokens accessing multiple entries, this will leave the first entry selected after completion.

Returns: Number of data sets flushed

◆ flushOne()

unsigned int dueca::ChannelReadToken::flushOne ( ) const

Flush a single dataset for this reader.

For read tokens accessing multiple entries, this will leave the first entry selected after completion.

Returns: Number of data sets flushed

◆ readAndStoreData()

AccessResult dueca::ChannelReadToken::readAndStoreData	(	AmorphStore &	s,
		TimeTickType &	tsprev )

Read channel data into an amorph store object.

This packs first timing information and then channel data into the AmorphStore object. If stream data that matches the previous timestep, packs just the end validity and the data. If event data, just time tick and data. If stream data that does not match up with the previous time step, a complete timespec is packed, and the return value is TimeSkip. If no data available, nothing is packed and this returns NoData.

Parameters

s	Amorphous storage object.
tsprev	Time for which previous data set packed, is updated keep this value for the next read.

Returns: AccessResult

Exceptions

AmorphStoreBoundary If there is no room in the store. The ChannelReadToken state is reset.

◆ readAndPack()

bool dueca::ChannelReadToken::readAndPack	(	AmorphStore &	s,
		DataTimeSpec &	ts,
		const TimeSpec &	tsreq = TimeSpec(0U, MAX_TIMETICK) )

Read channel data into an amorph store object.

Unlike readAndStoreData, this does not store time tick information.

Parameters

s	Amorphous storage object.
ts	Resulting time for the packed data
tsreq	Requested timespec, if not specified gives latest data, but always observing sequential reading if applicable

Returns: true if packed data

Exceptions

AmorphStoreBoundary If there is no room in the store. ChannelReadToken state is reset.

◆ applyFunctor()

bool dueca::ChannelReadToken::applyFunctor	(	DCOFunctor *	fnct,
		TimeTickType	time = MAX_TIMETICK )

Apply a given functor to channel data.

If successful, this has the same effect as reading the data, so with ReadAllData mode, the data point is marked as read and no longer available.

Functors are extensions to the data reading and writing system, providing a generic and datatype agnostic way of handling data points. The hdf5 reading and writing system is an example of these, providing generic access, in this case for logging and loading, without information on the channel data class.

Parameters

fnct	Functor to be applied (obtained from the data class registry, using GenericToken::getMetaFunctor )
time	Time for reading

Returns: True if data read and functor succeeded, false if no data available.

◆ getAccess()

const void * dueca::ChannelReadToken::getAccess	(	TimeTickType	t_request,
		DataTimeSpec &	ts,
		GlobalId &	origin,
		uint32_t	magic )

protected

Return a void pointer to the data in the current entry.

As a side effect it updates the time spec with the time specification of the data requested. Note that you do not normally want this type of interaction with the channel data!

Parameters

t_request	Time for which data is requested. If equal to max value, selects latest data if the reading mode is JumpToMatchTime, or the following unread data point if using ReadAllData or ReadReservation.
ts	Updated with the actual time point or span of the data.
origin	Updated with the source of the data.
magic	magic number, must match the data type magic number

Returns: Pointer to the data area.

Exceptions

ChannelWrongDataType	When type mismatch
NoDataAvailable	When no data found

◆ addTarget()

void dueca::ChannelReadToken::addTarget	(	const boost::intrusive_ptr< TriggerTarget > &	t,
		unsigned	id )

protectedvirtual

Override the addTarget method from the TriggerPuller class.

An access token does not pull itself, the TriggerPuller capabilities are faked, and the pulling job is handed over to the channel.

Reimplemented from dueca::TriggerPuller.

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

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

Public Types

Public Member Functions

Protected Member Functions

Friends

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ AccessResult

Constructor & Destructor Documentation

◆ ChannelReadToken() [1/5]

◆ ChannelReadToken() [2/5]

◆ ChannelReadToken() [3/5]

◆ ChannelReadToken() [4/5]

◆ ChannelReadToken() [5/5]

Member Function Documentation

◆ isValid()

◆ getClientId()

◆ getChannelId()

◆ isSequential()

◆ getOldestDataTime()

◆ getLatestDataTime()

◆ selectFirstEntry()

◆ selectNextEntry()

◆ haveEntry()

◆ getEntryId()

◆ getEntryLabel()

◆ getNumVisibleSets() [1/2]

◆ getNumVisibleSets() [2/2]

◆ getNumVisibleSetsInEntry() [1/2]

◆ getNumVisibleSetsInEntry() [2/2]

◆ haveVisibleSets() [1/2]

◆ haveVisibleSets() [2/2]

◆ haveVisibleSetsInEntry() [1/2]

◆ haveVisibleSetsInEntry() [2/2]

◆ flushTotalAvailableSets()

◆ flushOlderSets() [1/2]

◆ flushOlderSets() [2/2]

◆ flushOne()

◆ readAndStoreData()

◆ readAndPack()

◆ applyFunctor()

◆ getAccess()

◆ addTarget()