RTI Connext Modern C++ API Version 7.2.0
dds::pub::DataWriter< T > Class Template Reference

<<reference-type>> Allows an application to publish data for a dds::topic::Topic More...

#include <dds/pub/DataWriter.hpp>

Inheritance diagram for dds::pub::DataWriter< T >:
dds::core::Entity

Public Member Functions

 DataWriter (const dds::pub::Publisher &pub, const dds::topic::Topic< T > &the_topic)
 Creates a DataWriter. More...
 
 DataWriter (const dds::pub::Publisher &pub, const dds::topic::Topic< T > &the_topic, const dds::pub::qos::DataWriterQos &the_qos, dds::pub::DataWriterListener< T > *the_listener=NULL, const dds::core::status::StatusMask &mask=dds::core::status::StatusMask::all())
 Creates a DataWriter with QoS and listener. More...
 
 DataWriter (const dds::pub::Publisher &pub, const dds::topic::Topic< T > &the_topic, const dds::pub::qos::DataWriterQos &the_qos, std::shared_ptr< Listener > the_listener, const dds::core::status::StatusMask &mask=dds::core::status::StatusMask::all())
 Creates a DataWriter with QoS and listener. More...
 
void write (const T &instance_data)
 Modifies the value of a data instance. More...
 
void write (const T &instance_data, const dds::core::Time &timestamp)
 Modifies the value of a data instance and specifies the timestamp. More...
 
void write (const T &instance_data, const dds::core::InstanceHandle &handle)
 Modifies the value of a data instance. More...
 
void write (const T &instance_data, const dds::core::InstanceHandle &handle, const dds::core::Time &source_timestamp)
 Modifies the value of a data instance and specifies the timestamp. More...
 
void write (const dds::topic::TopicInstance< T > &topic_instance)
 Write a dds::topic::TopicInstance. More...
 
void write (const dds::topic::TopicInstance< T > &topic_instance, const dds::core::Time &timestamp)
 Write a topic instance with time stamp. More...
 
template<typename FWIterator >
void write (const FWIterator &begin, const FWIterator &end)
 
template<typename FWIterator >
void write (const FWIterator &begin, const FWIterator &end, const dds::core::Time &timestamp)
 
template<typename SamplesFWIterator , typename HandlesFWIterator >
void write (const SamplesFWIterator &data_begin, const SamplesFWIterator &data_end, const HandlesFWIterator &handle_begin, const HandlesFWIterator &handle_end)
 Write a series of samples and their parallel instance handles. More...
 
template<typename SamplesFWIterator , typename HandlesFWIterator >
void write (const SamplesFWIterator &data_begin, const SamplesFWIterator &data_end, const HandlesFWIterator &handle_begin, const HandlesFWIterator &handle_end, const dds::core::Time &timestamp)
 Write a series of samples and their parallel instance handles and a timestamp. More...
 
DataWriteroperator<< (const T &data)
 Writes a sample. More...
 
DataWriteroperator<< (const std::pair< T, dds::core::Time > &data)
 Writes a sample with a timestamp. More...
 
DataWriteroperator<< (const std::pair< T, dds::core::InstanceHandle > &data)
 Writes a sample with an instance handle. More...
 
const dds::core::InstanceHandle register_instance (const T &instance_data)
 Informs RTI Connext that the application will be modifying a particar instance. More...
 
const dds::core::InstanceHandle register_instance (const T &instance_data, const dds::core::Time &source_timestamp)
 Informs RTI Connext that the application will be modifying a particular instance and specifies the timestamp. More...
 
DataWriterunregister_instance (const dds::core::InstanceHandle &handle)
 Unregister an instance. More...
 
DataWriterunregister_instance (const dds::core::InstanceHandle &handle, const dds::core::Time &source_timestamp)
 Unregister an instance with timestamp. More...
 
DataWriterdispose_instance (const dds::core::InstanceHandle &handle)
 Requests the middleware to delete the instance identified by the instance handle. More...
 
DataWriterdispose_instance (const dds::core::InstanceHandle &the_instance_handle, const dds::core::Time &source_timestamp)
 Dispose an instance with a timestamp. More...
 
T & key_value (T &key_holder, const dds::core::InstanceHandle &handle)
 Retrieve the instance key that corresponds to an instance handle. More...
 
dds::topic::TopicInstance< T > & key_value (dds::topic::TopicInstance< T > &key_holder, const dds::core::InstanceHandle &handle)
 Retrieve the instance key that corresponds to an instance handle. More...
 
dds::core::InstanceHandle lookup_instance (const T &key_holder)
 Retrieve the instance handle that corresponds to an instance key_holder. More...
 
const dds::pub::qos::DataWriterQos qos () const
 Gets the DataWriterQos. More...
 
void qos (const dds::pub::qos::DataWriterQos &the_qos)
 Sets the DataWriterQos. More...
 
DataWriteroperator<< (const dds::pub::qos::DataWriterQos &the_qos)
 Set the DataWriterQos. More...
 
const DataWriteroperator>> (dds::pub::qos::DataWriterQos &the_qos) const
 Get the DataWriterQos. More...
 
const dds::topic::Topic< T > & topic () const
 Get the Topic associated with this DataWriter. More...
 
const dds::pub::Publisherpublisher () const
 Get the Publisher that owns this DataWriter. More...
 
void wait_for_acknowledgments (const dds::core::Duration &max_wait)
 Blocks the calling thread until all data written by reliable DataWriter entity is acknowledged, or until timeout expires. More...
 
void listener (DataWriterListener< T > *l, const dds::core::status::StatusMask &mask)
 Sets the DataWriter listener. More...
 
DataWriterListener< T > * listener () const
 Returns the listener currently associated with this DataWriter. More...
 
void set_listener (std::shared_ptr< Listener > the_listener, const dds::core::status::StatusMask &event_mask)
 Sets the listener associated with this writer. More...
 
void set_listener (std::shared_ptr< Listener > the_listener)
 Sets the listener associated with this writer. More...
 
std::shared_ptr< Listenerget_listener () const
 Returns the listener currently associated with this writer. More...
 
const dds::core::status::LivelinessLostStatus liveliness_lost_status ()
 Get the LivelinessLostStatus. More...
 
const dds::core::status::OfferedDeadlineMissedStatus offered_deadline_missed_status ()
 Get the OfferedDeadlineMissedStatus. More...
 
const dds::core::status::OfferedIncompatibleQosStatus offered_incompatible_qos_status ()
 Get the OfferedIncompatibleQosStatus. More...
 
const dds::core::status::PublicationMatchedStatus publication_matched_status ()
 Get the PublicationMatchedStatus. More...
 
void assert_liveliness ()
 Manually asserts the liveliness of this DataWriter. More...
 
void unregister_instance (rti::pub::WriteParams &params)
 <<extension>> Unregister an instance with parameters More...
 
void dispose_instance (rti::pub::WriteParams &params)
 <<extension>> Dispose an instance with parameters More...
 
bool is_sample_app_acknowledged (const rti::core::SampleIdentity &sample_id)
 <<extension>> Indicates if a sample is considered application-acknowledged More...
 
void wait_for_asynchronous_publishing (const dds::core::Duration &max_wait)
 <<extension>> Blocks the calling thread until asynchronous sending is complete. More...
 
rti::core::status::ReliableWriterCacheChangedStatus reliable_writer_cache_changed_status ()
 <<extension>> Get the reliable cache status for this writer. More...
 
rti::core::status::ReliableReaderActivityChangedStatus reliable_reader_activity_changed_status ()
 <<extension>> Get the reliable reader activity changed status for this writer More...
 
rti::core::status::DataWriterCacheStatus datawriter_cache_status ()
 <<extension>> Get the cache status for this writer More...
 
rti::core::status::DataWriterProtocolStatus datawriter_protocol_status ()
 <<extension>> Get the protocol status for this writer More...
 
rti::core::status::DataWriterProtocolStatus matched_subscription_datawriter_protocol_status (const dds::core::InstanceHandle &subscription_handle)
 <<extension>> Get the datawriter protocol status for this writer, per matched subscription identified by the subscription_handle. More...
 
rti::core::status::DataWriterProtocolStatus matched_subscription_datawriter_protocol_status (const rti::core::Locator &subscription_locator)
 <<extension>> Get the datawriter protocol status for this writer, per matched subscription identified by the locator More...
 
rti::core::status::ServiceRequestAcceptedStatus service_request_accepted_status ()
 <<extension>> Get the service request accepted status for this writer More...
 
void flush ()
 <<extension>> Flushes the batch in progress in the context of the calling thread. More...
 
void write (const T &instance_data, rti::pub::WriteParams &params)
 <<extension>> Write with advanced parameters More...
 
rti::core::Result< void > write_noexcept (const T &sample) noexcept
 <<extension>> Alternative to write() that doesn't throw exceptions. More...
 
rti::core::Result< void > write_noexcept (const T &sample, const dds::core::Time &timestamp) noexcept
 <<extension>> Alternative to write() that doesn't throw exceptions. More...
 
rti::core::Result< void > write_noexcept (const T &sample, const dds::core::InstanceHandle &instance) noexcept
 <<extension>> Alternative to write() that doesn't throw exceptions. More...
 
rti::core::Result< void > write_noexcept (const T &sample, const dds::core::InstanceHandle &instance, const dds::core::Time &timestamp) noexcept
 <<extension>> Alternative to write() that doesn't throw exceptions. More...
 
rti::core::Result< void > write_noexcept (const T &instance_data, rti::pub::WriteParams &params) noexcept
 <<extension>> Alternative to write() that doesn't throw exceptions. More...
 
T * create_data ()
 <<extension>> Create data from this writer and initialize it More...
 
bool delete_data (T *sample)
 <<extension>> Delete data created with create_data(). More...
 
T * get_loan ()
 <<extension>> Get a loaned sample from this writer More...
 
void discard_loan (T &sample)
 <<extension>> Discard a loaned sample from this writer More...
 
const dds::core::InstanceHandle register_instance (const T &key, rti::pub::WriteParams &params)
 <<extension>> Registers and instance with parameters 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.)

void ignore (dds::domain::DomainParticipant &participant, const dds::core::InstanceHandle &handle)
 Instructs RTI Connext to locally ignore a publication. More...
 
template<typename FwdIterator >
void ignore (dds::domain::DomainParticipant &participant, FwdIterator begin, FwdIterator end)
 Instructs RTI Connext to locally ignore several publications. More...
 
template<typename T >
dds::core::InstanceHandleSeq matched_subscriptions (const dds::pub::DataWriter< T > &writer)
 Retrieve the list of subscriptions currently associated with a dds::pub::DataWriter. More...
 
template<typename T , typename FwdIterator >
FwdIterator matched_subscriptions (const dds::pub::DataWriter< T > &writer, FwdIterator begin, FwdIterator end)
 Retrieve the list of subscriptions currently associated with a dds::pub::DataWriter. More...
 
