RTI Connext Modern C++ API Version 7.2.0
dds::sub::Subscriber Class Reference

<<reference-type>> A subscriber is the object responsible for actually receiving data from a subscription. More...

#include "dds/sub/Subscriber.hpp"

Inheritance diagram for dds::sub::Subscriber:
dds::core::Entity

Public Member Functions

 Subscriber (const ::dds::domain::DomainParticipant &the_participant)
 Create a Subscriber attached to the given DomainParticipant. More...
 
 Subscriber (const ::dds::domain::DomainParticipant &dp, const dds::sub::qos::SubscriberQos &the_qos, dds::sub::SubscriberListener *the_listener=NULL, const dds::core::status::StatusMask &mask=dds::core::status::StatusMask::all())
 Create a Subscriber attached to the given DomainParticipant. More...
 
 Subscriber (const ::dds::domain::DomainParticipant &dp, const dds::sub::qos::SubscriberQos &the_qos, std::shared_ptr< Listener > the_listener, const dds::core::status::StatusMask &mask=dds::core::status::StatusMask::all())
 Create a Subscriber attached to the given DomainParticipant. More...
 
void notify_datareaders ()
 This operation invokes the operation on_data_available on the DataReaderListener objects attached to contained DataReader entities with a DATA_AVAILABLE status that is considered changed as described in Changes in read communication status. More...
 
void listener (Listener *the_listener, const dds::core::status::StatusMask &event_mask)
 Attach a listener to this Subscriber. More...
 
Listenerlistener () const
 Get the Subscriber listener. More...
 
void set_listener (std::shared_ptr< Listener > the_listener, const dds::core::status::StatusMask &event_mask)
 Sets the listener associated with this subscriber. More...
 
void set_listener (std::shared_ptr< Listener > the_listener)
 Sets the listener associated with this subscriber. More...
 
std::shared_ptr< Listenerget_listener () const
 Returns the listener currently associated with this Subscriber. More...
 
const dds::sub::qos::SubscriberQos qos () const
 Get the Subscriber QoS. More...
 
void qos (const dds::sub::qos::SubscriberQos &the_qos)
 Set the Subscriber QoS. More...
 
dds::sub::qos::DataReaderQos default_datareader_qos () const
 Get the default DataReader QoS. More...
 
Subscriberdefault_datareader_qos (const dds::sub::qos::DataReaderQos &the_qos)
 Set the default DataReaderQoS. More...
 
const dds::domain::DomainParticipantparticipant () const
 Return the DomainParticipant that owns this Subscriber. More...
 
void close_contained_entities ()
 <<extension>> Closes all the entities created from this Subscriber More...
 
- Public Member Functions inherited from dds::core::Entity
void enable ()
 Enables this entity (if it was created disabled) More...
 
const dds::core::status::StatusMask status_changes ()
 Retrieves the list of communication statuses that are triggered. More...
 
const dds::core::InstanceHandle instance_handle () const
 Get the instance handle that represents this entity. More...
 
void close ()
 Forces the destruction of this entity. More...
 
void retain ()
 Disables the automatic destruction of this entity. More...
 

Related Functions

(Note that these are not member functions.)

dds::sub::Subscriber builtin_subscriber (const dds::domain::DomainParticipant &dp)
 Access the built-in Subscriber. More...
 
template<typename SubscriberForwardIterator >
uint32_t find_subscribers (const dds::domain::DomainParticipant participant, SubscriberForwardIterator begin, uint32_t max_size)
 <<extension>> Retrieve all of the dds::sub::Subscriber created from this dds::domain::DomainParticipant More...
 
template<typename SubscriberBackInsertIterator >
uint32_t find_subscribers (const dds::domain::DomainParticipant participant, SubscriberBackInsertIterator begin)
 <<extension>> Retrieve all of the dds::sub::Subscriber created from this dds::domain::DomainParticipant More...
 
dds::sub::Subscriber find_subscriber (const dds::domain::DomainParticipant participant, const std::string &subscriber_name)
 <<extension>> Finds a Subscriber by name More...
 
dds::sub::Subscriber implicit_subscriber (const dds::domain::DomainParticipant &dp)
 <<extension>> Retrieves the implicit dds::sub::Subscriber for the given dds::domain::DomainParticipant. More...
 

