Trait Entity 

pub trait Entity {
    // Required method
    fn id(&self) -> EntityId;

    // Provided methods
    fn instance_handle(&self) -> Result<InstanceHandle> { ... }
    fn status_changes(&self) -> Result<Status> { ... }
    fn take_status(&self, mask: Option<Status>) -> Result<Status> { ... }
    fn read_status(&self, mask: Option<Status>) -> Result<Status> { ... }
    fn status_mask(&self) -> Result<Status> { ... }
    fn set_status_mask(&self, mask: Status) -> Result<()> { ... }
}

Common interface implemented by all members of the DDS entity hierarchy.

• Participant: the root entity representing membership in a domain.
  • WaitSet: blocks until one or more attached conditions are triggered.
  • GuardCondition: a manually triggered condition for use with a WaitSet.
  • Topic<T>: names and types a data channel for a specific payload type T.
  • Publisher: groups Writers and controls their shared QoS.
    • Writer<T>: publishes samples of type T to a Topic.
  • Subscriber: groups Readers and controls their shared QoS.
    • Reader<T>: receives samples of type T from a Topic.
      • ReadCondition<T>: filters Reader samples by sample, view, and instance state.
      • QueryCondition<T, F>: filters Reader samples by sample state and a predicate.

Required Methods

fn id(&self) -> EntityId

Returns the EntityId of this entity.

Examples

use cyclonedds::entity::Entity;
use cyclonedds::{Reader, Topic, Writer};

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

// The reader and the writer have distinct IDs.
assert_ne!(reader.id(), writer.id());

Provided Methods

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

Returns the InstanceHandle of this entity.

Errors

Returns an Error specifying the reason if the instance handle fails to be retrieved.

Examples

use cyclonedds::entity::Entity;
use cyclonedds::{Reader, Topic, Writer};

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

// The reader and the writer have distinct instance handles.
assert_ne!(reader.instance_handle()?, writer.instance_handle()?);

// Instance handles can be used to identify entities across various API
// calls. For example, the writer's handle appears in the set of matched
// publications.
let matched = reader.matched_publications()?;
assert_eq!(matched[0], writer.instance_handle()?);

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

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

Errors

• Returns an Error if the status bits of the corresponding entity could not be retrieved (e.g. the entity no longer exists).

• Returns BadParameter if the retrieved bits do not correspond to a valid Status.

Examples

use cyclonedds::entity::Entity;
use cyclonedds::{Reader, Status, Topic, Writer};

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

// The reader has been created but nothing in particular has happened in
// terms of status changes.
let changed = reader.status_changes()?;
assert_eq!(changed, Status::empty());

// The writer that is created will match with the reader.
let writer = Writer::new(&topic)?;

// After a writer matches, the reader reports a status change.
let changed = reader.status_changes()?;
assert!(changed.contains(Status::SubscriptionMatched));

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

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

Unlike read_status, this clears the returned flags on the entity.

Errors

• Returns an Error if the status bits of the corresponding entity could not be retrieved (e.g. the entity no longer exists or the status mask contains entries that do not apply to the entity type).

• Returns BadParameter if the retrieved bits do not correspond to a valid Status.

Examples

use cyclonedds::entity::Entity;
use cyclonedds::{Reader, Status, Topic, Writer};

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

// The reader has matched with the writer, so its status should have
// updated.
let status = reader.take_status(Some(Status::SubscriptionMatched))?;
assert!(status.contains(Status::SubscriptionMatched));

// The flag has been cleared; a second take returns empty.
let cleared = reader.take_status(Some(Status::SubscriptionMatched))?;
assert!(cleared.is_empty());

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.

Errors

• Returns an Error if the status bits of the corresponding entity could not be retrieved (e.g. the entity no longer exists).

• Returns BadParameter if the retrieved bits do not correspond to a valid Status.

Examples

use cyclonedds::entity::Entity;
use cyclonedds::{Reader, Status, Topic, Writer};

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

// The reader has matched with the writer, so its status should have
// updated.
let status = reader.read_status(Some(Status::SubscriptionMatched))?;
assert!(status.contains(Status::SubscriptionMatched));

// The flag is preserved; a second read returns the same value.
let same = reader.read_status(Some(Status::SubscriptionMatched))?;
assert_eq!(status, same);

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

Returns the status mask enabled on the entity.

Errors

• Returns an Error if the status mask of the corresponding entity could not be retrieved (e.g. the entity no longer exists).

• Returns BadParameter if the retrieved bits do not correspond to a valid Status.

Examples

use cyclonedds::entity::Entity;
use cyclonedds::{Status, Topic, Writer};

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

// Get the initial active status mask.
assert_eq!(
    writer.status_mask()?,
    Status::OfferedDeadlineMissed
        | Status::OfferedIncompatibleQoS
        | Status::LivelinessLost
        | Status::PublicationMatched
);

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

Sets and enables a status mask on the entity.

Only status flags included in mask will trigger listener callbacks or be reported via status_changes.

Errors

• Returns an Error if the status mask of the corresponding entity could not be set (e.g. the entity no longer exists).

Examples

use cyclonedds::entity::Entity;
use cyclonedds::{Status, Topic, Writer};

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

// Set the active status mask.
writer.set_status_mask(Status::PublicationMatched)?;
// Get the active status mask.
assert_eq!(writer.status_mask()?, Status::PublicationMatched);

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl Entity for GuardCondition<'_>

impl Entity for Participant<'_>

impl Entity for Publisher<'_, '_>

impl Entity for Subscriber<'_, '_>

impl<A> Entity for WaitSet<'_, '_, '_, A>

impl<T: Topicable, F: Fn(&T) -> bool> Entity for QueryCondition<'_, '_, '_, '_, T, F>

impl<T: Topicable> Entity for ReadCondition<'_, '_, '_, '_, T>

impl<T: Topicable> Entity for Reader<'_, '_, '_, T>

impl<T: Topicable> Entity for Topic<'_, '_, T>

impl<T: Topicable> Entity for Writer<'_, '_, '_, T>