template<typename T >
const dds::topic::SubscriptionBuiltinTopicData matched_subscription_data (const dds::pub::DataWriter< T > &writer, const dds::core::InstanceHandle &subscription_handle)
 Retrieves information on a subscription that is currently associated with a dds::pub::DataWriter. More...
 
template<typename T >
dds::topic::ParticipantBuiltinTopicData matched_subscription_participant_data (const dds::pub::DataWriter< T > &writer, const dds::core::InstanceHandle &handle)
 <<extension>> This operation retrieves the information on the discovered dds::domain::DomainParticipant associated with the subscription that is currently matching with the dds::pub::DataWriter. More...
 
template<typename T >
rti::core::LocatorSeq matched_subscriptions_locators (const dds::pub::DataWriter< T > &writer)
 <<extension>> Retrieve the list of locators for subscriptions currently associated with this DataWriter. More...
 
template<typename T >
bool is_matched_subscription_active (const dds::pub::DataWriter< T > &writer, const dds::core::InstanceHandle &handle)
 <<extension>> Check if a matched subscription is active. More...
 
template<typename T >
std::vector< dds::topic::SubscriptionBuiltinTopicDatamatched_subscription_data (const dds::pub::DataWriter< T > &writer)
 <<extension>> Obtain the SubscriptionBuiltinTopicData for all of the subscriptions matched with a DataWriter. More...
 
template<typename Writer , typename FwdIterator >
uint32_t find (const dds::pub::Publisher &publisher, const std::string &topic_name, FwdIterator begin, uint32_t max_size)
 Retrieves the dds::pub::DataWriter for a specific topic name. More...
 
template<typename Writer , typename BinIterator >
uint32_t find (const dds::pub::Publisher &publisher, const std::string &topic_name, BinIterator begin)
 Retrieves the dds::pub::DataWriter for a specific topic name. More...
 
template<typename AnyDataWriterBackInsertIterator >
uint32_t find_datawriters (dds::pub::Publisher publisher, AnyDataWriterBackInsertIterator begin)
 Retrieve all the dds::pub::DataWriter created from this dds::pub::Publisher. More...
 
template<typename AnyDataWriterForwardIterator >
uint32_t find_datawriters (dds::pub::Publisher publisher, AnyDataWriterForwardIterator begin, uint32_t max_size)
 Retrieve all the dds::pub::DataWriter created from this dds::pub::Publisher. More...
 
template<typename Writer >
Writer find_datawriter_by_topic_name (dds::pub::Publisher publisher, const std::string &topic_name)
 <<extension>> Retrieves a dds::pub::DataWriter with the given name within the dds::pub::Publisher More...
 
template<typename Writer >
Writer find_datawriter_by_name (dds::pub::Publisher publisher, const std::string &datawriter_name)
 <<extension>> Retrieves a dds::pub::DataWriter with the given name within the dds::pub::Publisher More...
 
template<typename Writer >
Writer find_datawriter_by_name (dds::domain::DomainParticipant participant, const std::string &datawriter_name)
 <<extension>> Retrieves a dds::pub::DataWriter within the dds::domain::DomainParticipant with the given name More...
 

Detailed Description

template<typename T>
class dds::pub::DataWriter< T >

<<reference-type>> Allows an application to publish data for a dds::topic::Topic

Template Parameters
TThe topic-type that the DataWriter publishes
QoS:
dds::pub::qos::DataWriterQos
Status:
dds::core::status::StatusMask::liveliness_lost(), dds::core::status::LivelinessLostStatus;
dds::core::status::StatusMask::offered_deadline_missed(), dds::core::status::OfferedDeadlineMissedStatus;
dds::core::status::StatusMask::offered_incompatible_qos(), dds::core::status::OfferedIncompatibleQosStatus;
dds::core::status::StatusMask::publication_matched(), dds::core::status::PublicationMatchedStatus;
dds::core::status::StatusMask::reliable_reader_activity_changed(), rti::core::status::ReliableReaderActivityChangedStatus;
dds::core::status::StatusMask::reliable_writer_cache_changed(), rti::core::status::ReliableWriterCacheChangedStatus.
Listener:
dds::pub::DataWriterListener

A dds::pub::DataWriter is attached to exactly one dds::pub::Publisher, that acts as a factory for it.

A dds::pub::DataWriter is bound to exactly one dds::topic::Topic and therefore to exactly one data type. The dds::topic::Topic must exist prior to the dds::pub::DataWriter's creation.

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

Several dds::pub::DataWriter may operate in different threads. If they share the same dds::pub::Publisher, the middleware guarantees that its operations are thread-safe.

See also
Operations Allowed in Listener Callbacks

Notes about DataWriter destruction

The deletion of the dds::pub::DataWriter will automatically unregister all instances.

The DataWriter destructor will not throw any exceptions even if the destruction fails. Calling close() will throw in case of failure

See also
DataWriter Use Cases
Entity Use Cases
Examples
Foo_publisher.cxx.

Constructor & Destructor Documentation

◆ DataWriter() [1/3]

template<typename T >
dds::pub::DataWriter< T >::DataWriter ( const dds::pub::Publisher pub,
const dds::topic::Topic< T > &  the_topic 
)
inline

Creates a DataWriter.

It uses the default DataWriterQos, and sets no listener.

Parameters
pubThe publisher that this DataWriter belongs to
the_topicThe Topic associated with this DataWriter
See also
DataWriter(const dds::pub::Publisher& pub,const dds::topic::Topic<T>& topic,const dds::pub::qos::DataWriterQos& qos,dds::pub::DataWriterListener<T>* listener,const dds::core::status::StatusMask& mask)

◆ DataWriter() [2/3]

template<typename T >
dds::pub::DataWriter< T >::DataWriter ( const dds::pub::Publisher pub,
const dds::topic::Topic< T > &  the_topic,
const dds::pub::qos::DataWriterQos the_qos,
dds::pub::DataWriterListener< T > *  the_listener = NULL,
const dds::core::status::StatusMask mask = dds::core::status::StatusMask::all() 
)
inline

Creates a DataWriter with QoS and listener.

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

When a DataWriter is created, only those transports already registered are available to the DataWriter. See Built-in Transport Plugins for details on when a builtin transport is registered.

Precondition
If publisher is enabled, topic must have been enabled. Otherwise, this operation will fail and no DataWriter will be created.
The given dds::topic::Topic must have been created from the same participant as this publisher. If it was created from a different participant, this method will fail.
Parameters
pubThe publisher that this DataWriter belongs to
the_topicThe Topic associated with this DataWriter
the_qosQoS to be used for creating the new Datawriter.
the_listenerThe DataWriter listener. The caller owns the listener and is responsible for deleting it only after resetting it or after deleting the DataWriter.
maskChanges of communication status to be invoked on the listener
See also
Specifying QoS on entities for information on setting QoS before entity creation
dds::pub::qos::DataWriterQos for rules on consistency among QoS
dds::core::QosProvider::datawriter_qos()
dds::pub::Publisher::default_datawriter_qos()
dds::pub::qos::DataWriterQos::operator=(const dds::topic::qos::TopicQos&) which allows assigning the contents of a TopicQos into a DataWriterQos
listener()

◆ DataWriter() [3/3]

template<typename T >
dds::pub::DataWriter< T >::DataWriter ( const dds::pub::Publisher pub,
const dds::topic::Topic< T > &  the_topic,
const dds::pub::qos::DataWriterQos the_qos,
std::shared_ptr< Listener the_listener,
const dds::core::status::StatusMask mask = dds::core::status::StatusMask::all() 
)
inline

Creates a DataWriter with QoS and listener.

When a DataWriter is created, only those transports already registered are available to the DataWriter. See Built-in Transport Plugins for details on when a builtin transport is registered.

Precondition
If publisher is enabled, topic must have been enabled. Otherwise, this operation will fail and no DataWriter will be created.
The given dds::topic::Topic must have been created from the same participant as this publisher. If it was created from a different participant, this method will fail.
Parameters
pubThe publisher that this DataWriter belongs to
the_topicThe Topic associated with this DataWriter
the_qosQoS to be used for creating the new Datawriter.
the_listenerA shared_ptr to the listener. See set_listener() for more information.
maskIndicates which status updates the listener will receive
See also
Specifying QoS on entities for information on setting QoS before entity creation
dds::pub::qos::DataWriterQos for rules on consistency among QoS
dds::core::QosProvider::datawriter_qos()
dds::pub::Publisher::default_datawriter_qos()
dds::pub::qos::DataWriterQos::operator=(const dds::topic::qos::TopicQos&) which allows assigning the contents of a TopicQos into a DataWriterQos
listener()

Member Function Documentation

◆ write() [1/11]

template<typename T >
void dds::pub::DataWriter< T >::write ( const T &  instance_data)
inline

Modifies the value of a data instance.

This operations does the same as write(const T&, const dds::core::InstanceHandle&) except that it deduces the identity of the instance from instance_data (by means of the key).

Parameters
instance_dataThe data sample to write.
See also
write(const T&, const dds::core::InstanceHandle&)
Examples
Foo_publisher.cxx.

◆ write() [2/11]

template<typename T >
void dds::pub::DataWriter< T >::write ( const T &  instance_data,
const dds::core::Time timestamp 
)
inline

Modifies the value of a data instance and specifies the timestamp.

See also
void write(const T&, const dds::core::InstanceHandle&, const dds::core::Time&)
Notes about DataWriter destruction

◆ write() [3/11]

template<typename T >
void dds::pub::DataWriter< T >::write ( const T &  instance_data,
const dds::core::InstanceHandle handle 
)
inline

Modifies the value of a data instance.

When this operation is used, RTI Connext will automatically supply the value of the source_timestamp that is made available to dds::sub::DataReader objects by means of the source_timestamp attribute inside the dds::sub::SampleInfo. (Refer to dds::sub::SampleInfo and DESTINATION_ORDER QoS policy for details).

As a side effect, this operation asserts liveliness on the dds::pub::DataWriter itself, the dds::pub::Publisher and the dds::domain::DomainParticipant.

Note that the special value dds::core::InstanceHandle::nil() can be used for the parameter handle. This indicates the identity of the instance should be automatically deduced from the instance_data (by means of the key).

If handle is any value other than dds::core::InstanceHandle::nil(), then it must correspond to an instance that has been registered. If there is no correspondence, the operation will fail with dds::core::InvalidArgumentError.

RTI Connext will not detect the error when the handle is any value other than dds::core::InstanceHandle::nil(), corresponds to an instance that has been registered, but does not correspond to the instance deduced from the instance_data (by means of the key). RTI Connext will treat as if the write() operation is for the instance as indicated by the handle.

