<<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:

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...

Listener *	listener () 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< Listener >	get_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...

Subscriber &	default_datareader_qos (const dds::sub::qos::DataReaderQos &the_qos)
	Set the default DataReaderQoS. More...

const dds::domain::DomainParticipant &	participant () 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...

Related Functions inherited from dds::core::Entity
template<typename TO , typename FROM >
TO	polymorphic_cast (const FROM &from)
	Downcasts an Entity to a subclass. 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_participant the 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

dp	The DomainParticipant that will own this subscriber.
the_qos	The qos::SubscriberQos
the_listener	The subscriber listener.
mask	Indicates 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

dp	The DomainParticipant that will own this subscriber.
the_qos	The qos::SubscriberQos
the_listener	A shared_ptr to the listener. See set_listener() for more information.
mask	Indicates 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

One	of 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_listener	The listener
event_mask	The 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_listener	A shared pointer to the listener to receive status updates or `nullptr` to reset the current listener and stop receiving status updates.
event_mask	A 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:

subscriber.set_listener(the_listener, dds::core::status::StatusMask::all());

If the_listener is nullptr, it is equivalent to:

subscriber.set_listener(nullptr, dds::core::status::StatusMask::none());

Parameters

the_listener A 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_qos the 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_qos The 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 this->extensions(); 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

One	of the Standard Exceptions, or dds::core::PreconditionNotMetError

Friends And Related Function Documentation

◆ builtin_subscriber()

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

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

dp	The 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
	)

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

Template Parameters

SubscriberForwardIterator Type of the forward iterator passed into this function, whose value_type must be dds::sub::Subscriber.

Parameters

participant	The dds::domain::DomainParticipant the Publishers belong to
begin	A forward iterator to the position in the destination container where to begin copying the found Subscribers into
max_size	The maximum size of Subscribers to add

Returns: The number of found Subscribers

◆ find_subscribers() [2/2]

template<typename SubscriberBackInsertIterator >

uint32_t find_subscribers	(	const dds::domain::DomainParticipant	participant,
		SubscriberBackInsertIterator	begin
	)

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

Template Parameters

AnyDataReaderBackInsertIterator Type of the back-inserting iterator passed into this function, whose value_type must be dds::sub::Subscriber.

Parameters

participant	The dds::domain::DomainParticipant the Subscribers belong to
begin	A back-inserting iterator to the position in the destination container to insert the found Subscribers into

Returns: The number of found Subscribers

◆ find_subscriber()

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

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

Template Parameters

AnyDataReaderBackInsertIterator Type of the back-inserting iterator passed into this function, whose value_type must be dds::sub::AnyDataReader.

Parameters

participant	The dds::domain::DomainParticipant the Subscribers belong to
subscriber_name	The 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 )

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.

                \par 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

dp	The DomainParticipant that the implicit subscriber belongs to.

Returns: The implicit Subscriber

Public Member Functions

Related Functions

Detailed Description

Constructor & Destructor Documentation

◆ Subscriber() [1/3]

◆ Subscriber() [2/3]

◆ Subscriber() [3/3]

Member Function Documentation

◆ notify_datareaders()

◆ listener() [1/2]

◆ listener() [2/2]

◆ set_listener() [1/2]

◆ set_listener() [2/2]

◆ get_listener()

◆ qos() [1/2]

◆ qos() [2/2]

◆ default_datareader_qos() [1/2]

◆ default_datareader_qos() [2/2]

◆ participant()

◆ close_contained_entities()

Friends And Related Function Documentation

◆ builtin_subscriber()

◆ find_subscribers() [1/2]

◆ find_subscribers() [2/2]

◆ find_subscriber()

◆ implicit_subscriber()