Struct ReadCondition 

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

A filter on a Reader that restricts samples by their State.

A ReadCondition is created against a reader with a state mask and can be attached to a WaitSet to trigger when matching samples become available. Reading via the condition returns only samples whose combined sample, view, and instance state matches the mask.

Examples

use cyclonedds::state;
use cyclonedds::{Duration, ReadCondition, WaitSet};

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

let condition = ReadCondition::new(
    &reader,
    state::sample::Fresh | state::instance::Any | state::view::Any,
)?;
let mut waitset = WaitSet::<()>::new(&participant)?;
waitset.attach(&condition, None)?;
waitset.wait(Duration::INFINITE)?;

let samples = condition.take()?;

Implementations

impl<'d, 'p, 't, 'r, T> ReadCondition<'d, 'p, 't, 'r, T>

where T: Topicable,

pub fn new(reader: &'r Reader<'d, 'p, 't, T>, mask: State) -> Result<Self>

Creates a new ReadCondition on reader that matches samples whose state satisfies mask.

Errors

Returns an Error if the read condition fails to create.

Examples

use cyclonedds::{ReadCondition, state};

let topic = Topic::<Data>::new(&participant, "MyTopic")?;
let reader = Reader::new(&topic)?;
let condition = ReadCondition::new(&reader, state::sample::Fresh)?;

pub fn mask(&self) -> Result<State>

Returns the state mask this condition was created with.

Errors

Returns an Error if the mask returned by the read condition is invalid.

Examples

use cyclonedds::{ReadCondition, state};

let topic = Topic::<Data>::new(&participant, "MyTopic")?;
let reader = Reader::new(&topic)?;
let condition = ReadCondition::new(&reader, state::sample::Fresh)?;
assert_eq!(condition.mask()?, state::sample::Fresh);

pub fn triggered(&self) -> Result<bool>

Returns true if this condition is currently triggered.

A condition is triggered when samples matching its mask are available in the reader cache.

Errors

Returns an Error if the read condition fails to read the trigger state.

Examples

use cyclonedds::{ReadCondition, state};

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

let condition = ReadCondition::new(&reader, state::sample::Fresh)?;
writer.write(&Data::default())?;
assert!(condition.triggered()?);
Ok::<_, cyclonedds::Error>(())

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

where T: Clone,

Removes and returns all samples matching this condition’s mask from the reader cache.

Errors

Returns an Error if the read condition fails to take samples.

Examples

use cyclonedds::{ReadCondition, state};

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

let condition = ReadCondition::new(
    &reader,
    state::sample::Stale | state::instance::Any | state::view::Any,
)?;
writer.write(&Data::default())?;

// No sample matches this state initially.
let samples = condition.take()?;
assert_eq!(samples.len(), 0);

// Attempt a normal read.
assert_eq!(reader.read()?.len(), 1);

// Sample should now match this state because they're stale.
let samples = condition.take()?;
assert_eq!(samples.len(), 1);

// Samples should be removed from the cache.
assert_eq!(condition.take()?.len(), 0);

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

where T: Clone,

Returns all samples matching this condition’s mask without removing them from the reader cache.

Errors

Returns an Error if the read condition fails to read samples.

Examples

use cyclonedds::{ReadCondition, state};

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

let condition = ReadCondition::new(
    &reader,
    state::sample::Stale | state::instance::Any | state::view::Any,
)?;
writer.write(&Data::default())?;

// No sample matches this state initially.
let samples = condition.read()?;
assert_eq!(samples.len(), 0);

// Attempt a normal read.
assert_eq!(reader.read()?.len(), 1);

// Sample should now match this state because they're stale.
let samples = condition.read()?;
assert_eq!(samples.len(), 1);

// Samples remain in the cache.
assert_eq!(condition.read()?.len(), 1);

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

where T: Clone,

Returns all samples matching this condition’s mask without marking them as read or removing them from the cache.

Errors

Returns an Error if the read condition fails to peek samples.

Examples

use cyclonedds::{ReadCondition, state};

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

let condition = ReadCondition::new(
    &reader,
    state::sample::Stale | state::instance::Any | state::view::Any,
)?;
writer.write(&Data::default())?;

// No sample matches this state initially.
let samples = condition.peek()?;
assert_eq!(samples.len(), 0);

// Attempt a normal read.
assert_eq!(reader.read()?.len(), 1);

// Sample should now match this state because they're stale.
let samples = condition.peek()?;
assert_eq!(samples.len(), 1);

// Samples remain in the cache.
assert_eq!(condition.peek()?.len(), 1);

Trait Implementations

impl<'domain, 'participant, 'topic, 'reader, T> Debug for ReadCondition<'domain, 'participant, 'topic, 'reader, T>

where T: Topicable + Debug,

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

Formats the value using the given formatter.

impl<T> Drop for ReadCondition<'_, '_, '_, '_, 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 ReadCondition<'_, '_, '_, '_, 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.