This operation may block if the RELIABILITY kind is set to dds::core::policy::ReliabilityKind_def::RELIABLE and the modification would cause data to be lost or else cause one of the limits specified in the RESOURCE_LIMITS to be exceeded.

This operation will not block when using dds::core::policy::ReliabilityKind_def::BEST_EFFORT. If you are using BEST_EFFORT Reliability in combination with rti::core::policy::PublishModeKind_def::ASYNCHRONOUS, then instead of being blocked, samples that are queued to be sent by the asynchronous publishing thread will be overwritten when the number of DDS samples that are currently queued has reached the depth QoS value in the dds::core::policy::History.

If dds::core::policy::Reliability::max_blocking_time elapses before the dds::pub::DataWriter can store the modification without exceeding the limits, the operation will fail and return dds::core::TimeoutError for KEEP_ALL configurations.

Here is how the write operation behaves when dds::core::policy::HistoryKind::KEEP_LAST and dds::core::policy::ReliabilityKind_def::RELIABLE are used:

  • The send window size is determined by the rti::core::RtpsReliableWriterProtocol::max_send_window_size and rti::core::RtpsReliableWriterProtocol::min_send_window_size fields in the rti::core::policy::DataWriterProtocol. If a send window is specified (max_send_window_size is not UNLIMITED) and the window is full, the write operation will block until one of the samples in the send window is protocol-acknowledged (ACKed) (1) or until the dds::core::policy::Reliability::max_blocking_time expires.
  • Then, the dds::pub::DataWriter will try to add the new sample to the writer history.
  • If the instance associated with the sample is present in the writer history and there are depth (in the HISTORY) samples in the instance, the DataWriter will replace the oldest sample of that instance independently of that sample's acknowledged status, and the write operation will return . Otherwise, no sample will be replaced and the write operation will continue.
  • If the instance associated with the sample is not present in the writer history and dds::core::policy::ResourceLimits::max_instances is exceeded, the DataWriter will try to replace an existing instance (and its samples) according to the value of rti::core::policy::DataWriterResourceLimits::instance_replacement (see DataWriterResourceLimitsInstanceReplacementKind).

  • If dds::core::policy::ResourceLimits::max_samples is exceeded, the DataWriter will try to drop a sample from a different instance as follows:

    • The DataWriter will try first to remove a fully ACKed (2) sample from a different instance 'I' as long as that sample is not the last remaining sample for the instance 'I'. To find this sample, the DataWriter starts iterating from the oldest sample in the writer history to the newest sample.
    • If no such sample is found, the DataWriter will replace the oldest sample in the writer history.

  • The sample is added to the writer history, and the write operation returns .

Here is how the write operation behaves when dds::core::policy::HistoryKind::KEEP_ALL and dds::core::policy::ReliabilityKind_def::RELIABLE are used:

If there are no instance resources left, this operation may fail with dds::core::OutOfResourcesError. Calling dds::pub::DataWriter::unregister_instance may help freeing up some resources.

This operation will fail with dds::core::PreconditionNotMetError if the timestamp is less than the timestamp used in the last writer operation (register, unregister, dispose, or write, with either the automatically supplied timestamp or the application-provided timestamp).

If an instance obtained from dds::pub::DataWriter::get_loan is modified with this operation, then all instances modified thereafter should be from dds::pub::DataWriter::get_loan.

See rti::core::policy::AcknowledgmentKind_def for more information on the following notes:

(1) A sample in the writer history is considered "protocol ACKed" when the sample has been individually ACKed at the RTPS protocol level by each one of the DataReaders that matched the DataWriter at the moment the sample was added to the writer queue.

  • Late joiners do not change the protocol ACK state of a sample. If a sample is marked as protocol ACKed because it has been acknowledged by all the matching DataReaders and a DataReader joins later on, the historical sample is still considered protocol ACKed even if it has not been received by the late joiner.
  • If a sample 'S1' is protocol ACKed and a TopicQuery is received, triggering the publication of 'S1', the sample is still considered protocol ACKed. If a sample 'S1' is not ACKed and a TopicQuery is received triggering the publication of 'S1', the DataWriter will require that both the matching DataReaders on the live RTPS channel and the DataReader on the TopicQuery channel individually protocol ACK the sample in order to consider the sample protocol ACKed.

(2) A sample in the writer history is considered "fully ACKed" when all of the following conditions are met:

(3) It is possible within a single call to the write operation for a DataWriter to block both when the send window is full and then again when dds::core::policy::ResourceLimits::max_samples or dds::core::policy::ResourceLimits::max_samples_per_instance is exceeded. This can happen because blocking on the send window only considers protocol-ACKed samples, while blocking based on resource limits considers fully-ACKed samples. In any case, the total max blocking time of a single call to the write operation will not exceed dds::core::policy::Reliability::max_blocking_time.

Parameters
instance_data<<in>> The data to write.
Parameters
handle<<in>> Either the handle returned by a previous call to dds::pub::DataWriter::register_instance, or else the special value dds::core::InstanceHandle::nil(). If T has a key, handle must represent a registered instance of type T. Otherwise, this method may fail with dds::core::InvalidArgumentError.
Exceptions
Oneof the Standard Exceptions, dds::core::TimeoutError, dds::core::PreconditionNotMetError, dds::core::OutOfResourcesError, or dds::core::NotEnabledError.
MT Safety:
It is UNSAFE to modify instance_data before the operation has finished. The operation is otherwise SAFE.
See also
dds::sub::DataReader
dds::pub::DataWriter::write(const T&,const dds::core::Time&)
DESTINATION_ORDER

◆ write() [4/11]

template<typename T >
void dds::pub::DataWriter< T >::write ( const T &  instance_data,
const dds::core::InstanceHandle handle,
const dds::core::Time source_timestamp 
)
inline

Modifies the value of a data instance and specifies the timestamp.

Explicitly provides the timestamp that will be available to the dds::sub::DataReader objects by means of the source_timestamp attribute inside the dds::sub::SampleInfo. (Refer to dds::sub::SampleInfo and DESTINATION_ORDER QoS policy for details)

The constraints on the values of the handle parameter and the corresponding error behavior are the same specified for the dds::pub::DataWriter::write() operation.

This operation may block and time out (dds::core::TimeoutError) under the same circumtances described for dds::pub::DataWriter::write().

If there are no instance resources left, this operation may fail with dds::core::OutOfResourcesError. Calling dds::pub::DataWriter::unregister_instance may help free up some resources.

This operation may fail with dds::core::InvalidArgumentError under the same circumstances described for the write operation.

Parameters
instance_data<<in>> The data to write.
handle<<in>> Either the handle returned by a previous call to dds::pub::DataWriter::register_instance, or else the special value dds::core::InstanceHandle::nil(). If T has a key, handle must represent a registered instance of type T. Otherwise, this method may fail with dds::core::InvalidArgumentError.
source_timestamp<<in>> When using dds::core::policy::DestinationOrderKind::BY_SOURCE_TIMESTAMP the timestamp value must be greater than or equal to the timestamp value used in the last writer operation (register, unregister, dispose, or write, with either the automatically supplied timestamp or the application-provided timestamp) However, if it is less than the timestamp of the previous operation but the difference is less than the dds::core::policy::DestinationOrder::source_timestamp_tolerance, the timestamp of the previous operation will be used as the source timestamp of this sample. Otherwise, if the difference is greater than dds::core::policy::DestinationOrder::source_timestamp_tolerance, the function will return dds::core::InvalidArgumentError.
Exceptions
Oneof the Standard Exceptions, dds::core::TimeoutError, dds::core::OutOfResourcesError, or dds::core::NotEnabledError.
See also
dds::pub::DataWriter::write()
dds::sub::DataReader
DESTINATION_ORDER
Notes about DataWriter destruction

◆ write() [5/11]

template<typename T >
void dds::pub::DataWriter< T >::write ( const dds::topic::TopicInstance< T > &  topic_instance)
inline

Write a dds::topic::TopicInstance.

A TopicInstance encapsulates the sample and its associated instance handle.

Parameters
topic_instanceThe instance to write.
See also
write(const T&, const dds::core::InstanceHandle&)

◆ write() [6/11]

template<typename T >
void dds::pub::DataWriter< T >::write ( const dds::topic::TopicInstance< T > &  topic_instance,
const dds::core::Time timestamp 
)
inline

Write a topic instance with time stamp.

Parameters
topic_instancethe TopicInstance to write.
timestampthe timestamp for this sample.
See also
void write(const T&, const dds::core::InstanceHandle&, const dds::core::Time&)
Notes about DataWriter destruction

◆ write() [7/11]

template<typename T >
template<typename FWIterator >
void dds::pub::DataWriter< T >::write ( const FWIterator &  begin,
const FWIterator &  end 
)
inline

Write a series of samples or TopicInstances

Template Parameters
FWIteratorA forward iterator. Depending on its value type this function can write data samples or TopicInstance objects.
Parameters
beginThe beginning of the range
endThe end of the range
See also
write(const T&)
write(const dds::topic::TopicInstance<T>&)

◆ write() [8/11]

template<typename T >
template<typename FWIterator >
void dds::pub::DataWriter< T >::write ( const FWIterator &  begin,
const FWIterator &  end,
const dds::core::Time timestamp 
)
inline

Write a series of samples or TopicInstances with a given timestamp

Template Parameters
FWIteratorA forward iterator. Depending on its value type this function can write data samples or TopicInstance objects.
Parameters
beginThe beginning of the range
endThe end of the range
timestampThe timestamp to use for all samples in the range
See also
write(const T&, const dds::core::Time&)
write(const dds::topic::TopicInstance<T>&, const dds::core::Time&)
Notes about DataWriter destruction

◆ write() [9/11]

template<typename T >
template<typename SamplesFWIterator , typename HandlesFWIterator >
void dds::pub::DataWriter< T >::write ( const SamplesFWIterator &  data_begin,
const SamplesFWIterator &  data_end,
const HandlesFWIterator &  handle_begin,
const HandlesFWIterator &  handle_end 
)
inline

Write a series of samples and their parallel instance handles.

Template Parameters
SamplesFWIteratorSample forward iterator
HandlesFWIteratorInstanceHandle forward iterator
Parameters
data_beginThe beginning of the data sample range
data_endThe end of the data sample range
handle_beginThe beginning of the InstanceHandle range
handle_endThe end of the InstanceHandle range
See also
write(const T&, const dds::core::InstanceHandle&)

◆ write() [10/11]

template<typename T >
template<typename SamplesFWIterator , typename HandlesFWIterator >
void dds::pub::DataWriter< T >::write ( const SamplesFWIterator &  data_begin,
const SamplesFWIterator &  data_end,
const HandlesFWIterator &  handle_begin,
const HandlesFWIterator &  handle_end,
const dds::core::Time timestamp 
)
inline

Write a series of samples and their parallel instance handles and a timestamp.

