RTI Connext Modern C++ API  Version 6.1.0
dds::pub::Publisher Class Reference

<<reference-type>> A publisher is the object responsible for the actual dissemination of publications. More...

#include <dds/pub/Publisher.hpp>

Inheritance diagram for dds::pub::Publisher:
dds::core::Entity

Public Member Functions

 Publisher (const dds::domain::DomainParticipant &the_participant)
 Create a Publisher. More...
 
 Publisher (const dds::domain::DomainParticipant &the_participant, const dds::pub::qos::PublisherQos &the_qos, dds::pub::PublisherListener *the_listener=NULL, const dds::core::status::StatusMask &mask=dds::core::status::StatusMask::all())
 Create a Publisher with the desired QoS policies and attaches to it the specified PublisherListener. More...
 
 Publisher (const ::dds::domain::DomainParticipant &the_participant, const dds::pub::qos::PublisherQos &the_qos, std::shared_ptr< Listener > the_listener, const dds::core::status::StatusMask &mask=dds::core::status::StatusMask::all())
 Create a Publisher with the desired QoS policies and attaches to it the specified PublisherListener. More...
 
const dds::pub::qos::PublisherQos qos () const
 Gets the PublisherQos. More...
 
void qos (const dds::pub::qos::PublisherQos &the_qos)
 Set the PublisherQos. More...
 
Publisheroperator<< (const dds::pub::qos::PublisherQos &the_qos)
 Sets the PublisherQos. More...
 
Publisheroperator>> (dds::pub::qos::PublisherQos &the_qos)
 Gets the PublisherQos. More...
 
Publisherdefault_datawriter_qos (const dds::pub::qos::DataWriterQos &dwqos)
 Sets the default DataWriterQos. More...
 
dds::pub::qos::DataWriterQos default_datawriter_qos () const
 Gets the default DataWriterQos. More...
 
void listener (Listener *plistener, const dds::core::status::StatusMask &event_mask)
 Sets the Publisher listener. More...
 
Listenerlistener () const
 Returns the listener currently associated with this Publisher. More...
 
void set_listener (std::shared_ptr< Listener > the_listener, const dds::core::status::StatusMask &event_mask)
 Sets the listener associated with this publisher. More...
 
void set_listener (std::shared_ptr< Listener > the_listener)
 Sets the listener associated with this publisher. More...
 
std::shared_ptr< Listenerget_listener () const
 Returns the listener currently associated with this Publisher. More...
 
void wait_for_acknowledgments (const dds::core::Duration &max_wait)
 Blocks the calling thread until all data written by this Publisher's reliable DataWriters is acknowledged, or until timeout expires. More...
 
const dds::domain::DomainParticipantparticipant () const
 Gets the DomainParticipant to which this Publisher belongs. More...
 
void wait_for_asynchronous_publishing (const dds::core::Duration &max_wait)
 <<extension>> Blocks the calling thread until asynchronous sending is complete. More...
 
void close_contained_entities ()
 <<extension>> Closes all the entities created from this Publisher 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.)

template<typename PublisherForwardIterator >
uint32_t find_publishers (const dds::domain::DomainParticipant participant, PublisherForwardIterator begin, uint32_t max_size)
 <<extension>> Retrieve all of the dds::pub::Publisher created from this dds::domain::DomainParticipant More...
 
template<typename PublisherBackInsertIterator >
uint32_t find_publishers (const dds::domain::DomainParticipant participant, PublisherBackInsertIterator begin)
 Retrieve all the dds::pub::Publisher created from this dds::domain::DomainParticipant. More...
 
dds::pub::Publisher find_publisher (const dds::domain::DomainParticipant participant, const std::string &publisher_name)
 <<extension>> Looks up a dds::pub::Publisher by its entity name within the dds::domain::DomainParticipant. More...
 
dds::pub::Publisher implicit_publisher (const dds::domain::DomainParticipant &dp)
 <<extension>> Get the implicit dds::pub::Publisher for a given dds::domain::DomainParticipant. More...
 

Detailed Description

<<reference-type>> A publisher is the object responsible for the actual dissemination of publications.

QoS:
dds::pub::qos::PublisherQos
Listener:
PublisherListener

A publisher acts on the behalf of one or several dds::pub::DataWriter objects that belong to it. When it is informed of a change to the data associated with one of its dds::pub::DataWriter objects, it decides when it is appropriate to actually send the data-update message. In making this decision, it considers any extra information that goes with the data (timestamp, writer, etc.) as well as the QoS of the dds::pub::Publisher and the dds::pub::DataWriter.

The following operations may be called even if the dds::pub::Publisher is not enabled. Other operations will fail with the value dds::core::NotEnabledError if called on a disabled dds::pub::Publisher:

See also
Operations Allowed in Listener Callbacks
dds::pub::find() and related functions
dds::pub::SuspendedPublication
Publisher Use Cases
Entity Use Cases
Examples:
Foo_publisher.cxx.

Constructor & Destructor Documentation

◆ Publisher() [1/3]

dds::pub::Publisher::Publisher ( const dds::domain::DomainParticipant the_participant)
inlineexplicit

Create a Publisher.

It uses default qos::PublisherQos and no listener.

Parameters
the_participantThe DomainParticipant where this Publisher will be created

◆ Publisher() [2/3]

dds::pub::Publisher::Publisher ( const dds::domain::DomainParticipant the_participant,
const dds::pub::qos::PublisherQos the_qos,
dds::pub::PublisherListener the_listener = NULL,
const dds::core::status::StatusMask mask = dds::core::status::StatusMask::all() 
)
inline

Create a Publisher with the desired QoS policies and attaches to it the specified PublisherListener.

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

Precondition
The specified QoS policies must be consistent, or the operation will fail
Parameters
the_participantThe DomainParticipant where this Publisher will be created
the_qosThe PublisherQos
the_listenerThe PublisherListener
maskIndicates which status updates the listener will receive
Exceptions
dds::core::ErrorIf there is any error creating the Publisher

◆ Publisher() [3/3]

dds::pub::Publisher::Publisher ( const ::dds::domain::DomainParticipant the_participant,
const dds::pub::qos::PublisherQos the_qos,
std::shared_ptr< Listener the_listener,
const dds::core::status::StatusMask mask = dds::core::status::StatusMask::all() 
)
inline

Create a Publisher with the desired QoS policies and attaches to it the specified PublisherListener.

Precondition
The specified QoS policies must be consistent, or the operation will fail
Parameters
the_participantThe DomainParticipant where this Publisher will be created
the_qosThe PublisherQos
the_listenerA shared_ptr to the listener. See set_listener() for more information.
maskIndicates which status updates the listener will receive
Exceptions
dds::core::ErrorIf there is any error creating the Publisher

Member Function Documentation

◆ qos() [1/2]

const dds::pub::qos::PublisherQos dds::pub::Publisher::qos ( ) const
inline

Gets the PublisherQos.

◆ qos() [2/2]

void dds::pub::Publisher::qos ( const dds::pub::qos::PublisherQos the_qos)
inline

Set the PublisherQos.

This operation modifies the QoS of the dds::pub::Publisher.

The dds::core::policy::GroupData, dds::core::policy::Partition and dds::core::policy::EntityFactory can be changed. The other policies are immutable.

Parameters
the_qos<<in>> dds::pub::qos::PublisherQos to be set to. Policies must be consistent. Immutable policies cannot be changed after dds::pub::Publisher is enabled. The special value PUBLISHER_QOS_DEFAULT can be used to indicate that the QoS of the dds::pub::Publisher should be changed to match the current default dds::pub::qos::PublisherQos set in the dds::domain::DomainParticipant.
Exceptions
Oneof the Standard Exceptions, dds::core::ImmutablePolicyError, or dds::core::InconsistentPolicyError.
See also
dds::pub::qos::PublisherQos for rules on consistency among QoS
set_qos (abstract)
Operations Allowed in Listener Callbacks

