RTI Connext Modern C++ API  Version 5.2.0
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
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 &participant)
 Create a Publisher.
 
 Publisher (const dds::domain::DomainParticipant &participant, const dds::pub::qos::PublisherQos &qos, dds::pub::PublisherListener *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.
 
const dds::pub::qos::PublisherQos qos () const
 Gets the PublisherQos.
 
void qos (const dds::pub::qos::PublisherQos &the_qos)
 Set the PublisherQos.
 
Publisheroperator<< (const dds::pub::qos::PublisherQos &the_qos)
 Sets the PublisherQos.
 
Publisheroperator>> (dds::pub::qos::PublisherQos &the_qos)
 Gets the PublisherQos.
 
Publisherdefault_datawriter_qos (const dds::pub::qos::DataWriterQos &dwqos)
 Sets the default DataWriterQos.
 
dds::pub::qos::DataWriterQos default_datawriter_qos () const
 Gets the default DataWriterQos.
 
void listener (Listener *plistener, const dds::core::status::StatusMask &event_mask)
 Sets the Publisher listener.
 
Listenerlistener () const
 Returns the listener currently associated with this Publisher.
 
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.
 
const
dds::domain::DomainParticipant
participant () const
 Gets the DomainParticipant to which this Publisher belongs.
 
void wait_for_asynchronous_publishing (const dds::core::Duration &max_wait)
 <<extension>> Blocks the calling thread until asynchronous sending is complete.
 
- Public Member Functions inherited from dds::core::Entity
void enable ()
 Enables this entity (if it was created disabled)
 
const dds::core::status::StatusMask status_changes ()
 Retrieves the list of communication statuses that are triggered.
 
const dds::core::InstanceHandle instance_handle () const
 Get the instance handle that represents this entity.
 
void close ()
 Forces the destruction of this entity.
 
void retain ()
 Disables the automatic destruction of this entity.
 

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
 
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.
 
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.
 
dds::pub::Publisher implicit_publisher (const dds::domain::DomainParticipant &dp)
 <<extension>> Get the implicit dds::pub::Publisher for a given dds::domain::DomainParticipant.
 

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

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

Create a Publisher.

It uses default qos::PublisherQos and no listener.

Parameters
participantThe DomainParticipant where this Publisher will be created
dds::pub::Publisher::Publisher ( const dds::domain::DomainParticipant participant,
const dds::pub::qos::PublisherQos qos,
dds::pub::PublisherListener 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.

Precondition
The specified QoS policies must be consistent, or the operation will fail
Parameters
participantThe DomainParticipant where this Publisher will be created
qosThe PublisherQos
listenerThe PublisherListener
maskChanges of communication status to be invoked on the listener.
Exceptions
dds::core::ErrorIf there is any error creating the Publisher

Member Function Documentation

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

Gets the PublisherQos.

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
Publisher& dds::pub::Publisher::operator<< ( const dds::pub::qos::PublisherQos the_qos)
inline

Sets the PublisherQos.

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

Gets the PublisherQos.

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

Sets the default DataWriterQos.

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.

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

Sets the Publisher listener.

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* dds::pub::Publisher::listener ( ) const
inline

Returns the listener currently associated with this Publisher.

If there's no listener it returns NULL.

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 return value of 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.

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

Gets the DomainParticipant to which this Publisher belongs.

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

Friends And Related Function Documentation

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

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

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.
dds::pub::Publisher implicit_publisher ( const dds::domain::DomainParticipant dp)
related

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

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

RTI Connext Modern C++ API Version 5.2.0 Copyright © Sun Jun 21 2015 Real-Time Innovations, Inc