See also
Notes about DataWriter destruction

◆ operator<<() [1/4]

template<typename T >
DataWriter & dds::pub::DataWriter< T >::operator<< ( const T &  data)
inline

Writes a sample.

See also
write(const T&)

◆ operator<<() [2/4]

template<typename T >
DataWriter & dds::pub::DataWriter< T >::operator<< ( const std::pair< T, dds::core::Time > &  data)
inline

◆ operator<<() [3/4]

template<typename T >
DataWriter & dds::pub::DataWriter< T >::operator<< ( const std::pair< T, dds::core::InstanceHandle > &  data)
inline

Writes a sample with an instance handle.

See also
write(const T&, const dds::core::InstanceHandle&)

◆ register_instance() [1/3]

template<typename T >
const dds::core::InstanceHandle dds::pub::DataWriter< T >::register_instance ( const T &  instance_data)
inline

Informs RTI Connext that the application will be modifying a particar instance.

This operation is only useful for keyed data types. Using it for non-keyed types causes no effect and returns dds::core::InstanceHandle::nil(). The operation takes as a parameter an instance (of which only the key value is examined) and returns a handle that can be used in successive write() or dispose_instance() operations.

The operation gives RTI Connext an opportunity to pre-configure itself to improve performance.

The use of this operation by an application is optional even for keyed types. If an instance has not been pre-registered, the application can call the write() or dipose_instance() overloads that don't receive a dds::core::InstanceHandle and RTI Connext will auto-register the instance.

For best performance, the operation should be invoked prior to calling any operation that modifies the instance, such as dds::pub::DataWriter::write(), dds::pub::DataWriter::write(const T&,const dds::core::Time&), dds::pub::DataWriter::dispose_instance() and dds::pub::DataWriter::dispose_instance(const dds::core::InstanceHandle&,const dds::core::Time&) and the handle used in conjunction with the data for those calls.

When this operation is used, RTI Connext will automatically supply the value of the source_timestamp that is used.

This operation may fail and return dds::core::InstanceHandle::nil() if dds::core::policy::ResourceLimits::max_instances limit has been exceeded.

The operation is idempotent. If it is called for an already registered instance, it just returns the already allocated handle. This may be used to lookup and retrieve the handle allocated to a given instance.

This operation can only be called after dds::pub::DataWriter has been enabled. Otherwise, dds::core::InstanceHandle::nil() will be returned.

Parameters
instance_data<<in>> The instance that should be registered. Of this instance, only the fields that represent the key are examined by the function.
Returns
For keyed data type, a handle that can be used in the calls that take a dds::core::InstanceHandle, such as write, dispose, unregister_instance, or return dds::core::InstanceHandle::nil() on failure. If the instance_data is of a data type that has no keys, this function always returns dds::core::InstanceHandle::nil().
See also
dds::pub::DataWriter::unregister_instance, dds::pub::DataWriter::key_value, Relationship between registration, liveliness and ownership

◆ register_instance() [2/3]

template<typename T >
const dds::core::InstanceHandle dds::pub::DataWriter< T >::register_instance ( const T &  instance_data,
const dds::core::Time source_timestamp 
)
inline

Informs RTI Connext that the application will be modifying a particular instance and specifies the timestamp.

The provided source_timestamp potentially affects the relative order in which readers observe events from multiple writers. Refer to DESTINATION_ORDER QoS policy for details.

This operation may fail and return dds::core::InstanceHandle::nil() if dds::core::policy::ResourceLimits::max_instances limit has been exceeded.

This operation can only be called after dds::pub::DataWriter has been enabled. Otherwise, dds::core::InstanceHandle::nil() will be returned.

Parameters
instance_data<<in>> The instance that should be registered. Of this instance, only the fields that represent the key are examined by the function.
source_timestamp<<in>> The timestamp value must be greater than or equal to the timestamp value used in the last writer operation (used in a register, unregister, dispose, or write, with either the automatically supplied timestamp or the application provided timestamp). This timestamp may potentially affect the order in which readers observe events from multiple writers.
Returns
For keyed data type, return a handle that can be used in the calls that take a dds::core::InstanceHandle, such as write, dispose, unregister_instance, or return dds::core::InstanceHandle::nil() on failure. If the instance_data is of a data type that has no keys, this function always return dds::core::InstanceHandle::nil().
See also
dds::pub::DataWriter::unregister_instance, dds::pub::DataWriter::key_value
Notes about DataWriter destruction

◆ unregister_instance() [1/3]

template<typename T >
DataWriter & dds::pub::DataWriter< T >::unregister_instance ( const dds::core::InstanceHandle handle)
inline

Unregister an instance.

This operation is useful only for keyed data types. Using it for non-keyed types causes no effect and reports no error.

This operation should only be called on an instance that is currently registered. This includes instances that have been auto-registered by calling operations such as write or dispose as described in dds::pub::DataWriter::register_instance. Otherwise, this operation may fail with dds::core::InvalidArgumentError.

This only need be called just once per instance, regardless of how many times register_instance was called for that instance.

When this operation is used, RTI Connext will automatically supply the value of the source_timestamp that is used.

This operation informs RTI Connext that the dds::pub::DataWriter is no longer going to provide any information about the instance. This operation also indicates that RTI Connext can locally remove all information regarding that instance. The application should not attempt to use the handle previously allocated to that instance after calling this function.

The parameter handle must correspond to an instance that has been registered. If there is no correspondence, the operation will fail with dds::core::InvalidArgumentError.

If, after a dds::pub::DataWriter::unregister_instance, the application wants to modify (dds::pub::DataWriter::write() or dds::pub::DataWriter::dispose_instance()) an instance, it has to register it again, or else use the functions that don't receive a dds::core::InstanceHandle.

This operation does not indicate that the instance is deleted (that is the purpose of dds::pub::DataWriter::dispose_instance()). The operation dds::pub::DataWriter::unregister_instance just indicates that the dds::pub::DataWriter no longer has anything to say about the instance. dds::sub::DataReader entities that are reading the instance may receive a sample with dds::sub::status::InstanceState::not_alive_no_writers() for the instance, unless there are other dds::pub::DataWriter objects writing that same instance.

dds::core::policy::WriterDataLifecycle::autodispose_unregistered_instances controls whether instances are automatically disposed when they are unregistered.

This operation can affect the ownership of the data instance (see OWNERSHIP). If the dds::pub::DataWriter was the exclusive owner of the instance, then calling unregister_instance() will relinquish that ownership.

If dds::core::policy::Reliability::kind is set to dds::core::policy::ReliabilityKind_def::RELIABLE and the unregistration would overflow the resource limits of this writer or of a reader, this operation may block for up to dds::core::policy::Reliability::max_blocking_time; if this writer is still unable to unregister after that period, this method will fail with dds::core::TimeoutError.

Parameters
handle<<in>> represents the instance to be unregistered. It must represent an instance that has been registered. Otherwise, this method may fail with dds::core::InvalidArgumentError.
Exceptions
Oneof the Standard Exceptions, dds::core::TimeoutError or dds::core::NotEnabledError
See also
dds::pub::DataWriter::register_instance
dds::pub::DataWriter::unregister_instance(const dds::core::InstanceHandle&,const dds::core::Time&)
dds::pub::DataWriter::key_value
Relationship between registration, liveliness and ownership

◆ unregister_instance() [2/3]

template<typename T >
DataWriter & dds::pub::DataWriter< T >::unregister_instance ( const dds::core::InstanceHandle handle,
const dds::core::Time source_timestamp 
)
inline

Unregister an instance with timestamp.

The provided source_timestamp potentially affects the relative order in which readers observe events from multiple writers. Refer to DESTINATION_ORDER QoS policy for details.

The constraints on the values of the handle parameter and the corresponding error behavior are the same specified for the dds::pub::DataWriter::unregister_instance operation.

This operation may block and may time out (dds::core::TimeoutError) under the same circumtances described for the unregister_instance operation.

Parameters
handle<<in>> represents the instance to be unregistered. It must represent an instance that has been registered. Otherwise, this method may fail with dds::core::InvalidArgumentError.
source_timestamp<<in>> The timestamp value must be greater than or equal to the timestamp value used in the last writer operation (used in a register, unregister, dispose, or write, with either the automatically supplied timestamp or the application provided timestamp). This timestamp may potentially affect the order in which readers observe events from multiple writers.
Exceptions
Oneof the Standard Exceptions, dds::core::TimeoutError or dds::core::NotEnabledError.
See also
dds::pub::DataWriter::register_instance
dds::pub::DataWriter::unregister_instance
dds::pub::DataWriter::key_value

◆ dispose_instance() [1/3]

template<typename T >
DataWriter & dds::pub::DataWriter< T >::dispose_instance ( const dds::core::InstanceHandle handle)
inline

Requests the middleware to delete the instance identified by the instance handle.

This operation is useful only for keyed data types. Using it for non-keyed types has no effect and reports no error.

When an instance is disposed, the dds::pub::DataWriter communicates this state change to dds::sub::DataReader objects by propagating a dispose sample. When the instance changes to a disposed state, you can see the state change on the DataReader by looking at dds::sub::status::DataState::instance_state() in dds::sub::SampleInfo::state(). Disposed instances have the value dds::sub::status::InstanceState::not_alive_disposed().

The resources allocated to dispose instances on the DataWriter are not removed by default. The removal of the resources allocated to a dispose instance on the DataWriter queue can be controlled by using the QoS dds::core::policy::WriterDataLifecycle::autopurge_disposed_instances_delay.

Likewise, on the DataReader, the removal of the resources associated with an instance in the dispose state can be controlled by using the QoS dds::core::policy::ReaderDataLifecycle::autopurge_disposed_instances_delay.

When this operation is used, RTI Connext will automatically supply the value of the source_timestamp that is made available to dds::sub::DataReader objects by means of the source_timestamp attribute inside the dds::sub::SampleInfo.

The constraints on the values of the handle parameter and the corresponding error behavior are the same specified for the dds::pub::DataWriter::unregister_instance operation.

This operation may block and time out (dds::core::TimeoutError) under the same circumstances described for dds::pub::DataWriter::write().

If there are no instance resources left, this operation may fail with dds::core::OutOfResourcesError. Calling dds::pub::DataWriter::unregister_instance may help free up some resources.

Parameters
handleThe handle returned by a previous call to register_instance() or lookup_instance(). If instance_handle doesn't correspond to an instance previously written or registered with this writer, this function fails with dds::core::InvalidArgumentError.
Exceptions
Oneof the Standard Exceptions, dds::core::TimeoutError, dds::core::OutOfResourcesError or dds::core::NotEnabledError.
See also
dds::pub::DataWriter::dispose_instance(const dds::core::InstanceHandle&,const dds::core::Time&)
Relationship between registration, liveliness and ownership

◆ dispose_instance() [2/3]

