From 79d23a0b907fb6d6ea4f9c699aaef8f677e61b3c Mon Sep 17 00:00:00 2001 From: Eirik A Date: Fri, 19 Apr 2024 20:06:32 +0100 Subject: [PATCH] Fix minor broken doc links and add missing feature flag (#1471) * Fix minor broken doc links and add missing feature flag Signed-off-by: clux * suggestion + another broken link Signed-off-by: clux --------- Signed-off-by: clux --- kube-runtime/src/reflector/mod.rs | 17 ++++++++++++++++- kube-runtime/src/reflector/store.rs | 4 ++++ kube-runtime/src/scheduler.rs | 4 ++-- kube-runtime/src/utils/watch_ext.rs | 2 ++ 4 files changed, 24 insertions(+), 3 deletions(-) diff --git a/kube-runtime/src/reflector/mod.rs b/kube-runtime/src/reflector/mod.rs index 2c6048ba9..85726175d 100644 --- a/kube-runtime/src/reflector/mod.rs +++ b/kube-runtime/src/reflector/mod.rs @@ -17,7 +17,7 @@ pub use store::{store, Store}; /// Cache objects from a [`watcher()`] stream into a local [`Store`] /// -/// Observes the raw [`Stream`] of [`watcher::Event`] objects, and modifies the cache. +/// Observes the raw `Stream` of [`watcher::Event`] objects, and modifies the cache. /// It passes the raw [`watcher()`] stream through unmodified. /// /// ## Usage @@ -98,6 +98,21 @@ pub use store::{store, Store}; /// Additionally, only `labels`, `annotations` and `managed_fields` are safe to drop from `ObjectMeta`. /// /// For more information check out: for graphs and techniques. +/// +/// ## Stream sharing +/// +/// `reflector()` as an interface may optionally create a stream that can be +/// shared with other components to help with resource usage. +/// +/// To share a stream, the `Writer` consumed by `reflector()` must be +/// created through an interface that allows a store to be subscribed on, such +/// as [`store_shared()`]. When the store supports being subscribed on, it will +/// broadcast an event to all active listeners after caching any object +/// contained in the event. +/// +/// Creating subscribers requires an +/// [`unstable`](https://github.com/kube-rs/kube/blob/main/kube-runtime/Cargo.toml#L17-L21) +/// feature pub fn reflector(mut writer: store::Writer, stream: W) -> impl Stream where K: Lookup + Clone, diff --git a/kube-runtime/src/reflector/store.rs b/kube-runtime/src/reflector/store.rs index a78976c19..15db23d34 100644 --- a/kube-runtime/src/reflector/store.rs +++ b/kube-runtime/src/reflector/store.rs @@ -83,6 +83,10 @@ where /// /// Multiple subscribe handles may be obtained, by either calling /// `subscribe` multiple times, or by calling `clone()` + /// + /// This function returns a `Some` when the [`Writer`] is constructed through + /// [`Writer::new_shared`] or [`store_shared`], and a `None` otherwise. + #[cfg(feature = "unstable-runtime-subscribe")] pub fn subscribe(&self) -> Option> { self.dispatcher .as_ref() diff --git a/kube-runtime/src/scheduler.rs b/kube-runtime/src/scheduler.rs index 4c009bce2..d3dbb2c8d 100644 --- a/kube-runtime/src/scheduler.rs +++ b/kube-runtime/src/scheduler.rs @@ -1,4 +1,4 @@ -//! Delays and deduplicates [`Stream`] items +//! Delays and deduplicates [`Stream`](futures::stream::Stream) items use futures::{stream::Fuse, Stream, StreamExt}; use hashbrown::{hash_map::Entry, HashMap}; @@ -251,7 +251,7 @@ where } } -/// Stream transformer that delays and deduplicates [`Stream`] items. +/// Stream transformer that delays and deduplicates items. /// /// Items are deduplicated: if an item is submitted multiple times before being emitted then it will only be /// emitted at the earliest `Instant`. diff --git a/kube-runtime/src/utils/watch_ext.rs b/kube-runtime/src/utils/watch_ext.rs index f2033fc3d..1e2af1b62 100644 --- a/kube-runtime/src/utils/watch_ext.rs +++ b/kube-runtime/src/utils/watch_ext.rs @@ -277,6 +277,8 @@ pub trait WatchStreamExt: Stream { /// /// /// [`Store`]: crate::reflector::Store + /// [`subscribe()`]: crate::reflector::store::Writer::subscribe() + /// [`Stream`]: futures::stream::Stream /// [`ReflectHandle`]: crate::reflector::dispatcher::ReflectHandle /// ## Usage /// ```no_run