Struct Writer 

pub struct Writer<'domain, 'participant, 'topic, T>
where
    T: Topicable,
{ /* private fields */ }

A data writer for topic type T.

A Writer publishes samples of type T to a named Topic. Matched Readers on the same topic receive the samples subject to their QoS compatibility.

Use Writer::new for simple construction or Writer::builder for QoS, listener, and publisher configuration.

Instance lifecycle

For keyed topics, each unique key value identifies a distinct instance. Writers can explicitly manage instance lifecycle through register_instance, unregister_instance, and dispose. Unkeyed topics (where T::Key is ()) have a single instance shared by all samples.

Implementations

impl<'d, 'p, 't, T> Writer<'d, 'p, 't, T>

where T: Topicable,

pub fn new(topic: &'t Topic<'d, 'p, T>) -> Result<Self>

Creates a new Writer for the given Topic with default QoS and no listener.

Errors

Returns an Error if the writer fails to create.

Examples

use cyclonedds::Writer;

let topic = Topic::<Data>::new(&participant, "MyTopic")?;
let writer = Writer::new(&topic)?;

pub const fn builder<'q>( topic: &'t Topic<'d, 'p, T>, ) -> WriterBuilder<'d, 'p, 't, 'q, T>

Returns a WriterBuilder for constructing a writer with custom QoS or a listener.

Examples

use cyclonedds::{Duration, QoS, Writer, qos::policy::Reliability};

let topic = Topic::<Data>::new(&participant, "MyTopic")?;
let qos = QoS::new().with_reliability(Reliability::Reliable {
    max_blocking_time: Duration::from_millis(100),
});
let writer = Writer::builder(&topic).with_qos(&qos).build()?;

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

Writes a sample to the topic.

Errors

Returns an Error if the writers fails to write the sample.

Examples

let topic = Topic::<Data>::new(&participant, "MyTopic")?;
let writer = Writer::new(&topic)?;
writer.write(&Data { x: 1, y: 2 })?;

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

Writes a sample with an explicit source timestamp.

Use this when the write timestamp should reflect the time the data was generated rather than the time it was written.

Errors

Returns an Error if the writer fails to write the sample.

Examples

use cyclonedds::Time;

let topic = Topic::<Data>::new(&participant, "MyTopic")?;
let writer = Writer::new(&topic)?;
writer.write_with_timestamp(&Data::default(), Time::from_secs(1))?;

pub fn flush(&self) -> Result<()>

Flushes batched samples to the network.

Only relevant when write batching is enabled in the domain configuration. Has no effect otherwise.

Errors

Returns an Error if the writer fails to flush.

Examples

let topic = Topic::<Data>::new(&participant, "MyTopic")?;
let writer = Writer::new(&topic)?;
writer.write(&Data::default())?;
writer.flush()?;

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

Blocks until all written samples have been acknowledged by all matched reliable readers, or until timeout elapses.

Errors

Returns an Error if the timeout elapses before all acknowledgements are received or if the writer encounters an unexpected error.

Examples

use cyclonedds::Duration;

let topic = Topic::<Data>::new(&participant, "MyTopic")?;
let writer = Writer::new(&topic)?;
writer.write(&Data::default())?;
writer.wait_for_acks(Duration::from_secs(1))?;

pub fn matched_subscriptions(&self) -> Result<Vec<InstanceHandle>>

Returns the instance handles of all readers currently matched with this writer.

The returned handles can be compared against InstanceHandle values from reader entities to identify specific matched readers.

Errors

Returns an Error if the writer fails to retrieve the matched subscriptions.

Examples

use cyclonedds::entity::Entity;

let topic = Topic::<Data>::new(&participant, "MyTopic")?;
let writer = Writer::new(&topic)?;
let reader = Reader::new(&topic)?;

let matched = writer.matched_subscriptions()?;
assert_eq!(matched[0], reader.instance_handle()?);

pub fn register_instance(&self, key: &T::Key) -> Result<InstanceHandle>

Registers an instance identified by key with this writer.

Registration is optional but allows for the pre-allocation of resources for the instance. Returns the InstanceHandle assigned to the instance.

Errors

Returns an Error if the writer fails to register the instance.

Examples

let topic = Topic::<Data>::new(&participant, "MyTopic")?;
let writer = Writer::new(&topic)?;
let handle = writer.register_instance(&Key::<Data> { x: 1, y: 2 })?;

