Namespace dds::sub¶

This operation retrieves the list of publications currently “associated” with the DataReader. That is, subscriptions that have a matching Topic and compatible QoS that the application has not indicated should be “ignored” by means of the ignore_publication operation on the DomainParticipant.

The handles returned in the dds::core::InstanceHandleSeq are the ones that are used by the DDS implementation to locally identify the corresponding matched DataWriter entities. You can access more detailed information about a particular publication by passing its publication_handle to either the dds::sub::matched_publication_data operation or to the read with instance operation on the built-in reader for the “DCPSPublication” topic.

See Builtin Topics for more information.

Parameters

dr – the DataReader

Throws

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::NotEnabledError – The DataReader has not yet been enabled.
dds::core::UnsupportedError – The information about “associated” subscriptions are not maintained.
dds::core::OutOfResourcesError – The Data Distribution Service ran out of resources to complete this operation.

Returns

a sequence of handles

template<typename T, typename FwdIterator> uint32_t matched_publications(const dds::sub::DataReader<T> &dr, FwdIterator begin, uint32_t max_size)¶

This operation retrieves the list of publications currently “associated” with the DataReader. That is, subscriptions that have a matching Topic and compatible QoS that the application has not indicated should be “ignored” by means of the ignore_publication operation on the DomainParticipant.

The handles returned in the dds::core::InstanceHandleSeq are the ones that are used by the DDS implementation to locally identify the corresponding matched DataWriter entities. You can access more detailed information about a particular publication by passing its publication_handle to either the dds::sub::matched_publication_data operation or to the read with instance operation on the built-in reader for the “DCPSPublication” topic.

See Builtin Topics for more information.

Parameters

dr – the DataReader
begin – an iterator indicating the beginning of a sequence of instance handles in which to put the matched subscriptions
max_size – the maximum number of matched subscriptions to return

Throws

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::NotEnabledError – The DataReader has not yet been enabled.
dds::core::UnsupportedError – The information about “associated” subscriptions are not maintained.
dds::core::OutOfResourcesError – The Data Distribution Service ran out of resources to complete this operation.

Returns

the number of matched subscriptions returned

template<typename T> const dds::topic::PublicationBuiltinTopicData matched_publication_data(const dds::sub::DataReader<T> &dr, const ::dds::core::InstanceHandle &h)¶

This operation retrieves information on the specified publication that is currently “associated” with the DataReader. That is, a publication with a matching Topic and compatible QoS that the application has not indicated should be “ignored” by means of the ignore_publication operation on the DomainParticipant. The publication_handle must correspond to a publication currently associated with the DataReader, otherwise the operation will fail and throw InvalidArgumentError. The operation dds::sub::matched_publications can be used to find the publications that are currently matched with the DataReader.

The operation may fail if the infrastructure does not locally maintain the connectivity information. In such cases the operation will throw UnsupportedError.

See also DCPS_Builtin_Topics and DCPS_Builtin_Topics_PublicationData.

Parameters

dr – the DataReader
h – the InstanceHandle

Throws

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::NotEnabledError – The DataReader has not yet been enabled.
dds::core::UnsupportedError – The information about “associated” subscriptions are not maintained.
dds::core::InvalidArgumentError – Publication not associated with the DataReader.
dds::core::OutOfResourcesError – The Data Distribution Service ran out of resources to complete this operation.

Returns

the PublicationBuiltinTopicData

template<typename READER, typename FwdIterator> uint32_t find(const dds::sub::Subscriber &sub, const std::string &topic_name, FwdIterator begin, uint32_t max_size)¶

This function retrieves a previously-created DataReader belonging to the Subscriber that is attached to a Topic with a matching topic_name. If no such DataReader exists, the operation will return an empty container.

The use of this operation on the built-in Subscriber allows access to the built-in DataReader entities for the built-in topics (see Builtin Topics).

Parameters

sub – the Subscriber for which to find a DataReader
topic_name – the topic name to find
begin – a forward iterator pointing to the start of a container in which to put the DataReaders
max_size – the number of DataReaders to return

Returns

the total number of elements returned. Notice that at most max_size will be copied using the provided iterator

template<typename READER, typename BinIterator> uint32_t find(const dds::sub::Subscriber &sub, const std::string &topic_name, BinIterator begin)¶

This function retrieves a previously-created DataReader belonging to the Subscriber that is attached to a Topic with a matching topic_name. If no such DataReader exists, the operation will return an empty container.

The use of this operation on the built-in Subscriber allows access to the built-in DataReader entities for the built-in topics (see Builtin Topics).

Parameters

sub – the Subscriber for which to find a DataReader
topic_name – the topic name to find
begin – a back inserting iterator pointing to the start of a container in which to put the DataReaders

Returns

the total number of elements returned

template<typename READER, typename T, typename FwdIterator> uint32_t find(const dds::sub::Subscriber &sub, const dds::topic::TopicDescription &topic_description, FwdIterator begin, uint32_t max_size)¶

This function retrieves a previously-created DataReader belonging to the Subscriber that is attached to a Topic with a matching topic_name. If no such DataReader exists, the operation will return an empty container.

The use of this operation on the built-in Subscriber allows access to the built-in DataReader entities for the built-in topics (see Builtin Topics).

Parameters

sub – the Subscriber for which to find a DataReader
topic_description – the topic description to find
begin – a forward iterator pointing to the start of a container in which to put the DataReaders
max_size – the number of DataReaders to return

Returns

the total number of elements returned. Notice that at most max_size will be copied using the provided iterator

template<typename READER, typename T, typename BinIterator> uint32_t find(const dds::sub::Subscriber &sub, const dds::topic::TopicDescription &topic_description, BinIterator begin)¶

