dueca::MultiStreamReadToken< T > Class Template Reference

Handle type identifying entries in the channel. More...

#include <MultiStreamReadToken.hxx>

Inheritance diagram for dueca::MultiStreamReadToken< T >:

Collaboration diagram for dueca::MultiStreamReadToken< T >:

Public Member Functions
	MultiStreamReadToken (const GlobalId &holder, const NameSet &name_set, TimeTickType span, Channel::TransportClass tclass=Channel::Regular, Channel::TransportClass bclass=Channel::Regular, GenericCallback *when_valid=NULL)
	Constructor.
	~MultiStreamReadToken ()
	Destructor.
Public Member Functions inherited from 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.
	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.

Friends
class	MultiStreamReaderBase< T >
	These methods accessible by readerbase.

Additional Inherited Members
Public Types inherited from dueca::ChannelReadToken
enum	AccessResult { NoData , TimeSkip , DataSuccess }
	Different type of access result. More...
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 Member Functions inherited from dueca::ChannelReadToken
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.
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

template<class T>
class dueca::MultiStreamReadToken< T >

Handle type identifying entries in the channel.

Access token used to read data from a MultiStreamChannel.

A MultiStreamChannel is a stream channel version that contains the Entries of multiple similar entities. You may compare this with the HLA-style publish-subscribe mechanism, (still?) without the inheritance and data management.

The channel builds forth on the GenericChannel class. It adds the functionality needed for reading and writing data on a channel with multiple "entries" or "personalities" in it. For example it may be used to transmit entity-to-entity data from all aircraft in a simulation. However, don't limit your imagination to conventional entries in a channel. The MultiStreamChannel can for example also be used to contain the data for an FMS track, with each entry being a track element. Efficient transmission of data (as long as no changes are made to the data or no new channel ends are added, nothing is transmitted, and if changes are made, the differences are coded and transmitted) allows for a wide variety of uses.

To get read or write access to the channel, components need to create a MultiStreamReadToken or a MultiStreamWriteToken. The local copy of the channel is then created if it did not previously exist. Each MultiStreamWriteToken creates an entry in the channel, and this entry will be replicated on any channel ends on other nodes. With the destruction of the MultiStreamWriteToken the entry disappears again. A MultiStreamReadToken can be used to read all the entries in the channel.

A typical reading application might do:

// spool to the first entry in the channel
my_token.selectFirstEntry();
 
// read all the entries
while (my_token.haveEntry()) {
 
  {
    // use a MultiStreamReader to access this entry in the channel
    MultiStreamReader<MyDataType> r(my_token, ts);
 
    // read, with r.data()
 
    // close off this block, so reader is destroyed and read
    // access is released. If you don't do that, the
    // selectNextEntry call will throw an AccessNotReleased
    // exception!
  }
 
  // step to the next entry in the channel
  my_token.selectNextEntry();
}

Note that the order in which the entries appear does not need to be the order in which the write tokens were made. As a write token is destroyed, the place in the channel it occupied is cleaned up, and after some cycles this place is again available for re-use by a new write token.

Note that this is now obsolete. Use the new dueca::ChannelReadToken with appropriate settings to access a channel with multiple entries. It is even better to use a dueca::ChannelWatcher to watch for added or deleted entries in such a channel, and open each of these entries with a separate read token.

Constructor & Destructor Documentation

MultiStreamReadToken()

template<class T >

dueca::MultiStreamReadToken< T >::MultiStreamReadToken	(	const GlobalId &	holder,
		const NameSet &	name_set,
		TimeTickType	span,
		Channel::TransportClass	tclass = Channel::Regular,
		Channel::TransportClass	bclass = Channel::Regular,
		GenericCallback *	when_valid = NULL )

Constructor.

Constructs an access token to read the stream channel with the specified name.

Parameters

holder	ID of the requester.
name_set	NameSet with the name of the channel that you request access for.
span	Time span, in integer ticks, that the data should be kept.
tclass	Transport class (priority) for sending the control data and differences/changes.
bclass	Transport class (priority) for sending the initial value of the entry. Consider using Bulk here if you expect to write large and largely static entries.
when_valid	Method called when the token becomes valid.

~MultiStreamReadToken()

template<class T >

dueca::MultiStreamReadToken< T >::~MultiStreamReadToken

(

)

Destructor.

The existence of the channel may continue, it is really destroyed when you were the last user.

---

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

• /home/abuild/rpmbuild/BUILD/dueca-4.1.3/dueca/MultiStreamReadToken.hxx