Allows you to receive samples from a SharedReaderQueue. More...

Inherits AlreadyDisposedHelper< QueueConsumer< T >>, and IDisposable.

Inherited by RTI.Connext.Queuing.QueueConsumer< T >.EmptyReaderListener, and RTI.Connext.Queuing.QueueConsumer< T >.QueueConsumerReaderListener.

Public Member Functions
	QueueConsumer (DomainParticipant participant, String queueTopicName, String sharedSubscriber, TypeSupport queueTypeSupport)
	Creates a QueueConsumer with the minimum set of parameters.

	QueueConsumer (QueueConsumerParams< T > parameters)
	Creates a QueueConsumer with parameters.

bool	ReceiveSample (Sample< T > sample, Duration_t maxWait)
	Waits for a sample and copies its contents into a Sample.

IList< Sample< T > >	ReceiveSamples (IList< Sample< T >> samples, int maxCount, Duration_t maxWait)
	Waits for multiple samples and copies them into a list.

IList< Sample< T > >	ReceiveSamples (IList< Sample< T >> samples, int minCount, int maxCount, Duration_t maxWait)
	Waits for multiple samples and copies them into a list.

LoanedSamples< T >	ReceiveSamples (Duration_t maxWait)
	Waits for multiple samples and provides a loaned container to access them.

LoanedSamples< T >	ReceiveSamples (int minCount, int maxCount, Duration_t maxWait)
	Waits for multiple samples and provides a loaned container to access them.

bool	TakeSample (Sample< T > sample)
	Copies the contents of a sample into a Sample.

LoanedSamples< T >	TakeSamples ()
	Provides a loaned container to access the existing samples.

LoanedSamples< T >	TakeSamples (int maxCount)
	Provides a loaned container to access the existing samples.

IList< Sample< T > >	TakeSamples (IList< Sample< T >> samples, int maxCount)
	Copies existing samples into a list.

bool	ReadSample (Sample< T > sample)
	Copies the contents of a sample into a Sample.

LoanedSamples< T >	ReadSamples ()
	Provides a loaned container to access the existing samples.

LoanedSamples< T >	ReadSamples (int maxCount)
	Provides a loaned container to access the existing samples.

IList< Sample< T > >	ReadSamples (IList< Sample< T >> samples, int maxCount)
	Copies existing samples into a list.

bool	WaitForSamples (Duration_t maxWait)
	Waits for samples.

bool	WaitForSamples (int minCount, Duration_t maxWait)
	Waits for samples.

void	AcknowledgeAll (bool isPositiveAck)
	Acknowledge all previously accessed samples.

void	AcknowledgeSample (SampleInfo sampleInfo, bool isPositiveAck)
	Explicitly acknowledges a single sample.

void	SendAvailability (ConsumerAvailabilityParams_t parameters)
	Sends the QueueConsumer availability to Queuing Service.

bool	HasMatchingSharedReaderQueue ()
	Checks whether this QueueConsumer has matched at least one SharedReaderQueue.

Sample< T >	CreateSample ()
	Creates a Sample for receiving samples from the SharedReaderQueue.

Sample< T >	CreateSample (T data)
	Creates a Sample for receiving samples from the SharedReaderQueue.

Properties
TypedDataReader< T >	Reader `[get]`
	Retrieves the underlying DDS::DataReader.

GUID_t	Guid `[get]`
	Returns the GUID of this QueueConsumer.

Detailed Description

Allows you to receive samples from a SharedReaderQueue.

A QueueConsumer is an entity that allows you to receive samples from a SharedReaderQueue hosted by Queuing Service. A QueueConsumer has one underlying DDS::DataReader to communicate with a SharedReaderQueue.

Valid types for the topic of the DataReader (T) are those generated by the rtiddsgen code generator, the DDS built-in types, and DynamicData.

For example:

QueueConsumer<Foo> consumer
QueueConsumer<DynamicData> consumer
QueueConsumer<Octets> consumer

To receive samples from a SharedReaderQueue, a QueueConsumer must set its topic name (see RTI::Connext::Queuing::QueueConsumerParams<T>::SetQueueTopicName) equal to the SharedReaderQueue topic name (set with the XML tag <topic_name> under <shared_reader_queue>).

In addition, the QueueConsumer must set its SharedSubscriber name (RTI::Connext::Queuing::QueueConsumerParams<T>::SetSharedSubscriberName) equal to the name of the SharedSubscriber hosting the SharedReaderQuueue.