◆ operator<<()

Publisher& dds::pub::Publisher::operator<< ( const dds::pub::qos::PublisherQos the_qos)
inline

Sets the PublisherQos.

◆ operator>>()

Publisher& dds::pub::Publisher::operator>> ( dds::pub::qos::PublisherQos the_qos)
inline

Gets the PublisherQos.

◆ default_datawriter_qos() [1/2]

Publisher& dds::pub::Publisher::default_datawriter_qos ( const dds::pub::qos::DataWriterQos dwqos)
inline

Sets the default DataWriterQos.

◆ default_datawriter_qos() [2/2]

dds::pub::qos::DataWriterQos dds::pub::Publisher::default_datawriter_qos ( ) const
inline

Gets the default DataWriterQos.

The retrieved DataWriterQos will match the set of values specified on the last call to default_datawriter_qos(const dds::pub::qos::DataWriterQos&). If the application never called that function, the default value comes from the dds::domain::DomainParticipant.

◆ listener() [1/2]

void dds::pub::Publisher::listener ( Listener plistener,
const dds::core::status::StatusMask event_mask 
)
inline

Sets the Publisher listener.

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

Exceptions
Oneof the Standard Exceptions
See also
set_listener (abstract)
Parameters
plistenerthe topic listener
event_maskChanges of communication status to be invoked on the listener

◆ listener() [2/2]

Listener* dds::pub::Publisher::listener ( ) const
inline

Returns the listener currently associated with this Publisher.

[DEPRECATED] Use get_listener instead of this function.

If there's no listener it returns NULL.

◆ set_listener() [1/2]

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

Sets the listener associated with this publisher.

The Publisher will hold a shared_ptr to the listener argument, ensuring that it is not deleted at least until this Publisher 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 Publisher. If it does, the application needs to manually reset the listener or manually close this Publisher 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::pub::Publisher::set_listener ( std::shared_ptr< Listener the_listener)
inline

Sets the listener associated with this publisher.

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

If the_listener is nullptr, it is equivalent to:

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::pub::Publisher::get_listener ( ) const
inline

Returns the listener currently associated with this Publisher.

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

◆ wait_for_acknowledgments()

void dds::pub::Publisher::wait_for_acknowledgments ( const dds::core::Duration max_wait)
inline

Blocks the calling thread until all data written by this Publisher's reliable DataWriters is acknowledged, or until timeout expires.

This operation blocks the calling thread until either all data written by the reliable DataWriters entities is acknowledged by (a) all reliable dds::sub::DataReader entities that are matched and alive and (b) by all required subscriptions, or until the duration specified by the max_wait parameter elapses, whichever happens first. A successful completion indicates that all the samples written have been acknowledged; a timeout indicates that max_wait elapsed before all the data was acknowledged.

Note that if a thread is blocked in the call to this operation on a dds::pub::Publisher and a different thread writes new samples on any of the reliable DataWriters that belong to this Publisher, the new samples must be acknowledged before unblocking the thread that is waiting on this operation.

If none of the dds::pub::DataWriter instances have dds::core::policy::Reliability kind set to RELIABLE, the operation will complete successfully.

Exceptions
Oneof the Standard Exceptions, dds::core::NotEnabledError, dds::core::TimeoutError

◆ participant()

const dds::domain::DomainParticipant& dds::pub::Publisher::participant ( ) const
inline

Gets the DomainParticipant to which this Publisher belongs.

◆ wait_for_asynchronous_publishing()

void wait_for_asynchronous_publishing ( const dds::core::Duration max_wait)

<<extension>> Blocks the calling thread until asynchronous sending is complete.

