From ae2db0131c7989d5f091cd974e96d6ffea2b2174 Mon Sep 17 00:00:00 2001 From: Luca Cominardi Date: Tue, 17 Sep 2024 16:15:09 +0200 Subject: [PATCH 01/16] Fix docs --- zenoh/src/api/query.rs | 2 ++ zenoh/src/api/queryable.rs | 9 ++++----- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/zenoh/src/api/query.rs b/zenoh/src/api/query.rs index edeb2db185..0812b3e744 100644 --- a/zenoh/src/api/query.rs +++ b/zenoh/src/api/query.rs @@ -138,6 +138,8 @@ impl Reply { } #[zenoh_macros::unstable] + // @TODO: maybe return an `Option`? + // /// Gets the id of the zenoh instance that answered this Reply. pub fn replier_id(&self) -> Option { self.replier_id.map(Into::into) diff --git a/zenoh/src/api/queryable.rs b/zenoh/src/api/queryable.rs index c0c3f76c38..60b5a2bad5 100644 --- a/zenoh/src/api/queryable.rs +++ b/zenoh/src/api/queryable.rs @@ -132,7 +132,7 @@ impl Query { self.attachment.as_mut() } - /// Sends a reply in the form of [`Sample`] to this Query. + /// Send a reply in the form of [`Sample`] to this Query. /// /// By default, queries only accept replies whose key expression intersects with the query's. /// Unless the query has enabled disjoint replies (you can check this through [`Query::accepts_replies`]), @@ -147,7 +147,7 @@ impl Query { } } - /// Sends a reply to this Query. + /// Send a put as a reply to this Query. /// /// By default, queries only accept replies whose key expression intersects with the query's. /// Unless the query has enabled disjoint replies (you can check this through [`Query::accepts_replies`]), @@ -178,8 +178,7 @@ impl Query { } } - /// Sends a error reply to this Query. - /// + /// Send an error as a reply to this Query. #[inline(always)] pub fn reply_err(&self, payload: IntoZBytes) -> ReplyErrBuilder<'_> where @@ -191,7 +190,7 @@ impl Query { } } - /// Sends a delete reply to this Query. + /// Send a delete as a reply to this Query. /// /// By default, queries only accept replies whose key expression intersects with the query's. /// Unless the query has enabled disjoint replies (you can check this through [`Query::accepts_replies`]), From a5722ddced961472fa71db121c9e13503d5a44a6 Mon Sep 17 00:00:00 2001 From: Mahmoud Mazouz Date: Wed, 18 Sep 2024 14:14:49 +0200 Subject: [PATCH 02/16] Align naming style of `zenoh_config::defaults` (#1423) --- commons/zenoh-config/src/connection_retry.rs | 17 +++----- commons/zenoh-config/src/defaults.rs | 44 ++++++++++++-------- 2 files changed, 32 insertions(+), 29 deletions(-) diff --git a/commons/zenoh-config/src/connection_retry.rs b/commons/zenoh-config/src/connection_retry.rs index 55234dcc91..80aa5334bb 100644 --- a/commons/zenoh-config/src/connection_retry.rs +++ b/commons/zenoh-config/src/connection_retry.rs @@ -16,14 +16,7 @@ use serde::{Deserialize, Serialize}; use zenoh_core::zparse_default; use zenoh_protocol::core::{EndPoint, WhatAmI}; -use crate::{ - defaults::{ - self, DEFAULT_CONNECT_EXIT_ON_FAIL, DEFAULT_CONNECT_TIMEOUT_MS, - DEFAULT_LISTEN_EXIT_ON_FAIL, DEFAULT_LISTEN_TIMEOUT_MS, - }, - mode_dependent::*, - Config, -}; +use crate::{defaults, mode_dependent::*, Config}; #[derive(Debug, Deserialize, Serialize, Clone)] pub struct ConnectionRetryModeDependentConf { @@ -128,7 +121,7 @@ pub fn get_global_listener_timeout(config: &Config) -> std::time::Duration { .listen() .timeout_ms() .get(whatami) - .unwrap_or(DEFAULT_LISTEN_TIMEOUT_MS.get(whatami).unwrap()), + .unwrap_or(defaults::listen::timeout_ms.get(whatami).unwrap()), ) } @@ -139,7 +132,7 @@ pub fn get_global_connect_timeout(config: &Config) -> std::time::Duration { .connect() .timeout_ms() .get(whatami) - .unwrap_or(DEFAULT_CONNECT_TIMEOUT_MS.get(whatami).unwrap()), + .unwrap_or(defaults::connect::timeout_ms.get(whatami).unwrap()), ) } @@ -164,7 +157,7 @@ pub fn get_retry_config( .listen() .exit_on_failure() .get(whatami) - .unwrap_or(DEFAULT_LISTEN_EXIT_ON_FAIL.get(whatami).unwrap()); + .unwrap_or(defaults::listen::exit_on_failure.get(whatami).unwrap()); } else { retry = config .connect() @@ -176,7 +169,7 @@ pub fn get_retry_config( .connect() .exit_on_failure() .get(whatami) - .unwrap_or(DEFAULT_CONNECT_EXIT_ON_FAIL.get(whatami).unwrap()); + .unwrap_or(defaults::connect::exit_on_failure.get(whatami).unwrap()); } let mut res = ConnectionRetryConf::new(whatami, exit_on_failure, retry, default_retry); diff --git a/commons/zenoh-config/src/defaults.rs b/commons/zenoh-config/src/defaults.rs index 7c98098d97..b1380873b8 100644 --- a/commons/zenoh-config/src/defaults.rs +++ b/commons/zenoh-config/src/defaults.rs @@ -30,6 +30,33 @@ macro_rules! mode_accessor { #[allow(dead_code)] pub const mode: WhatAmI = WhatAmI::Peer; +#[allow(non_upper_case_globals)] +#[allow(dead_code)] +pub mod connect { + use super::{ModeDependentValue, ModeValues}; + + pub const timeout_ms: ModeDependentValue = ModeDependentValue::Dependent(ModeValues { + router: Some(-1), + peer: Some(-1), + client: Some(0), + }); + pub const exit_on_failure: ModeDependentValue = + ModeDependentValue::Dependent(ModeValues { + router: Some(false), + peer: Some(false), + client: Some(true), + }); +} + +#[allow(non_upper_case_globals)] +#[allow(dead_code)] +pub mod listen { + use super::ModeDependentValue; + + pub const timeout_ms: ModeDependentValue = ModeDependentValue::Unique(0); + pub const exit_on_failure: ModeDependentValue = ModeDependentValue::Unique(true); +} + #[allow(non_upper_case_globals)] #[allow(dead_code)] pub mod scouting { @@ -259,23 +286,6 @@ impl Default for AclConfig { } } -pub const DEFAULT_CONNECT_TIMEOUT_MS: ModeDependentValue = - ModeDependentValue::Dependent(ModeValues { - client: Some(0), - peer: Some(-1), - router: Some(-1), - }); - -pub const DEFAULT_CONNECT_EXIT_ON_FAIL: ModeDependentValue = - ModeDependentValue::Dependent(ModeValues { - client: Some(true), - peer: Some(false), - router: Some(false), - }); - -pub const DEFAULT_LISTEN_TIMEOUT_MS: ModeDependentValue = ModeDependentValue::Unique(0); -pub const DEFAULT_LISTEN_EXIT_ON_FAIL: ModeDependentValue = ModeDependentValue::Unique(true); - impl Default for ConnectionRetryModeDependentConf { fn default() -> Self { Self { From 2ce27b2ff271244bc63ec47e88f49b1a0997aeb8 Mon Sep 17 00:00:00 2001 From: Joseph Perez Date: Wed, 18 Sep 2024 17:13:13 +0200 Subject: [PATCH 03/16] Put `SourceSn` behind unstable (#1448) --- zenoh/src/lib.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/zenoh/src/lib.rs b/zenoh/src/lib.rs index 0275cbe8be..3987a56f08 100644 --- a/zenoh/src/lib.rs +++ b/zenoh/src/lib.rs @@ -206,12 +206,12 @@ pub mod sample { #[zenoh_macros::unstable] pub use crate::api::sample::Locality; #[zenoh_macros::unstable] - pub use crate::api::sample::SourceInfo; + pub use crate::api::sample::{SourceInfo, SourceSn}; pub use crate::api::{ builders::sample::{ SampleBuilder, SampleBuilderAny, SampleBuilderDelete, SampleBuilderPut, }, - sample::{Sample, SampleFields, SampleKind, SourceSn}, + sample::{Sample, SampleFields, SampleKind}, }; } From a8e0b422310aad0905aebdcd9535233e3dbd708d Mon Sep 17 00:00:00 2001 From: Mahmoud Mazouz Date: Wed, 18 Sep 2024 17:39:00 +0200 Subject: [PATCH 04/16] Notify subscribers on `Notifier::insert_json5` (#1449) --- zenoh/src/api/config.rs | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/zenoh/src/api/config.rs b/zenoh/src/api/config.rs index 675c8a93a9..673bc5d422 100644 --- a/zenoh/src/api/config.rs +++ b/zenoh/src/api/config.rs @@ -190,7 +190,9 @@ impl Notifier { } pub fn insert_json5(&self, key: &str, value: &str) -> ZResult<()> { - self.lock_config().insert_json5(key, value) + self.lock_config().insert_json5(key, value)?; + self.notify(key); + Ok(()) } #[allow(dead_code)] From f2c351619e26ed0a2d04ccf6dcb021dae3f5be79 Mon Sep 17 00:00:00 2001 From: Mahmoud Mazouz Date: Wed, 18 Sep 2024 17:51:16 +0200 Subject: [PATCH 05/16] Hide `zenoh_buffers::reader::DidntRead` (#1447) --- Cargo.lock | 10 ------ zenoh/src/api/bytes.rs | 81 ++++++++++++++++++++++-------------------- 2 files changed, 42 insertions(+), 49 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 0ce6b3123e..c051a3914e 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -3868,16 +3868,6 @@ version = "1.3.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64" -[[package]] -name = "signal-hook" -version = "0.3.17" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "8621587d4798caf8eb44879d42e56b9a93ea5dcd315a6487c357130095b62801" -dependencies = [ - "libc", - "signal-hook-registry", -] - [[package]] name = "signal-hook-registry" version = "1.4.2" diff --git a/zenoh/src/api/bytes.rs b/zenoh/src/api/bytes.rs index d7ef8b6383..8428a5d737 100644 --- a/zenoh/src/api/bytes.rs +++ b/zenoh/src/api/bytes.rs @@ -22,7 +22,7 @@ use uhlc::Timestamp; use unwrap_infallible::UnwrapInfallible; use zenoh_buffers::{ buffer::{Buffer, SplitBuffer}, - reader::{DidntRead, HasReader, Reader}, + reader::{HasReader, Reader}, writer::HasWriter, ZBuf, ZBufReader, ZBufWriter, ZSlice, ZSliceBuffer, }; @@ -473,13 +473,16 @@ impl ZBytes { #[derive(Debug)] pub struct ZBytesReader<'a>(ZBufReader<'a>); +#[derive(Debug)] +pub struct ReadError; + #[derive(Debug)] pub enum ZReadOrDeserializeError where T: TryFrom, >::Error: Debug, { - Read(DidntRead), + Read(ReadError), Deserialize(>::Error), } @@ -1778,18 +1781,18 @@ impl From<&mut Timestamp> for ZBytes { impl Deserialize for ZSerde { type Input<'a> = &'a ZBytes; - type Error = zenoh_buffers::reader::DidntRead; + type Error = ReadError; fn deserialize(self, v: Self::Input<'_>) -> Result { let codec = Zenoh080::new(); let mut reader = v.0.reader(); - let e: Timestamp = codec.read(&mut reader)?; + let e: Timestamp = codec.read(&mut reader).map_err(|_| ReadError)?; Ok(e) } } impl TryFrom for Timestamp { - type Error = zenoh_buffers::reader::DidntRead; + type Error = ReadError; fn try_from(value: ZBytes) -> Result { ZSerde.deserialize(&value) @@ -1797,7 +1800,7 @@ impl TryFrom for Timestamp { } impl TryFrom<&ZBytes> for Timestamp { - type Error = zenoh_buffers::reader::DidntRead; + type Error = ReadError; fn try_from(value: &ZBytes) -> Result { ZSerde.deserialize(value) @@ -1805,7 +1808,7 @@ impl TryFrom<&ZBytes> for Timestamp { } impl TryFrom<&mut ZBytes> for Timestamp { - type Error = zenoh_buffers::reader::DidntRead; + type Error = ReadError; fn try_from(value: &mut ZBytes) -> Result { ZSerde.deserialize(&*value) @@ -1867,18 +1870,18 @@ impl From<&mut Encoding> for ZBytes { impl Deserialize for ZSerde { type Input<'a> = &'a ZBytes; - type Error = zenoh_buffers::reader::DidntRead; + type Error = ReadError; fn deserialize(self, v: Self::Input<'_>) -> Result { let codec = Zenoh080::new(); let mut reader = v.0.reader(); - let e: EncodingProto = codec.read(&mut reader)?; + let e: EncodingProto = codec.read(&mut reader).map_err(|_| ReadError)?; Ok(e.into()) } } impl TryFrom for Encoding { - type Error = zenoh_buffers::reader::DidntRead; + type Error = ReadError; fn try_from(value: ZBytes) -> Result { ZSerde.deserialize(&value) @@ -1886,7 +1889,7 @@ impl TryFrom for Encoding { } impl TryFrom<&ZBytes> for Encoding { - type Error = zenoh_buffers::reader::DidntRead; + type Error = ReadError; fn try_from(value: &ZBytes) -> Result { ZSerde.deserialize(value) @@ -1894,7 +1897,7 @@ impl TryFrom<&ZBytes> for Encoding { } impl TryFrom<&mut ZBytes> for Encoding { - type Error = zenoh_buffers::reader::DidntRead; + type Error = ReadError; fn try_from(value: &mut ZBytes) -> Result { ZSerde.deserialize(&*value) @@ -2628,17 +2631,17 @@ where let codec = Zenoh080::new(); let mut reader = bytes.0.reader(); - let abuf: ZBuf = codec - .read(&mut reader) - .map_err(|e| ZReadOrDeserializeErrorTuple2::One(ZReadOrDeserializeError::Read(e)))?; + let abuf: ZBuf = codec.read(&mut reader).map_err(|_| { + ZReadOrDeserializeErrorTuple2::One(ZReadOrDeserializeError::Read(ReadError)) + })?; let apld = ZBytes::new(abuf); let a = A::try_from(apld).map_err(|e| { ZReadOrDeserializeErrorTuple2::One(ZReadOrDeserializeError::Deserialize(e)) })?; - let bbuf: ZBuf = codec - .read(&mut reader) - .map_err(|e| ZReadOrDeserializeErrorTuple2::Two(ZReadOrDeserializeError::Read(e)))?; + let bbuf: ZBuf = codec.read(&mut reader).map_err(|_| { + ZReadOrDeserializeErrorTuple2::Two(ZReadOrDeserializeError::Read(ReadError)) + })?; let bpld = ZBytes::new(bbuf); let b = B::try_from(bpld).map_err(|e| { ZReadOrDeserializeErrorTuple2::Two(ZReadOrDeserializeError::Deserialize(e)) @@ -2824,25 +2827,25 @@ where let codec = Zenoh080::new(); let mut reader = bytes.0.reader(); - let abuf: ZBuf = codec - .read(&mut reader) - .map_err(|e| ZReadOrDeserializeErrorTuple3::One(ZReadOrDeserializeError::Read(e)))?; + let abuf: ZBuf = codec.read(&mut reader).map_err(|_| { + ZReadOrDeserializeErrorTuple3::One(ZReadOrDeserializeError::Read(ReadError)) + })?; let apld = ZBytes::new(abuf); let a = A::try_from(apld).map_err(|e| { ZReadOrDeserializeErrorTuple3::One(ZReadOrDeserializeError::Deserialize(e)) })?; - let bbuf: ZBuf = codec - .read(&mut reader) - .map_err(|e| ZReadOrDeserializeErrorTuple3::Two(ZReadOrDeserializeError::Read(e)))?; + let bbuf: ZBuf = codec.read(&mut reader).map_err(|_| { + ZReadOrDeserializeErrorTuple3::Two(ZReadOrDeserializeError::Read(ReadError)) + })?; let bpld = ZBytes::new(bbuf); let b = B::try_from(bpld).map_err(|e| { ZReadOrDeserializeErrorTuple3::Two(ZReadOrDeserializeError::Deserialize(e)) })?; - let cbuf: ZBuf = codec - .read(&mut reader) - .map_err(|e| ZReadOrDeserializeErrorTuple3::Three(ZReadOrDeserializeError::Read(e)))?; + let cbuf: ZBuf = codec.read(&mut reader).map_err(|_| { + ZReadOrDeserializeErrorTuple3::Three(ZReadOrDeserializeError::Read(ReadError)) + })?; let cpld = ZBytes::new(cbuf); let c = C::try_from(cpld).map_err(|e| { ZReadOrDeserializeErrorTuple3::Three(ZReadOrDeserializeError::Deserialize(e)) @@ -3053,33 +3056,33 @@ where let codec = Zenoh080::new(); let mut reader = bytes.0.reader(); - let abuf: ZBuf = codec - .read(&mut reader) - .map_err(|e| ZReadOrDeserializeErrorTuple4::One(ZReadOrDeserializeError::Read(e)))?; + let abuf: ZBuf = codec.read(&mut reader).map_err(|_| { + ZReadOrDeserializeErrorTuple4::One(ZReadOrDeserializeError::Read(ReadError)) + })?; let apld = ZBytes::new(abuf); let a = A::try_from(apld).map_err(|e| { ZReadOrDeserializeErrorTuple4::One(ZReadOrDeserializeError::Deserialize(e)) })?; - let bbuf: ZBuf = codec - .read(&mut reader) - .map_err(|e| ZReadOrDeserializeErrorTuple4::Two(ZReadOrDeserializeError::Read(e)))?; + let bbuf: ZBuf = codec.read(&mut reader).map_err(|_| { + ZReadOrDeserializeErrorTuple4::Two(ZReadOrDeserializeError::Read(ReadError)) + })?; let bpld = ZBytes::new(bbuf); let b = B::try_from(bpld).map_err(|e| { ZReadOrDeserializeErrorTuple4::Two(ZReadOrDeserializeError::Deserialize(e)) })?; - let cbuf: ZBuf = codec - .read(&mut reader) - .map_err(|e| ZReadOrDeserializeErrorTuple4::Three(ZReadOrDeserializeError::Read(e)))?; + let cbuf: ZBuf = codec.read(&mut reader).map_err(|_| { + ZReadOrDeserializeErrorTuple4::Three(ZReadOrDeserializeError::Read(ReadError)) + })?; let cpld = ZBytes::new(cbuf); let c = C::try_from(cpld).map_err(|e| { ZReadOrDeserializeErrorTuple4::Three(ZReadOrDeserializeError::Deserialize(e)) })?; - let dbuf: ZBuf = codec - .read(&mut reader) - .map_err(|e| ZReadOrDeserializeErrorTuple4::Four(ZReadOrDeserializeError::Read(e)))?; + let dbuf: ZBuf = codec.read(&mut reader).map_err(|_| { + ZReadOrDeserializeErrorTuple4::Four(ZReadOrDeserializeError::Read(ReadError)) + })?; let dpld = ZBytes::new(dbuf); let d = D::try_from(dpld).map_err(|e| { ZReadOrDeserializeErrorTuple4::Four(ZReadOrDeserializeError::Deserialize(e)) From f93a2feb8116c1199e5fbd5f71fa9e96c9f7f29a Mon Sep 17 00:00:00 2001 From: Luca Cominardi Date: Wed, 18 Sep 2024 17:53:10 +0200 Subject: [PATCH 06/16] Apply suggestions from code review Co-authored-by: Mahmoud Mazouz --- zenoh/src/api/queryable.rs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/zenoh/src/api/queryable.rs b/zenoh/src/api/queryable.rs index 31349b020e..e1a0ce5257 100644 --- a/zenoh/src/api/queryable.rs +++ b/zenoh/src/api/queryable.rs @@ -132,7 +132,7 @@ impl Query { self.attachment.as_mut() } - /// Send a reply in the form of [`Sample`] to this Query. + /// Sends a reply in the form of [`Sample`] to this Query. /// /// By default, queries only accept replies whose key expression intersects with the query's. /// Unless the query has enabled disjoint replies (you can check this through [`Query::accepts_replies`]), @@ -147,7 +147,7 @@ impl Query { } } - /// Send a put as a reply to this Query. + /// Sends a [`crate::sample::Sample`] of kind [`crate::sample::SampleKind::Put`] as a reply to this Query. /// /// By default, queries only accept replies whose key expression intersects with the query's. /// Unless the query has enabled disjoint replies (you can check this through [`Query::accepts_replies`]), @@ -178,7 +178,7 @@ impl Query { } } - /// Send an error as a reply to this Query. + /// Sends a [`crate::query::ReplyError`] as a reply to this Query. #[inline(always)] pub fn reply_err(&self, payload: IntoZBytes) -> ReplyErrBuilder<'_> where @@ -190,7 +190,7 @@ impl Query { } } - /// Send a delete as a reply to this Query. + /// Sends a [`crate::sample::Sample`] of kind [`crate::sample::SampleKind::Delete`] as a reply to this Query. /// /// By default, queries only accept replies whose key expression intersects with the query's. /// Unless the query has enabled disjoint replies (you can check this through [`Query::accepts_replies`]), From 91a883b26b625e95451a439bea1c5675a7653407 Mon Sep 17 00:00:00 2001 From: Luca Cominardi Date: Wed, 18 Sep 2024 18:17:55 +0200 Subject: [PATCH 07/16] Add #[doc(hidden)] to internal_config feature --- commons/zenoh-macros/src/lib.rs | 2 ++ 1 file changed, 2 insertions(+) diff --git a/commons/zenoh-macros/src/lib.rs b/commons/zenoh-macros/src/lib.rs index 3d5749fe6c..97a81b9e0f 100644 --- a/commons/zenoh-macros/src/lib.rs +++ b/commons/zenoh-macros/src/lib.rs @@ -196,7 +196,9 @@ pub fn internal_config(args: TokenStream, tokens: TokenStream) -> TokenStream { }; let feature_gate: Attribute = parse_quote!(#[cfg(feature = "internal_config")]); + let hide_doc: Attribute = parse_quote!(#[doc(hidden)]); attrs.push(feature_gate); + attrs.push(hide_doc); TokenStream::from(item.to_token_stream()) } From ceecf4a137103a35b6d896066d80ac843fa9d917 Mon Sep 17 00:00:00 2001 From: Luca Cominardi Date: Wed, 18 Sep 2024 18:26:31 +0200 Subject: [PATCH 08/16] Update ZBytes docs --- zenoh/src/api/bytes.rs | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/zenoh/src/api/bytes.rs b/zenoh/src/api/bytes.rs index 8428a5d737..9842cc133f 100644 --- a/zenoh/src/api/bytes.rs +++ b/zenoh/src/api/bytes.rs @@ -107,10 +107,15 @@ pub trait Deserialize { /// `ZBytes` provides convenient methods to the user for serialization/deserialization based on the default Zenoh serializer [`ZSerde`]. /// /// **NOTE 1:** Zenoh semantic and protocol take care of sending and receiving bytes without restricting the actual data types. -/// [`ZSerde`] is the default serializer/deserializer provided for convenience to the users to deal with primitives data types via -/// a simple out-of-the-box encoding. [`ZSerde`] is **NOT** by any means the only serializer/deserializer users can use nor a limitation -/// to the types supported by Zenoh. Users are free and encouraged to use any serializer/deserializer of their choice like *serde*, -/// *protobuf*, *bincode*, *flatbuffers*, etc. +/// +/// **NOTE 2:** [`ZSerde`] is the default serializer/deserializer provided for convenience to the users to deal with primitives data types via +/// a simple out-of-the-box encoding. That is, [`ZSerde`] is provided as a facilitator for simple use cases that need to send/receive data +/// over Zenoh, and doing so potentially to/from different programming languages. Make simple use cases simple and provide freedom for more +/// advanced use cases. +/// +/// **NOTE 3:** [`ZSerde`] is **NOT** by any means the only serializer/deserializer users can use nor a limitation to the types supported by Zenoh. +/// [`ZSerde`] does not have the ambition nor the plan to be a full alternative of more complete seriliazation libraries like *serde*, *protobuf*, +/// *bincode*, *flatbuffers*, etc. Users are free and encouraged to use any serializer/deserializer of their choice that better suits their use case. /// /// `ZBytes` can be used to serialize a single type: /// ```rust @@ -185,7 +190,7 @@ pub trait Deserialize { /// assert_eq!(start, end); /// ``` /// -/// **NOTE 2:** `ZBytes` may store data in non-contiguous regions of memory. +/// **NOTE 4:** `ZBytes` may store data in non-contiguous regions of memory. /// The typical case for `ZBytes` to store data in different memory regions is when data is received fragmented from the network. /// The user then can decided to use [`ZBytes::deserialize`], [`ZBytes::reader`], [`ZBytes::into`], or [`ZBytes::slices`] depending /// on their needs. From 30857ee27e42c59ca3cbcc7affcb2ee9d6d966b8 Mon Sep 17 00:00:00 2001 From: Luca Cominardi Date: Wed, 18 Sep 2024 18:29:19 +0200 Subject: [PATCH 09/16] Update ZSerde docs --- zenoh/src/api/bytes.rs | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/zenoh/src/api/bytes.rs b/zenoh/src/api/bytes.rs index 9842cc133f..634d18b864 100644 --- a/zenoh/src/api/bytes.rs +++ b/zenoh/src/api/bytes.rs @@ -242,12 +242,12 @@ impl ZBytes { Self(t.into()) } - /// Returns whether the ZBytes is empty or not. + /// Returns whether the [`ZBytes`] is empty or not. pub fn is_empty(&self) -> bool { self.0.is_empty() } - /// Returns the total number of bytes in the ZBytes. + /// Returns the total number of bytes in the [`ZBytes`]. pub fn len(&self) -> usize { self.0.len() } @@ -718,11 +718,16 @@ where /// The default serializer for [`ZBytes`]. It supports primitives types, such as: `Vec`, `uX`, `iX`, `fX`, `String`, `bool`. /// It also supports common Rust serde values like [`serde_json::Value`]. /// -/// **NOTE:** Zenoh semantic and protocol take care of sending and receiving bytes without restricting the actual data types. -/// [`ZSerde`] is the default serializer/deserializer provided for convenience to the users to deal with primitives data types via -/// a simple out-of-the-box encoding. [`ZSerde`] is **NOT** by any means the only serializer/deserializer users can use nor a limitation -/// to the types supported by Zenoh. Users are free and encouraged to use any serializer/deserializer of their choice like *serde*, -/// *protobuf*, *bincode*, *flatbuffers*, etc. +/// **NOTE 1:** Zenoh semantic and protocol take care of sending and receiving bytes without restricting the actual data types. +/// +/// **NOTE 2:** [`ZSerde`] is the default serializer/deserializer provided for convenience to the users to deal with primitives data types via +/// a simple out-of-the-box encoding. That is, [`ZSerde`] is provided as a facilitator for simple use cases that need to send/receive data +/// over Zenoh, and doing so potentially to/from different programming languages. Make simple use cases simple and provide freedom for more +/// advanced use cases. +/// +/// **NOTE 3:** [`ZSerde`] is **NOT** by any means the only serializer/deserializer users can use nor a limitation to the types supported by Zenoh. +/// [`ZSerde`] does not have the ambition nor the plan to be a full alternative of more complete seriliazation libraries like *serde*, *protobuf*, +/// *bincode*, *flatbuffers*, etc. Users are free and encouraged to use any serializer/deserializer of their choice that better suits their use case. #[derive(Clone, Copy, Debug)] pub struct ZSerde; From 6bf57ce162212a16984c0d7e646911b523e3f282 Mon Sep 17 00:00:00 2001 From: Luca Cominardi Date: Wed, 18 Sep 2024 18:31:14 +0200 Subject: [PATCH 10/16] Update ZSerde docs --- zenoh/src/api/bytes.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/zenoh/src/api/bytes.rs b/zenoh/src/api/bytes.rs index 634d18b864..c0ac34a27a 100644 --- a/zenoh/src/api/bytes.rs +++ b/zenoh/src/api/bytes.rs @@ -716,7 +716,7 @@ where } /// The default serializer for [`ZBytes`]. It supports primitives types, such as: `Vec`, `uX`, `iX`, `fX`, `String`, `bool`. -/// It also supports common Rust serde values like [`serde_json::Value`]. +/// It also supports common Rust serde values like [`serde_json::Value`]. See [`ZBytes`] for examples. /// /// **NOTE 1:** Zenoh semantic and protocol take care of sending and receiving bytes without restricting the actual data types. /// From 543560e574d95bcaf4edbf79fb4adc7d6fb91b00 Mon Sep 17 00:00:00 2001 From: Luca Cominardi Date: Wed, 18 Sep 2024 18:36:11 +0200 Subject: [PATCH 11/16] Fix ZBytesIterator docs --- zenoh/src/api/bytes.rs | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/zenoh/src/api/bytes.rs b/zenoh/src/api/bytes.rs index c0ac34a27a..4f39c204cd 100644 --- a/zenoh/src/api/bytes.rs +++ b/zenoh/src/api/bytes.rs @@ -676,6 +676,18 @@ impl<'a> Iterator for ZBytesSliceIterator<'a> { /// An iterator that implements [`std::iter::Iterator`] trait to iterate on values `T` in a [`ZBytes`]. /// Note that [`ZBytes`] contains a serialized version of `T` and iterating over a [`ZBytes`] performs lazy deserialization. +/// +/// Example: +/// ```rust +/// use zenoh::bytes::ZBytes; +/// +/// let list: Vec = vec![1.1, 2.2, 3.3]; +/// let mut zbs = ZBytes::from_iter(list.iter()); +/// +/// for (index, elem) in zbs.iter::().enumerate() { +/// assert_eq!(list[index], elem.unwrap()); +/// } +/// ``` #[repr(transparent)] #[derive(Debug)] pub struct ZBytesIterator<'a, T> { From e3c04b9d4a16b69c7d0ce53fbf173cc108b33aab Mon Sep 17 00:00:00 2001 From: Luca Cominardi Date: Wed, 18 Sep 2024 18:43:14 +0200 Subject: [PATCH 12/16] Fix ZBytesWriter and ZBytesReader docs --- zenoh/src/api/bytes.rs | 39 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 37 insertions(+), 2 deletions(-) diff --git a/zenoh/src/api/bytes.rs b/zenoh/src/api/bytes.rs index 4f39c204cd..b4653eb484 100644 --- a/zenoh/src/api/bytes.rs +++ b/zenoh/src/api/bytes.rs @@ -253,6 +253,8 @@ impl ZBytes { } /// Get a [`ZBytesReader`] implementing [`std::io::Read`] trait. + /// + /// See [`ZBytesWriter`] on how to chain the deserialization of different types from a single [`ZBytes`]. pub fn reader(&self) -> ZBytesReader<'_> { ZBytesReader(self.0.reader()) } @@ -473,7 +475,7 @@ impl ZBytes { } } -/// A reader that implements [`std::io::Read`] trait to read from a [`ZBytes`]. +/// A reader that implements [`std::io::Read`] trait to deserialize from a [`ZBytes`]. See [`ZBytesWriter`] for an example. #[repr(transparent)] #[derive(Debug)] pub struct ZBytesReader<'a>(ZBufReader<'a>); @@ -552,7 +554,40 @@ impl std::io::Seek for ZBytesReader<'_> { } } -/// A writer that implements [`std::io::Write`] trait to write into a [`ZBytes`]. +/// A writer that implements [`std::io::Write`] trait to serialize into a [`ZBytes`]. +/// +/// Example: +/// ```rust +/// use zenoh::bytes::ZBytes; +/// +/// #[derive(Debug, PartialEq)] +/// struct Foo { +/// one: usize, +/// two: String, +/// three: Vec, +/// } +/// +/// let start = Foo { +/// one: 42, +/// two: String::from("Forty-Two"), +/// three: vec![42u8; 42], +/// }; +/// +/// let mut bytes = ZBytes::empty(); +/// let mut writer = bytes.writer(); +/// +/// writer.serialize(&start.one); +/// writer.serialize(&start.two); +/// writer.serialize(&start.three); +/// +/// let mut reader = bytes.reader(); +/// let end = Foo { +/// one: reader.deserialize().unwrap(), +/// two: reader.deserialize().unwrap(), +/// three: reader.deserialize().unwrap(), +/// }; +/// assert_eq!(start, end); +/// ``` #[repr(transparent)] #[derive(Debug)] pub struct ZBytesWriter<'a>(ZBufWriter<'a>); From b9de666f38bfd90731a23c71f3deea26b8b84494 Mon Sep 17 00:00:00 2001 From: Luca Cominardi Date: Wed, 18 Sep 2024 18:45:45 +0200 Subject: [PATCH 13/16] Fix ZBytesSliceIterator docs --- zenoh/src/api/bytes.rs | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/zenoh/src/api/bytes.rs b/zenoh/src/api/bytes.rs index b4653eb484..c142afb302 100644 --- a/zenoh/src/api/bytes.rs +++ b/zenoh/src/api/bytes.rs @@ -693,6 +693,32 @@ impl std::io::Write for ZBytesWriter<'_> { } /// An iterator that implements [`std::iter::Iterator`] trait to iterate on [`&[u8]`]. +/// +/// Example: +/// ```rust +/// use std::io::Write; +/// use zenoh::bytes::ZBytes; +/// +/// let buf1: Vec = vec![1, 2, 3]; +/// let buf2: Vec = vec![4, 5, 6, 7, 8]; +/// let mut zbs = ZBytes::empty(); +/// let mut writer = zbs.writer(); +/// writer.write(&buf1); +/// writer.write(&buf2); +/// +/// // Access the raw content +/// for slice in zbs.slices() { +/// println!("{:02x?}", slice); +/// } +/// +/// // Concatenate input in a single vector +/// let buf: Vec = buf1.into_iter().chain(buf2.into_iter()).collect(); +/// // Concatenate raw bytes in a single vector +/// let out: Vec = zbs.slices().fold(Vec::new(), |mut b, x| { b.extend_from_slice(x); b }); +/// // The previous line is the equivalent of +/// // let out: Vec = zbs.into(); +/// assert_eq!(buf, out); +/// ``` #[repr(transparent)] #[derive(Debug)] pub struct ZBytesSliceIterator<'a>(ZBytesSliceIteratorInner<'a>); From 55ec8c677358180242984c6afecaf4fa346ac3e0 Mon Sep 17 00:00:00 2001 From: Luca Cominardi Date: Wed, 18 Sep 2024 18:51:36 +0200 Subject: [PATCH 14/16] Fix ZenohId docs --- commons/zenoh-config/src/wrappers.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/commons/zenoh-config/src/wrappers.rs b/commons/zenoh-config/src/wrappers.rs index 10389ce979..31afe358e7 100644 --- a/commons/zenoh-config/src/wrappers.rs +++ b/commons/zenoh-config/src/wrappers.rs @@ -24,7 +24,7 @@ use zenoh_protocol::{ scouting::HelloProto, }; -/// The global unique id of a zenoh peer. +/// The global unique id of a Zenoh session. #[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize, Default)] #[repr(transparent)] pub struct ZenohId(ZenohIdProto); From b5d798d25d9b5a5145b9cb5043070bceefab7e6f Mon Sep 17 00:00:00 2001 From: Luca Cominardi Date: Wed, 18 Sep 2024 19:24:02 +0200 Subject: [PATCH 15/16] Fix docstring --- zenoh/src/api/bytes.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/zenoh/src/api/bytes.rs b/zenoh/src/api/bytes.rs index c142afb302..6958c36445 100644 --- a/zenoh/src/api/bytes.rs +++ b/zenoh/src/api/bytes.rs @@ -695,7 +695,7 @@ impl std::io::Write for ZBytesWriter<'_> { /// An iterator that implements [`std::iter::Iterator`] trait to iterate on [`&[u8]`]. /// /// Example: -/// ```rust +/// ```rust /// use std::io::Write; /// use zenoh::bytes::ZBytes; /// From 57ab8802073bd04a0914c3eeb7c2060f70d1c372 Mon Sep 17 00:00:00 2001 From: Luca Cominardi Date: Wed, 18 Sep 2024 19:30:18 +0200 Subject: [PATCH 16/16] Improve FifoChannel and RingChannel docs --- zenoh/src/api/handlers/fifo.rs | 10 +++++++--- zenoh/src/api/handlers/ring.rs | 3 +++ 2 files changed, 10 insertions(+), 3 deletions(-) diff --git a/zenoh/src/api/handlers/fifo.rs b/zenoh/src/api/handlers/fifo.rs index db73aae0ef..44a542e538 100644 --- a/zenoh/src/api/handlers/fifo.rs +++ b/zenoh/src/api/handlers/fifo.rs @@ -18,14 +18,18 @@ use std::sync::Arc; use crate::api::handlers::{callback::Callback, IntoHandler, API_DATA_RECEPTION_CHANNEL_SIZE}; -/// The default handler in Zenoh is a FIFO queue. - +/// An handler implementing FIFO semantics. +/// +/// Note that pushing on a full [`FifoChannel`] that is full will block until a slot is available. +/// E.g., a slow subscriber could block the underlying Zenoh thread because is not emptying the +/// [`FifoChannel`] fast enough. In this case, you may want to look into [`crate::api::handlers::RingChannel`] that +/// will drop samples when full. pub struct FifoChannel { capacity: usize, } impl FifoChannel { - /// Initialize the RingBuffer with the capacity size. + /// Initialize the [`FifoChannel`] with the capacity size. pub fn new(capacity: usize) -> Self { Self { capacity } } diff --git a/zenoh/src/api/handlers/ring.rs b/zenoh/src/api/handlers/ring.rs index 87bb860213..95654e57d6 100644 --- a/zenoh/src/api/handlers/ring.rs +++ b/zenoh/src/api/handlers/ring.rs @@ -27,6 +27,9 @@ use crate::api::{ }; /// A synchronous ring channel with a limited size that allows users to keep the last N data. +/// +/// [`RingChannel`] implements FIFO semantics with a dropping strategy when full. +/// The oldest elements will be dropped when newer arrive. pub struct RingChannel { capacity: usize, }