hiroz 0.2.0

Native Rust ROS 2 implementation using Zenoh
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148

//! # hiroz — Zenoh-native ROS 2 in pure Rust
//!
//! `hiroz` provides ROS 2-style pub/sub, services, and actions built directly
//! on [Zenoh](https://zenoh.io), with no C/C++ dependencies.
//!
//! ## Getting started
//!
//! ```rust,ignore
//! use hiroz::prelude::*;
//! use hiroz_msgs::std_msgs::String as RosString;
//!
//! let ctx = ZContextBuilder::default().build()?;
//! let node = ctx.create_node("talker").build()?;
//! let publisher = node.create_pub::<RosString>("/chatter").build()?;
//! publisher.async_publish(&RosString { data: "hello".into() }).await?;
//! ```
//!
//! ## Sync and async APIs
//!
//! Most hiroz types expose both a blocking and an async variant of each
//! operation. The naming convention is:
//!
//! | Suffix | Behaviour |
//! |--------|-----------|
//! | *(none)* | Blocking — safe to call from any context |
//! | `_async` | Async — must be `.await`ed inside a Tokio (or compatible) runtime |
//!
//! For example, [`ZPub::publish`](pubsub::ZPub::publish) blocks until
//! the put completes, while [`ZPub::async_publish`](pubsub::ZPub::async_publish)
//! yields to the async executor.
//!
//! ## Imports
//!
//! The easiest way to import all common types is via the prelude:
//!
//! ```rust,ignore
//! use hiroz::prelude::*;
//! ```
//!
//! Or import types individually from their modules.

/// ROS 2 action support (goal, feedback, result).
pub mod action;
/// Attachment helpers for carrying metadata alongside messages.
pub mod attachment;
/// Timestamp-indexed, capacity-bounded message cache.
pub mod cache;
mod common;
/// Configuration types and builder helpers.
pub mod config;
/// Zenoh session context and context builder.
pub mod context;
/// Dynamic (schema-less) message support.
pub mod dynamic;
pub mod encoding;
/// Entity identity types (`TypeHash`, `TypeInfo`).
pub mod entity;
/// Structured error types (e.g. the timeout variant) shared across the API.
pub mod error;
/// Graph events emitted by the Zenoh network graph.
pub mod event;
#[cfg(feature = "ffi")]
pub mod ffi;
/// ROS 2 graph introspection (node/topic/service discovery).
pub mod graph;
/// ROS 2 lifecycle node support (state machine, lifecycle publisher).
pub mod lifecycle;
/// Typed message wrappers and helpers.
pub mod msg;
/// ROS 2 node creation and management.
pub mod node;
/// Convenience re-exports for common hiroz types.
pub mod prelude;
/// Publishers and subscribers.
pub mod pubsub;
/// Python FFI bridge types.
pub mod python_bridge;
/// Quality-of-Service profiles and options.
pub mod qos;
/// Internal message queues.
pub mod queue;
/// Debug-time enforcement of "no user callback under a hiroz lock guard".
pub mod reentrancy;
/// Message type metadata traits (`WithTypeInfo`, etc.).
pub mod ros_msg;
/// ROS 2 service client and server.
pub mod service;
/// Shared-memory transport helpers.
pub mod shm;
/// Time and clock primitives for runtime and replay integration.
pub mod time;
/// ROS 2 topic name validation and manipulation.
pub mod topic_name;
/// Owned Zenoh buffer type.
pub mod zbuf;

/// Zero-copy buffer view for Python bindings.
#[cfg(feature = "python")]
pub mod zbuf_view;

#[macro_use]
pub mod utils;

/// ROS 2 parameter subsystem.
pub mod parameter;

pub use attachment::GidArray;
pub use entity::{TypeHash, TypeInfo};
pub use hiroz_derive::MessageTypeInfo;
pub use ros_msg::{ActionTypeInfo, MessageTypeInfo, ServiceTypeInfo, WithTypeInfo};
pub use zbuf::ZBuf;
pub use zenoh::Result;

/// Builds a configured object, consuming the builder.
///
/// All hiroz builders implement this trait. Bring it into scope to call `.build()`:
///
/// ```rust,ignore
/// use hiroz::Builder;
/// let ctx = ZContextBuilder::default().build()?;
/// ```
///
/// Alternatively, use `use hiroz::prelude::*;` which includes `Builder`.
pub trait Builder {
    /// The type produced by this builder.
    type Output;
    /// Consume the builder and construct the configured object.
    ///
    /// # Errors
    ///
    /// Returns an error if the configuration is invalid or if network/resource
    /// initialization fails (e.g. Zenoh session could not be opened).
    fn build(self) -> Result<Self::Output>;
}

impl Builder for config::RouterConfigBuilder {
    type Output = zenoh::Config;
    fn build(self) -> Result<zenoh::Config> {
        self.build_config()
    }
}

impl Builder for config::SessionConfigBuilder {
    type Output = zenoh::Config;
    fn build(self) -> Result<zenoh::Config> {
        self.build_config()
    }
}