The QueueConsumer and the SharedReaderQueue must also be in the same DDS domain (that is, they must have the same domain ID).

A QueueConsumer has an associated DDS::DomainParticipant, which can be shared with other QueueConsumers or RTI Connext routines. All the other DDS entities required for queuing interaction, including the DDS::DataReader to receive samples, are automatically created when the QueueConsumer is constructed.

Quality of Service (QoS) for the underlying DataReader is configurable (see RTI::Connext::Queuing::QueueConsumerParams<T>::SetQosProfile and RTI::Connext::Queuing::QueueConsumerParams<T>::SetDataReaderQos).

If no QoS is specified in the RTI::Connext::Queuing::QueueConsumerParams<T>, the default DataReaderQos will be used.

A QueueConsumer must always be reliable in order to match and communicate with the SharedReaderQueue. In addition, it shall use application acknowledgement to notify Queuing Service that a sample has been consumed successfully. Hence, whichever DataReaderQos is selected, the following QoS settings are always overriden:

DDS::ReliabilityQosPolicy::kind is set to ::DDS::ReliabilityQosPolicyKind::RELIABLE_RELIABILITY_QOS.
DDS::ReliabilityQosPolicy::acknowledgement_mode is set to ::DDS::ReliabilityQosPolicyAcknowledgmentModeKind::APPLICATION_EXPLICIT_ACKNOWLEDGMENT_MODE.
DDS::DataReaderResourceLimitsQosPolicy::max_app_ack_response_length is set to 1.

The underlying DataReader is created with an internal DDS::DataReaderListener, which is required to provide the behavior of a QueueConsumer, including notification of events via RTI::Connext::Queuing::QueueConsumerListener<T>. For this reason, when accessing the underlying DataReader, the listener should not be set, removed or modified; otherwise the behavior of the QueueConsumer will be incorrect and unpredictable.

Optionally, a QueueConsumer can be configured to create an availability channel (RTI::Connext::Queuing::QueueConsumerParams<T>::SetEnableAvailability). This channel is used to report the QueueConsumer's availability to the SharedReaderQueue from which the QueueConsumer receives samples. Queuing Service uses the reported availability to distribute samples to the QueueConsumer.

If the availability channel is enabled for the QueueConsumer, a DDS::DataWriter is created to send availability samples to the SharedReaderQueue.

You can configure the DataWriterQos used by the availability DataWriter by using RTI::Connext::Queuing::QueueConsumerParams<T>::SetQosProfile.

Whichever DataWriterQos is selected, the following QoS settings are always overriden:

DDS::ReliabilityQosPolicy::kind is set to ::DDS::ReliabilityQosPolicyKind::RELIABLE_RELIABILITY_QOS.
DDS::DurabilityQosPolicy::kind is set to ::DDS::DurabilityQosPolicyKind::TRANSIENT_LOCAL_DURABILITY_QOS.
DDS::HistoryQosPolicy::kind is set to ::DDS::HistoryQosPolicyKind::KEEP_LAST_HISTORY_QOS.

Template Parameters

T	The data type for the SharedReaderQueue topic

See Also: RTI::Connext::Queuing::QueueConsumer<T>; RTI::Connext::Queuing::QueueConsumerListener<T>

Type Constraints

T	:	class
T	:	global
T	:	DDS.ICopyable<T>
T	:	new()

Constructor & Destructor Documentation

RTI.Connext.Queuing.QueueConsumer< T >.QueueConsumer	(	DomainParticipant	participant,
		String	queueTopicName,
		String	sharedSubscriber,
		TypeSupport	queueTypeSupport
	)

inline

Creates a QueueConsumer with the minimum set of parameters.

Parameters

participant	The DomainParticipant that this QueueConsumer uses to join a DDS domain.
queueTopicName	The queue topic name as specified in a Queuing Service SharedReaderQueue configuration. See RTI::Connext::Queuing::QueueConsumerParams<T>::SetQueueTopicName
sharedSubscriberName	The name of the SharedSubscriber in a Queuing Service that hosts the queue. See RTI::Connext::Queuing::QueueConsumerParams<T>::SetSharedSubscriberName
queueTypeSupport	The type support for type `T`

Exceptions

One	of the Standard Return Codes

RTI.Connext.Queuing.QueueConsumer< T >.QueueConsumer ( QueueConsumerParams< T > parameters )

inline

Creates a QueueConsumer with parameters.

Parameters

params All the parameters that configure this QueueConsumer