template<typename T >
DataWriter & dds::pub::DataWriter< T >::dispose_instance ( const dds::core::InstanceHandle the_instance_handle,
const dds::core::Time source_timestamp 
)
inline

Dispose an instance with a timestamp.

The constraints on the values of the handle parameter and the corresponding error behavior are the same specified for the dds::pub::DataWriter::dispose_instance() operation.

This operation may block and time out (dds::core::TimeoutError) under the same circumtances described for dds::pub::DataWriter::write().

If there are no instance resources left, this operation may fail with dds::core::OutOfResourcesError. Calling dds::pub::DataWriter::unregister_instance may help freeing up some resources.

Parameters
the_instance_handle<<in>> Either the handle returned by a previous call to dds::pub::DataWriter::register_instance, or else the special value dds::core::InstanceHandle::nil(). If T has a key, handle must represent a registered instance of type T. Otherwise, this method may fail with dds::core::InvalidArgumentError.
source_timestamp<<in>> The timestamp value must be greater than or equal to the timestamp value used in the last writer operation (used in a register, unregister, dispose, or write, with either the automatically supplied timestamp or the application provided timestamp). This timestamp may potentially affect the order in which readers observe events from multiple writers. This timestamp will be available to the dds::sub::DataReader objects by means of the source_timestamp attribute inside the dds::sub::SampleInfo.
Exceptions
Oneof the Standard Exceptions, dds::core::TimeoutError, dds::core::OutOfResourcesError or dds::core::NotEnabledError.
See also
dds::pub::DataWriter::dispose_instance()

◆ key_value() [1/2]

template<typename T >
T & dds::pub::DataWriter< T >::key_value ( T &  key_holder,
const dds::core::InstanceHandle handle 
)
inline

Retrieve the instance key that corresponds to an instance handle.

Useful for keyed data types.

The operation will only fill the fields that form the key inside the key_holder instance. If the type has no keys, this method has no effect and exits with no error.

For keyed data types, this operation may fail with dds::core::InvalidArgumentError if the handle does not correspond to an existing data-object known to the dds::pub::DataWriter.

Parameters
key_holder<<inout>> a user data type specific key holder, whose key fields are filled by this operation. If T has no key, this method has no effect.
Parameters
handle<<in>> the instance whose key is to be retrieved. If T has a key, handle must represent a registered instance of type T. Otherwise, this method will fail with dds::core::InvalidArgumentError. If T has a key and handle is dds::core::InstanceHandle::nil(), this method will fail with dds::core::InvalidArgumentError.
Exceptions
Oneof the Standard Exceptions or dds::core::NotEnabledError.
Returns
A reference to key_holder
See also
dds::sub::DataReader::key_value

◆ key_value() [2/2]

template<typename T >
dds::topic::TopicInstance< T > & dds::pub::DataWriter< T >::key_value ( dds::topic::TopicInstance< T > &  key_holder,
const dds::core::InstanceHandle handle 
)
inline

Retrieve the instance key that corresponds to an instance handle.

See also
key_value(T&, const dds::core::InstanceHandle&)

◆ lookup_instance()

template<typename T >
dds::core::InstanceHandle dds::pub::DataWriter< T >::lookup_instance ( const T &  key_holder)
inline

Retrieve the instance handle that corresponds to an instance key_holder.

Useful for keyed data types.

This operation takes as a parameter an instance and returns a handle that can be used in subsequent operations that accept an instance handle as an argument. The instance parameter is only used for the purpose of examining the fields that define the key. This operation does not register the instance in question. If the instance has not been previously registered, or if for any other reason RTI Connext is unable to provide an instance handle, RTI Connext will return the special value HANDLE_NIL.

Parameters
key_holder<<in>> a user data type specific key holder.
Returns
the instance handle associated with this instance. If T has no key, this method has no effect and returns dds::core::InstanceHandle::nil()

◆ qos() [1/2]

template<typename T >
const dds::pub::qos::DataWriterQos dds::pub::DataWriter< T >::qos ( ) const
inline

Gets the DataWriterQos.

◆ qos() [2/2]

template<typename T >
void dds::pub::DataWriter< T >::qos ( const dds::pub::qos::DataWriterQos the_qos)
inline

Sets the DataWriterQos.

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

The dds::core::policy::UserData, dds::core::policy::Deadline, dds::core::policy::LatencyBudget, dds::core::policy::OwnershipStrength, dds::core::policy::TransportPriority, dds::core::policy::Lifespan and dds::core::policy::WriterDataLifecycle can be changed. The other policies are immutable.

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

◆ operator<<() [4/4]

template<typename T >
DataWriter & dds::pub::DataWriter< T >::operator<< ( const dds::pub::qos::DataWriterQos the_qos)
inline

Set the DataWriterQos.

Parameters
the_qosthe new qos for this DataWriter.
See also
qos()

◆ operator>>()

template<typename T >
const DataWriter & dds::pub::DataWriter< T >::operator>> ( dds::pub::qos::DataWriterQos the_qos) const
inline

Get the DataWriterQos.

Parameters
the_qosthe object to populate with the qos for this DataWriter.
See also
qos()

◆ topic()

template<typename T >
const dds::topic::Topic< T > & dds::pub::DataWriter< T >::topic ( ) const
inline

Get the Topic associated with this DataWriter.

◆ publisher()

template<typename T >
const dds::pub::Publisher & dds::pub::DataWriter< T >::publisher ( ) const
inline

Get the Publisher that owns this DataWriter.

◆ wait_for_acknowledgments()

template<typename T >
void dds::pub::DataWriter< T >::wait_for_acknowledgments ( const dds::core::Duration max_wait)
inline

Blocks the calling thread until all data written by reliable DataWriter entity is acknowledged, or until timeout expires.

This operation blocks the calling thread until either all data written by the reliable dds::pub::DataWriter entity 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 by all reliable matched data readers and by all required subscriptions; a timeout indicates that max_wait elapsed before all the data was acknowledged.

Note that if a thread is blocked in the call to wait_for_acknowledgments on a DataWriter and a different thread writes new samples on the same DataWriter, the new samples must be acknowledged before unblocking the thread waiting on wait_for_acknowledgments.

If the dds::pub::DataWriter does not have dds::core::policy::Reliability kind set to RELIABLE, this operation will complete immediately with

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

◆ listener() [1/2]

template<typename T >
void dds::pub::DataWriter< T >::listener ( DataWriterListener< T > *  l,
const dds::core::status::StatusMask mask 
)
inline

Sets the DataWriter 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.

Parameters
lThe DataWriterListener to set
maskThe dds::core::status::StatusMask associated with the listener

◆ listener() [2/2]

template<typename T >
DataWriterListener< T > * dds::pub::DataWriter< T >::listener ( ) const
inline

Returns the listener currently associated with this DataWriter.

[DEPRECATED] Prefer get_listener() instead of this function.

If there's no listener it returns NULL.

◆ set_listener() [1/2]

template<typename T >
void dds::pub::DataWriter< T >::set_listener ( std::shared_ptr< Listener the_listener,
const dds::core::status::StatusMask event_mask 
)
inline

Sets the listener associated with this writer.

The writer will hold a shared_ptr to the listener argument, ensuring that it is not deleted at least until this writer 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 writer. If it does, the application needs to manually reset the listener or manually close this writer 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]

template<typename T >
void dds::pub::DataWriter< T >::set_listener ( std::shared_ptr< Listener the_listener)
inline

Sets the listener associated with this writer.

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

writer.set_listener(the_listener, dds::core::status::StatusMask::all());
static const StatusMask all()
All the bits are set.
Definition: State.hpp:168

If the_listener is nullptr, it is equivalent to:

writer.set_listener(nullptr, dds::core::status::StatusMask::none());
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()

template<typename T >
std::shared_ptr< Listener > dds::pub::DataWriter< T >::get_listener ( ) const
inline

Returns the listener currently associated with this writer.

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

◆ liveliness_lost_status()

template<typename T >
const dds::core::status::LivelinessLostStatus dds::pub::DataWriter< T >::liveliness_lost_status ( )
inline

Get the LivelinessLostStatus.

This also resets the status so that it is no longer considered changed.

Exceptions
Oneof the Standard Exceptions

◆ offered_deadline_missed_status()

template<typename T >
const dds::core::status::OfferedDeadlineMissedStatus dds::pub::DataWriter< T >::offered_deadline_missed_status ( )
inline

Get the OfferedDeadlineMissedStatus.

This also resets the status so that it is no longer considered changed.

Exceptions
Oneof the Standard Exceptions

◆ offered_incompatible_qos_status()

template<typename T >
const dds::core::status::OfferedIncompatibleQosStatus dds::pub::DataWriter< T >::offered_incompatible_qos_status ( )
inline

Get the OfferedIncompatibleQosStatus.

This also resets the status so that it is no longer considered changed.

Exceptions
Oneof the Standard Exceptions

◆ publication_matched_status()

template<typename T >
const dds::core::status::PublicationMatchedStatus dds::pub::DataWriter< T >::publication_matched_status ( )
inline

Get the PublicationMatchedStatus.

This also resets the status so that it is no longer considered changed.

Exceptions
Oneof the Standard Exceptions

◆ assert_liveliness()

template<typename T >
void dds::pub::DataWriter< T >::assert_liveliness ( )
inline

Manually asserts the liveliness of this DataWriter.

This is used in combination with the LIVELINESS policy to indicate to RTI Connext that the dds::pub::DataWriter remains active.

You only need to use this operation if the LIVELINESS setting is either dds::core::policy::LivelinessKind::MANUAL_BY_PARTICIPANT or dds::core::policy::LivelinessKind::MANUAL_BY_TOPIC. Otherwise, it has no effect.

Note: writing data via the dds::pub::DataWriter::write() or dds::pub::DataWriter::write(const T&,const dds::core::Time&) operation asserts liveliness on the dds::pub::DataWriter itself, and its dds::domain::DomainParticipant. Consequently the use of assert_liveliness() is only needed if the application is not writing data regularly.

Exceptions
Oneof the Standard Exceptions or dds::core::NotEnabledError
See also
dds::core::policy::Liveliness

◆ unregister_instance() [3/3]

template<typename T >
void unregister_instance ( rti::pub::WriteParams params)

<<extension>> Unregister an instance with parameters

Note
This function is an extension, it must be called via the extensions() member function
See also
dds::pub::DataWriter::write(const T&,rti::pub::WriteParams&)
dds::pub::DataWriter::dispose_instance(rti::pub::WriteParams&)

◆ dispose_instance() [3/3]

template<typename T >
void dispose_instance ( rti::pub::WriteParams params)

<<extension>> Dispose an instance with parameters

Note
This function is an extension, it must be called via the extensions() member function
See also
dds::pub::DataWriter::write(const T&,rti::pub::WriteParams&)

◆ is_sample_app_acknowledged()