Detailed Description

<<reference-type>> A subscriber is the object responsible for actually receiving data from a subscription.

QoS:
dds::sub::qos::SubscriberQos
Status:
dds::core::status::StatusMask::data_on_readers()
Listener:
dds::sub::SubscriberListener

A subscriber acts on the behalf of one or several dds::sub::DataReader objects that are related to it. When it receives data (from the other parts of the system), it builds the list of concerned dds::sub::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 dds::sub::DataReader objects through the operation dds::sub::find and then access the data available through operations on the dds::sub::DataReader.

The following operations may be called even if the dds::sub::Subscriber is not enabled. Other operations will the value dds::core::NotEnabledError if called on a disabled dds::sub::Subscriber:

All operations except for dds::sub::Subscriber::qos(const dds::sub::qos::SubscriberQos&), dds::sub::Subscriber::qos() const, dds::sub::Subscriber::set_listener, dds::sub::Subscriber::get_listener, dds::core::Entity::enable and dds::sub::DataReader::DataReader() may fail with dds::core::NotEnabledError.

See also
Operations Allowed in Listener Callbacks
dds::sub::find() and related functions
Entity Use Cases
Examples
Foo_subscriber.cxx.

Constructor & Destructor Documentation

◆ Subscriber() [1/3]

dds::sub::Subscriber::Subscriber ( const ::dds::domain::DomainParticipant the_participant)
inlineexplicit

Create a Subscriber attached to the given DomainParticipant.

The subscriber QoS will be set to participant.default_subscriber_qos()

Parameters
the_participantthe DomainParticipant that will own this subscriber.

◆ Subscriber() [2/3]

dds::sub::Subscriber::Subscriber ( const ::dds::domain::DomainParticipant dp,
const dds::sub::qos::SubscriberQos the_qos,
dds::sub::SubscriberListener the_listener = NULL,
const dds::core::status::StatusMask mask = dds::core::status::StatusMask::all() 
)
inline

Create a Subscriber attached to the given DomainParticipant.

[DEPRECATED] When using a listener, prefer the constructor that receives a shared_ptr<Listener> instead of a regular Listener* pointer.

Parameters
dpThe DomainParticipant that will own this subscriber.
the_qosThe qos::SubscriberQos
the_listenerThe subscriber listener.
maskIndicates which status updates the listener will receive

◆ Subscriber() [3/3]

dds::sub::Subscriber::Subscriber ( const ::dds::domain::DomainParticipant dp,
const dds::sub::qos::SubscriberQos the_qos,
std::shared_ptr< Listener the_listener,
const dds::core::status::StatusMask mask = dds::core::status::StatusMask::all() 
)
inline

Create a Subscriber attached to the given DomainParticipant.

Parameters
dpThe DomainParticipant that will own this subscriber.
the_qosThe qos::SubscriberQos
the_listenerA shared_ptr to the listener. See set_listener() for more information.
maskIndicates which status updates the listener will receive

Member Function Documentation

◆ notify_datareaders()

void dds::sub::Subscriber::notify_datareaders ( )
inline

This operation invokes the operation on_data_available on the DataReaderListener objects attached to contained DataReader entities with a DATA_AVAILABLE status that is considered changed as described in Changes in read communication status.

This operation is typically invoked from the dds::sub::SubscriberListener::on_data_on_readers operation in the dds::sub::SubscriberListener. That way the dds::sub::SubscriberListener can delegate to the dds::sub::DataReaderListener objects the handling of the data.

The operation will notify the data readers that have a sample_state of dds::sub::status::SampleState::not_read(), view_state of any() and instance_state of any().

Exceptions
Oneof the Standard Exceptions, or dds::core::NotEnabledError.

◆ listener() [1/2]

void dds::sub::Subscriber::listener ( Listener the_listener,
const dds::core::status::StatusMask event_mask 
)
inline

Attach a listener to this Subscriber.

[DEPRECATED] The use of set_listener() is recommended. Unlike this function, set_listener receives a shared_ptr which simplifies the management of listener's lifecycle.

Parameters
the_listenerThe listener
event_maskThe event mask for the listener.

◆ listener() [2/2]

Listener * dds::sub::Subscriber::listener ( ) const
inline