Exceptions

One	of the Standard Return Codes

See Also: RTI::Connext::Queuing::QueueConsumerParams<T>

Member Function Documentation

bool RTI.Connext.Queuing.QueueConsumer< T >.ReceiveSample	(	Sample< T >	sample,
		Duration_t	maxWait
	)

inline

Waits for a sample and copies its contents into a Sample.

Equivalent to using WaitForSamples(int,Duration_t) and TakeSample(Sample<T>).

See Also: RTI::Connext::Infrastructure::Sample<T>; WaitForSamples(int,Duration_t); TakeSample(Sample<T>)

IList<Sample<T> > RTI.Connext.Queuing.QueueConsumer< T >.ReceiveSamples	(	IList< Sample< T >>	samples,
		int	maxCount,
		Duration_t	maxWait
	)

inline

Waits for multiple samples and copies them into a list.

Equivalent to ReceiveSamples(IList<Sample<T>>,int,int,Duration_t) with min_count = 0.

See Also: RTI::Connext::Infrastructure::Sample<T>; ReceiveSamples(IList<Sample<T>>,int,Duration_t)

IList<Sample<T> > RTI.Connext.Queuing.QueueConsumer< T >.ReceiveSamples	(	IList< Sample< T >>	samples,
		int	minCount,
		int	maxCount,
		Duration_t	maxWait
	)

inline

Waits for multiple samples and copies them into a list.

Equivalent to using WaitForSamples(int,Duration_t) and TakeSamples(IList<Sample<T>>,int).

See Also: RTI::Connext::Infrastructure::Sample<T>; WaitForSamples(int,Duration_t); TakeSamples(IList<Sample<T>>,int)

LoanedSamples<T> RTI.Connext.Queuing.QueueConsumer< T >.ReceiveSamples ( Duration_t maxWait )

inline

Waits for multiple samples and provides a loaned container to access them.

Equivalent to using ReceiveSamples(int,int,Duration_t) with min_count=1 and max_count=DDS::ResourceLimitsQosPolicy::LENGTH_UNLIMITED.

See Also: RTI::Connext::Infrastructure::LoanedSamples<T>; ReceiveSamples(int,int,Duration_t)

LoanedSamples<T> RTI.Connext.Queuing.QueueConsumer< T >.ReceiveSamples	(	int	minCount,
		int	maxCount,
		Duration_t	maxWait
	)

inline

Waits for multiple samples and provides a loaned container to access them.

Equivalent to using WaitForSamples(int,Duration_t) and TakeSamples(int).

See Also: RTI::Connext::Infrastructure::LoanedSamples<T>; WaitForSamples(int,Duration_t); TakeSamples(int)

bool RTI.Connext.Queuing.QueueConsumer< T >.TakeSample ( Sample< T > sample )

inline

Copies the contents of a sample into a Sample.

Takes a sample from the QueueConsumer and makes a copy.

This operation may be used after a call to WaitForSamples(int,Duration_t).

To avoid copies, you can use .

Parameters

sample The sample where the reply data and the related SampleInfo are copied

Returns: true if there was a sample to get. If this operation returns false, the contents of sample remain unchanged, except DDS::SampleInfo::valid_data becomes false.

Exceptions

One	of the Standard Return Codes

MT Safety:: SAFE

See Also: RTI::Connext::Infrastructure::Sample<T>; WaitForSamples(int,Duration_t)

LoanedSamples<T> RTI.Connext.Queuing.QueueConsumer< T >.TakeSamples ( )

inline

Provides a loaned container to access the existing samples.

This operation is equivalent to using TakeSamples(int) with max_count=DDS::ResourceLimitsQosPolicy::LENGTH_UNLIMITED.

See Also: RTI::Connext::Infrastructure::LoanedSamples<T>; RTI::Connext::Queuing::QueueConsumer<T>::TakeSamples()

LoanedSamples<T> RTI.Connext.Queuing.QueueConsumer< T >.TakeSamples ( int maxCount )

inline

Provides a loaned container to access the existing samples.

Takes all the existing samples up to maxCount and provides a loaned container to access them.

This operation does not make a copy of the data.

The loan is returned with RTI::Connext::Infrastructure::LoanedSamples<T>::Dispose.

This operation may be used after a call to WaitForSamples(int,Duration_t).

Parameters

maxCount The maximum number of samples that are taken at a time. The special value DDS::ResourceLimitsQosPolicy::LENGTH_UNLIMITED may be used. This value will read up to the limit specified by DDS::DataReaderResourceLimitsQosPolicy::max_samples_per_read.

