Crate cyclonedds

Expand description

The official Rust binding for Cyclone DDS.

DDS (Data Distribution Service) is a publish-subscribe middleware standard for real-time, data-centric communication. It is used in a variety of mission critical applications in domains such as aerospace, defense, autonomous systems (e.g. vehicles, robotics), industrial control, smart energy grids, transportation, simulation, and medical devices.

Participants within a specific Domain discover each other automatically via the DDSI/RTPS discovery protocol. Once two endpoints sharing the same topic name, type information, and compatible Quality of Service (QoS) discover each other, the middleware establishes a connection between them.

Publishers and Subscribers allow you to group Writers and Readers respectively to allow you to set their collective behavior. These Writers and Readers exchange typed samples via Topics.

                            DOMAIN
                               │
            ┌──────────────────┴──────────────────┐
            │                                     │
       PARTICIPANT                           PARTICIPANT
            │      T ≡ struct Position {x, y}     │
       ┌────┴────┐                           ┌────┴────┐
       │         │                           │         │
  PUBLISHER   TOPIC<T> ═══════════════════ TOPIC<T>  SUBSCRIBER
       │         ║                           ║         │
       │     "Position"                 "Position"     │
       │         ║                           ║         │
    WRITER<T> ═══╝                           ╚═══ READER<T>
         ╰───────── matched via Topic<T> ─────────╯
         Node 01                               Node 02
        ─────────                             ─────────

Data delivery characteristics, such as how samples are buffered, retransmitted, and received, are controlled via Quality of Service, a collection of QoS policies that configure characteristics such as:

durability (whether late-joining readers receive historical samples)
reliability (best-effort vs reliable delivery)
history depth (the number of samples to store in history)
deadline (whether a signal should be generated when a sample is not received within a specified period)

Policies are set independently on the writer and reader side, and compatibility is checked at discovery time. A writer’s offered QoS must be compatible with a reader’s requested QoS for the two endpoints to match.

There are a variety of other elements to the DDS API such as:

WaitSets: to allow you to block until a particular status occurs on a DDS entity. Listeners: to notify applications of a change in the status of a particular entity. GuardConditions, StatusConditions, ReadConditions, and QueryConditions: Mechanisms to trigger the condition associated with a waitset.

See the DDS Specification and the OMG DDS Wiki for these other elements and see the rest of the Rust Documentation for what is supported by this API.//!

§Getting started

Every DDS application begins with a Domain and a Participant:

use cyclonedds::{Domain, Participant};

let domain = Domain::default();
let participant = Participant::new(&domain)?;

Types that can be used as a topic payload must implement the Topicable trait, either manually or via the Topicable derive macro. Once you have a topic, create a Writer or Reader directly via new or through their builders to set QoS or to associate specific publishers or subscribers. You can then create samples and write them via the writer and read those samples back via the reader.

use cyclonedds::qos;
use cyclonedds::{QoS, Reader, Subscriber, Topic, Writer};

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

let qos = QoS::new()
    .with_reliability(qos::policy::Reliability::BestEffort)
    .with_history(qos::policy::History::KeepLast { depth: 10 });

let subscriber = Subscriber::builder(&participant).with_qos(&qos).build()?;

let writer = Writer::builder(&topic).with_qos(&qos).build()?;
let reader = Reader::builder(&topic)
    .with_qos(&qos)
    .with_subscriber(&subscriber)
    .build()?;

for x in 0..10 {
    let sample = MyData { x };
    writer.write(&sample)?;
}

// Does not remove the samples from the history,
// and does not update metadata.
for sample in reader.peek()? {
    // process sample
}

// Does not remove the samples from the history,
// but does update metadata.
for sample in reader.read()? {
    // process sample
}

// Removes the samples from the history,
// and updates metadata.
for sample in reader.take()? {
    // process sample
}

For further reading, see the Cyclone DDS documentation, the OMG DDS specification, and the examples.

Re-exports§

pub use listener::Listener;
pub use listener::PublisherListener;
pub use listener::ReaderListener;
pub use listener::SubscriberListener;
pub use listener::TopicListener;
pub use listener::WriterListener;
pub use qos::QoS;
pub use state::State;

Modules§

builder: Builder types for constructing DDS entities with custom QoS and listeners.
cdr_bounds: Traits and types for describing the serialized CDR size bounds of keys.
entity: The base of the DDS entity hierarchy.
listener: Listener types for reacting to status events on entities.
qos: Quality of Service (QoS) policies for DDS entities.
sample: Types representing received DDS samples and their associated metadata.
state: This holds the state masks that provide information on the state of a sample, of a view, or of an instance.
status: Event metadata types delivered to DDS listener callbacks.

Structs§

Domain: A communication boundary for DDS publish-subscribe traffic.
Duration: A relative span of time represented as nanoseconds.
GuardCondition: A manually triggered condition for use with a WaitSet.
Participant: A domain participant.
Publisher: A Publisher groups Writers and controls their shared QoS. Writers created under a publisher inherit its QoS where applicable.
QueryCondition: A filter on a Reader that restricts samples by their State and a predicate.
ReadCondition: A filter on a Reader that restricts samples by their State.
Reader: A data reader for topic type T.
Status: Flags for specifying the set of statuses that are of interest.
Subscriber: A Subscriber groups Readers and controls their shared QoS. Readers created under a subscriber inherit its QoS where applicable.
Time: An absolute point in time represented as nanoseconds since the UNIX epoch.
Topic: A typed communication channel.
WaitSet: An entity for blocking until one or more conditions are met.
Writer: A data writer for topic type T.

Enums§

Error: Errors that can occur during DDS operations.

Traits§

Topicable: A type that can be used as a DDS topic payload.

Type Aliases§

Key: Evaluates to the Key type associated with the Topicable type T.
Result: Result type specialized for DDS Errors.

Derive Macros§

Topicable: Derives Topicable for a named-field struct.