Get the Subscriber listener.

[DEPRECATED] Use get_listener instead of this function.

◆ set_listener() [1/2]

void dds::sub::Subscriber::set_listener ( std::shared_ptr< Listener the_listener,
const dds::core::status::StatusMask event_mask 
)
inline

Sets the listener associated with this subscriber.

The Subscriber will hold a shared_ptr to the listener argument, ensuring that it is not deleted at least until this Subscriber is deleted or the listener is reset with set_listener(nullptr).

Warning
It's recommended that the listener implementation doesn't hold a permanent reference to the Subscriber. If it does, the application needs to manually reset the listener or manually close this Subscriber to ensure that there is no cycle that prevents the destruction of these two objects.
Parameters
the_listenerA shared pointer to the listener to receive status updates or nullptr to reset the current listener and stop receiving status updates.
event_maskA mask that indicates which status updates will be notified to the listener

◆ set_listener() [2/2]

void dds::sub::Subscriber::set_listener ( std::shared_ptr< Listener the_listener)
inline

Sets the listener associated with this subscriber.

If the_listener is not nullptr, this overload is equivalent to:

static const StatusMask all()
All the bits are set.
Definition: State.hpp:168
void set_listener(std::shared_ptr< Listener > the_listener, const dds::core::status::StatusMask &event_mask)
Sets the listener associated with this subscriber.
Definition: TSubscriber.hpp:182

If the_listener is nullptr, it is equivalent to:

static const StatusMask none()
No bits are set.
Definition: State.hpp:176
Parameters
the_listenerA shared pointer to the listener to receive status updates or nullptr to reset the current listener and stop receiving status updates.

◆ get_listener()

std::shared_ptr< Listener > dds::sub::Subscriber::get_listener ( ) const
inline

Returns the listener currently associated with this Subscriber.

Returns
The shared pointer to the current listener or nullptr if there is currently no listener associated to this entity.

◆ qos() [1/2]

const dds::sub::qos::SubscriberQos dds::sub::Subscriber::qos ( ) const
inline

Get the Subscriber QoS.

◆ qos() [2/2]

void dds::sub::Subscriber::qos ( const dds::sub::qos::SubscriberQos the_qos)
inline

Set the Subscriber QoS.

Parameters
the_qosthe new QoS.

◆ default_datareader_qos() [1/2]

dds::sub::qos::DataReaderQos dds::sub::Subscriber::default_datareader_qos ( ) const
inline

Get the default DataReader QoS.

Returns
dds::sub::qos::DataReaderQos

◆ default_datareader_qos() [2/2]

Subscriber & dds::sub::Subscriber::default_datareader_qos ( const dds::sub::qos::DataReaderQos the_qos)
inline

Set the default DataReaderQoS.

Parameters
the_qosThe default DataReaderQoS.

◆ participant()

const dds::domain::DomainParticipant & dds::sub::Subscriber::participant ( ) const
inline

Return the DomainParticipant that owns this Subscriber.

Returns
const dds::domain::DomainParticipant& The DomainParticipant that owns this subscriber

◆ close_contained_entities()

void close_contained_entities ( )

<<extension>> Closes all the entities created from this Subscriber

Note
This function is an extension, it must be called via the extensions() member function
Calling this function explicitly is not necessary to close a Subscriber.

Deletes all contained dds::sub::DataReader objects. This pattern is applied recursively. In this manner, the operation dds::sub::Subscriber::close_contained_entities on the dds::sub::Subscriber will end up deleting all the entities recursively contained in the dds::sub::Subscriber, including the dds::sub::cond::QueryCondition, dds::sub::cond::ReadCondition, and rti::sub::TopicQuery objects belonging to the contained dds::sub::DataReader.

The operation will fail with dds::core::PreconditionNotMetError if any of the contained entities is in a state where it cannot be deleted. This will occur, for example, if a contained dds::sub::DataReader cannot be deleted because the application has called a dds::sub::DataReader::read or dds::sub::DataReader::take operation and the loan has not been returned.

MT Safety:
UNSAFE. It is not safe to delete an entity while another thread may be simultaneously calling an API that uses the entity.
Exceptions
Oneof the Standard Exceptions, or dds::core::PreconditionNotMetError