This function retrieves a previously-created DataReader belonging to the Subscriber that is attached to a Topic with a matching topic_name. If no such DataReader exists, the operation will return an empty container.

The use of this operation on the built-in Subscriber allows access to the built-in DataReader entities for the built-in topics (see Builtin Topics).

Parameters

sub – the Subscriber for which to find a DataReader
topic_description – the topic description to find
begin – a back inserting iterator pointing to the start of a container in which to put the DataReaders

Returns

the total number of elements returned

template<typename READER, typename FwdIterator> uint32_t find(const dds::sub::Subscriber &sub, const dds::sub::status::DataState &rs, FwdIterator begin, uint32_t max_size)¶

This operation allows the application to access the DataReader objects that contain samples with the specified sample_states, view_states, and instance_states.

If the Presentation QosPolicy of the Subscriber to which the DataReader belongs has the access_scope set to ‘GROUP’, this operation should only be invoked inside a begin_access/end_access block. Otherwise it will throw error PreconditionNotMetError.

Depending on the setting of the dds::core::policy::Presentation QoSPolicy, the returned collection of DataReader objects may be:

a ‘set’ containing each DataReader at most once in no specified order,
a ‘list’ containing each DataReader one or more times in a specific order.

This difference is due to the fact that, in the second situation it is required to access samples belonging to different DataReader objects in a particular order. In this case, the application should process each DataReader in the same order it appears in the ‘list’ and read or take exactly one sample from each DataReader. The patterns that an application should use to access data is fully described in dds::core::policy::Presentation.

Parameters

sub – the Subscriber for which to find a DataReader
data_state – the data_state to find
begin – a forward iterator pointing to the start of a container in which to put the DataReaders
max_size – the number of DataReaders to return

Returns

the total number of elements returned. Notice that at most max_size will be copied using the provided iterator

template<typename READER, typename BinIterator> uint32_t find(const dds::sub::Subscriber &sub, const dds::sub::status::DataState &rs, BinIterator begin)¶

This operation allows the application to access the DataReader objects that contain samples with the specified sample_states, view_states, and instance_states.

If the Presentation QosPolicy of the Subscriber to which the DataReader belongs has the access_scope set to ‘GROUP’, this operation should only be invoked inside a begin_access/end_access block. Otherwise it will throw error PreconditionNotMetError.

Depending on the setting of the dds::core::policy::Presentation QoSPolicy, the returned collection of DataReader objects may be:

a ‘set’ containing each DataReader at most once in no specified order,
a ‘list’ containing each DataReader one or more times in a specific order.

This difference is due to the fact that, in the second situation it is required to access samples belonging to different DataReader objects in a particular order. In this case, the application should process each DataReader in the same order it appears in the ‘list’ and read or take exactly one sample from each DataReader. The patterns that an application should use to access data is fully described in dds::core::policy::Presentation.

Parameters

sub – the Subscriber for which to find a DataReader
rs – the data_state to find
begin – a back inserting iterator pointing to the start of a container in which to put the DataReaders

Returns

the total number of elements returned

void ignore(const dds::domain::DomainParticipant &dp, const dds::core::InstanceHandle &handle)¶

Ignore subscriptions.

Parameters

dp – the DomainParticipant for which the remote entity will be ignored
handle – the InstanceHandle of the remote entity that has to be ignored

const dds::sub::Subscriber builtin_subscriber(const dds::domain::DomainParticipant &dp)¶

This operation returns the built-in Subscriber associated with the given given DomainParticipant.

Each DomainParticipant contains several built-in Topic objects. The built-in Subscriber contains the corresponding DataReader objects to access them. All these DataReader objects belong to a single built-in Subscriber. Note that there is exactly one built-in Subscriber associated with each DomainParticipant.

See Builtin Topics for more information.

Parameters: dp – the domain participant
Returns: the built-in Subscriber

template<typename T, template<typename Q> class D> LoanedSamples<T, D> move(LoanedSamples<T, D> &a)¶

Move loan and its ownership to a new LoanedSamples object.

Returns: LoanedSampless

class AnyDataReaderListener¶

#include <AnyDataReaderListener.hpp>

AnyDataReader events Listener.

Because Subscriber and DomainParticipant do not have knowledge of data types, they have to use non-data-type-listeners. In other words Any* listeners.

See also

dds::sub::SubscriberListener

See also

dds::domain::DomainParticipantListener

Subclassed by dds::sub::NoOpAnyDataReaderListener, dds::sub::SubscriberListener

class NoOpAnyDataReaderListener : public virtual dds::sub::AnyDataReaderListener ¶

#include <AnyDataReaderListener.hpp>

AnyDataReader events Listener.

This listener is just like AnyDataReaderListener, except that the application doesn’t have to implement all operations.

This class is used as a base for other listeners and is not used on its own.

See also

dds::sub::AnyDataReaderListener

See also

dds::sub::NoOpSubscriberListener

Subclassed by dds::sub::NoOpSubscriberListener

template<typename T, template<typename Q> class DELEGATE> class DataReader : public dds::sub::TAnyDataReader<DELEGATE<T>>¶

#include <TDataReader.hpp>

DataReader allows the applicatin to access published sample data.

A DataReader allows the application:

to declare the data it wishes to receive (i.e., make a subscription)
to access the data received by the attached Subscriber

A DataReader refers to exactly one TopicDescription (either a Topic, a ContentFilteredTopic or a MultiTopic) that identifies the samples to be read. The Topic must exist prior to the DataReader creation.

A DataReader is attached to exactly one Subscriber which acts as a factory for it.

