Struct DataWriter 

pub struct DataWriter<T>
where
    T: DdsType,
{ /* private fields */ }

Typed DataWriter — sends samples to all matched readers of the topic.

Two modes:

• Live (runtime: Some, entity_id: Some): write() delegates to the runtime → ReliableWriter → UDP.
• Offline (offline fallback, runtime=None): write() queues in-memory; for unit tests without a network.

Implementations

impl<T> DataWriter<T>

where T: DdsType,

pub fn topic(&self) -> &Topic<T>

The topic that is sent to.

pub fn rtps_guid(&self) -> Option<[u8; 16]>

This writer’s 16-byte RTPS GUID, when it is bound to a live runtime (online participant). None in offline mode. Used by the iceoryx-cyclone bridge to stamp the cross-vendor PSMX chunk with the writer’s real GUID so a peer that discovered it over RTPS associates the SHM sample with it.

pub fn set_listener( &self, listener: Option<Arc<dyn DataWriterListener>>, mask: u32, )

Sets the DataWriterListener + StatusMask. None clears the slot. Spec §2.2.2.4.2.x set_listener.

pub fn get_listener(&self) -> Option<Arc<dyn DataWriterListener>>

Current listener clone, if present.

pub fn qos(&self) -> DataWriterQos

Current QoS (cloned, .1).

pub fn write(&self, sample: &T) -> Result<(), DdsError>

Sends a sample to all matched readers.

Spec §2.2.3.19 RESOURCE_LIMITS reliable block: If the local writer cache has reached max_samples AND Reliability=RELIABLE AND max_blocking_time > 0, write() blocks until a reader ACK frees the slot or the timeout expires. In best-effort mode or with max_blocking_time = 0, write() fails immediately with OutOfResources.

Errors

• WireError if T::encode fails.
• OutOfResources if the queue is full + best-effort/no blocking time, or if the block timeout expired before a drain.
• PreconditionNotMet on lock poisoning.

pub fn samples_pending(&self) -> usize

Number of samples written so far. Test helper, replaced by real HistoryCache counters in the runtime.

pub fn matched_subscription_count(&self) -> usize

Number of matched remote readers. Always 0 in offline mode.

Spec: OMG DDS 1.4 §2.2.2.4.2.11 get_matched_subscriptions. That returns a list; this returns only the count, the full list comes with listener callbacks.

Side effect — on a change of the matched count relative to the last call, on_publication_matched is fired via the bubble-up chain (Spec §2.2.4.2.4.4).

pub fn wait_for_matched_subscription( &self, min_count: usize, timeout: Duration, ) -> Result<(), DdsError>

Blocks until at least min_count remote readers are matched or timeout elapses. Event-driven via a runtime condvar (D.5e phase 1) — wakes up directly when SEDP propagates a match, no more 20-ms polling.

Related to OMG DDS 1.4 §2.2.2.4.2.22 wait_for_acknowledgments, but focused on matching rather than ACK. Covers the typical producer pattern “first create the writer, then wait for subscribers, then write”.

Errors

DdsError::Timeout if min_count is not reached within the time window.

pub fn offered_deadline_missed_count(&self) -> u64

Counter for offered-deadline violations (Spec §2.2.4.2.9 OFFERED_DEADLINE_MISSED_STATUS). Monotonically increasing; increments by 1 per expired deadline window without a write. Always 0 in offline mode or with deadline=INFINITE.

Fires on_offered_deadline_missed over the bubble-up chain on a delta relative to the last call, if applicable.

pub fn liveliness_lost_count(&self) -> u64

Counter for LivelinessLost detections (Spec §2.2.4.2.10). Triggers on_liveliness_lost via bubble-up, if applicable.

pub fn offered_incompatible_qos_status(&self) -> OfferedIncompatibleQosStatus

Current OfferedIncompatibleQosStatus (Spec §2.2.4.2.4.2). Triggers on_offered_incompatible_qos, if applicable.

pub fn drive_listeners(&self)

Polls all statuses once and fires pending listeners. Convenience helper for tests + periodic tick callers.

pub fn assert_liveliness(&self)

Manual liveliness assert. Spec §2.2.2.4.2.20 assert_liveliness. Sets the last_liveliness_assert timestamp; a no-op with automatic liveliness (every write asserts anyway).

pub fn wait_for_acknowledgments( &self, timeout: Duration, ) -> Result<(), DdsError>

Blocks until all matched remote readers have acknowledged all samples written so far, or timeout elapses.

Spec: OMG DDS 1.4 §2.2.2.4.2.22 wait_for_acknowledgments. Returns Ok(()) immediately in offline mode and without matched readers.

Errors

DdsError::Timeout if not all samples are acknowledged within the time window.

pub fn publication_handle(&self) -> InstanceHandle

Local publication handle of this DataWriter (Spec §2.2.2.5.1.11). Passed along in the publication_handle field of SampleInfo. Note: this is NOT the same handle as the entity InstanceHandle (Spec §2.2.2.1.1) — see Self::instance_handle.

pub fn instance_handle(&self) -> InstanceHandle

Spec §2.2.2.1.1 get_instance_handle — entity identifier of this DataWriter for comparisons via DomainParticipant::contains_entity.

pub fn instance_tracker(&self) -> InstanceTracker