Friends And Related Function Documentation

◆ builtin_subscriber()

dds::sub::Subscriber builtin_subscriber ( const dds::domain::DomainParticipant dp)
related

Access the built-in Subscriber.

Each dds::domain::DomainParticipant contains several built-in dds::topic::Topic objects as well as corresponding dds::sub::DataReader objects to access them. All of these dds::sub::DataReader objects belong to a single built-in dds::sub::Subscriber.

The built-in Topics are used to communicate information about other dds::domain::DomainParticipant, dds::topic::Topic, dds::sub::DataReader, and dds::pub::DataWriter objects.

The built-in subscriber is created when this operation is called for the first time. The built-in subscriber is deleted automatically when the dds::domain::DomainParticipant is deleted.

Returns
The built-in dds::sub::Subscriber singleton.
See also
dds::topic::SubscriptionBuiltinTopicData
dds::topic::PublicationBuiltinTopicData
dds::topic::ParticipantBuiltinTopicData
dds::topic::TopicBuiltinTopicData
Parameters
dpThe DomainParticipant that the built-in subscriber belongs to.

◆ find_subscribers() [1/2]

template<typename SubscriberForwardIterator >
uint32_t find_subscribers ( const dds::domain::DomainParticipant  participant,
SubscriberForwardIterator  begin,
uint32_t  max_size 
)
related

<<extension>> Retrieve all of the dds::sub::Subscriber created from this dds::domain::DomainParticipant

Note
This is a standalone function in the namespace rti::sub
Template Parameters
SubscriberForwardIteratorType of the forward iterator passed into this function, whose value_type must be dds::sub::Subscriber.
Parameters
participantThe dds::domain::DomainParticipant the Publishers belong to
beginA forward iterator to the position in the destination container where to begin copying the found Subscribers into
max_sizeThe maximum size of Subscribers to add
Returns
The number of found Subscribers

References rti::sub::begin().

◆ find_subscribers() [2/2]

template<typename SubscriberBackInsertIterator >
uint32_t find_subscribers ( const dds::domain::DomainParticipant  participant,
SubscriberBackInsertIterator  begin 
)
related

<<extension>> Retrieve all of the dds::sub::Subscriber created from this dds::domain::DomainParticipant

Note
This is a standalone function in the namespace rti::sub
Template Parameters
AnyDataReaderBackInsertIteratorType of the back-inserting iterator passed into this function, whose value_type must be dds::sub::Subscriber.
Parameters
participantThe dds::domain::DomainParticipant the Subscribers belong to
beginA back-inserting iterator to the position in the destination container to insert the found Subscribers into
Returns
The number of found Subscribers

References rti::sub::begin().

◆ find_subscriber()

dds::sub::Subscriber find_subscriber ( const dds::domain::DomainParticipant  participant,
const std::string &  subscriber_name 
)
related

<<extension>> Finds a Subscriber by name

Note
This is a standalone function in the namespace rti::sub
Template Parameters
AnyDataReaderBackInsertIteratorType of the back-inserting iterator passed into this function, whose value_type must be dds::sub::AnyDataReader.
Parameters
participantThe dds::domain::DomainParticipant the Subscribers belong to
subscriber_nameThe name of the Subscriber
Returns
A valid reference if the a subscriber with that name exists or a reference equals to dds::core::null otherwise.

◆ implicit_subscriber()

dds::sub::Subscriber implicit_subscriber ( const dds::domain::DomainParticipant dp)
related

<<extension>> Retrieves the implicit dds::sub::Subscriber for the given dds::domain::DomainParticipant.

Note
This is a standalone function in the namespace rti::sub

If an implicit Subscriber does not already exist, this creates one.

The implicit Subscriber is created with default dds::sub::qos::SubscriberQos and no listener. When a DomainParticipant is deleted, if there are no attached dds::sub::DataReader that belong to the implicit Subscriber, the implicit Subscriber will be implicitly deleted.

MT Safety:
UNSAFE. it is not safe to create the implicit subscriber while another thread may be simultaneously calling dds::domain::DomainParticipant::default_subscriber_qos(const dds::sub::qos::SubscriberQos & qos ).
Parameters
dpThe DomainParticipant that the implicit subscriber belongs to.
Returns
The implicit Subscriber