The DataReader may give access to several instances of the data type, which are distinguished from each other by their key.

The pre-processor generates from IDL type descriptions the application DataReader<type> classes. For each application data type that is used as Topic data type, a typed class DataReader<type> is derived from the AnyDataReader class.

For instance, for an application, the definitions are located in the Foo.idl file. The pre-processor will generate a ccpp_Foo.h include file.

General note: The name ccpp_Foo.h is derived from the IDL file Foo.idl, that defines Foo::Bar, for all relevant DataReader<Foo::Bar> operations.

Example

// Default creation of a DataReader
dds::domain::DomainParticipant participant(org::eclipse::cyclonedds::domain::default_id());
dds::topic::Topic<Foo::Bar> topic(participant, "TopicName");
dds::sub::Subscriber subscriber(participant);
dds::sub::DataReader<Foo::Bar> reader(subscriber, topic);

{
    // Default read of a sample on the DataReader
    dds::sub::LoanedSamples<Foo::Bar> samples;
    samples = reader.read();

    // Default way of accessing the loaned samples
    dds::sub::LoanedSamples<Foo::Bar>::const_iterator it;
    for (it = samples.begin(); it != samples.end(); ++it) {
        const dds::sub::Sample<Foo::Bar>& sample = *it;
        const Foo::Bar& data = sample.data();
        const dds::sub::SampleInfo& info = sample.info();
        // Use sample data and meta information.
    }
}
// Like the name says, the read samples are loans from the DataReader. The loan
// was automatically returned when the LoanedSamples went out of scope.

See also

for more information: Subscription concept

See also

for more information: DataReader concept

Note

Apart from idl files, Google protocol buffers are also supported. For the API itself, it doesn’t matter if the type header files were generated from idl or protocol buffers. The resulting API usage and includes remain the same.

template<typename T> class DataReaderListener¶

#include <DataReaderListener.hpp>

DataReader events Listener.

Since a DataReader is an Entity, it has the ability to have a Listener associated with it. In this case, the associated Listener should be of type DataReaderListener. This interface must be implemented by the application. A user-defined class must be provided by the application which must extend from the DataReaderListener class.

The DataReaderListener provides a generic mechanism (actually a callback function) for the Data Distribution Service to notify the application of relevant asynchronous status change events, such as a missed deadline, violation of a QosPolicy setting, etc. The DataReaderListener is related to changes in communication status StatusConditions.

// Application example listener
class ExampleListener :
               public virtual dds::sub::DataReaderListener<Foo::Bar>
{
public:
    virtual void on_requested_deadline_missed (
        dds::sub::DataReader<Foo::Bar>& reader,
        const dds::core::status::RequestedDeadlineMissedStatus & status)
    {
        std::cout << "on_requested_deadline_missed" << std::endl;
    }

    virtual void on_requested_incompatible_qos (
        dds::sub::DataReader<Foo::Bar>& reader,
        const dds::core::status::RequestedIncompatibleQosStatus & status)
    {
        std::cout << "on_requested_incompatible_qos" << std::endl;
    }

    virtual void on_sample_rejected (
        dds::sub::DataReader<Foo::Bar>& reader,
        const dds::core::status::SampleRejectedStatus & status)
    {
        std::cout << "on_sample_rejected" << std::endl;
    }

    virtual void on_liveliness_changed (
        dds::sub::DataReader<Foo::Bar>& reader,
        const dds::core::status::LivelinessChangedStatus & status)
    {
        std::cout << "on_liveliness_changed" << std::endl;
    }

    virtual void on_data_available (
        dds::sub::DataReader<Foo::Bar>& reader)
    {
        std::cout << "on_data_available" << std::endl;
    }

    virtual void on_subscription_matched (
        dds::sub::DataReader<Foo::Bar>& reader,
        const dds::core::status::SubscriptionMatchedStatus & status)
    {
        std::cout << "on_subscription_matched" << std::endl;
    }

    virtual void on_sample_lost (
        dds::sub::DataReader<Foo::Bar>& reader,
        const dds::core::status::SampleLostStatus & status)
    {
        std::cout << "on_sample_lost" << std::endl;
    }
};

// Create DataReader with the listener
dds::domain::DomainParticipant participant(org::eclipse::cyclonedds::domain::default_id());
dds::topic::Topic<Foo::Bar> topic(participant, "TopicName");
dds::sub::Subscriber subscriber(participant);
dds::sub::DataReader<Foo::Bar> reader(subscriber,
                                      topic,
                                      subscriber.default_datareader_qos(),
                                      new ExampleListener(),
                                      dds::core::status::StatusMask::all());

See also

for more information: Data Reader

See also

for more information: Listener information

Subclassed by dds::sub::NoOpDataReaderListener< T >

template<typename T> class NoOpDataReaderListener : public virtual dds::sub::DataReaderListener<T>¶

#include <DataReaderListener.hpp>

DataReader events Listener.

This listener is just like DataReaderListener, except that the application doesn’t have to implement all operations.

class ExampleListener : public virtual dds::sub::NoOpDataReaderListener<Foo::Bar>
{
   // Not necessary to implement any Listener operations.
};

See also

dds::sub::DataReaderListener

template<typename T, template<typename Q> class DELEGATE> class LoanedSamples¶

#include <LoanedSamples.hpp>

This class encapsulates and automates the management of loaned samples.

It is a container which is used to hold samples which have been read or taken by the DataReader. Samples are effectively “loaned” from the DataReader to avoid the need to copy the data. When the LoanedSamples container goes out of scope the loan is automatically returned.

LoanedSamples maintains a ref count so that the loan will only be returned once all copies of the same LoanedSamples have been destroyed.