Returns: A container with up to maxCount elements. May be empty if there were no replies to get.

Exceptions

One	of the Standard Return Codes

MT Safety:: SAFE

See Also: RTI::Connext::Infrastructure::Sample<T>; RTI::Connext::Infrastructure::LoanedSamples<T>; RTI::Connext::Infrastructure::LoanedSamples<T>::Dispose; WaitForSamples(int,Duration_t); DDS::TypedDataReader::take (for a more detailed description on how QoS and other parameters affect the underlying DataReader)

IList<Sample<T> > RTI.Connext.Queuing.QueueConsumer< T >.TakeSamples	(	IList< Sample< T >>	samples,
		int	maxCount
	)

inline

Copies existing samples into a list.

Takes all the existing samples up to maxCount and copies them into a list.

If the first argument is null, this creates a new list containing the copies and returns the list.

If a non-null list is passed as the first argument, the copies are inserted into that list. The list may already contain some elements. Any existing elements are overwritten. If the list contains fewer elements than needed, samples are appended at the end; if it contains more elements than needed, the excess samples are removed from the end.

You can use this operation after a call to WaitForSamples(int,Duration_t).

Parameters

replies	The list where the samples are copied, or null to create a new list.
maxCount	The maximum number of samples that are taken at a time. The special value DDS::ResourceLimitsQosPolicy::LENGTH_UNLIMITED may be used.

Returns: Returns replies if it is not null. Otherwise it returns a new list.

Exceptions

One	of the Standard Return Codes

MT Safety:: SAFE

See Also: RTI::Connext::Infrastructure::Sample<T>; WaitForSamples(int,Duration_t); TakeSamples(int)

bool RTI.Connext.Queuing.QueueConsumer< T >.ReadSample ( Sample< T > sample )

inline

Copies the contents of a sample into a Sample.

This operation is equivalent to RTI::Connext::Queuing::QueueConsumer<T>::TakeSample(Sample<T>), except the sample remains in the QueueConsumer and can be read or taken again.

LoanedSamples<T> RTI.Connext.Queuing.QueueConsumer< T >.ReadSamples ( )

inline

Provides a loaned container to access the existing samples.

This operation is equivalent to RTI::Connext::Queuing::QueueConsumer<T>::TakeSamples(), except the samples remain in the QueueConsumer and can be read or taken again.

LoanedSamples<T> RTI.Connext.Queuing.QueueConsumer< T >.ReadSamples ( int maxCount )

inline

Provides a loaned container to access the existing samples.

This operation is equivalent to RTI::Connext::Queuing::QueueConsumer<T>::TakeSamples(int), except the samples remain in the QueueConsumer and can be read or taken again.

IList<Sample<T> > RTI.Connext.Queuing.QueueConsumer< T >.ReadSamples	(	IList< Sample< T >>	samples,
		int	maxCount
	)

inline

Copies existing samples into a list.

This operation is equivalent to RTI::Connext::Queuing::QueueConsumer<T>::TakeSamples(IList<Sample<T>>,int), except the samples remain in the QueueConsumer and can be read or taken again.

bool RTI.Connext.Queuing.QueueConsumer< T >.WaitForSamples ( Duration_t maxWait )

inline

Waits for samples.

This operation is equivalent to WaitForSamples(int,Duration_t) with min_count=1.

See Also: WaitForSamples(int,Duration_t)

bool RTI.Connext.Queuing.QueueConsumer< T >.WaitForSamples	(	int	minCount,
		Duration_t	maxWait
	)

inline

Waits for samples.

This operation waits for minCount samples to be available. It will wait up to maxWait .

If this operation is called several times but the available samples are not taken (with ), this operation may return immediately and will not wait for new samples. New samples may replace existing ones if they are not taken, depending on the DDS::HistoryQosPolicy used to configure this QueueConsumer.

Parameters

minCount	Minimum number of replies that need to be available for this operation to unblock.
maxWait	Maximum waiting time after which this operation unblocks, regardless of how many replies are available.
minCount	Minimum number of samples that need to be available for this operation to unblock.
maxWait	Maximum waiting time after which this operation unblocks regardless of how many samples are available.

Returns: true if at least minCount samples were available before maxWait elapsed, or false otherwise.

MT Safety:: Concurrent calls to this operation on the same object are not allowed.

See Also: TakeSamples(int)