pub fn unregister_instance(&self, key: &T::Key) -> Result<()>

Unregisters an instance identified by key from this writer.

Notifies matched readers that this writer will no longer publish samples for the given instance.

Errors

Returns an Error if the writer fails to unregister the instance.

Examples

let topic = Topic::<Data>::new(&participant, "MyTopic")?;
let writer = Writer::new(&topic)?;
writer.register_instance(&Key::<Data> { x: 1, y: 2 })?;
writer.unregister_instance(&Key::<Data> { x: 1, y: 2 })?;

pub fn unregister_instance_by_handle( &self, instance_handle: InstanceHandle, ) -> Result<()>

Unregisters an instance identified by its InstanceHandle.

Errors

Returns an Error if the writer fails to unregister the instance.

Examples

let topic = Topic::<Data>::new(&participant, "MyTopic")?;
let writer = Writer::new(&topic)?;
let handle = writer.register_instance(&Key::<Data> { x: 1, y: 2 })?;
writer.unregister_instance_by_handle(handle)?;

pub fn unregister_instance_with_timestamp( &self, key: &T::Key, timestamp: Time, ) -> Result<()>

Unregisters an instance identified by key with an explicit timestamp.

Errors

Returns an Error if the writer fails to unregister the instance.

Examples

use cyclonedds::Time;

let topic = Topic::<Data>::new(&participant, "MyTopic")?;
let writer = Writer::new(&topic)?;
writer.unregister_instance_with_timestamp(&Key::<Data> { x: 1, y: 2 }, Time::from_secs(1))?;

pub fn unregister_instance_by_handle_with_timestamp( &self, instance_handle: InstanceHandle, timestamp: Time, ) -> Result<()>

Unregisters an instance identified by its InstanceHandle with an explicit timestamp.

Errors

Returns an Error if the writer fails to unregister the instance.

Examples

use cyclonedds::Time;

let topic = Topic::<Data>::new(&participant, "MyTopic")?;
let writer = Writer::new(&topic)?;
let handle = writer.register_instance(&Key::<Data> { x: 1, y: 2 })?;
writer.unregister_instance_by_handle_with_timestamp(handle, Time::from_secs(1))?;

pub fn lookup_instance(&self, key: &T::Key) -> Option<InstanceHandle>

Returns the InstanceHandle for the instance identified by key, or None if the instance is not registered.

Examples

let topic = Topic::<Data>::new(&participant, "MyTopic")?;
let writer = Writer::new(&topic)?;
let handle = writer.register_instance(&Key::<Data> { x: 1, y: 2 })?;
assert_eq!(
    writer.lookup_instance(&Key::<Data> { x: 1, y: 2 }),
    Some(handle)
);
assert_eq!(writer.lookup_instance(&Key::<Data> { x: 9, y: 9 }), None);

pub fn write_dispose(&self, data: &T) -> Result<()>

Writes a sample and immediately disposes the instance.

Equivalent to calling write followed by dispose but in a single operation.

Errors

Returns an Error if the writer fails to write or dispose.

Examples

let topic = Topic::<Data>::new(&participant, "MyTopic")?;
let writer = Writer::new(&topic)?;
writer.write_dispose(&Data { x: 1, y: 2 })?;

pub fn write_dispose_with_timestamp( &self, data: &T, timestamp: Time, ) -> Result<()>

Writes a sample and immediately disposes the instance with an explicit timestamp.

Errors

Returns an Error if the writer fails to write or dispose.

Examples

use cyclonedds::Time;

let topic = Topic::<Data>::new(&participant, "MyTopic")?;
let writer = Writer::new(&topic)?;
writer.write_dispose_with_timestamp(&Data::default(), Time::from_secs(1))?;

pub fn dispose(&self, key: &T::Key) -> Result<()>

Disposes the instance identified by key.

Notifies matched readers that the instance is no longer valid. The instance remains known but its state transitions to disposed.

Errors

Returns an Error if the writer fails to dispose the instance.

Examples

let topic = Topic::<Data>::new(&participant, "MyTopic")?;
let writer = Writer::new(&topic)?;
writer.write(&Data { x: 1, y: 2 })?;
writer.dispose(&Key::<Data> { x: 1, y: 2 })?;

pub fn dispose_with_timestamp( &self, key: &T::Key, timestamp: Time, ) -> Result<()>

Disposes the instance identified by key with an explicit timestamp.