dds::domain::DomainParticipant participant(org::eclipse::cyclonedds::domain::default_id());
dds::topic::Topic<Foo::Bar> topic(participant, "TopicName");
dds::sub::Subscriber subscriber(participant);
dds::sub::DataReader<Foo::Bar> reader(subscriber, topic);

// Assume there is data to read
{
    dds::sub::LoanedSamples<Foo::Bar> samples = reader.read();
    dds::sub::LoanedSamples<Foo::Bar>::const_iterator it;
    for (it = samples.begin(); it != samples.end(); ++it) {
        const dds::sub::Sample<Foo::Bar>& sample = *it;
        const Foo::Bar& data = sample.data();
        const dds::sub::SampleInfo& info = sample.info();
        // Use sample data and meta information.
    }

    function(samples);
}
// LoanedSamples out of scope. Whether the loan is returned, depends what the reference
// count of the LoanedSamples is. That again, depends on what the function() did with it.
// Maybe function() stored the LoanedSamples, maybe not. Whatever the case, LoanedSamples
// takes care of the loan and resource handling.

See also

for more information: DataSample

See also

for more information: SampleInfo

See also

for more information: Subscription

Private Members

DELEGATE_REF_T delegate_¶

template<typename T, template<typename Q> class DELEGATE> class Sample : public dds::core::Value<DELEGATE<T>>¶

#include <TSample.hpp>

This class encapsulates the data and info meta-data associated with DDS samples.

It is normally used with dds::sub::LoanedSamples:

dds::sub::LoanedSamples<Foo::Bar> samples = reader.read();
dds::sub::LoanedSamples<Foo::Bar>::const_iterator it;
for (it = samples.begin(); it != samples.end(); ++it) {
    const dds::sub::Sample<Foo::Bar>& sample = *it;
    const Foo::Bar& data = sample.data();
    const dds::sub::SampleInfo& info = sample.info();
    // Use sample data and meta information.
}

Or more implicitly:

dds::sub::LoanedSamples<Foo::Bar> samples = reader.read();
dds::sub::LoanedSamples<Foo::Bar>::const_iterator it;
for (it = samples.begin(); it != samples.end(); ++it) {
    const Foo::Bar& data = it->data();
    const dds::sub::SampleInfo& info = it->info();
    // Use sample data and meta information.
}

See also

for more information: DataSample

See also

for more information: SampleInfo

See also

for more information: Subscription

template<typename T, template<typename Q> class DELEGATE> class SampleRef : public dds::core::Value<DELEGATE<T>>¶

#include <TSampleRef.hpp>

This class encapsulates a reference to the data and info meta-data associated with DDS samples.

It is normally used with dds::sub::LoanedSamples:

dds::sub::LoanedSamples<Foo::Bar> samples = reader.read();
dds::sub::LoanedSamples<Foo::Bar>::const_iterator it;
for (it = samples.begin(); it != samples.end(); ++it) {
    const dds::sub::Sample<Foo::Bar>& sample = *it;
    const Foo::Bar& data = sample.data();
    const dds::sub::SampleInfo& info = sample.info();
    // Use sample data and meta information.
}

Or more implicitly:

dds::sub::LoanedSamples<Foo::Bar> samples = reader.read();
dds::sub::LoanedSamples<Foo::Bar>::const_iterator it;
for (it = samples.begin(); it != samples.end(); ++it) {
    const Foo::Bar& data = it->data();
    const dds::sub::SampleInfo& info = it->info();
    // Use sample data and meta information.
}

See also

for more information: DataSample

See also

for more information: SampleInfo

See also

for more information: Subscription

template<typename T, template<typename Q> class DELEGATE> class SharedSamples¶

#include <SharedSamples.hpp>

This class encapsulates and automates the management of loaned samples.

Note

The specification of this class is not yet finished. It will possibly change in the future. Anyway, this class is basically a copy of LoanedSamples when considering its functionality. So, anything you would want to do with this class can also be done by the LoanedSamples.

Private Members

DELEGATE_REF_T delegate_¶

class SubscriberListener : public virtual dds::sub::AnyDataReaderListener ¶

#include <SubscriberListener.hpp>

Subscriber events Listener.

Since a Subscriber is an Entity, it has the ability to have a Listener associated with it. In this case, the associated Listener should be of type SubscriberListener. This interface must be implemented by the application. A user-defined class must be provided by the application which must extend from the SubscriberListener class.

The SubscriberListener provides a generic mechanism (actually a callback function) for the Data Distribution Service to notify the application of relevant asynchronous status change events, such as a missed deadline, violation of a QosPolicy setting, etc. The SubscriberListener is related to changes in communication status StatusConditions.

// Application example listener
class ExampleListener :
               public virtual dds::sub::SubscriberListener
{
public:
    virtual void on_requested_deadline_missed (
        dds::sub::AnyDataReader& reader,
        const dds::core::status::RequestedDeadlineMissedStatus & status)
    {
        std::cout << "on_requested_deadline_missed" << std::endl;
    }

    virtual void on_requested_incompatible_qos (
        dds::sub::AnyDataReader& reader,
        const dds::core::status::RequestedIncompatibleQosStatus & status)
    {
        std::cout << "on_requested_incompatible_qos" << std::endl;
    }

    virtual void on_sample_rejected (
        dds::sub::AnyDataReader& reader,
        const dds::core::status::SampleRejectedStatus & status)
    {
        std::cout << "on_sample_rejected" << std::endl;
    }

    virtual void on_liveliness_changed (
        dds::sub::AnyDataReader& reader,
        const dds::core::status::LivelinessChangedStatus & status)
    {
        std::cout << "on_liveliness_changed" << std::endl;
    }

    virtual void on_data_available (
        dds::sub::AnyDataReader& reader)
    {
        std::cout << "on_data_available" << std::endl;
    }

    virtual void on_subscription_matched (
        dds::sub::AnyDataReader& reader,
        const dds::core::status::SubscriptionMatchedStatus & status)
    {
        std::cout << "on_subscription_matched" << std::endl;
    }

    virtual void on_sample_lost (
        dds::sub::AnyDataReader& reader,
        const dds::core::status::SampleLostStatus & status)
    {
        std::cout << "on_sample_lost" << std::endl;
    }

    virtual void on_data_on_readers (
        dds::sub::Subscriber& subs)
    {
        std::cout << "on_data_on_readers" << std::endl;
    }
};