template<typename T >
bool is_sample_app_acknowledged ( const rti::core::SampleIdentity sample_id)

<<extension>> Indicates if a sample is considered application-acknowledged

Note
This function is an extension, it must be called via the extensions() member function

This method can be used to see if a sample has been application acknowledged by all the matching DataReaders that were alive when the sample was written.

If a DataReader does not enable application acknowledgment (by setting dds::core::policy::Reliability::acknowledgment_kind to a value other than rti::core::policy::AcknowledgmentKind_def::PROTOCOL), the sample is considered application acknowledged for that DataReader.

Parameters
sample_id<<in>> Sample identity.
Returns
true when the sample has been application acknowledged. Otherwise, false.
Exceptions
Oneof the Standard Exceptions

◆ wait_for_asynchronous_publishing()

template<typename T >
void wait_for_asynchronous_publishing ( const dds::core::Duration max_wait)

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

Note
This function is an extension, it must be called via the extensions() member function

This operation blocks the calling thread (up to max_wait) until all data written by the asynchronous dds::pub::DataWriter 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; a time out 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::DataWriter::wait_for_acknowledgments provides.

If the dds::pub::DataWriter does not have rti::core::policy::PublishMode kind set to rti::core::policy::PublishModeKind_def::ASYNCHRONOUS the operation will complete immediately with .

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

◆ reliable_writer_cache_changed_status()

template<typename T >
rti::core::status::ReliableWriterCacheChangedStatus reliable_writer_cache_changed_status ( )

<<extension>> Get the reliable cache status for this writer.

Note
This function is an extension, it must be called via the extensions() member function

This also resets the status so that it is no longer considered changed.

Exceptions
Oneof the Standard Exceptions

◆ reliable_reader_activity_changed_status()

template<typename T >
rti::core::status::ReliableReaderActivityChangedStatus reliable_reader_activity_changed_status ( )

<<extension>> Get the reliable reader activity changed status for this writer

Note
This function is an extension, it must be called via the extensions() member function

This also resets the status so that it is no longer considered changed.

Exceptions
Oneof the Standard Exceptions

◆ datawriter_cache_status()

template<typename T >
rti::core::status::DataWriterCacheStatus datawriter_cache_status ( )

<<extension>> Get the cache status for this writer

Note
This function is an extension, it must be called via the extensions() member function

This also resets the status so that it is no longer considered changed.

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

◆ datawriter_protocol_status()

template<typename T >
rti::core::status::DataWriterProtocolStatus datawriter_protocol_status ( )

<<extension>> Get the protocol status for this writer

Note
This function is an extension, it must be called via the extensions() member function

This also resets the status so that it is no longer considered changed.

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

◆ matched_subscription_datawriter_protocol_status() [1/2]

template<typename T >
rti::core::status::DataWriterProtocolStatus matched_subscription_datawriter_protocol_status ( const dds::core::InstanceHandle subscription_handle)

<<extension>> Get the datawriter protocol status for this writer, per matched subscription identified by the subscription_handle.

Note
This function is an extension, it must be called via the extensions() member function

This also resets the status so that it is no longer considered changed.

Note: Status for a remote entity is only kept while the entity is alive. Once a remote entity is no longer alive, its status is deleted.

Parameters
subscription_handle<<in>> Handle to a specific subscription associated with the dds::sub::DataReader. Must correspond to a subscription currently associated with the dds::pub::DataWriter.
Exceptions
Oneof the Standard Exceptions or dds::core::NotEnabledError.

◆ matched_subscription_datawriter_protocol_status() [2/2]

template<typename T >
rti::core::status::DataWriterProtocolStatus matched_subscription_datawriter_protocol_status ( const rti::core::Locator subscription_locator)

<<extension>> Get the datawriter protocol status for this writer, per matched subscription identified by the locator

Note
This function is an extension, it must be called via the extensions() member function

This also resets the status so that it is no longer considered changed.

Note: Status for a remote entity is only kept while the entity is alive. Once a remote entity is no longer alive, its status is deleted.

Exceptions
Oneof the Standard Exceptions or dds::core::NotEnabledError.
Parameters
subscription_locator<<in>> Locator to a specific locator associated with the DataReader. Must correspond to a locator of one or more subscriptions currently associated with the DataWriter.

◆ service_request_accepted_status()

template<typename T >
rti::core::status::ServiceRequestAcceptedStatus service_request_accepted_status ( )

<<extension>> Get the service request accepted status for this writer

Note
This function is an extension, it must be called via the extensions() member function

This also resets the status so that it is no longer considered changed.

Note: Status for a remote entity is only kept while the entity is alive. Once a remote entity is no longer alive, its status is deleted.

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

◆ flush()

template<typename T >
void flush ( )

<<extension>> Flushes the batch in progress in the context of the calling thread.

Note
This function is an extension, it must be called via the extensions() member function

After being flushed, the batch is available to be sent on the network.

If the dds::pub::DataWriter does not have rti::core::policy::PublishMode kind set to rti::core::policy::PublishModeKind_def::ASYNCHRONOUS, the batch will be sent on the network immediately (in the context of the calling thread).

If the dds::pub::DataWriter does have rti::core::policy::PublishMode kind set to rti::core::policy::PublishModeKind_def::ASYNCHRONOUS, the batch will be sent in the context of the asynchronous publishing thread.

This operation may block in the same conditions as dds::pub::DataWriter::write().

If this operation does block, the RELIABILITY max_blocking_time configures the maximum time the write operation may block (waiting for space to become available). If max_blocking_time elapses before the DDS_DataWriter is able to store the modification without exceeding the limits, the operation will fail with DDS_RETCODE_TIMEOUT.

MT Safety:
flush() is only thread-safe with batching if rti::core::policy::Batch::thread_safe_write is TRUE.
Exceptions
Oneof the Standard Exceptions, dds::core::TimeoutError, dds::core::OutOfResourcesError or dds::core::NotEnabledError.

◆ write() [11/11]

template<typename T >
void write ( const T &  instance_data,
rti::pub::WriteParams params 
)

<<extension>> Write with advanced parameters

Note
This function is an extension, it must be called via the extensions() member function

Allows provision of the sample identity, related sample identity, source timestamp, instance handle, and publication priority contained in params.

This operation may block and time out (dds::core::TimeoutError) under the same circumstances described for dds::pub::DataWriter::write().

If there are no instance resources left, this operation may fail with dds::core::OutOfResourcesError. Calling dds::pub::DataWriter::unregister_instance(rti::pub::WriteParams&) may help free up some resources.

This operation may fail with dds::core::InvalidArgumentError under the same circumstances described for the dds::pub::DataWriter::write().

Parameters
instance_data<<in>> The data to write.
params<<inout>> The write parameters. Note that this is an inout parameter if you activate rti::pub::WriteParams::replace_automatic_values; otherwise it won't be modified.
Exceptions
Oneof the Standard Exceptions, dds::core::TimeoutError, dds::core::OutOfResourcesError or dds::core::NotEnabledError.
See also
dds::pub::DataWriter::write()
dds::sub::DataReader

◆ write_noexcept() [1/5]

template<typename T >
rti::core::Result< void > write_noexcept ( const T &  sample)
noexcept

<<extension>> Alternative to write() that doesn't throw exceptions.

This operation behaves exactly like write(const T&) but is guaranteed to not throw exceptions.

As an extension function, it must be accessed with the extensions() method or with the -> operator. Since extensions() can throw if the object is not a valid reference, the -> operator is recommended.

Example:

auto result = writer->write_noexcept(sample);
if (!result.is_ok()) {
if (result.get_return_code() == DDS_RETCODE_TIMEOUT) {
// Handle timeout
}
// ...
}
Returns
The Result of the operation.

◆ write_noexcept() [2/5]

template<typename T >
rti::core::Result< void > write_noexcept ( const T &  sample,
const dds::core::Time timestamp 
)
noexcept

<<extension>> Alternative to write() that doesn't throw exceptions.

This operation behaves exactly like write(const T&, const dds::core::Time&) but is guaranteed to not throw exceptions.

As an extension function, it must be accessed with the extensions() method or with the -> operator. Since extensions() can throw if the object is not a valid reference, the -> operator is recommended.

Returns
The Result of the operation.

◆ write_noexcept() [3/5]

template<typename T >
rti::core::Result< void > write_noexcept ( const T &  sample,
const dds::core::InstanceHandle instance 
)
noexcept

<<extension>> Alternative to write() that doesn't throw exceptions.

This operation behaves exactly like write(const T&, const dds::core::InstanceHandle&) but is guaranteed to not throw exceptions.

As an extension function, it must be accessed with the extensions() method or with the -> operator. Since extensions() can throw if the object is not a valid reference, the -> operator is recommended.

Returns
The Result of the operation.

◆ write_noexcept() [4/5]

template<typename T >
rti::core::Result< void > write_noexcept ( const T &  sample,
const dds::core::InstanceHandle instance,
const dds::core::Time timestamp 
)
noexcept

<<extension>> Alternative to write() that doesn't throw exceptions.

This operation behaves exactly like write(const T&, const dds::core::InstanceHandle&, const dds::core::Time&) but is guaranteed to not throw exceptions.

As an extension function, it must be accessed with the extensions() method or with the -> operator. Since extensions() can throw if the object is not a valid reference, the -> operator is recommended.

Returns
The Result of the operation.

◆ write_noexcept() [5/5]

template<typename T >
rti::core::Result< void > write_noexcept ( const T &  instance_data,
rti::pub::WriteParams params 
)
noexcept

<<extension>> Alternative to write() that doesn't throw exceptions.

This operation behaves exactly like write(const T&, rti::pub::WriteParams&) but is guaranteed to not throw exceptions.

As an extension function, it must be accessed with the extensions() method or with the -> operator. Since extensions() can throw if the object is not a valid reference, the -> operator is recommended.

Returns
The Result of the operation.

◆ create_data()

template<typename T >
T * create_data ( )

<<extension>> Create data from this writer and initialize it

Note
This function is an extension, it must be called via the extensions() member function
Returns
Newly created data type
Exceptions
Oneof the Standard Exceptions
See also
dds::pub::DataWriter::delete_data

◆ delete_data()

template<typename T >
bool delete_data ( T *  sample)

<<extension>> Delete data created with create_data().

Note
This function is an extension, it must be called via the extensions() member function

The behavior of this API is identical to FooTypeSupport::delete_data.

Parameters
sample<<in>> Cannot be NULL.
Returns
true on success.
See also
dds::pub::DataWriter::create_data

◆ get_loan()

template<typename T >
T * get_loan ( )

<<extension>> Get a loaned sample from this writer

Note
This function is an extension, it must be called via the extensions() member function

This operation is supported while using Zero Copy transfer over shared memory" or \ref RTIFlatDataModule "FlatData language binding". For FlatData types, this function should be used directly if the type is final; if the type is mutable, rti::flat::build_data() should be used to obtain a sample builder to work with the loaned sample.