Errors

Returns an Error if the writer fails to dispose the instance.

Examples

use cyclonedds::Time;

let topic = Topic::<Data>::new(&participant, "MyTopic")?;
let writer = Writer::new(&topic)?;
writer.dispose_with_timestamp(&Key::<Data> { x: 1, y: 2 }, Time::from_secs(1))?;

pub fn dispose_instance_by_handle( &self, instance_handle: InstanceHandle, ) -> Result<()>

Disposes the instance identified by its InstanceHandle.

Errors

Returns an Error if the writer fails to dispose the instance.

Examples

let topic = Topic::<Data>::new(&participant, "MyTopic")?;
let writer = Writer::new(&topic)?;
let handle = writer.register_instance(&Key::<Data> { x: 1, y: 2 })?;
writer.dispose_instance_by_handle(handle)?;

pub fn dispose_instance_by_handle_with_timestamp( &self, instance_handle: InstanceHandle, timestamp: Time, ) -> Result<()>

Disposes the instance identified by its InstanceHandle with an explicit timestamp.

Errors

Returns an Error if the writer fails to dispose the instance.

Examples

use cyclonedds::Time;

let topic = Topic::<Data>::new(&participant, "MyTopic")?;
let writer = Writer::new(&topic)?;
let handle = writer.register_instance(&Key::<Data> { x: 1, y: 2 })?;
writer.dispose_instance_by_handle_with_timestamp(handle, Time::from_secs(1))?;

pub fn set_listener<L>(&mut self, listener: L) -> Result<()>

where L: AsRef<WriterListener<T>>,

Sets the WriterListener on this writer, replacing any previously set listener.

Errors

Returns an Error if the writer fails to set the listener.

Examples

use cyclonedds::listener::WriterListener;

let topic = Topic::<Data>::new(&participant, "MyTopic")?;
let mut writer = Writer::new(&topic)?;
writer.set_listener(WriterListener::new().with_publication_matched(|_, status| {
    println!("matched readers: {}", status.current.count);
}))?;

pub fn unset_listener(&mut self) -> Result<()>

Removes the listener from this writer.

Errors

Returns an Error if the writer fails to unset the listener.

Examples

let topic = Topic::<Data>::new(&participant, "MyTopic")?;
let mut writer = Writer::new(&topic)?;
writer.unset_listener()?;

pub fn with_listener<L>(self, listener: L) -> Result<Self>

where L: AsRef<WriterListener<T>>,

Sets the WriterListener on this writer, consuming and returning self.

Errors

Returns an Error if the writer fails to set the listener.

Examples

use cyclonedds::listener::WriterListener;

let topic = Topic::<Data>::new(&participant, "MyTopic")?;
let writer = Writer::new(&topic)?.with_listener(WriterListener::new())?;

Trait Implementations

impl<'domain, 'participant, 'topic, T> Debug for Writer<'domain, 'participant, 'topic, T>

where T: Topicable + Debug,

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

Formats the value using the given formatter.

impl<T> Drop for Writer<'_, '_, '_, T>

where T: Topicable,

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: Topicable> Entity for Writer<'_, '_, '_, T>

fn id(&self) -> EntityId

Returns the EntityId of this entity.

fn instance_handle(&self) -> Result<InstanceHandle>

Returns the InstanceHandle of this entity.

fn status_changes(&self) -> Result<Status>

Returns the set of status flags that have changed since they were last read or taken.

fn take_status(&self, mask: Option<Status>) -> Result<Status>

Takes and clears the status flags matching mask, or all flags if mask is None.

fn read_status(&self, mask: Option<Status>) -> Result<Status>

Reads the status flags matching mask without clearing them, or all flags if mask is None.

fn status_mask(&self) -> Result<Status>

Returns the status mask enabled on the entity.

fn set_status_mask(&self, mask: Status) -> Result<()>

Sets and enables a status mask on the entity.

impl<'domain, 'participant, 'topic, T> Eq for Writer<'domain, 'participant, 'topic, T>

where T: Topicable + Eq,

impl<'domain, 'participant, 'topic, T> PartialEq for Writer<'domain, 'participant, 'topic, T>

where T: Topicable + PartialEq,

fn eq(&self, other: &Writer<'domain, 'participant, 'topic, T>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'domain, 'participant, 'topic, T> StructuralPartialEq for Writer<'domain, 'participant, 'topic, T>

where T: Topicable,