// Create Subscriber with the listener
dds::domain::DomainParticipant participant(org::eclipse::cyclonedds::domain::default_id());
dds::sub::Subscriber subscriber(participant,
                                participant.default_subscriber_qos(),
                                new ExampleListener(),
                                dds::core::status::StatusMask::all());

See also

for more information: Subscriber

See also

for more information: Listener information

Subclassed by dds::domain::DomainParticipantListener, dds::sub::NoOpSubscriberListener

class NoOpSubscriberListener : public virtual dds::sub::SubscriberListener, public virtual dds::sub::NoOpAnyDataReaderListener ¶

#include <SubscriberListener.hpp>

Subscriber events Listener.

This listener is just like SubscriberListener, except that the application doesn’t have to implement all operations.

class ExampleListener : public virtual dds::sub::NoOpSubscriberListener
{
   // Not necessary to implement any Listener operations.
};

See also

dds::sub::SubscriberListener

Subclassed by dds::domain::NoOpDomainParticipantListener

template<typename DELEGATE> class TAnyDataReader : public dds::core::TEntity<DELEGATE>¶

#include <TAnyDataReader.hpp>

Typeless base class for the typed DataReader.

DataReaders are created type specific (fi DataReader<Foo::Bar> reader). However, there are many places in the API (and possibly application) where the type can not be known while still some DataReader

has to be passed around, stored or even typeless functionality called.

Main examples in the API that need typeless

DataReader are: Subscriber, SubscriberListener and DomainParticipantListener.

See also

dds::sub::DataReader

template<typename DELEGATE> class TCoherentAccess : public dds::core::Value<DELEGATE>¶

#include <TCoherentAccess.hpp>

Class for RAII way of beginning/ending coherent access.

Coherent access indicates that the application is about to access the data samples in any of the DataReader objects attached to the Subscriber.

The application is required to use this operation only if Presentation QosPolicy of the Subscriber to which the DataReader belongs has the access_scope set to “GROUP”. In the aforementioned case, the operation must be called prior to calling any of the sample-accessing operations, i.e. read and take on DataReader. Otherwise the sample-accessing operations will throw a PreconditionNotMetError exception.

Once the application has finished accessing the data samples it must end the coherent access. It is not required for the application to begin or end access if the Presentation QosPolicy has the access_scope set to something other than GROUP. Beginning or ending access in this case is not considered an error and has no effect. Beginning and ending access may be nested. In that case, the application end access as many times as it began access.

dds::domain::DomainParticipant participant(org::eclipse::cyclonedds::domain::default_id());
dds::topic::Topic<Foo::Bar> topic(participant, "TopicName");

dds::sub::qos::SubscriberQos sQos sQos = participant.default_subscriber_qos()
                                         << dds::core::policy::Presentation::TopicAccessScope(false, true);
dds::sub::Subscriber subscriber(participant, sQos);

{
    std::vector< dds::sub::DataReader<Foo::Bar> > readers;
    // Start coherent access.
    dds::sub::TCoherentAccess coherentAccess(subscriber);
    // Find (previously created with the subscriber) datareaders that now got data.
    dds::sub::find< dds::sub::DataReader<Foo::Bar> >(subscriber,
                                                     dds::sub::status::DataState::any(),
                                                     back_inserter(readers));
    // Get data from the readers
    for (size_type i = 0; i < rv.size(); i++) {
        dds::sub::LoanedSamples<Foo::Bar> samples = readers[i].read()
        dds::sub::LoanedSamples<Type1>::const_iterator it;
        for (it = samples.begin(); it != samples.end(); iterator++) {
            const dds::sub::Sample<Foo::Bar>& sample = *it;
            const Foo::Bar& data = sample.data();
            const dds::sub::SampleInfo& info = sample.info();
            // Use sample data and meta information.
        }
    }
}
// CoherentAccess went out of scope: it is ended implicitly

See also

for more information: Subscription

See also

dds::sub::Subscriber

Private Functions

TCoherentAccess(const TCoherentAccess&)¶

TCoherentAccess &operator=(const TCoherentAccess&)¶

template<typename DELEGATE> class TGenerationCount : public dds::core::Value<DELEGATE>¶

#include <TGenerationCount.hpp>

Class to hold sample GenerationCount information and is part of dds::sub::SampleInfo.

Generations A generation is defined as: ‘the number of times an instance has become alive (with instance_state==ALIVE) at the time the sample was received’. Note that the generation counters are initialized to zero when a DataReader first detects a never-seen-before instance.

For each instance the middleware internally maintains two counts: the disposed_generation_count and no_writers_generation_count, relative to each DataReader:

Two types of generations are distinguished: disposed_generation_count and no_writers_generation_count.

The disposed_generation_count and no_writers_generation_count are initialized to zero when the DataReader first detects the presence of a never-seen-before instance.
The disposed_generation_count is incremented each time the instance_state of the corresponding instance changes from not_alive_disposed to alive.
The no_writers_generation_count is incremented each time the instance_state of the corresponding instance changes from not_alive_no_writers to alive.