This operation blocks the calling thread (up to max_wait) until all data written by the asynchronous dds::pub::DataWriter entities is sent and acknowledged (if reliable) by all matched dds::sub::DataReader entities. A successful completion indicates that all the samples written have been sent and acknowledged where applicable; if it times out, this indicates that max_wait elapsed before all the data was sent and/or acknowledged.

In other words, this guarantees that sending to best effort dds::sub::DataReader is complete in addition to what dds::pub::Publisher::wait_for_acknowledgments provides.

If none of the dds::pub::DataWriter instances have rti::core::policy::PublishMode::kind set to rti::core::policy::PublishModeKind_def::ASYNCHRONOUS, the operation will complete immediately .

Parameters
max_wait<<in>> Specifies maximum time to wait for acknowledgements dds::core::Duration.
Exceptions
Oneof the Standard Exceptions, dds::core::NotEnabledError, dds::core::TimeoutError

◆ close_contained_entities()

void close_contained_entities ( )

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

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

Deletes all contained dds::pub::DataWriter objects. Once dds::pub::Publisher::close_contained_entities completes successfully, the application may delete the dds::pub::Publisher, knowing that it has no contained dds::pub::DataWriter objects.

The operation will fail with dds::core::PreconditionNotMetError if any of the contained entities is in a state where it cannot be deleted.

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

◆ find_publishers() [1/2]

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

<<extension>> Retrieve all of the dds::pub::Publisher created from this dds::domain::DomainParticipant

Note
This is a standalone function in the namespace rti::pub
Template Parameters
PublisherForwardIteratorA forward iterator whose value type is dds::pub::Publisher
Parameters
participantThe dds::domain::DomainParticipant the Publishers belong to
beginA forward iterator to the position in the destination container to insert the found Publishers into
max_sizeThe maximum number of Publishers to add
Returns
The number of found Publishers
See also
DDSWriterExampleModule_lookup

◆ find_publishers() [2/2]

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

Retrieve all the dds::pub::Publisher created from this dds::domain::DomainParticipant.

Template Parameters
PublisherBackInsertIteratorA back-inserting iterator whose value type is dds::pub::Publisher
Parameters
participantThe dds::domain::DomainParticipant the Publishers belong to
beginA back-inserting iterator to the position in the destination container to insert the found Publishers in
Returns
The number of found Publishers
See also
DDSWriterExampleModule_lookup

◆ find_publisher()

dds::pub::Publisher find_publisher ( const dds::domain::DomainParticipant  participant,
const std::string &  publisher_name 
)
related

<<extension>> Looks up a dds::pub::Publisher by its entity name within the dds::domain::DomainParticipant.

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

Every dds::pub::Publisher in the system has an entity name which is configured and stored in the EntityName policy, ENTITY_NAME.

This operation retrieves a dds::pub::Publisher within the dds::domain::DomainParticipant given the entity's name. If there are several dds::pub::Publisher with the same name within the dds::domain::DomainParticipant, this function returns the first matching occurrence.

Parameters
participantThe dds::domain::DomainParticipant to look for the dds::pub::Publisher in.
publisher_nameEntity name of the Publisher
Returns
The first Publisher found with the specified name or dds::core::null if it is not found.
See also
DDSWriterExampleModule_lookup

◆ implicit_publisher()

dds::pub::Publisher implicit_publisher ( const dds::domain::DomainParticipant dp)
related

<<extension>> Get the implicit dds::pub::Publisher for a given dds::domain::DomainParticipant.

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

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

The implicit Publisher is created with default dds::pub::qos::PublisherQos and no listener. When a DomainParticipant is deleted, if there are no attached dds::pub::DataWriter that belong to the implicit Publisher, the implicit Publisher will be implicitly deleted.

MT Safety:
UNSAFE. It is not safe to create an implicit Publisher while another thread may be simultaneously calling dds::domain::DomainParticipant::default_publisher_qos.
Parameters
dpThe DomainParticipant that the implicit publisher belongs to
Returns
The implicit publisher