The loaned sample is obtained from a DataWriter-managed sample pool and is uninitialized by default. An initialized sample can be obtained by setting rti::core::policy::DataWriterResourceLimits::initialize_writer_loaned_sample to true. The rti::core::policy::DataWriterResourceLimits::writer_loaned_sample_allocation settings can be used to configure the DataWriter-managed sample pool.

dds::pub::DataWriter::get_loan fails with dds::core::OutOfResourcesError if rti::core::AllocationSettings::max_count samples have been loaned, and none of those samples has been written with dds::pub::DataWriter::write() or discarded via dds::pub::DataWriter::discard_loan.

Samples returned from dds::pub::DataWriter::get_loan have an associated state. Due to the optimized nature of the write operation while using Zero Copy transfer over shared memory or FlatData language binding, this sample state is used to control when a sample is available for reuse after the write operation. The possible sample states are free, allocated, removed or serialized. A sample that has never been allocated is "free". dds::pub::DataWriter::get_loan takes a "free" or "removed" sample and makes it "allocated". When a sample is written, its state transitions from "allocated" to "serialized", and the DataWriter takes responsibility for returning the sample back to its sample pool. The sample remains in the "serialized" state until it is removed from the DataWriter queue. For a reliable DataWriter, the sample is removed from the DataWriter's queue when the sample is acknowledged by all DataReaders. For a best-effort DataWriter, the sample is removed from the queue immediately after the write operation. After the sample is removed from the DataWriter queue, the sample is put back into the sample pool, and its state transitions from "serialized" to "removed". At this time, a new call to dds::pub::DataWriter::get_loan may return the same sample.

A loaned sample should not be reused to write a new value after the first write operation. Instead, a new sample from dds::pub::DataWriter::get_loan should be used to write the new value. A loaned sample that has not been written can be returned to the DataWriter's sample pool by using dds::pub::DataWriter::discard_loan. If the write operation fails, then the sample can be used again with a write or discard_loan operation. Disposing or unregistering an instance with loaned samples follows the same pattern. A loaned sample used successfully with a dispose or unregister operation cannot be used again. But if the dispose or unregister operation fails, the sample is available for reuse.

A DataWriter cannot write managed samples (created with get_loan) and unmanaged samples (created in any other way) at the same time. The first call to get_loan automatically prepares this DataWriter to work with managed samples. Calls to get_loan will fail with dds::core::PreconditionNotMetError if an unmanaged sample was written with this DataWriter earlier. Similarly, dds::pub::DataWriter::write() will fail to write an unmanaged sample if get_loan was called.

Returns
a loaned sample
Exceptions
Oneof the Standard Exceptions, dds::core::OutOfResourcesError or dds::core::PreconditionNotMetError.
See also
dds::pub::DataWriter::discard_loan

Referenced by rti::flat::build_data().

◆ discard_loan()

template<typename T >
void discard_loan ( T &  sample)

<<extension>> Discard a loaned sample from this writer

Note
This function is an extension, it must be called via the extensions() member function

This operation is supported while using Zero Copy transfer over shared memory" or the FlatData language binding.

A loaned sample that hasn't been written can be returned to the DataWriter with this operation.

Parameters
sample<<in>> loaned sample to be discarded.
Exceptions
Oneof the Standard Exceptions or dds::core::NotEnabledError.
See also
dds::pub::DataWriter::get_loan

Referenced by rti::flat::discard_builder().

◆ register_instance() [3/3]

template<typename T >
const dds::core::InstanceHandle register_instance ( const T &  key,
rti::pub::WriteParams params 
)

<<extension>> Registers and instance with parameters

Note
This function is an extension, it must be called via the extensions() member function
See also
dds::pub::DataWriter::write(const T&,rti::pub::WriteParams&)

Friends And Related Function Documentation

◆ ignore() [1/2]

template<typename T >
void ignore ( dds::domain::DomainParticipant participant,
const dds::core::InstanceHandle handle 
)
related

Instructs RTI Connext to locally ignore a publication.

A publication is defined by the association of a topic name, user data, and partition set on the dds::pub::Publisher (see dds::topic::PublicationBuiltinTopicData). After this call, any data written by that publication's dds::pub::DataWriter will be ignored.

This operation can be used to ignore local and remote DataWriters.

The publication (DataWriter) to ignore is identified by the handle argument.

There is no way to reverse this operation.

Parameters
participantThe DomainParticipant where the publication will be ignored
handle<<in>> Handle of the dds::pub::DataWriter to be ignored.
Exceptions
Oneof the Standard Exceptions, dds::core::OutOfResourcesError or dds::core::NotEnabledError
See also
dds::topic::PublicationBuiltinTopicData
dds::topic::publication_topic_name()
dds::sub::builtin_subscriber

◆ ignore() [2/2]

template<typename FwdIterator >
void ignore ( dds::domain::DomainParticipant participant,
FwdIterator  begin,
FwdIterator  end 
)
related

Instructs RTI Connext to locally ignore several publications.

Template Parameters
FwdIteratorA forward iterator whose value type is dds::core::InstanceHandle
See also
ignore(dds::domain::DomainParticipant&, const dds::core::InstanceHandle&);

References dds::pub::ignore().

◆ matched_subscriptions() [1/2]

template<typename T >
dds::core::InstanceHandleSeq matched_subscriptions ( const dds::pub::DataWriter< T > &  writer)
related

Retrieve the list of subscriptions currently associated with a dds::pub::DataWriter.

A subscription is considered to be matching if all of the following criteria are true:

  • The subscription is within the same domain as this publication.
  • The subscription has a matching dds::topic::Topic.
  • The subscription has compatible QoS.
  • If the applications are using partitions, the subscription shares a common partition with this publication.
  • The dds::domain::DomainParticipant has not indicated that the subscription's dds::domain::DomainParticipant should be "ignored" by means of the dds::pub::ignore API.
  • If the publication is using the rti::core::policy::MultiChannel and the subscription is using a dds::topic::ContentFilteredTopic, there is an intersection between at least one of the associated filters.
  • If the endpoints need to exchange key material to communicate (i.e., they are securing their communications), the writer has completed the key exchange with reader.

The handles returned list are the ones that RTI Connext uses to locally identify the corresponding matched dds::sub::DataReader entities. These handles match the ones that appear in the dds::sub::SampleInfo::instance_handle field of the dds::sub::SampleInfo when reading the dds::topic::subscription_topic_name() builtin topic.

This API may return the subscription handles of subscriptions that are inactive. dds::pub::DataWriter::is_matched_subscription_active can be used to check this.

The maximum number of matches possible is configured with rti::core::policy::DomainParticipantResourceLimits. .

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

◆ matched_subscriptions() [2/2]

template<typename T , typename FwdIterator >
FwdIterator matched_subscriptions ( const dds::pub::DataWriter< T > &  writer,
FwdIterator  begin,
FwdIterator  end 
)
related

Retrieve the list of subscriptions currently associated with a dds::pub::DataWriter.

This operation is similar to matched_subscriptions(const dds::pub::DataWriter<T>&) but it copies the instance handles into an iterator range.

Template Parameters
FwdIteratorA forward iterator whose value type is dds::core::InstanceHandle

References dds::pub::matched_subscriptions().

◆ matched_subscription_data() [1/2]

template<typename T >
const dds::topic::SubscriptionBuiltinTopicData matched_subscription_data ( const dds::pub::DataWriter< T > &  writer,
const dds::core::InstanceHandle subscription_handle 
)
related

Retrieves information on a subscription that is currently associated with a dds::pub::DataWriter.

The subscription_handle must correspond to a subscription currently associated with the dds::pub::DataWriter. Otherwise, the operation will fail and fail with dds::core::InvalidArgumentError. Use dds::pub::matched_subscriptions() to find the subscriptions that are currently matched with the dds::pub::DataWriter.

The above information is also available through dds::sub::DataReaderListener::on_data_available() (if a reader listener is installed on the dds::sub::DataReader<dds::topic::SubscriptionBuiltinTopicData>).

When the subscription data is updated, for example when the content filter property changes, there is a small window of time in between when the DataWriter is made aware of these changes and when they actually take effect. Taking effect in this example means that the DataWriter will perform writer-side filtering using the new filter property values (filter expression and/or parameters).

When the DataWriter is made aware of the changes they will first be seen in the dds::sub::DataReaderListener::on_data_available() of the dds::sub::DataReader<dds::topic::SubscriptionBuiltinTopicData>. When these changes are applied, they will be seen in the output of this API because this API blocks until the most recent changes known to the DataWriter have taken effect. This API will only block when called outside of a listener callback, in order to not block the internal threads from making progress.

If application behavior depends on being made aware of information about a subscription only after it has taken effect on the DataWriter, the recommended pattern for usage of this API is to wait for subscription data to be received either through polling this API or by installing a listener on the dds::sub::DataReader<dds::topic::SubscriptionBuiltinTopicData>. When a new sample is received by the builtin DataReader, this API may be called in a separate thread and will return the expected matched subscription data once it has been applied to the DataWriter.

Because this API blocks, it is possible for this API to time out while waiting for the changes to be applied. A timeout may happen if the DataReader's subscription data is changing rapidly, preventing the DataWriter from returning valid information before newer data has been received, or if an application is performing a task in a listener callback, thereby preventing the middleware's threads from executing events in a timely manner.

Note: This operation does not retrieve the dds::topic::SubscriptionBuiltinTopicData::type. This information is available through dds::sub::DataReaderListener::on_data_available() (if a reader listener is installed on the dds::sub::DataReader<dds::topic::SubscriptionBuiltinTopicData>).

Parameters
writerThe DataWriter to which the subscription is associated
subscription_handle<<in>>. Handle to a specific subscription associated with the dds::sub::DataReader. Must correspond to a subscription currently associated with the dds::pub::DataWriter.
Exceptions
Oneof the Standard Exceptions, dds::core::NotEnabledError, or dds::core::TimeoutError

◆ matched_subscription_participant_data()

template<typename T >
dds::topic::ParticipantBuiltinTopicData matched_subscription_participant_data ( const dds::pub::DataWriter< T > &  writer,
const dds::core::InstanceHandle handle 
)
related

<<extension>> This operation retrieves the information on the discovered dds::domain::DomainParticipant associated with the subscription that is currently matching with the dds::pub::DataWriter.

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

The subscription_handle must correspond to a subscription currently associated with the dds::pub::DataWriter. Otherwise, the operation will fail with dds::core::InvalidArgumentError. The operation may also fail with dds::core::PreconditionNotMetError if the subscription corresponds to the same dds::domain::DomainParticipant that the DataWriter belongs to. Use dds::pub::matched_subscriptions() to find the subscriptions that are currently matched with the dds::pub::DataWriter.