The disposed_generation_count and no_writers_generation_count associated with the SampleInfo capture a snapshot of the corresponding counters at the time the sample was received.

See also

for more information: SampleInfo

template<typename DELEGATE> class TQuery : public virtual dds::core::Reference<DELEGATE>¶

#include <TQuery.hpp>

Query objects contain expressions that allow the application to specify a filter on the locally available data.

A Query is used in a QueryCondition or DataReader::Selector and is associated with one DataReader.

See also

dds::sub::cond::QueryCondition

See also

dds::sub::DataReader::Selector

See also

dds::sub::DataReader::ManipulatorSelector

See also

for more information: Subscription concept

SQL Expression

The SQL query string is set by expression which must be a subset of the SQL query language. In this query expression, parameters may be used, which must be set in the sequence of strings defined by the parameter query_parameters. A parameter is a string which can define an integer, float, string or enumeration. The number of values in query_parameters must be equal or greater than the highest referenced n token in the query_expression (e.g. if %1 and %8 are used as parameters in the query_expression, the query_parameters should at least contain n+1 = 9 values).

Look here for the specific query expression syntax.

template<typename DELEGATE> class TRank : public dds::core::Value<DELEGATE>¶

#include <TRank.hpp>

Class to hold sample Rank information and is part of dds::sub::SampleInfo.

The sample_rank and generation_rank available in dds::sub::Rank are computed based solely on the actual samples in the ordered collection returned by read or take.

The sample_rank indicates the number of samples of the same instance that follow the current one in the collection.
The generation_rank indicates the difference in ‘generations’ between the sample (S) and the Most Recent Sample of the same instance that appears In the returned Collection (MRSIC). That is, it counts the number of times the instance transitioned from not-alive to alive in the time from the reception of the S to the reception of MRSIC.

The generation_rank is computed using the formula:

generation_rank = (MRSIC.disposed_generation_count + MRSIC.no_writers_generation_count) - (S.disposed_generation_count + S.no_writers_generation_count)

The absolute_generation_rank indicates the difference in ‘generations’ between the sample (S) and the Most Recent Sample of the same instance that the middleware has received (MRS). That is, it counts the number of times the instance transitioned from not-alive to alive in the time from the reception of the S to the time when the read or take was called.

The absolute_generation_rank is computed using the formula:

absolute_generation_rank = (MRS.disposed_generation_count + MRS.no_writers_generation_count) - (S.disposed_generation_count + S.no_writers_generation_count)

See also

for more information: SampleInfo

template<typename DELEGATE> class TSampleInfo¶

template<typename DELEGATE> class TSubscriber : public dds::core::TEntity<DELEGATE>¶

#include <TSubscriber.hpp>

A Subscriber is the object responsible for the actual reception of the data resulting from its subscriptions.

A Subscriber acts on the behalf of one or several DataReader objects that are related to it. When it receives data (from the other parts of the system), it builds the list of concerned DataReader objects, and then indicates to the application that data is available, through its listener or by enabling related conditions. The application can access the list of concerned DataReader objects through the operation get_datareaders and then access the data available through operations on the DataReader.

See also

for more information: Subscriber

namespace cond¶

Typedefs

typedef dds::sub::cond::detail::ReadCondition ReadCondition¶

template<typename DELEGATE> class TQueryCondition¶

template<typename DELEGATE> class TReadCondition : public dds::core::cond::TCondition<DELEGATE>¶

#include <TReadCondition.hpp>

ReadCondition objects are conditions specifically dedicated to read operations and attached to one DataReader.

ReadCondition objects allow an application to specify the data samples it is interested in (by specifying the desired sample states, view states, and instance states). (See the parameter definitions for DataReader’s read/take operations.) This allows the middle-ware to enable the condition only when suitable information is available. They are to be used in conjunction with a WaitSet as normal conditions. More than one ReadCondition may be attached to the same DataReader.

See the WaitSet examples

for some examples.

Although the WaitSet examples use the StatusCondition, the basic usage of this Condition with a WaitSet is the same.

See also

dds::core::cond::Condition

See also

for more information: Status concept

See also

for more information: WaitSet concept

See also

for more information: Subscription concept

See also

for more information: WaitSet examples

namespace detail¶

Typedefs

typedef dds::sub::cond::TQueryCondition<org::eclipse::cyclonedds::sub::cond::QueryConditionDelegate> QueryCondition¶

typedef dds::sub::cond::TReadCondition<org::eclipse::cyclonedds::sub::cond::ReadConditionDelegate> ReadCondition¶

namespace detail¶

Typedefs

typedef dds::sub::TAnyDataReader<org::eclipse::cyclonedds::sub::AnyDataReaderDelegate> AnyDataReader¶

typedef ::dds::sub::TCoherentAccess<org::eclipse::cyclonedds::sub::CoherentAccessDelegate> CoherentAccess¶

typedef std::vector<org::eclipse::cyclonedds::sub::AnyDataReaderDelegate::ref_type> base_readers_vector¶

typedef std::vector<org::eclipse::cyclonedds::sub::AnyDataReaderDelegate::ref_type>::iterator base_readers_iterator¶

typedef dds::sub::TGenerationCount<org::eclipse::cyclonedds::sub::GenerationCountImpl> GenerationCount¶

typedef dds::sub::TQuery<org::eclipse::cyclonedds::sub::QueryDelegate> Query¶

typedef dds::sub::TRank<org::eclipse::cyclonedds::sub::RankImpl> Rank¶