Returns the writer’s shared instance tracker (test and inspection helper, Spec §2.2.2.4.2.5+ lifecycle bookkeeping).

pub fn register_instance( &self, instance: &T, ) -> Result<InstanceHandle, DdsError>

Registers an instance with the DataWriter and returns its stable InstanceHandle. Spec §2.2.2.4.2.5 register_instance.

For non-keyed topics the call returns HANDLE_NIL (each sample is its own “instance”; the spec explicitly says register/ unregister/dispose are optional here).

Errors

Currently the call cannot fail. Later (live mode) resource limits may return an OutOfResources error here.

pub fn register_instance_w_timestamp( &self, instance: &T, timestamp: Time, ) -> Result<InstanceHandle, DdsError>

Like register_instance, but with an explicit timestamp. Spec §2.2.2.4.2.6.

pub fn lookup_instance(&self, instance: &T) -> InstanceHandle

Turns a sample value into its corresponding local InstanceHandle, or HANDLE_NIL if unknown / non-keyed. Spec §2.2.2.4.2.14 lookup_instance.

pub fn unregister_instance( &self, instance: &T, handle: InstanceHandle, ) -> Result<(), DdsError>

Removes the instance from the writer set (Spec §2.2.2.4.2.7). Sets the lifecycle state to NOT_ALIVE_NO_WRITERS once the last writer has unregistered.

Errors

BadParameter if handle does not match the instance of instance (the spec requires this consistency check). If handle == HANDLE_NIL, the handle is derived from instance.

pub fn unregister_instance_w_timestamp( &self, instance: &T, handle: InstanceHandle, timestamp: Time, ) -> Result<(), DdsError>

Like unregister_instance, but with a timestamp. Spec §2.2.2.4.2.8.

Spec §2.2.3.21 WriterDataLifecycle: if autodispose_unregistered_instances=true (default), the instance is also disposed in addition to being unregistered — readers then see both NOT_ALIVE_DISPOSED and NOT_ALIVE_NO_WRITERS.

pub fn dispose( &self, instance: &T, handle: InstanceHandle, ) -> Result<(), DdsError>

Disposes an instance (Spec §2.2.2.4.2.10). Marks it as NOT_ALIVE_DISPOSED; readers then see a sample with valid_data == false.

Errors

Like unregister_instance.

pub fn dispose_w_timestamp( &self, instance: &T, handle: InstanceHandle, timestamp: Time, ) -> Result<(), DdsError>

Like dispose, but with a timestamp. Spec §2.2.2.4.2.11.

pub fn get_key_value(&self, handle: InstanceHandle) -> Result<T, DdsError>

Returns the sample value with only the @key fields populated (Spec §2.2.2.4.2.13 get_key_value). Implementation: we reconstruct T via decode from the stored PLAIN_CDR2-BE key holder. For this to work, T::decode must accept a key-only stream — for simple records this is trivially the case.

Errors

• BadParameter if the handle is unknown.
• WireError if the key holder cannot be reconstructed via T::decode.

pub fn write_w_timestamp( &self, sample: &T, timestamp: Time, ) -> Result<(), DdsError>

Writes a sample with an explicit timestamp (Spec §2.2.2.4.2.16 write_w_timestamp) and updates the instance bookkeeping.

Errors

Like Self::write.

Trait Implementations

impl<T> Debug for DataWriter<T>

where T: DdsType,

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<T> Drop for DataWriter<T>

where T: DdsType,

Available on crate feature std only.

RAII teardown (Spec §2.2.2.4.1.2 — deleting a DataWriter). Dropping the user’s handle deregisters the writer from the runtime: it removes the slot (stopping the RTPS heartbeats), rebuilds the intra-runtime route, and sends an SEDP dispose so remote peers drop the matched writer at once instead of waiting for a liveliness timeout. Offline writers (no runtime) are no-ops.

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl<T> Entity for DataWriter<T>

where T: DdsType,

Available on crate feature std only.

fn set_qos(&self, qos: <DataWriter<T> as Entity>::Qos) -> Result<(), DdsError>

Spec §2.2.3 / §2.2.2.4.2: DURABILITY, RELIABILITY, HISTORY, RESOURCE_LIMITS, OWNERSHIP, LIVELINESS are Changeable=NO post-enable.

type Qos = DataWriterQos

QoS type for this entity (e.g. DomainParticipantQos, DataWriterQos, …).

fn get_qos(&self) -> <DataWriter<T> as Entity>::Qos

Returns the current QoS (clone). Spec §2.2.2.1.2 get_qos.

fn enable(&self) -> Result<(), DdsError>

Enables the entity (idempotent). Spec §2.2.2.1.4 enable.

fn entity_state(&self) -> Arc<EntityState>

Internal accessor — each impl returns its Arc<EntityState>.

fn is_enabled(&self) -> bool

True if the entity is already enabled.

fn get_status_condition(&self) -> StatusCondition

StatusCondition of this entity. Spec §2.2.2.1.6 get_status_condition.

fn get_status_changes(&self) -> u32

Bitmask of the status kinds changed since the last read. Spec §2.2.2.1.5 get_status_changes.

fn get_instance_handle(&self) -> InstanceHandle

Local 64-bit identifier. Spec §2.2.2.1.7 get_instance_handle.