Exceptions
Oneof the Standard Exceptions, or dds::core::NotEnabledError
Template Parameters
TThe topic-type that the DataWriter subscribes to
Parameters
writerThe writer to lookup the matched participant data of
handleThe InstanceHandle to a specific subscription. Must correspond to a subscription currently associated with the DataWriter.
Returns
The dds::topic::ParticipantBuiltinTopicData of the DomainParticipant of a matched subscription of a dds::pub::DataWriter

◆ matched_subscriptions_locators()

template<typename T >
rti::core::LocatorSeq matched_subscriptions_locators ( const dds::pub::DataWriter< T > &  writer)
related

<<extension>> Retrieve the list of locators for subscriptions currently associated with this DataWriter.

The locators returned are the ones that are used by the DDS implementation to communicate with the corresponding matched DataReaders.

Template Parameters
TThe topic-type that the DataWriter publishes.
Parameters
writerThe DataWriter.
Returns
The list of locators

◆ is_matched_subscription_active()

template<typename T >
bool is_matched_subscription_active ( const dds::pub::DataWriter< T > &  writer,
const dds::core::InstanceHandle handle 
)
related

<<extension>> Check if a matched subscription is active.

Note
This is a standalone function in the namespace rti::pub
Template Parameters
TThe topic-type that the DataWriter publishes.
Parameters
writerThe DataWriter.
handleThe dds::core::InstanceHandle of the matched subscription.

This API is used for querying the endpoint liveliness of a matched subscription. A matched subscription will be marked as inactive when it becomes nonprogessing (e.g., not responding to a DataWriter's heartbeats, or letting its internal queue fill up without taking the available data). Note that if the participant associated with the matched subscription loses liveliness, the dds::core::InstanceHandle will become invalid and this function will fail with dds::core::InvalidArgumentError.

Returns
A boolean indicating whether or not the matched subscription is active.

◆ matched_subscription_data() [2/2]

template<typename T >
std::vector< dds::topic::SubscriptionBuiltinTopicData > matched_subscription_data ( const dds::pub::DataWriter< T > &  writer)
related

<<extension>> Obtain the SubscriptionBuiltinTopicData for all of the subscriptions matched with a DataWriter.

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

This API retrieves the matched publication data from all of the subscriptions currently matched a DataWriter.

Template Parameters
TThe topic-type that the DataWriter publishes.
Parameters
writerThe DataWriter.
Returns
A std::vector containing all of the matched subscription data.

◆ find() [1/2]

template<typename Writer , typename FwdIterator >
uint32_t find ( const dds::pub::Publisher publisher,
const std::string &  topic_name,
FwdIterator  begin,
uint32_t  max_size 
)
related

Retrieves the dds::pub::DataWriter for a specific topic name.

This returned dds::pub::DataWriter is either enabled or disabled.

If more than one dds::pub::DataWriter is attached to the dds::pub::Publisher with the same topic_name, then this operation may return any one of them.

MT Safety:
UNSAFE. It is not safe to lookup a dds::pub::DataWriter in one thread while another thread is simultaneously creating or destroying that dds::pub::DataWriter.

This function retrieves a previously-created DataWriter belonging to the dds::pub::Publisher that is attached to a dds::topic::Topic with a matching topic name. If no such DataWriter exists, the operation will return an empty container. The use of this operation on the built-in Publisher allows access to the built-in DataWriter entities for the built-in topics

Template Parameters
WriterThe type of the writer. It can be dds::pub::AnyDataWriter, or an instantiation of dds::pub::DataWriter<T> (if T is not the correct type, this function throws dds::core::InvalidDowncastError)
FwdIteratorThe type of forward iterator passed to this function
Parameters
publisherThe dds::pub::Publisher the DataWriter belongs to
topic_nameName of the dds::topic::Topic associated with the DataWriter that is to be looked up.
beginA forward iterator to the position in the destination container to insert the found DataWriter in
max_sizeOnly 1 DataWriter will be returned from this function
Returns
The number of DataWriters that were found (either 0 or 1)

◆ find() [2/2]

template<typename Writer , typename BinIterator >
uint32_t find ( const dds::pub::Publisher publisher,
const std::string &  topic_name,
BinIterator  begin 
)
related

Retrieves the dds::pub::DataWriter for a specific topic name.

This returned dds::pub::DataWriter is either enabled or disabled.

If more than one dds::pub::DataWriter is attached to the dds::pub::Publisher with the same topic_name, then this operation may return any one of them.

MT Safety:
UNSAFE. It is not safe to lookup a dds::pub::DataWriter in one thread while another thread is simultaneously creating or destroying that dds::pub::DataWriter.

This function retrieves a previously created DataWriter belonging to the dds::pub::Publisher that is attached to a dds::topic::Topic with a matching topic name. If no such DataWriter exists, the operation will return an empty container. The use of this operation on the built-in Publisher allows access to the built-in DataWriter entities for the built-in topics

Template Parameters
WriterThe type of the writer. It can be dds::pub::AnyDataWriter, or an instantiation of dds::pub::DataWriter<T> (if T is not the correct type, this function throws dds::core::InvalidDowncastError)
BinIteratorBinIterator The type of back-inserting iterator passed to this function
Parameters
publisherThe dds::pub::Publisher the DataWriter belongs to
topic_nameName of the dds::topic::Topic associated with the DataWriter that is to be looked up.
beginA back-inserting iterator to the position in the destination container to insert the found DataWriter into
Returns
The number of DataWriters that were found (either 0 or 1)

◆ find_datawriters() [1/2]

template<typename AnyDataWriterBackInsertIterator >
uint32_t find_datawriters ( dds::pub::Publisher  publisher,
AnyDataWriterBackInsertIterator  begin 
)
related

Retrieve all the dds::pub::DataWriter created from this dds::pub::Publisher.

Note
This is a standalone function in the namespace rti::pub
Template Parameters
AnyDataWriterBackInsertIteratorAn iterator whose value_type is dds::pub::AnyDataWriter
Parameters
publisherThe dds::pub::Publisher the DataWriters belong to
beginA back-inserting iterator to the position in the destination container to insert the found DataWriters into
Returns
The number of found DataWriters
See also
Looking up DataWriters

◆ find_datawriters() [2/2]

template<typename AnyDataWriterForwardIterator >
uint32_t find_datawriters ( dds::pub::Publisher  publisher,
AnyDataWriterForwardIterator  begin,
uint32_t  max_size 
)
related

Retrieve all the dds::pub::DataWriter created from this dds::pub::Publisher.

Note
This is a standalone function in the namespace rti::pub
Template Parameters
AnyDataWriterForwardIteratorAn iterator whose value_type is dds::pub::AnyDataWriter
Parameters
publisherThe dds::pub::Publisher the DataWriters belong to
beginA forward iterator to the first position in the destination container to copy the found DataWriters into
max_sizeThe maximum number of DataWriters to return
Returns
The number of found DataWriters
See also
Looking up DataWriters

◆ find_datawriter_by_topic_name()

template<typename Writer >
Writer find_datawriter_by_topic_name ( dds::pub::Publisher  publisher,
const std::string &  topic_name 
)
related

<<extension>> Retrieves a dds::pub::DataWriter with the given name within the dds::pub::Publisher

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

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

This operation retrieves the dds::pub::DataWriter within the dds::pub::Publisher whose name matches the one specified. If there are several dds::pub::DataWriter with the same name within the dds::pub::Publisher, the operation returns the first matching occurrence.

Template Parameters
WriterThe type of the writer. It can be dds::pub::AnyDataWriter, or an instantiation of dds::pub::DataWriter<T> (if T is not the correct type, this function throws dds::core::InvalidDowncastError)
Parameters
publisherThe dds::pub::Publisher that created the DataWriter to find
topic_nameEntity name of the DataWriter to find
Returns
The AnyDataWriter with the given name
See also
Looking up DataWriters

References dds::core::null.

◆ find_datawriter_by_name() [1/2]

template<typename Writer >
Writer find_datawriter_by_name ( dds::pub::Publisher  publisher,
const std::string &  datawriter_name 
)
related

<<extension>> Retrieves a dds::pub::DataWriter with the given name within the dds::pub::Publisher

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

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

This operation retrieves the dds::pub::DataWriter within the dds::pub::Publisher whose name matches the one specified. If there are several dds::pub::DataWriter with the same name within the dds::pub::Publisher, the operation returns the first matching occurrence.

Template Parameters
WriterThe type of the writer. It can be dds::pub::AnyDataWriter, or an instantiation of dds::pub::DataWriter<T> (if T is not the correct type, this function throws dds::core::InvalidDowncastError)
Parameters
publisherThe dds::pub::Publisher that created the DataWriter to find
datawriter_nameEntity name of the DataWriter to find
Returns
The WRITER with the given name
See also
Looking up DataWriters

References dds::core::null.

◆ find_datawriter_by_name() [2/2]

template<typename Writer >
Writer find_datawriter_by_name ( dds::domain::DomainParticipant  participant,
const std::string &  datawriter_name 
)
related

<<extension>> Retrieves a dds::pub::DataWriter within the dds::domain::DomainParticipant with the given name

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

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

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

This operation retrieves a dds::pub::DataWriter within a dds::pub::Publisher given the specified name which encodes both to the dds::pub::DataWriter and the dds::pub::Publisher name.

If there are several dds::pub::DataWriter with the same name within the corresponding dds::pub::Publisher this function returns the first matching occurrence.

The specified name might be given as a fully-qualified entity name or as a plain name.

The fully qualified entity name is a concatenation of the dds::pub::Publisher to which the dds::pub::DataWriter belongs and the entity name of of the dds::pub::DataWriter itself, separated by a double colon "::". For example: MyPublisherName::MyDataWriterName

The plain name contains the dds::pub::DataWriter name only. In this situation it is implied that the dds::pub::DataWriter belongs to the implicit dds::pub::Publisher so the use of a plain name is equivalent to specifying a fully qualified name with the dds::pub::Publisher name part being "implicit". For example: the plain name "MyDataWriterName" is equivalent to specifiying the fully qualified name "implicit::MyDataWriterName"

The dds::pub::DataWriter is only looked up within the dds::pub::Publisher specified in the fully qualified name, or within the implicit dds::pub::Publisher if the name was not fully qualified.

Template Parameters
WriterThe type of the writer. It can be dds::pub::AnyDataWriter, or an instantiation of dds::pub::DataWriter<T> (if T is not the correct type, this function throws dds::core::InvalidDowncastError)
Parameters
participantThe dds::domain::DomainParticipant within which the dds::pub::DataWriter exists
datawriter_nameEntityName of the DataWriter to find
Returns
The WRITER with the given name
See also
implicit_publisher(const dds::domain::DomainParticipant& dp);
Looking up DataWriters

References dds::core::null.