dds::sub::DataReader< T >::ManipulatorSelector Class Reference

#include "DataReader.hpp"

Public Member Functions
	ManipulatorSelector (DataReader &dr)
ManipulatorSelector &	content (const dds::sub::Query &query)
ManipulatorSelector &	instance (const dds::core::InstanceHandle &handle)
ManipulatorSelector &	max_samples (uint32_t n)
ManipulatorSelector &	next_instance (const dds::core::InstanceHandle &handle)
ManipulatorSelector &	operator>> (dds::sub::LoanedSamples< T > &samples)
template<typename Functor >
ManipulatorSelector	operator>> (Functor f)
ManipulatorSelector &	operator>> (ManipulatorSelector &(manipulator)(ManipulatorSelector &))
bool	read_mode ()
void	read_mode (bool readmode)
ManipulatorSelector &	state (const dds::sub::status::DataState &state)

Detailed Description

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

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

A ManipulatorSelector can perform complex data selections, such as per-instance selection, content and status filtering, etc, when reading or taking samples through the streaming operator.

Convenience functors
The following convenience functors use a ManipulatorSelector implicitly and can be used in the streaming operator:

• dds::sub::read
• dds::sub::take
• dds::sub::max_samples
• dds::sub::content
• dds::sub::state
• dds::sub::instance
• dds::sub::next_instance

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

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

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

// Create a ManipulatorSelector as selective reader up front.
dds::sub::DataReader<Foo::Bar>::ManipulatorSelector 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);
selectiveReader.read_mode(false); // take
 
// Use the configured ManipulatorSelector to -take- a maximum of 3 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 ManipulatorSelectors for every take.
selectiveReader >> samples;

Defaults

Element	Default Value
read_mode	true (read)
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 stream operator>>

Definition at line 508 of file DataReader.hpp.

Constructor & Destructor Documentation

ManipulatorSelector()

template<typename T>

dds::sub::DataReader< T >::ManipulatorSelector::ManipulatorSelector

(

DataReader &

dr

)

Construct a ManipulatorSelector for a DataReader.

See also DataReader stream operator>>

Parameters

DataReader

Member Function Documentation

content()

template<typename T>

ManipulatorSelector& dds::sub::DataReader< T >::ManipulatorSelector::content

(

const dds::sub::Query &

query

)

Set Query to filter with during the read or take.

Convenience Functor: dds::sub::content

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 ManipulatorSelector
reader >> dds::sub::content(query) >> samples;
 
// Explicit use of ManipulatorSelector
dds::sub::DataReader<Foo::Bar>::ManipulatorSelector selectiveReader(reader);
selectiveReader.content(query);
selectiveReader >> read;

See also DataReader stream operator>>

Parameters

query

The Query to apply to a read/take

instance()

template<typename T>

ManipulatorSelector& dds::sub::DataReader< T >::ManipulatorSelector::instance

(

const dds::core::InstanceHandle &

handle

)

Set InstanceHandle to filter with during the read or take.

Convenience Functor: dds::sub::instance

Example
Read only samples of the given instance.

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

See also DataReader stream operator>>

Parameters

handle

the InstanceHandle for the read/take

max_samples()

template<typename T>

ManipulatorSelector& dds::sub::DataReader< T >::ManipulatorSelector::max_samples

(

uint32_t

n

)

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

Convenience Functor: dds::sub::max_samples

Example
Read a maximum of three samples.

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

See also DataReader stream operator>>

Parameters

n	maximum number of samples

next_instance()

template<typename T>

ManipulatorSelector& dds::sub::DataReader< T >::ManipulatorSelector::next_instance

(

const dds::core::InstanceHandle &

handle

)

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

Convenience Functor: dds::sub::next_instance

Example
Read all samples, instance by instance.

// Implicit use of ManipulatorSelector
{
    // Get sample(s) of first instance
    dds::core::InstanceHandle hdl; //nil
    reader >> dds::sub::next_instance(hdl) >> samples;
    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();
        reader >> dds::sub::next_instance(hdl) >> samples;
    }
}
 
// Explicit use of ManipulatorSelector
{
    // Get sample(s) of first instance
    dds::sub::DataReader<Foo::Bar>::ManipulatorSelector selectiveReader(reader);
    dds::core::InstanceHandle hdl; //nil
    selectiveReader.next_instance(hdl);
    selectiveReader >> samples;
    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);
        selectiveReader >> samples;
    }
}

