From 71743c403c1b47d90f8cfc44cc327bdd11033e62 Mon Sep 17 00:00:00 2001 From: Gus Wynn Date: Thu, 9 Jun 2022 16:03:24 -0700 Subject: [PATCH] docs and cleanup the type parameters --- tracing-subscriber/src/reload.rs | 93 +++++++++++++++++++------------- 1 file changed, 57 insertions(+), 36 deletions(-) diff --git a/tracing-subscriber/src/reload.rs b/tracing-subscriber/src/reload.rs index bab7767c59..b2a0a837b2 100644 --- a/tracing-subscriber/src/reload.rs +++ b/tracing-subscriber/src/reload.rs @@ -1,15 +1,26 @@ //! Wrapper for a `Collect` or `Subscribe` to allow it to be dynamically reloaded. //! -//! This module provides a type implementing [`Subscribe`] which wraps another type implementing -//! the [`Subscribe`] trait, allowing the wrapped type to be replaced with another +//! This module provides a type implementing [`Subscribe`] and [`Filter`] +//! which wraps another type implementing the corresponding trait. This +//! allows the wrapped type to be replaced with another //! instance of that type at runtime. //! -//! This can be used in cases where a subset of `Collect` functionality +//! This can be used in cases where a subset of `Collect` or `Filter` functionality //! should be dynamically reconfigured, such as when filtering directives may //! change at runtime. Note that this subscriber introduces a (relatively small) //! amount of overhead, and should thus only be used as needed. //! +//! ## Note +//! +//! The [`Subscribe`] implementation is unable to implement downcasting functionality, +//! so certain `Subscribers` fail to function properly if wrapped in a +//! `reload::Subscriber`. +//! +//! If you only want to be able to dynamically change the +//! `Filter` on your layer, prefer wrapping that `Filter` in the `reload::Subscriber`. +//! //! [`Subscribe`]: crate::Subscribe +//! [`Filter`]: crate::subscribe::Filter use crate::subscribe; use crate::sync::RwLock; @@ -23,7 +34,10 @@ use tracing_core::{ span, Event, Metadata, }; -/// Wraps a `Collect` or `Subscribe`, allowing it to be reloaded dynamically at runtime. +/// Wraps a `Filter` or `Subscribe`, allowing it to be reloaded dynamically at runtime. +/// +/// [`Filter`]: crate::subscribe::Filter +/// [`Subscribe`]: crate::Subscribe #[derive(Debug)] pub struct Subscriber { // TODO(eliza): this once used a `crossbeam_util::ShardedRwLock`. We may @@ -119,25 +133,6 @@ where } } -impl Subscriber { - /// Wraps the given `Subscribe`, returning a subscriber and a `Handle` that allows - /// the inner type to be modified at runtime. - pub fn new(inner: S) -> (Self, Handle) { - let this = Self { - inner: Arc::new(RwLock::new(inner)), - }; - let handle = this.handle(); - (this, handle) - } - - /// Returns a `Handle` that can be used to reload the wrapped `Subscribe`. - pub fn handle(&self) -> Handle { - Handle { - inner: Arc::downgrade(&self.inner), - } - } -} - #[cfg(all(feature = "registry", feature = "std"))] #[cfg_attr(docsrs, doc(cfg(all(feature = "registry", feature = "std"))))] impl crate::subscribe::Filter for Subscriber @@ -191,24 +186,50 @@ where } } +impl Subscriber { + /// Wraps the given `Subscribe` or `Filter`, + /// returning a subscriber or filter and a `Handle` that allows + /// the inner type to be modified at runtime. + /// + /// [`Filter`]: crate::subscribe::Filter + /// [`Subscribe`]: crate::Subscribe + pub fn new(inner: T) -> (Self, Handle) { + let this = Self { + inner: Arc::new(RwLock::new(inner)), + }; + let handle = this.handle(); + (this, handle) + } + + /// Returns a `Handle` that can be used to reload the wrapped `Subscribe`. + pub fn handle(&self) -> Handle { + Handle { + inner: Arc::downgrade(&self.inner), + } + } +} + // ===== impl Handle ===== -impl Handle { - /// Replace the current subscriber with the provided `new_subscriber`. +impl Handle { + /// Replace the current subscriber or filter with the provided `new_object`. /// - /// **Warning:** The [`Filtered`](crate::filter::Filtered) type currently can't be changed + /// **Warning:** If this `Handle` is being used with the [`Filtered`](crate::filter::Filtered) + /// subscriber, it currently can't be changed /// at runtime via the [`Handle::reload`] method. /// Use the [`Handle::modify`] method to change the filter instead. - /// (see ) - pub fn reload(&self, new_subscriber: impl Into) -> Result<(), Error> { - self.modify(|subscriber| { - *subscriber = new_subscriber.into(); + /// (see ) However, if you only want to change + /// the underlying [`Filter`](crate::subscribe::Filter), then use the `reload::Subscriber` to + /// wrap the `Filter` itself. + pub fn reload(&self, new_object: impl Into) -> Result<(), Error> { + self.modify(|object| { + *object = new_object.into(); }) } /// Invokes a closure with a mutable reference to the current subscriber, /// allowing it to be modified in place. - pub fn modify(&self, f: impl FnOnce(&mut S)) -> Result<(), Error> { + pub fn modify(&self, f: impl FnOnce(&mut T)) -> Result<(), Error> { let inner = self.inner.upgrade().ok_or(Error { kind: ErrorKind::CollectorGone, })?; @@ -235,16 +256,16 @@ impl Handle { /// Returns a clone of the subscriber's current value if it still exists. /// Otherwise, if the collector has been dropped, returns `None`. - pub fn clone_current(&self) -> Option + pub fn clone_current(&self) -> Option where - S: Clone, + T: Clone, { - self.with_current(S::clone).ok() + self.with_current(T::clone).ok() } /// Invokes a closure with a borrowed reference to the current subscriber, /// returning the result (or an error if the collector no longer exists). - pub fn with_current(&self, f: impl FnOnce(&S) -> T) -> Result { + pub fn with_current(&self, f: impl FnOnce(&T) -> Output) -> Result { let inner = self.inner.upgrade().ok_or(Error { kind: ErrorKind::CollectorGone, })?; @@ -253,7 +274,7 @@ impl Handle { } } -impl Clone for Handle { +impl Clone for Handle { fn clone(&self) -> Self { Handle { inner: self.inner.clone(),