Struct Publisher 

pub struct Publisher<'domain, 'participant> { /* private fields */ }

A Publisher groups Writers and controls their shared QoS. Writers created under a publisher inherit its QoS where applicable.

Use Publisher::new for simple construction or Publisher::builder for QoS and listener configuration.

In most applications a publisher is created implicitly when constructing a Writer directly. Use an explicit publisher when you need coordinated writes across multiple writers.

Implementations

impl<'d, 'p> Publisher<'d, 'p>

pub fn new(participant: &'p Participant<'d>) -> Result<Self>

Creates a new Publisher under participant with default QoS and no listener.

Errors

Returns an Error if the publisher fails to create.

Examples

use cyclonedds::Publisher;

let publisher = Publisher::new(&participant)?;
Ok::<_, cyclonedds::Error>(())

pub const fn builder<'q>( participant: &'p Participant<'d>, ) -> PublisherBuilder<'d, 'p, 'q>

Returns a PublisherBuilder for constructing a publisher with custom QoS or a listener.

Examples

use cyclonedds::{
    Publisher, QoS,
    qos::policy::{Durability, Presentation},
};

let qos = QoS::new().with_presentation(Presentation::Topic {
    coherent_access: true,
    ordered_access: true,
});
let publisher = Publisher::builder(&participant).with_qos(&qos).build()?;
Ok::<_, cyclonedds::Error>(())

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

(WARN: unimplemented in C lib): Suspends publication on all writers belonging to this publisher.

This function is currently not implemented by the underlying C library and will thus always return an unsupported error.

While suspended, calls to Writer::write may be batched by the middleware. Call resume to flush and resume normal publication. Suspend and resume are typically used together to send a coherent set of updates.

Errors

Returns an Error if publisher fails to suspend.

Examples

use cyclonedds::{Topic, Writer};
let topic = Topic::<Data>::new(&participant, "MyTopic")?;

// Create the publisher.
let publisher = Publisher::new(&participant)?;

// Create two Writers under the publisher.
let writer01 = Writer::builder(&topic).with_publisher(&publisher).build()?;
let writer02 = Writer::builder(&topic).with_publisher(&publisher).build()?;

// Suspend all the writers.
publisher.suspend()?;

writer01.write(&Data { x: 0, y: 1 })?;
writer02.write(&Data { x: 2, y: 3 })?;

// Resume all the writers.
publisher.resume()?;

Ok::<_, cyclonedds::Error>(())

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

(WARN: unimplemented in C lib): Resumes publication on all writers belonging to this publisher.

This function is currently not implemented by the underlying C library and will thus always return an unsupported error.

Flushes any writes that were batched during a suspend and resumes normal publication.

Errors

Returns an Error if the publisher fails to resume.

Examples

use cyclonedds::{Topic, Writer};
let topic = Topic::<Data>::new(&participant, "MyTopic")?;

// Create the publisher.
let publisher = Publisher::new(&participant)?;

// Create two Writers under the publisher.
let writer01 = Writer::builder(&topic).with_publisher(&publisher).build()?;
let writer02 = Writer::builder(&topic).with_publisher(&publisher).build()?;

// Suspend all the writers.
publisher.suspend()?;

writer01.write(&Data { x: 0, y: 1 })?;
writer02.write(&Data { x: 2, y: 3 })?;

// Resume all the writers.
publisher.resume()?;

Ok::<_, cyclonedds::Error>(())

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

(WARN: unimplemented in C lib): Blocks until all samples written by writers under this publisher have been acknowledged by all matched reliable readers, or until timeout elapses.

This function is currently not implemented by the underlying C library and will thus always return an unsupported error.

Errors

Returns an Error if the timeout elapses before all acknowledgements are received or if the publisher returns an error.

Examples

use cyclonedds::Duration;

let publisher = Publisher::new(&participant)?;
publisher.wait_for_acks(Duration::from_secs(1))?;
Ok::<_, cyclonedds::Error>(())

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

where L: AsRef<PublisherListener>,

Sets the PublisherListener on this publisher, replacing any previously set listener.

Errors

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

Examples

use cyclonedds::PublisherListener;

let mut publisher = Publisher::new(&participant)?;
publisher.set_listener(PublisherListener::new())?;

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

Removes the listener from this publisher.

Errors

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

Examples

let mut publisher = Publisher::new(&participant)?;
publisher.unset_listener()?;

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

where L: AsRef<PublisherListener>,

Sets the PublisherListener on this publisher, consuming and returning self.

Errors

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

Examples

use cyclonedds::PublisherListener;

let publisher = Publisher::new(&participant)?.with_listener(PublisherListener::new())?;

Trait Implementations

impl<'domain, 'participant> Debug for Publisher<'domain, 'participant>

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

Formats the value using the given formatter.

impl Drop for Publisher<'_, '_>

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 Entity for Publisher<'_, '_>

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.