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

Public Member Functions
	Publisher (const dds::domain::DomainParticipant &the_participant)
	Create a 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())
	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.

Publisher &	operator<< (const dds::pub::qos::PublisherQos &the_qos)
	Sets the PublisherQos.

Publisher &	operator>> (dds::pub::qos::PublisherQos &the_qos)
	Gets the PublisherQos.

Publisher &	default_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.

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

Related Functions inherited from dds::core::Entity
template<typename TO , typename FROM >
TO	polymorphic_cast (FROM &from)
	Downcasts an Entity to a subclass.

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 & the_participant )

inlineexplicit

Create a Publisher.

It uses default qos::PublisherQos and no listener.

Parameters

the_participant The DomainParticipant where this Publisher will be created

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.

Precondition: The specified QoS policies must be consistent, or the operation will fail

Parameters

the_participant	The DomainParticipant where this Publisher will be created
the_qos	The PublisherQos
the_listener	The PublisherListener
mask	Changes of communication status to be invoked on the listener.

Exceptions

dds::core::Error If 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

One	of 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

One	of the Standard Exceptions

See Also: set_listener (abstract)

Parameters

plistener	the topic listener
event_mask	Changes 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

One	of 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

One	of 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
	)

Template Parameters

PublisherForwardIterator A forward iterator whose value type is dds::pub::Publisher

Parameters

participant	The dds::domain::DomainParticipant the Publishers belong to
begin	A forward iterator to the position in the destination container to insert the found Publishers into
max_size	The 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
	)

Template Parameters

PublisherBackInsertIterator A back-inserting iterator whose value type is dds::pub::Publisher

Parameters

participant	The dds::domain::DomainParticipant the Publishers belong to
begin	A 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
	)

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

participant	The dds::domain::DomainParticipant to look for the dds::pub::Publisher in.
publisher_name	Entity 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 )

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

dp	The DomainParticipant that the implicit publisher belongs to

Returns: The implicit publisher

Public Member Functions

Related Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation