rti::routing::processor::Selector< Data, Info > Class Template Reference

An element that allows reading data that meet a set of specified attributes. More...

#include <Input.hpp>

Public Member Functions
	Selector (const rti::routing::processor::TypedInput< Data, Info > input)
	Create a Selector for a TypedInput.
	Selector (const Selector &other)
	Copy constructor.
Selector &	state (const dds::sub::status::DataState &the_state)
	Select a specific dds::sub::status::DataState.
Selector &	max_samples (const int32_t count)
	Choose to only read/take up to a maximum number of samples.
Selector &	instance (const dds::core::InstanceHandle &the_handle)
	Select a specific instance to read/take.
Selector &	next_instance (const dds::core::InstanceHandle &the_handle)
	Select the instance after a specific instance.
Selector &	filter (const dds::topic::Filter &the_filter)
	Select samples based on a content filter parameters.
Selector &	query (const rti::routing::processor::Query &the_query)
	Select samples based on a rti::routing::processor::Query.
LoanedSamples< Data, Info >	take ()
	Take samples based on the state associated with this Selector.
LoanedSamples< Data, Info >	read ()
	Read samples based on the state associated with this Selector.

Detailed Description

template<typename Data, typename Info>
class rti::routing::processor::Selector< Data, Info >

An element that allows reading data that meet a set of specified attributes.

The Selector class is used by the TypedInput to compose read and take operations.

A Selector has an associated TypedInput and configures the behavior of the read or take operation performed by that TypedInput.

For example, to perform a read of at most 5 unread samples:

LoanedSamples<Foo> samples = reader.select()
    .read()
    .max_samples(5)
    .state(dds::sub::status::DataState::new_data());

Note

It's very important to consider that the behavior of this class is tightly coupled and dependent on the underlying rti::routing::adapter::StreamReader of the attached TypedInput. In particular, the samples returned by a Selector depend on the behavior of the rti::routing::adapter::StreamReader::take(SelectorState) and rti::routing::adapter::StreamReader::read(SelectorState). If the implementation of these operations behave according to the requirements, then the behavior offered by this class will be consistent.

See Also

rti::routing::adapter::SelectorState

dds::sub::DataReader::Selector for equivalent semantics and behavior with DataReaders

Constructor & Destructor Documentation

template<typename Data, typename Info>

rti::routing::processor::Selector< Data, Info >::Selector ( const rti::routing::processor::TypedInput< Data, Info >  input )

inline

Create a Selector for a TypedInput.

Selectors are created with the default filter state of the TypedInput.

Parameters

[in]

input

The TypedInput that this Selector is attached to.

template<typename Data, typename Info>

rti::routing::processor::Selector< Data, Info >::Selector ( const Selector< Data, Info > &  other )

inline

Copy constructor.

Member Function Documentation

template<typename Data, typename Info>

Selector& rti::routing::processor::Selector< Data, Info >::state ( const dds::sub::status::DataState &  the_state )

inline

Select a specific dds::sub::status::DataState.

By setting the DataState, you can specify the state of the samples that should be read or taken. The DataState of a sample encapsulates the SampleState, ViewState, and InstanceState of a sample.

Parameters

[in]

the_state

The selected DataState

References rti::routing::processor::Selector< Data, Info >::state().

Referenced by rti::routing::processor::Selector< Data, Info >::state().

template<typename Data, typename Info>

Selector& rti::routing::processor::Selector< Data, Info >::max_samples ( const int32_t  count )

inline

Choose to only read/take up to a maximum number of samples.

Parameters

[in]

count

The maximum number of samples to read/take.

References rti::routing::processor::Selector< Data, Info >::max_samples().

Referenced by rti::routing::processor::Selector< Data, Info >::max_samples().

template<typename Data, typename Info>

Selector& rti::routing::processor::Selector< Data, Info >::instance ( const dds::core::InstanceHandle &  the_handle )

inline

Select a specific instance to read/take.

This operation causes the subsequent read or take operation to access only samples belonging the single specified instance whose handle is the_handle.

Upon successful completion, the data collection will contain samples all belonging to the same instance.

The subsequent read/take may operation may fail if the InstanceHandle does not correspond to an existing data-object known to the TypedInput.

Parameters

[in]

the_handle

The handle of the instance to select

See Also

rti::routing::adapter::SelectorState

dds::sub::DataReader::Selector::instance

References rti::routing::processor::Selector< Data, Info >::instance().

Referenced by rti::routing::processor::Selector< Data, Info >::instance().

template<typename Data, typename Info>

Selector& rti::routing::processor::Selector< Data, Info >::next_instance ( const dds::core::InstanceHandle &  the_handle )

inline

Select the instance after a specific instance.

This operation causes the subsequent read or take operation to access only samples belonging a single instance whose handle is considered 'next' after the provided InstanceHandle, the_handle.

The accessed samples will all belong to the 'next' instance with InstanceHandle 'greater' than the specified previous handle that has available samples.

The special value dds::core::InstanceHandle::nil() is guaranteed to be 'less than' any valid instance_handle. So the use of the parameter value previous_handle == dds::core::InstanceHandle::nil() will return the samples for the instance that has the smallest instance_handle among all the instances that contain available samples.

Note that it is possible to call the dds::sub::next_instance(const dds::core::InstanceHandle& h) operation with a previous_handle that does not correspond to an instance currently managed by the underlying rti::routing::adapter::StreamReader.

Parameters

[in]

the_handle

The reference instance. The instance after this one will be selected.

See Also

rti::routing::adapter::SelectorState

dds::sub::DataReader::Selector::next_instance

References rti::routing::processor::Selector< Data, Info >::next_instance().

Referenced by rti::routing::processor::Selector< Data, Info >::next_instance().

template<typename Data, typename Info>

Selector& rti::routing::processor::Selector< Data, Info >::filter ( const dds::topic::Filter &  the_filter )

inline

Select samples based on a content filter parameters.

The effect of using this manipulator is that the subsequent read/take will filter the samples based on the dds::topic::Filter. If the Input has no samples that meet the constraints, the read/take will not return any data.

This selection is applied in combination with the other settings of this Selector.

Parameters

[in]

the_filter

References rti::routing::processor::Selector< Data, Info >::filter().

Referenced by rti::routing::processor::Selector< Data, Info >::filter().

template<typename Data, typename Info>

Selector& rti::routing::processor::Selector< Data, Info >::query ( const rti::routing::processor::Query &  the_query )

inline

Select samples based on a rti::routing::processor::Query.

When passing a Query, the effect of calling this method is that the underlying rti::routing::adapter::StreamReader shall filter the samples based only on the Query's settings.

Using this manipulator will always override the selection specified with Selector::filter, no matter the order in which operations are called. To reset this selection, you can call this operation passing dds::core::null.

Parameters

[in]

the_query

The Query to read/take with.

template<typename Data, typename Info>

LoanedSamples<Data, Info> rti::routing::processor::Selector< Data, Info >::take ( )

inline

Take samples based on the state associated with this Selector.

Note

This operation will call rti::routing::adapter::StreamReader::take(SelectorState) on the underlying rti::routing::adapter::StreamReader.

Exceptions

std::exception

Returns

rti::routing::processor::LoanedSamples

template<typename Data, typename Info>

LoanedSamples<Data, Info> rti::routing::processor::Selector< Data, Info >::read ( )

inline

Read samples based on the state associated with this Selector.

Note

This operation will call rti::routing::adapter::StreamReader::read(SelectorState) on the underlying rti::routing::adapter::StreamReader.

Exceptions

std::exception

Returns

rti::routing::processor::LoanedSamples