See also DataReader stream operator>>

Parameters

handle

the 'previous' InstanceHandle associated with new the read/take

operator>>() [1/3]

template<typename T>

ManipulatorSelector& dds::sub::DataReader< T >::ManipulatorSelector::operator>>

(

dds::sub::LoanedSamples< T > &

samples

)

This operation works the same as the DataReader stream operator>> , except that it is performed on this ManipulatorSelector with possible filters set.

Exceptions

dds::core::Error	An internal error has occurred.
dds::core::NullReferenceError	The entity was not properly created and references to dds::core::null.
dds::core::AlreadyClosedError	The entity has already been closed.
dds::core::OutOfResourcesError	The Data Distribution Service ran out of resources to complete this operation.
dds::core::NotEnabledError	The DataReader has not yet been enabled.

operator>>() [2/3]

template<typename T>

template<typename Functor >

ManipulatorSelector dds::sub::DataReader< T >::ManipulatorSelector::operator>>

(

Functor

f

)

This operation works the same as the DataReader stream operator>> , except that it is performed on this ManipulatorSelector with possible filters set.

Exceptions

dds::core::Error	An internal error has occurred.
dds::core::NullReferenceError	The entity was not properly created and references to dds::core::null.
dds::core::AlreadyClosedError	The entity has already been closed.
dds::core::OutOfResourcesError	The Data Distribution Service ran out of resources to complete this operation.
dds::core::NotEnabledError	The DataReader has not yet been enabled.

operator>>() [3/3]

template<typename T>

ManipulatorSelector& dds::sub::DataReader< T >::ManipulatorSelector::operator>>

(

ManipulatorSelector &

manipulator)(ManipulatorSelector &

)

This operation works the same as the DataReader stream operator>> , except that it is performed on this ManipulatorSelector with possible filters set.

Exceptions

dds::core::Error	An internal error has occurred.
dds::core::NullReferenceError	The entity was not properly created and references to dds::core::null.
dds::core::AlreadyClosedError	The entity has already been closed.
dds::core::OutOfResourcesError	The Data Distribution Service ran out of resources to complete this operation.
dds::core::NotEnabledError	The DataReader has not yet been enabled.

read_mode() [1/2]

template<typename T>

bool dds::sub::DataReader< T >::ManipulatorSelector::read_mode

(

)

Get the read_mode.

The read_mode specifies if a sample should be read or taken:

• true = read (default)
• false = take

Returns

true if read_mode is set to read

read_mode() [2/2]

template<typename T>

void dds::sub::DataReader< T >::ManipulatorSelector::read_mode

(

bool

readmode

)

Set the read_mode.

The read_mode specifies if a sample should be read or taken:

• true = read (default)
• false = take

Convenience Functor: dds::sub::read
Convenience Functor: dds::sub::take

Example
Determine to read or take samples.

// No usage of ManipulatorSelector, means a read iso take as default.
reader >> samples;
 
// Implicit use of ManipulatorSelector
reader >> dds::sub::read >> samples;
reader >> dds::sub::take >> samples;
 
// Explicit use of ManipulatorSelector
dds::sub::DataReader<Foo::Bar>::ManipulatorSelector readingReader(reader);
readingReader.read_mode(true); // Read, which is already the default.
readingReader >> samples;
 
dds::sub::DataReader<Foo::Bar>::ManipulatorSelector takingReader(reader);
takingReader.read_mode(false); // Take.
takingReader >> samples;

See also DataReader stream operator>>

Parameters

readmode

the read mode of the DataReader

state()

template<typename T>

ManipulatorSelector& dds::sub::DataReader< T >::ManipulatorSelector::state

(

const dds::sub::status::DataState &

state

)

Set DataState to filter with during the read or take.

Convenience Functor: dds::sub::state

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 ManipulatorSelector
reader >> dds::sub::state(newData) >> samples;
 
// Explicit use of ManipulatorSelector
dds::sub::DataReader<Foo::Bar>::ManipulatorSelector selectiveReader(reader);
selectiveReader.state(newData);
selectiveReader.read() >> samples;

See also DataReader stream operator>>

Parameters

state

the required DataState of the samples

---

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

• dds/sub/DataReader.hpp