typedef dds::sub::TSampleInfo<org::eclipse::cyclonedds::sub::SampleInfoImpl> SampleInfo¶

typedef dds::sub::TSubscriber<org::eclipse::cyclonedds::sub::SubscriberDelegate> Subscriber¶

template<typename T> class DataReader : public org::eclipse::cyclonedds::sub::AnyDataReaderDelegate¶

Private Types

enum SelectMode¶

Values:

enumerator SELECT_MODE_READ¶

enumerator SELECT_MODE_READ_INSTANCE¶

enumerator SELECT_MODE_READ_NEXT_INSTANCE¶

enumerator SELECT_MODE_READ_WITH_CONDITION¶

enumerator SELECT_MODE_READ_INSTANCE_WITH_CONDITION¶

enumerator SELECT_MODE_READ_NEXT_INSTANCE_WITH_CONDITION¶

Private Functions

dds::sub::LoanedSamples<T> read(const Selector &selector)¶

dds::sub::LoanedSamples<T> take(const Selector &selector)¶

template<typename SamplesFWIterator> uint32_t read(SamplesFWIterator samples, uint32_t max_samples, const Selector &selector)¶

template<typename SamplesFWIterator> uint32_t take(SamplesFWIterator samples, uint32_t max_samples, const Selector &selector)¶

template<typename SamplesBIIterator> uint32_t read(SamplesBIIterator samples, const Selector &selector)¶

template<typename SamplesBIIterator> uint32_t take(SamplesBIIterator samples, const Selector &selector)¶

Private Members

dds::sub::Subscriber sub_¶

dds::sub::status::DataState status_filter_¶

T typed_sample_¶

template<typename READER, typename ITERATOR> class ReadersCopySpecialization¶

template<typename ITERATOR> AnyDataReader, ITERATOR >

template<typename READER, typename ITERATOR> class ReadersCopy¶

template<typename T> class LoanedSamples¶

Private Members

LoanedSamplesContainer samples_¶

template<> CDRBlob >

Private Members

LoanedSamplesContainer samples_¶

template<typename T> class Sample¶

Private Members

T data_¶

dds::sub::SampleInfo info_¶

template<typename T> class SampleRef¶

Private Functions

inline void copy(const SampleRef &other)¶

Private Members

ddscxx_serdata<T> *data_¶

dds::sub::SampleInfo info_¶

template<typename T> class LoanedSamplesHolder : public SamplesHolder¶

Private Members

dds::sub::LoanedSamples<T> &samples_¶

dds::sub::SampleRef<T> latest_sample¶

uint32_t index_¶

class CDRSamplesHolder : public SamplesHolder¶

Private Functions

inline void copy_buffer_to_cdr_blob(const uint8_t *buffer, const size_t size, const org::eclipse::cyclonedds::topic::BlobKind data_kind, org::eclipse::cyclonedds::topic::CDRBlob &cdr_blob) const¶

Private Members

dds::sub::LoanedSamples<org::eclipse::cyclonedds::topic::CDRBlob> &samples_¶

uint32_t index_¶

template<typename T, typename SamplesFWIterator> class SamplesFWInteratorHolder : public SamplesHolder¶

Private Members

SamplesFWIterator &iterator¶

uint32_t size¶

template<typename T, typename SamplesBIIterator> class SamplesBIIteratorHolder : public SamplesHolder¶

Private Members

SamplesBIIterator &iterator¶

dds::sub::Sample<T> last_sample¶

uint32_t size¶

template<typename T> class SharedSamples¶

Private Members

dds::sub::LoanedSamples<T> samples_¶

namespace functors¶

Typedefs

typedef dds::sub::functors::detail::MaxSamplesManipulatorFunctor MaxSamplesManipulatorFunctor¶

typedef dds::sub::functors::detail::ContentFilterManipulatorFunctor ContentFilterManipulatorFunctor¶

typedef dds::sub::functors::detail::StateFilterManipulatorFunctor StateFilterManipulatorFunctor¶

typedef dds::sub::functors::detail::InstanceManipulatorFunctor InstanceManipulatorFunctor¶

typedef dds::sub::functors::detail::NextInstanceManipulatorFunctor NextInstanceManipulatorFunctor¶

namespace detail¶

class MaxSamplesManipulatorFunctor¶

Private Members

uint32_t n_¶

class ContentFilterManipulatorFunctor¶

Private Members

const dds::sub::Query query_¶

class StateFilterManipulatorFunctor¶

Private Members

dds::sub::status::DataState state_¶

class InstanceManipulatorFunctor¶

Private Members

dds::core::InstanceHandle handle_¶

class NextInstanceManipulatorFunctor¶

Private Members

dds::core::InstanceHandle handle_¶

namespace qos¶

Typedefs

typedef dds::sub::qos::detail::DataReaderQos DataReaderQos¶

typedef dds::sub::qos::detail::SubscriberQos SubscriberQos¶

class DataReaderQos : public dds::core::EntityQos<org::eclipse::cyclonedds::sub::qos::DataReaderQosDelegate>

#include <DataReaderQos.hpp>

This class provides the basic mechanism for an application to specify Quality of Service attributes for a DataReader.

A QosPolicy can be set when the DataReader is created or modified with the set qos operation. Both operations take the DataReaderQos object as a parameter. There may be cases where several policies are in conflict. Consistency checking is performed each time the policies are modified when they are being created and, in case they are already enabled, via the set qos operation.

Attributes

