Cyclone ISO C++ API Reference Guide
Public Member Functions | List of all members
dds::sub::DataReader< T >::Selector Class Reference

#include "DataReader.hpp"

Public Member Functions

 Selector (DataReader &dr)
 
Selector & content (const dds::sub::Query &query)
 
Selector & instance (const dds::core::InstanceHandle &handle)
 
Selector & max_samples (uint32_t maxsamples)
 
Selector & next_instance (const dds::core::InstanceHandle &handle)
 
dds::sub::LoanedSamples< T > read ()
 
template<typename SamplesBIIterator >
uint32_t read (SamplesBIIterator sbit)
 
template<typename SamplesFWIterator >
uint32_t read (SamplesFWIterator sfit, uint32_t max_samples)
 
Selector & state (const dds::sub::status::DataState &state)
 
dds::sub::LoanedSamples< T > take ()
 
template<typename SamplesBIIterator >
uint32_t take (SamplesBIIterator sbit)
 
template<typename SamplesFWIterator >
uint32_t take (SamplesFWIterator sfit, uint32_t max_samples)
 

Detailed Description

template<typename T>
class dds::sub::DataReader< T >::Selector

The Selector class is used by the DataReader to compose read operations.

A Selector can perform complex data selections, such as per-instance selection, content and status filtering, etc, when reading or taking samples. These settings on a Selector can be concatenated.

The DataReader has the select() operation, which can be used to aqcuire the Selector functionality on the reader implicitly.

// Take a maximum of 3 new samples of a certain instance.
samples = reader.select()
.max_samples(3)
.state(dds::sub::status::DataState::new_data())
.instance(someValidInstanceHandle)
.take();

However, this will create and destroy a Selector for every read, which is not very performance friendly.

The performance can be increase by creating a Selector up front and doing the reading on that Selector directly and re-using it.

// Create a Selector as selective reader up front.
dds::sub::DataReader<Foo::Bar>::Selector selectiveReader(reader);
// Configure it to take a maximum of 3 new samples of a certain instance
selectiveReader.max_samples(3);
selectiveReader.state(dds::sub::status::DataState::new_data());
selectiveReader.instance(someValidInstanceHandle);
// Use the configured Selector to -take- a maximum of 3 new samples of a
// certain instance (which it was configured to do).
// This can be used in loops for example, reducing the need for creating
// implicit Selectors for every take.
samples = selectiveReader.take();

Defaults

Element Default Value
state dds::sub::status::DataState::any
content Empty dds::sub::Query
max_samples dds::core::LENGTH_UNLIMITED
instance dds::core::InstanceHandle nil
See also
DataReader select()

Definition at line 163 of file DataReader.hpp.

Constructor & Destructor Documentation

◆ Selector()

template<typename T>
dds::sub::DataReader< T >::Selector::Selector ( DataReader &  dr)

Construct a Selector for a DataReader.

Parameters
DataReader

Member Function Documentation

◆ content()

template<typename T>
Selector& dds::sub::DataReader< T >::Selector::content ( const dds::sub::Query &  query)

Set the Query to filter with during the read or take.

Example
Read only samples that will be filtered according to the given dds::sub::Query.

// Assume data type has an element called long_1
dds::sub::Query query(reader, "long_1 > 1 and long_1 < 7");
// Implicit use of Selector
samples = reader.select().content(query).read();
// Explicit use of Selector
dds::sub::DataReader<Foo::Bar>::Selector selectiveReader(reader);
selectiveReader.content(query);
samples = selectiveReader.read();

See also DataReader select() operation.

Parameters
querythe Query to apply to the selector
Returns
a Selector to be able to concatenate Selector settings.

◆ instance()

template<typename T>
Selector& dds::sub::DataReader< T >::Selector::instance ( const dds::core::InstanceHandle &  handle)

Set InstanceHandle to filter with during the read or take.

Example
Read only samples of the given instance.

dds::core::InstanceHandle hdl = someValidInstanceHandle;
// Implicit use of Selector
samples = reader.select().instance(hdl).read();
// Explicit use of Selector
dds::sub::DataReader<Foo::Bar>::Selector selectiveReader(reader);
selectiveReader.instance(hdl);
samples = selectiveReader.read();

