Struct Reader 

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

A data reader for topic type T.

A Reader receives samples of type T from a named Topic. Samples are retrieved via read, take, or peek. Matched Writers on the same topic deliver samples subject to QoS compatibility.

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

peek vs read vs take

Method	Behavior	Cache effect	Read state effect
peek	Returns samples without consuming them. Useful for checking whether data is available.	Samples remain in the reader cache.	Stays unread.
read	Returns samples and marks them as read (but leaves them available for subsequent reads).	Samples remain in the reader cache.	Marked as read.
take	Returns samples and removes them (making them unavailable for subsequent reads).	Samples are removed from the reader cache.	Consumed and no longer cached.

Implementations

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

where T: Topicable,

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

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

Errors

Returns an Error if the reader fails to create.

Examples

use cyclonedds::Reader;

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

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

Returns a ReaderBuilder for constructing a reader with custom QoS or a listener.

Examples

use cyclonedds::{QoS, Reader, qos::policy::History};


let topic = Topic::<Data>::new(&participant, "Example")?;
let qos = QoS::new().with_history(History::KeepAll);
let reader = Reader::builder(&topic).with_qos(&qos).build()?;

pub fn take(&self) -> Result<Vec<SampleOrKey<T>>>

where T: Clone,

Removes and returns all available samples from the reader cache.

Each call to take consumes the returned samples so they will not be returned by subsequent calls. See read to leave samples in the cache.

Errors

Returns an Error if the reader fails to take samples.

Examples

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

writer.write(&Data::default())?;
let samples = reader.take()?;
assert_eq!(samples.len(), 1);

// Samples have been consumed.
assert!(reader.take()?.is_empty());

pub fn read(&self) -> Result<Vec<SampleOrKey<T>>>

where T: Clone,

Returns all available samples from the reader cache without removing them.

Samples returned by read remain in the cache and will be returned again by subsequent calls, marked as read in their Info state. See take to consume samples.

Errors

Returns an Error if the reader fails to read samples.

Examples

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

writer.write(&Data::default())?;
let samples = reader.read()?;
assert_eq!(samples.len(), 1);

// Samples are still in the cache.
assert_eq!(reader.read()?.len(), 1);

pub fn peek(&self) -> Result<Vec<SampleOrKey<T>>>

where T: Clone,

Returns all available samples without marking them as read or removing them from the cache.

Useful for checking whether data is available without affecting the read state of samples. Subsequent calls to read or take will still return the same samples as unread.

Errors

Returns an Error if the reader fails to peek.

Examples

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

writer.write(&Data::default())?;
assert_eq!(reader.peek()?.len(), 1);

// Samples are unaffected.
assert_eq!(reader.take()?.len(), 1);

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

Returns the instance handles of all writers currently matched with this reader.

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

Errors

Returns an Error if the reader fails to retrieve the matched publications.

Examples

use cyclonedds::entity::Entity;

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

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

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

Blocks until all historical data available from matched writers with TransientLocal or higher durability has been received, or until timeout elapses.

Errors

Returns an Error if the timeout elapses before historical data is received or if the reader returns an error.

Examples

use cyclonedds::Duration;

let topic = Topic::<Data>::new(&participant, "Example")?;
let reader = Reader::new(&topic)?;
reader.wait_for_historical_data(Duration::from_secs(1))?;

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

where L: AsRef<ReaderListener<T>>,

Sets the ReaderListener on this reader, replacing any previously set listener.

Errors

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

Examples

use cyclonedds::listener::ReaderListener;

let topic = Topic::<Data>::new(&participant, "Example")?;
let mut reader = Reader::new(&topic)?;
reader.set_listener(
    ReaderListener::new().with_subscription_matched(|_, status| {
        println!("matched writers: {}", status.current.count);
    }),
)?;

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

Removes the listener from this reader.

Errors

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

Examples

let topic = Topic::<Data>::new(&participant, "Example")?;
let mut reader = Reader::new(&topic)?;
reader.unset_listener()?;

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

where L: AsRef<ReaderListener<T>>,

Sets the ReaderListener on this reader, consuming and returning self.

Errors

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

Examples

use cyclonedds::listener::ReaderListener;

let topic = Topic::<Data>::new(&participant, "Example")?;
let reader = Reader::new(&topic)?.with_listener(ReaderListener::new())?;

Trait Implementations

impl<'domain, 'participant, 'topic, T> Debug for Reader<'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 Reader<'_, '_, '_, 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 Reader<'_, '_, '_, 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 Reader<'domain, 'participant, 'topic, T>

where T: Topicable + Eq,

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

where T: Topicable + PartialEq,

fn eq(&self, other: &Reader<'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 Reader<'domain, 'participant, 'topic, T>

where T: Topicable,