void RTI.Connext.Queuing.QueueConsumer< T >.AcknowledgeAll ( bool isPositiveAck )

inline

Acknowledge all previously accessed samples.

This is equivalent to calling AcknowledgeSample(SampleInfo, bool) for every single previously accessed sample.

Parameters

isPositiveAck Indicates whether or not the acknowledged samples were successfully processed by the application. If the samples were not processed successfully, Queuing Service will try to redeliver them to a different QueueConsumer according to the delivery policy of the SharedReaderQueue.

Exceptions

One	of the Standard Return Codes

See Also: AcknowledgeSample(SampleInfo, bool)

void RTI.Connext.Queuing.QueueConsumer< T >.AcknowledgeSample	(	SampleInfo	sampleInfo,
		bool	isPositiveAck
	)

inline

Explicitly acknowledges a single sample.

This operation calls DDS::DataReader::acknowledge_sample on the underlying DataReader.

The parameter isPositiveAck indicates whether or not the acknowledged sample was successfully processed by the application. If the sample was not processed successfully, Queuing Service will try to redeliver it to a different QueueConsumer according to the delivery policy of the SharedReaderQueue.

Parameters

sampleInfo	Identifies the sample being acknowledged. The sampleInfo can be extracted from RTI::Connext::Infrastructure::Sample<T>::Info.
isPositiveAck	Indicates whether or not the sample was succesfully processed.

Exceptions

One	of the Standard Return Codes

void RTI.Connext.Queuing.QueueConsumer< T >.SendAvailability ( ConsumerAvailabilityParams_t parameters )

inline

Sends the QueueConsumer availability to Queuing Service.

This method will use the availability DataWriter to send a sample to Queue Service indicating the availability status of the QueueConsumer application.

The method throws DDS::Retcode_PreconditionNotMet if availability is not enabled for this QueueConsumer using RTI::Connext::Queuing::QueueConsumerParams<T>::SetEnableAvailability.

Exceptions

One	of the Standard Return Codes ;

Parameters

parameters Availability status

MT Safety:: SAFE

See Also: RTI::Connext::Queuing::QueueConsumerParams<T>::SetEnableAvailability

bool RTI.Connext.Queuing.QueueConsumer< T >.HasMatchingSharedReaderQueue ( )

inline

Checks whether this QueueConsumer has matched at least one SharedReaderQueue.

Exceptions

One	of the Standard Return Codes ;

Returns: True if this QueueConsumer matches at least one SharedReaderQueue.

MT Safety:: SAFE

See Also: RTI::Connext::Queuing::QueueConsumerListener<T>::OnSharedReaderQueueMatched

Sample<T> RTI.Connext.Queuing.QueueConsumer< T >.CreateSample ( )

inline

Creates a Sample for receiving samples from the SharedReaderQueue.

Returns: A new Sample with default data of type T and invalid SampleInfo.

See Also: RTI::Connext::Infrastructure::Sample<T>; CreateSample(T)

Sample<T> RTI.Connext.Queuing.QueueConsumer< T >.CreateSample ( T data )

inline

Creates a Sample for receiving samples from the SharedReaderQueue.

Returns: A new Sample with the specified data and invalid SampleInfo.

See Also: RTI::Connext::Infrastructure::Sample<T>; CreateSample()

Property Documentation

TypedDataReader<T> RTI.Connext.Queuing.QueueConsumer< T >.Reader

get

Retrieves the underlying DDS::DataReader.

Accessing the DataReader may be useful for a number of advanced use cases, such as getting DataReader protocol or cache statuses.

MT Safety:: SAFE

See Also: DDS::DataReader; DDS::TypedDataReader; DDS::DataReader::get_datareader_protocol_status

GUID_t RTI.Connext.Queuing.QueueConsumer< T >.Guid

get

Returns the GUID of this QueueConsumer.

The GUID of the QueueConsumer is determined based on the value of RTI::Connext::Queuing::QueueConsumerParams<T>::SetEntityName and RTI::Connext::Queuing::QueueConsumerParams<T>::SetQueueTopicName. Note that the QueueConsumer GUID may be equal or different than the GUID of the underlying DataReader virtual GUID.

The GUID identifies a QueueConsumer and the samples it consumes. The underlying DataReader's content filter on the related_reader_guid is set to the QueueConsumer's GUID.

See Also: RTI::Connext::Queuing::QueueConsumerParams<T>::SetEntityName

Public Member Functions

Properties

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Property Documentation