See also DataReader select() operation.

Parameters
handlethe InstanceHandle to read/take for
Returns
a Selector to be able to concatenate Selector settings.

◆ max_samples()

template<typename T>
Selector& dds::sub::DataReader< T >::Selector::max_samples ( uint32_t  maxsamples)

Set max_samples to limit the number of sample to get during the read or take.

Example
Read a maximum of three samples.

// Implicit use of Selector
samples = reader.select().max_samples(3).read();
// Explicit use of Selector
dds::sub::DataReader<Foo::Bar>::Selector selectiveReader(reader);
selectiveReader.max_samples(3);
samples = selectiveReader.read();

See also DataReader select() operation.

Parameters
maxsamplesmaximum number of samples to read/take
Returns
a Selector to be able to concatenate Selector settings.

◆ next_instance()

template<typename T>
Selector& dds::sub::DataReader< T >::Selector::next_instance ( const dds::core::InstanceHandle &  handle)

Set next InstanceHandle to filter with during the read or take.

Example
Read all samples, instance by instance.

// Implicit use of Selector
{
// Get sample(s) of first instance
dds::core::InstanceHandle hdl; //nil
samples = reader.select().next_instance(hdl).read();
while (samples.length() > 0) {
// Handle the sample(s) of this instance (just the first one in this case)
const dds::sub::Sample<Foo::Bar>& sample = *(samples.begin());
// Get sample(s) of the next instance
hdl = sample.info().instance_handle();
samples = reader.select().next_instance(hdl).read();
}
}
// Explicit use of Selector
{
// Get sample(s) of first instance
dds::sub::DataReader<Foo::Bar>::Selector selectiveReader(reader);
dds::core::InstanceHandle hdl; //nil
selectiveReader.next_instance(hdl);
samples = selectiveReader.read();
while (samples.length() > 0) {
// Handle the sample(s) of this instance (just the first one in this case)
const dds::sub::Sample<Foo::Bar>& sample = *(samples.begin());
// Get sample(s) of the next instance
hdl = sample.info().instance_handle();
selectiveReader.next_instance(hdl);
samples = selectiveReader.read();
}
}

See also DataReader select() operation.

Parameters
handlethe 'previous' InstanceHandle associated with new the read/take
Returns
a Selector to be able to concatenate Selector settings.

◆ read() [1/3]

template<typename T>
dds::sub::LoanedSamples<T> dds::sub::DataReader< T >::Selector::read ( )

This operation works the same as the default DataReader read() , except that it is performed on this Selector with possible filters set.

Returns
The samples in the LoanedSamples container
Exceptions
dds::core::ErrorAn internal error has occurred.
dds::core::NullReferenceErrorThe entity was not properly created and references to dds::core::null.
dds::core::AlreadyClosedErrorThe entity has already been closed.
dds::core::OutOfResourcesErrorThe Data Distribution Service ran out of resources to complete this operation.
dds::core::NotEnabledErrorThe DataReader has not yet been enabled.

◆ read() [2/3]

template<typename T>
template<typename SamplesBIIterator >
uint32_t dds::sub::DataReader< T >::Selector::read ( SamplesBIIterator  sbit)

This operation works the same as the backward iterator DataReader read() , except that it is performed on this Selector with possible filters set.

Parameters
sbitBack-inserting container iterator
Returns
The number of samples in the LoanedSamples container
Exceptions
dds::core::ErrorAn internal error has occurred.
dds::core::NullReferenceErrorThe entity was not properly created and references to dds::core::null.
dds::core::AlreadyClosedErrorThe entity has already been closed.
dds::core::OutOfResourcesErrorThe Data Distribution Service ran out of resources to complete this operation.
dds::core::NotEnabledErrorThe DataReader has not yet been enabled.

◆ read() [3/3]

template<typename T>
template<typename SamplesFWIterator >
uint32_t dds::sub::DataReader< T >::Selector::read ( SamplesFWIterator  sfit,
uint32_t  max_samples 
)

This operation works the same as the forward iterator DataReader read() , except that it is performed on this Selector with possible filters set.

