From de939d7b723aa6a3ac93d50b462d00c26e837214 Mon Sep 17 00:00:00 2001 From: Michael Ilyin Date: Fri, 16 Feb 2024 17:11:59 +0300 Subject: [PATCH] tags --- commons/zenoh-buffers/src/zbuf.rs | 25 ++++++------ .../zenoh-keyexpr/src/key_expr/borrowed.rs | 34 ++++++++-------- commons/zenoh-keyexpr/src/key_expr/owned.rs | 10 ++--- commons/zenoh-protocol/src/core/mod.rs | 39 ++++++++++--------- zenoh/src/handlers.rs | 2 +- 5 files changed, 57 insertions(+), 53 deletions(-) diff --git a/commons/zenoh-buffers/src/zbuf.rs b/commons/zenoh-buffers/src/zbuf.rs index 5da37aabe7..a75cead344 100644 --- a/commons/zenoh-buffers/src/zbuf.rs +++ b/commons/zenoh-buffers/src/zbuf.rs @@ -28,42 +28,42 @@ fn get_mut_unchecked(arc: &mut Arc) -> &mut T { } #[derive(Debug, Clone, Default, Eq)] -// tags{zbuf, buffer} -// tags{zbuf.clone, buffer.rcinc} +// tags{rust.zbuf.zbuf, api.buffer} +// tags{rust.zbuf.zbuf.clone, api.buffer.rcinc} pub struct ZBuf { slices: SingleOrVec, } impl ZBuf { #[must_use] - // tags{zbuf.create, buffer.create} + // tags{rust.zbuf.zbuf.empty, api.buffer.create.empty} pub fn empty() -> Self { Self::default() } - // tags{zbuf.clear} + // tags{rust.zbuf.zbuf.clear} pub fn clear(&mut self) { self.slices.clear(); } - // tags{zbuf.slices.iter} + // tags{rust.zbuf.zbuf.zslices} pub fn zslices(&self) -> impl Iterator + '_ { self.slices.as_ref().iter() } - // tags{zbuf.slices.iter} + // tags{rust.zbuf.zbuf.zslices_mut} pub fn zslices_mut(&mut self) -> impl Iterator + '_ { self.slices.as_mut().iter_mut() } - // tags{zbuf.slices.push} + // tags{rust.zbuf.zbuf.push_zslice} pub fn push_zslice(&mut self, zslice: ZSlice) { if !zslice.is_empty() { self.slices.push(zslice); } } - // tags{zbuf.splice} + // tags{rust.zbuf.zbuf.splice} pub fn splice>(&mut self, erased: Range, replacement: &[u8]) { let start = match erased.start_bound() { core::ops::Bound::Included(n) => *n, @@ -147,7 +147,7 @@ impl ZBuf { // Buffer impl Buffer for ZBuf { #[inline(always)] - // tags{zbuf.len, buffer.len} + // tags{rust.zbuf.zbuf.buffer.len, api.buffer.len} fn len(&self) -> usize { self.slices .as_ref() @@ -160,14 +160,14 @@ impl Buffer for ZBuf { impl SplitBuffer for ZBuf { type Slices<'a> = iter::Map, fn(&'a ZSlice) -> &'a [u8]>; - // tags{zbuf.slices.get} + // tags{rust.zbuf.zbuf.split_buffer.slices} fn slices(&self) -> Self::Slices<'_> { self.slices.as_ref().iter().map(ZSlice::as_slice) } } impl PartialEq for ZBuf { - // tags{zbuf.compare, buffer.compare} + // tags{rust.zbuf.zbuf.partial_eq.eq, api.buffer.compare} fn eq(&self, other: &Self) -> bool { let mut self_slices = self.slices(); let mut other_slices = other.slices(); @@ -225,6 +225,7 @@ pub struct ZBufPos { } #[derive(Debug, Clone)] +// tags{rust.zbuf.zbuf_reader} pub struct ZBufReader<'a> { inner: &'a ZBuf, cursor: ZBufPos, @@ -394,8 +395,8 @@ impl<'a> SiphonableReader for ZBufReader<'a> { } #[cfg(feature = "std")] -// tags{zbuf.read, buffer.read} impl<'a> std::io::Read for ZBufReader<'a> { + // tags{rust.zbuf.zbuf_reader.read api.buffer.read} fn read(&mut self, buf: &mut [u8]) -> std::io::Result { match ::read(self, buf) { Ok(n) => Ok(n.get()), diff --git a/commons/zenoh-keyexpr/src/key_expr/borrowed.rs b/commons/zenoh-keyexpr/src/key_expr/borrowed.rs index 3b0e0cdd55..be12b08e47 100644 --- a/commons/zenoh-keyexpr/src/key_expr/borrowed.rs +++ b/commons/zenoh-keyexpr/src/key_expr/borrowed.rs @@ -42,7 +42,7 @@ use zenoh_result::{bail, Error as ZError, ZResult}; /// * Two sets [intersect](keyexpr::intersects()) if they have at least one element in common. `a/*` intersects `*/a` on `a/a` for example. /// * One set A [includes](keyexpr::includes()) the other set B if all of B's elements are in A: `a/*/**` includes `a/b/**` /// * Two sets A and B are equal if all A includes B and B includes A. The Key Expression language is designed so that string equality is equivalent to set equality. -// tags{keyexpr} +// tags{rust.keyexpr.keyexpr, api.keyexpr} #[allow(non_camel_case_types)] #[repr(transparent)] #[derive(PartialEq, Eq, Hash)] @@ -55,8 +55,8 @@ impl keyexpr { /// Note that to be considered a valid key expression, a string MUST be canon. /// /// [`keyexpr::autocanonize`] is an alternative constructor that will canonize the passed expression before constructing it. - // tags{keyexpr.create} - // tags{keyexpr.is_canon} + // tags{rust.keyexpr.keyexpr.new, api.keyexpr.create.checked} + // tags{api.keyexpr.is_canon} pub fn new<'a, T, E>(t: &'a T) -> Result<&'a Self, E> where &'a Self: TryFrom<&'a T, Error = E>, @@ -70,7 +70,8 @@ impl keyexpr { /// Will return Err if the passed value isn't a valid key expression despite canonization. /// /// Note that this function does not allocate, and will instead mutate the passed value in place during canonization. - // tags{keyexpr.canonize} + // tags{rust.keyexpr.keyexpr.autocanonize, api.keyexpr.create.autocanonize} + // tags{api.keyexpr.canonize} pub fn autocanonize<'a, T, E>(t: &'a mut T) -> Result<&'a Self, E> where &'a Self: TryFrom<&'a T, Error = E>, @@ -81,14 +82,14 @@ impl keyexpr { } /// Returns `true` if the `keyexpr`s intersect, i.e. there exists at least one key which is contained in both of the sets defined by `self` and `other`. - /// tags{keyexpr.intersects} + /// tags{rust.keyexpr.keyexpr.intersects, api.keyexpr.intersects} pub fn intersects(&self, other: &Self) -> bool { use super::intersect::Intersector; super::intersect::DEFAULT_INTERSECTOR.intersect(self, other) } /// Returns `true` if `self` includes `other`, i.e. the set defined by `self` contains every key belonging to the set defined by `other`. - // tags{keyexpr.includes} + // tags{rust.keyexpr.keyexpr.includes, api.keyexpr.includes} pub fn includes(&self, other: &Self) -> bool { use super::include::Includer; super::include::DEFAULT_INCLUDER.includes(self, other) @@ -97,7 +98,7 @@ impl keyexpr { /// Returns the relation between `self` and `other` from `self`'s point of view ([`SetIntersectionLevel::Includes`] signifies that `self` includes `other`). /// /// Note that this is slower than [`keyexpr::intersects`] and [`keyexpr::includes`], so you should favor these methods for most applications. - // tags{keyexpr.relation_to} + // tags{rust.keyexpr.keyexpr.relation_to, api.keyexpr.relation_to} pub fn relation_to(&self, other: &Self) -> SetIntersectionLevel { use SetIntersectionLevel::*; if self.intersects(other) { @@ -127,13 +128,13 @@ impl keyexpr { /// ``` /// /// If `other` is of type `&keyexpr`, you may use `self / other` instead, as the joining becomes infallible. - // tags{keyexpr.join} + // tags{rust.keyexpr.keyexpr.join, api.keyexpr.join} pub fn join + ?Sized>(&self, other: &S) -> ZResult { OwnedKeyExpr::autocanonize(format!("{}/{}", self, other.as_ref())) } /// Returns `true` if `self` contains any wildcard character (`**` or `$*`). - // tags{keyexpr.is_wild} + // tags{rust.keyexpr.keyexpr.is_wild, api.keyexpr.is_wild} pub fn is_wild(&self) -> bool { self.0.contains(super::SINGLE_WILD as char) } @@ -166,7 +167,7 @@ impl keyexpr { /// None, /// keyexpr::new("dem$*").unwrap().get_nonwild_prefix()); /// ``` - // tags{keyexpr.get_nonwild_prefix} + // tags{rust.keyexpr.keyexpr.get_nonwild_prefix, api.keyexpr.get_nonwild_prefix} pub fn get_nonwild_prefix(&self) -> Option<&keyexpr> { match self.0.find('*') { Some(i) => match self.0[..i].rfind('/') { @@ -231,7 +232,7 @@ impl keyexpr { /// keyexpr::new("demo/example/test/**").unwrap().strip_prefix(keyexpr::new("not/a/prefix").unwrap()).is_empty() /// ); /// ``` - // tags{keyexpr.strip_prefix} + // tags{rust.keyexpr.keyexpr.strip_prefix, api.keyexpr.strip_prefix} pub fn strip_prefix(&self, prefix: &Self) -> Vec<&keyexpr> { let mut result = vec![]; 'chunks: for i in (0..=self.len()).rev() { @@ -276,7 +277,7 @@ impl keyexpr { result } - // tags{keyexpr.as_str} + // tags{rust.keyexpr.keyexpr.as_str, api.keyexpr.as_str} pub fn as_str(&self) -> &str { self } @@ -286,7 +287,7 @@ impl keyexpr { /// /// Much like [`core::str::from_utf8_unchecked`], this is memory-safe, but calling this without maintaining /// [`keyexpr`]'s invariants yourself may lead to unexpected behaviors, the Zenoh network dropping your messages. - // tags{keyexpr.create.unchecked} + // tags{rust.keyexpr.keyexpr.from_str_unchecked, api.keyexpr.create.unchecked} pub unsafe fn from_str_unchecked(s: &str) -> &Self { core::mem::transmute(s) } @@ -296,11 +297,11 @@ impl keyexpr { /// /// Much like [`core::str::from_utf8_unchecked`], this is memory-safe, but calling this without maintaining /// [`keyexpr`]'s invariants yourself may lead to unexpected behaviors, the Zenoh network dropping your messages. - // tags{keyexpr.create.unchecked} + // tags{rust.keyexpr.keyexpr.from_slice_unchecked, api.keyexpr.create.unchecked} pub unsafe fn from_slice_unchecked(s: &[u8]) -> &Self { core::mem::transmute(s) } - // tags{keyexpr.chunks} + // tags{rust.keyexpr.keyexpr.chunks, api.keyexpr.chunks} pub fn chunks(&self) -> impl Iterator + DoubleEndedIterator { self.split('/').map(|c| unsafe { // Any chunk of a valid KE is itself a valid KE => we can safely call the unchecked constructor. @@ -321,7 +322,7 @@ impl Div for &keyexpr { /// Note that [`Equals`](SetIntersectionLevel::Equals) implies [`Includes`](SetIntersectionLevel::Includes), which itself implies [`Intersects`](SetIntersectionLevel::Intersects). /// /// You can check for intersection with `level >= SetIntersecionLevel::Intersection` and for inclusion with `level >= SetIntersectionLevel::Includes`. -// tags{options.keyexpr.set_intersection_level} +// rust.keyexpr.set_intersection_level, api.options.keyexpr.set_intersection_level} #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)] pub enum SetIntersectionLevel { Disjoint, @@ -350,7 +351,6 @@ impl fmt::Display for keyexpr { } } -// tags{options.keyexpr.construction_error} #[repr(i8)] enum KeyExprConstructionError { LoneDollarStar = -1, diff --git a/commons/zenoh-keyexpr/src/key_expr/owned.rs b/commons/zenoh-keyexpr/src/key_expr/owned.rs index 65e78b323b..662f509eb0 100644 --- a/commons/zenoh-keyexpr/src/key_expr/owned.rs +++ b/commons/zenoh-keyexpr/src/key_expr/owned.rs @@ -26,7 +26,7 @@ use core::{ /// A [`Arc`] newtype that is statically known to be a valid key expression. /// /// See [`keyexpr`](super::borrowed::keyexpr). -// tags{keyexpr} +// tags{rust.keyexpr.owned_key_expr} #[derive(Clone, PartialEq, Eq, Hash, serde::Deserialize)] #[cfg_attr(feature = "std", derive(schemars::JsonSchema))] #[serde(try_from = "String")] @@ -47,7 +47,7 @@ impl OwnedKeyExpr { /// Note that to be considered a valid key expression, a string MUST be canon. /// /// [`OwnedKeyExpr::autocanonize`] is an alternative constructor that will canonize the passed expression before constructing it. - // tags{keyexpr.create} + // tags{rust.keyexpr.owned_key_expr, api.keyexpr.create.checked} pub fn new(t: T) -> Result where Self: TryFrom, @@ -58,7 +58,7 @@ impl OwnedKeyExpr { /// Canonizes the passed value before returning it as an `OwnedKeyExpr`. /// /// Will return Err if the passed value isn't a valid key expression despite canonization. - // tags{keyexpr.canonize} + // tags{rust.keyexpr.owned_key_expr.autocanonize, api.keyexpr.create.autocanonize} pub fn autocanonize(mut t: T) -> Result where Self: TryFrom, @@ -72,7 +72,7 @@ impl OwnedKeyExpr { /// # Safety /// Key Expressions must follow some rules to be accepted by a Zenoh network. /// Messages addressed with invalid key expressions will be dropped. - // tags{keyexpr.create.unchecked} + // tags{rust.keyexpr.owned_key_expr.from_string_unchecked, api.keyexpr.create.unchecked} pub unsafe fn from_string_unchecked(s: String) -> Self { Self::from_boxed_string_unchecked(s.into_boxed_str()) } @@ -80,7 +80,7 @@ impl OwnedKeyExpr { /// # Safety /// Key Expressions must follow some rules to be accepted by a Zenoh network. /// Messages addressed with invalid key expressions will be dropped. - // tags{keyexpr.create.unchecked} + // tags{rust.keyexpr.owned_key_expr.from_boxed_string_unchecked, api.keyexpr.create.unchecked} pub unsafe fn from_boxed_string_unchecked(s: Box) -> Self { OwnedKeyExpr(s.into()) } diff --git a/commons/zenoh-protocol/src/core/mod.rs b/commons/zenoh-protocol/src/core/mod.rs index 0d52273de7..fe580aa282 100644 --- a/commons/zenoh-protocol/src/core/mod.rs +++ b/commons/zenoh-protocol/src/core/mod.rs @@ -24,7 +24,8 @@ use core::{ hash::Hash, str::FromStr, }; -// tags{timestamp} +// tags{rust.uhlc.timestamp} +// tags{rust.uhlc.ntp64} pub use uhlc::{Timestamp, NTP64}; use zenoh_keyexpr::OwnedKeyExpr; use zenoh_result::{bail, zerror}; @@ -64,14 +65,16 @@ pub mod resolution; pub use resolution::*; #[derive(Debug, Clone, PartialEq, Eq)] -// tags{} +// tags{rust.property} pub struct Property { + // tags{rust.property.key} pub key: u64, + // tags{rust.property.value} pub value: Vec, } /// The kind of a `Sample`. -// tags{options.sample.kind} +// tags{rust.sample_kind, api.options.sample.kind} #[repr(u8)] #[derive(Debug, Default, Copy, Clone, PartialEq, Eq)] pub enum SampleKind { @@ -105,31 +108,31 @@ impl TryFrom for SampleKind { /// The global unique id of a zenoh peer. #[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)] #[repr(transparent)] -// tags{zid} +// tags{rust.zenoh_id, api.zid} pub struct ZenohId(uhlc::ID); impl ZenohId { - // tags{zid.MAX_SIZE} + // tags{rust.zenoh_id.max_size, api.zid.max_size} pub const MAX_SIZE: usize = 16; #[inline] - // tags{zid.size} + // tags{rust.zenoh_id.size, api.zid.size} pub fn size(&self) -> usize { self.0.size() } #[inline] - // tags{zid.to_le_bytes} + // tags{rust.zenoh_id.to_le_bytes, api.zid.to_le_bytes} pub fn to_le_bytes(&self) -> [u8; uhlc::ID::MAX_SIZE] { self.0.to_le_bytes() } - // tags{zid.rand} + // tags{rust.zenoh_id.rand, api.zid.create.rand} pub fn rand() -> ZenohId { ZenohId(uhlc::ID::rand()) } - // tags{zid.into_keyexpr} + // tags{rust.zenoh_id.into_keyexpr, api.keyexpr.create.from_zid} pub fn into_keyexpr(self) -> OwnedKeyExpr { self.into() } @@ -369,7 +372,7 @@ impl TryFrom for Priority { #[derive(Debug, Default, Copy, Clone, PartialEq, Eq)] #[repr(u8)] -// tags{options.reliability} +// tags{rust.reliability, api.options.reliability} pub enum Reliability { #[default] BestEffort, @@ -378,7 +381,7 @@ pub enum Reliability { impl Reliability { #[cfg(feature = "test")] - // tags{} + // tags{rust.reliability.rand, api.options.reliability.create.rand} pub fn rand() -> Self { use rand::Rng; @@ -393,18 +396,18 @@ impl Reliability { } #[derive(Debug, Copy, Clone, PartialEq, Eq, Default)] -// tags{} +// tags{rust.channel} pub struct Channel { - // tags{} + // tags{rust.channel.priority} pub priority: Priority, - // tags{} + // tags{rust.channel.reliability} pub reliability: Reliability, } /// The kind of congestion control. #[derive(Debug, Default, Copy, Clone, PartialEq, Eq)] #[repr(u8)] -// tags{options.congestion_control} +// tags{rust.congestion_control, api.options.congestion_control} pub enum CongestionControl { #[default] Drop = 0, @@ -414,7 +417,7 @@ pub enum CongestionControl { /// The subscription mode. #[derive(Debug, Default, Copy, Clone, PartialEq, Eq)] #[repr(u8)] -// tags{options.subscriber.mode} +// tags{rust.sub_mode, api.options.sub_mode} pub enum SubMode { #[default] Push = 0, @@ -423,7 +426,7 @@ pub enum SubMode { /// The kind of consolidation. #[derive(Debug, Clone, PartialEq, Eq, Copy)] -// tags{options.consolidation_mode} +// tags{rust.consolidation_mode, api.options.consolidation_mode} pub enum ConsolidationMode { /// No consolidation applied: multiple samples may be received for the same key-timestamp. None, @@ -441,7 +444,7 @@ pub enum ConsolidationMode { /// The `zenoh::queryable::Queryable`s that should be target of a `zenoh::Session::get()`. #[derive(Debug, Default, Clone, Copy, PartialEq, Eq)] -// tags{query.options.target} +// tags{rust.query_target, api.options.query_target} pub enum QueryTarget { #[default] BestMatching, diff --git a/zenoh/src/handlers.rs b/zenoh/src/handlers.rs index bef7b9a269..3351546fb8 100644 --- a/zenoh/src/handlers.rs +++ b/zenoh/src/handlers.rs @@ -99,7 +99,7 @@ pub fn locked(fnmut: impl FnMut(T)) -> impl Fn(T) { /// - `callback` will never be called once `drop` has started. /// - `drop` will only be called **once**, and **after every** `callback` has ended. /// - The two previous guarantees imply that `call` and `drop` are never called concurrently. -// tags{} +// tags{rust.callback_pair} pub struct CallbackPair where DropFn: FnMut() + Send + Sync + 'static,