QosPolicy	Desciption	Default Value
dds::core::policy::Durability	Data storage settings for late joiners (info)	Durability::Volatile()
dds::core::policy::Deadline	Period in which new sample is written (info)	Deadline::Deadline(infinite)
dds::core::policy::LatencyBudget	Used for optimization (info)	LatencyBudget::LatencyBudget(zero)
dds::core::policy::Liveliness	Liveliness assertion mechanism (info)	Liveliness::Automatic()
dds::core::policy::Reliability	Reliability settings (info)	Reliability::BestEffort()
dds::core::policy::DestinationOrder	DataReader data order settings (info)	DestinationOrder::ReceptionTimestamp()
dds::core::policy::History	Data storage settings (info)	History::KeepLast(depth 1)
dds::core::policy::ResourceLimits	Maximum resource settings (info)	ResourceLimits::ResourceLimits(all unlimited)
dds::core::policy::UserData	Additional information (info)	UserData::UserData(empty)
dds::core::policy::Ownership	Exclusive ownership or not (info)	Ownership::Shared()
dds::core::policy::TimeBasedFilter	Maximum data rate (info)	TimeBasedFilter::TimeBasedFilter(0)
dds::core::policy::ReaderDataLifecycle	Instance state changes and notifications (info)	ReaderDataLifecycle::NoAutoPurgeDisposedSamples()
dds::core::policy::DataRepresentation	Supported data representation kinds (info)	DataRepresentation::DataRepresentation(dds::core::policy::DataRepresentationId::XCDR1)
dds::core::policy::TypeConsistencyEnforcement	Type consistency enforcement policies (info)	dds::core::policy::TypeConsistencyKind::DISALLOW_TYPE_COERCION

Some QosPolicy have “immutable” semantics meaning that they can only be specified either at DataReader creation time or prior to calling the enable operation on the DataReader.

See also

for more information: DCPS_QoS

class SubscriberQos : public dds::core::EntityQos<org::eclipse::cyclonedds::sub::qos::SubscriberQosDelegate>

#include <SubscriberQos.hpp>

This class provides the basic mechanism for an application to specify Quality of Service attributes for a Subscriber.

A QosPolicy can be set when the Subscriber is created or modified with the set qos operation. Both operations take the SubscriberQos object as a parameter. There may be cases where several policies are in conflict. Consistency checking is performed each time the policies are modified when they are being created and, in case they are already enabled, via the set qos operation.

Attributes

QosPolicy	Desciption	Default Value
dds::core::policy::Presentation	Data-instance change dependencies (info)	Presentation::InstanceAccessScope(coherent=false, ordered=false)
dds::core::policy::Partition	Active partitions (info)	Partition::Partition(empty)
dds::core::policy::GroupData	Additional information (info)	GroupData::GroupData(empty)
dds::core::policy::EntityFactory	Create enabled (info)	EntityFactory::AutoEnable()

Some QosPolicy have “immutable” semantics meaning that they can only be specified either at Subscriber creation time or prior to calling the enable operation on the Subscriber.

See also

for more information: DCPS_QoS

namespace detail¶

namespace status¶

class SampleState : public std::bitset<OMG_DDS_STATE_BIT_COUNT>¶

#include <DataState.hpp>

Class to hold SampleState information.

For each sample, the Data Distribution Service internally maintains a sample_state specific to each DataReader. The sample_state can either be READ_SAMPLE_STATE or NOT_READ_SAMPLE_STATE.

- The DataReader has already accessed that sample by means of read. Had the sample been accessed by take it would no longer be available to the DataReader.
- The DataReader has not accessed that sample before.

See also

for more information: SampleInfo

class ViewState : public std::bitset<OMG_DDS_STATE_BIT_COUNT>¶

#include <DataState.hpp>

Class to hold sample ViewState information.

For each instance (identified by the key), the Data Distribution Service internally maintains a view_state relative to each DataReader. The ViewSate can either be NEW_VIEW_STATE or NOT_NEW_VIEW_STATE.

- Either this is the first time that the DataReader has ever accessed samples of that instance, or else that the DataReader has accessed previous samples of the instance, but the instance has since been reborn (i.e. become not-alive and then alive again).
- The DataReader has already accessed samples of the same instance and that the instance has not been reborn since.

See also

for more information: SampleInfo

class InstanceState : public std::bitset<OMG_DDS_STATE_BIT_COUNT>¶

#include <DataState.hpp>

Class to hold sample InstanceState information.

For each instance the Data Distribution Service internally maintains an InstanceState. The InstanceState can be:

, which indicates that
- samples have been received for the instance
- there are live DataWriter objects writing the instance
- the instance has not been explicitly disposed of (or else samples have been received after it was disposed of)
, which indicates that
- the instance was disposed of by a DataWriter, either explicitly by means of the dispose operation or implicitly in case the autodispose_unregistered_instances field of the WriterDataLyfecycle QosPolicy equals TRUE when the instance gets unregistered, WriterDataLifecycle QosPolicy and no new samples for that instance have been written afterwards.
, which indicates that
- the instance has been declared as not-alive by the DataReader because it detected that there are no live DataWriter objects writing that instance.

See also

for more information: SampleInfo

class DataState¶

#include <DataState.hpp>

Class to hold sample DataState information.

The DataState is part of dds::sub::SampleInfo but can also be used as data filter for DataReaders.

The DataState contains the following:

The sample_state of the Data value (i.e., if the sample has already been READ or NOT_READ by that same DataReader).
The view_state of the related instance (i.e., if the instance is NEW, or NOT_NEW for that DataReader).
The instance_state of the related instance (i.e., if the instance is ALIVE, NOT_ALIVE_DISPOSED, or NOT_ALIVE_NO_WRITERS).

See also

for more information: SampleInfo

Private Members

dds::sub::status::SampleState ss_¶

dds::sub::status::ViewState vs_¶

dds::sub::status::InstanceState is_¶