Parameters
sfitForward-inserting container iterator
max_samplesMaximum samples to read and copy into the given container
Returns
The number of samples in the LoanedSamples container
Exceptions
dds::core::ErrorAn internal error has occurred.
dds::core::NullReferenceErrorThe entity was not properly created and references to dds::core::null.
dds::core::AlreadyClosedErrorThe entity has already been closed.
dds::core::OutOfResourcesErrorThe Data Distribution Service ran out of resources to complete this operation.
dds::core::NotEnabledErrorThe DataReader has not yet been enabled.

◆ state()

template<typename T>
Selector& dds::sub::DataReader< T >::Selector::state ( const dds::sub::status::DataState &  state)

Set DataState to filter with during the read or take.

Example
Read only new data.

// DataState to filter only new data
dds::sub::status::DataState newData = dds::sub::status::DataState::new_data();
// Implicit use of Selector
samples = reader.select().state(newData).read();
// Explicit use of Selector
dds::sub::DataReader<Foo::Bar>::Selector selectiveReader(reader);
selectiveReader.state(newData);
samples = selectiveReader.read();

See also DataReader select() operation.

Parameters
statethe requested DataState of the samples
Returns
a Selector to be able to concatenate Selector settings.

◆ take() [1/3]

template<typename T>
dds::sub::LoanedSamples<T> dds::sub::DataReader< T >::Selector::take ( )

This operation works the same as the default DataReader take() , except that it is performed on this Selector with possible filters set.

Returns
The samples in the LoanedSamples container
Exceptions
dds::core::ErrorAn internal error has occurred.
dds::core::NullReferenceErrorThe entity was not properly created and references to dds::core::null.
dds::core::AlreadyClosedErrorThe entity has already been closed.
dds::core::OutOfResourcesErrorThe Data Distribution Service ran out of resources to complete this operation.
dds::core::NotEnabledErrorThe DataReader has not yet been enabled.

◆ take() [2/3]

template<typename T>
template<typename SamplesBIIterator >
uint32_t dds::sub::DataReader< T >::Selector::take ( SamplesBIIterator  sbit)

This operation works the same as the backward iterator DataReader take() , except that it is performed on this Selector with possible filters set.

Parameters
sbitBack-inserting container iterator
Returns
The number of samples in the LoanedSamples container
Exceptions
dds::core::ErrorAn internal error has occurred.
dds::core::NullReferenceErrorThe entity was not properly created and references to dds::core::null.
dds::core::AlreadyClosedErrorThe entity has already been closed.
dds::core::OutOfResourcesErrorThe Data Distribution Service ran out of resources to complete this operation.
dds::core::NotEnabledErrorThe DataReader has not yet been enabled.

◆ take() [3/3]

template<typename T>
template<typename SamplesFWIterator >
uint32_t dds::sub::DataReader< T >::Selector::take ( SamplesFWIterator  sfit,
uint32_t  max_samples 
)

This operation works the same as the forward iterator DataReader take() , except that it is performed on this Selector with possible filters set.

Parameters
sfitForward-inserting container iterator
max_samplesMaximum samples to read and copy into the given container
Returns
The number of samples in the LoanedSamples container
Exceptions
dds::core::ErrorAn internal error has occurred.
dds::core::NullReferenceErrorThe entity was not properly created and references to dds::core::null.
dds::core::AlreadyClosedErrorThe entity has already been closed.
dds::core::OutOfResourcesErrorThe Data Distribution Service ran out of resources to complete this operation.
dds::core::NotEnabledErrorThe DataReader has not yet been enabled.
The documentation for this class was generated from the following file:
dds::sub::Query
Query objects contain expressions that allow the application to specify a filter on the locally avail...
Definition: Query.hpp:61
dds::sub::status::DataState
Class to hold sample DataState information.
Definition: DataState.hpp:371
dds::sub::Sample
This class encapsulates the data and info meta-data associated with DDS samples.
Definition: Sample.hpp:30
dds::core::InstanceHandle
Class to hold the handle associated with in sample instance.
Definition: InstanceHandle.hpp:40
dds::sub::Sample::info
const SampleInfo & info() const
dds::sub::status::DataState::new_data
static DataState new_data()
Definition: DataState.hpp:631
dds::sub::DataReader::Selector
Definition: DataReader.hpp:163