Vendor things

third-party/vendor/tracing-subscriber/src/reload.rs

@@ -0,0 +1,384 @@
+//! Wrapper for a `Layer` to allow it to be dynamically reloaded.
+//!
+//! This module provides a [`Layer` type] implementing the [`Layer` trait] or [`Filter` trait]
+//! 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 `Layer` or `Filter` functionality
+//! should be dynamically reconfigured, such as when filtering directives may
+//! change at runtime. Note that this layer introduces a (relatively small)
+//! amount of overhead, and should thus only be used as needed.
+//!
+//! # Examples
+//!
+//! Reloading a [global filtering](crate::layer#global-filtering) layer:
+//!
+//! ```rust
+//! # use tracing::info;
+//! use tracing_subscriber::{filter, fmt, reload, prelude::*};
+//! let filter = filter::LevelFilter::WARN;
+//! let (filter, reload_handle) = reload::Layer::new(filter);
+//! tracing_subscriber::registry()
+//!   .with(filter)
+//!   .with(fmt::Layer::default())
+//!   .init();
+//! #
+//! # // specifying the Registry type is required
+//! # let _: &reload::Handle<filter::LevelFilter, tracing_subscriber::Registry> = &reload_handle;
+//! #
+//! info!("This will be ignored");
+//! reload_handle.modify(|filter| *filter = filter::LevelFilter::INFO);
+//! info!("This will be logged");
+//! ```
+//!
+//! Reloading a [`Filtered`](crate::filter::Filtered) layer:
+//!
+//! ```rust
+//! # use tracing::info;
+//! use tracing_subscriber::{filter, fmt, reload, prelude::*};
+//! let filtered_layer = fmt::Layer::default().with_filter(filter::LevelFilter::WARN);
+//! let (filtered_layer, reload_handle) = reload::Layer::new(filtered_layer);
+//! #
+//! # // specifying the Registry type is required
+//! # let _: &reload::Handle<filter::Filtered<fmt::Layer<tracing_subscriber::Registry>,
+//! # filter::LevelFilter, tracing_subscriber::Registry>,tracing_subscriber::Registry>
+//! # = &reload_handle;
+//! #
+//! tracing_subscriber::registry()
+//!   .with(filtered_layer)
+//!   .init();
+//! info!("This will be ignored");
+//! reload_handle.modify(|layer| *layer.filter_mut() = filter::LevelFilter::INFO);
+//! info!("This will be logged");
+//! ```
+//!
+//! ## Note
+//!
+//! The [`Layer`] implementation is unable to implement downcasting functionality,
+//! so certain [`Layer`] will fail to downcast if wrapped in a `reload::Layer`.
+//!
+//! If you only want to be able to dynamically change the
+//! `Filter` on a layer, prefer wrapping that `Filter` in the `reload::Layer`.
+//!
+//! [`Filter` trait]: crate::layer::Filter
+//! [`Layer` type]: Layer
+//! [`Layer` trait]: super::layer::Layer
+use crate::layer;
+use crate::sync::RwLock;
+
+use core::any::TypeId;
+use std::{
+    error, fmt,
+    marker::PhantomData,
+    sync::{Arc, Weak},
+};
+use tracing_core::{
+    callsite, span,
+    subscriber::{Interest, Subscriber},
+    Dispatch, Event, LevelFilter, Metadata,
+};
+
+/// Wraps a `Layer` or `Filter`, allowing it to be reloaded dynamically at runtime.
+#[derive(Debug)]
+pub struct Layer<L, S> {
+    // TODO(eliza): this once used a `crossbeam_util::ShardedRwLock`. We may
+    // eventually wish to replace it with a sharded lock implementation on top
+    // of our internal `RwLock` wrapper type. If possible, we should profile
+    // this first to determine if it's necessary.
+    inner: Arc<RwLock<L>>,
+    _s: PhantomData<fn(S)>,
+}
+
+/// Allows reloading the state of an associated [`Layer`](crate::layer::Layer).
+#[derive(Debug)]
+pub struct Handle<L, S> {
+    inner: Weak<RwLock<L>>,
+    _s: PhantomData<fn(S)>,
+}
+
+/// Indicates that an error occurred when reloading a layer.
+#[derive(Debug)]
+pub struct Error {
+    kind: ErrorKind,
+}
+
+#[derive(Debug)]
+enum ErrorKind {
+    SubscriberGone,
+    Poisoned,
+}
+
+// ===== impl Layer =====
+
+impl<L, S> crate::Layer<S> for Layer<L, S>
+where
+    L: crate::Layer<S> + 'static,
+    S: Subscriber,
+{
+    fn on_register_dispatch(&self, subscriber: &Dispatch) {
+        try_lock!(self.inner.read()).on_register_dispatch(subscriber);
+    }
+
+    fn on_layer(&mut self, subscriber: &mut S) {
+        try_lock!(self.inner.write(), else return).on_layer(subscriber);
+    }
+
+    #[inline]
+    fn register_callsite(&self, metadata: &'static Metadata<'static>) -> Interest {
+        try_lock!(self.inner.read(), else return Interest::sometimes()).register_callsite(metadata)
+    }
+
+    #[inline]
+    fn enabled(&self, metadata: &Metadata<'_>, ctx: layer::Context<'_, S>) -> bool {
+        try_lock!(self.inner.read(), else return false).enabled(metadata, ctx)
+    }
+
+    #[inline]
+    fn on_new_span(&self, attrs: &span::Attributes<'_>, id: &span::Id, ctx: layer::Context<'_, S>) {
+        try_lock!(self.inner.read()).on_new_span(attrs, id, ctx)
+    }
+
+    #[inline]
+    fn on_record(&self, span: &span::Id, values: &span::Record<'_>, ctx: layer::Context<'_, S>) {
+        try_lock!(self.inner.read()).on_record(span, values, ctx)
+    }
+
+    #[inline]
+    fn on_follows_from(&self, span: &span::Id, follows: &span::Id, ctx: layer::Context<'_, S>) {
+        try_lock!(self.inner.read()).on_follows_from(span, follows, ctx)
+    }
+
+    #[inline]
+    fn event_enabled(&self, event: &Event<'_>, ctx: layer::Context<'_, S>) -> bool {
+        try_lock!(self.inner.read(), else return false).event_enabled(event, ctx)
+    }
+
+    #[inline]
+    fn on_event(&self, event: &Event<'_>, ctx: layer::Context<'_, S>) {
+        try_lock!(self.inner.read()).on_event(event, ctx)
+    }
+
+    #[inline]
+    fn on_enter(&self, id: &span::Id, ctx: layer::Context<'_, S>) {
+        try_lock!(self.inner.read()).on_enter(id, ctx)
+    }
+
+    #[inline]
+    fn on_exit(&self, id: &span::Id, ctx: layer::Context<'_, S>) {
+        try_lock!(self.inner.read()).on_exit(id, ctx)
+    }
+
+    #[inline]
+    fn on_close(&self, id: span::Id, ctx: layer::Context<'_, S>) {
+        try_lock!(self.inner.read()).on_close(id, ctx)
+    }
+
+    #[inline]
+    fn on_id_change(&self, old: &span::Id, new: &span::Id, ctx: layer::Context<'_, S>) {
+        try_lock!(self.inner.read()).on_id_change(old, new, ctx)
+    }
+
+    #[inline]
+    fn max_level_hint(&self) -> Option<LevelFilter> {
+        try_lock!(self.inner.read(), else return None).max_level_hint()
+    }
+
+    #[doc(hidden)]
+    unsafe fn downcast_raw(&self, id: TypeId) -> Option<*const ()> {
+        // Safety: it is generally unsafe to downcast through a reload, because
+        // the pointer can be invalidated after the lock is dropped.
+        // `NoneLayerMarker` is a special case because it
+        // is never dereferenced.
+        //
+        // Additionally, even if the marker type *is* dereferenced (which it
+        // never will be), the pointer should be valid even if the subscriber
+        // is reloaded, because all `NoneLayerMarker` pointers that we return
+        // actually point to the global static singleton `NoneLayerMarker`,
+        // rather than to a field inside the lock.
+        if id == TypeId::of::<layer::NoneLayerMarker>() {
+            return try_lock!(self.inner.read(), else return None).downcast_raw(id);
+        }
+
+        None
+    }
+}
+
+// ===== impl Filter =====
+
+#[cfg(all(feature = "registry", feature = "std"))]
+#[cfg_attr(docsrs, doc(cfg(all(feature = "registry", feature = "std"))))]
+impl<S, L> crate::layer::Filter<S> for Layer<L, S>
+where
+    L: crate::layer::Filter<S> + 'static,
+    S: Subscriber,
+{
+    #[inline]
+    fn callsite_enabled(&self, metadata: &'static Metadata<'static>) -> Interest {
+        try_lock!(self.inner.read(), else return Interest::sometimes()).callsite_enabled(metadata)
+    }
+
+    #[inline]
+    fn enabled(&self, metadata: &Metadata<'_>, ctx: &layer::Context<'_, S>) -> bool {
+        try_lock!(self.inner.read(), else return false).enabled(metadata, ctx)
+    }
+
+    #[inline]
+    fn on_new_span(&self, attrs: &span::Attributes<'_>, id: &span::Id, ctx: layer::Context<'_, S>) {
+        try_lock!(self.inner.read()).on_new_span(attrs, id, ctx)
+    }
+
+    #[inline]
+    fn on_record(&self, span: &span::Id, values: &span::Record<'_>, ctx: layer::Context<'_, S>) {
+        try_lock!(self.inner.read()).on_record(span, values, ctx)
+    }
+
+    #[inline]
+    fn on_enter(&self, id: &span::Id, ctx: layer::Context<'_, S>) {
+        try_lock!(self.inner.read()).on_enter(id, ctx)
+    }
+
+    #[inline]
+    fn on_exit(&self, id: &span::Id, ctx: layer::Context<'_, S>) {
+        try_lock!(self.inner.read()).on_exit(id, ctx)
+    }
+
+    #[inline]
+    fn on_close(&self, id: span::Id, ctx: layer::Context<'_, S>) {
+        try_lock!(self.inner.read()).on_close(id, ctx)
+    }
+
+    #[inline]
+    fn max_level_hint(&self) -> Option<LevelFilter> {
+        try_lock!(self.inner.read(), else return None).max_level_hint()
+    }
+}
+
+impl<L, S> Layer<L, S> {
+    /// Wraps the given [`Layer`] or [`Filter`], returning a `reload::Layer`
+    /// and a `Handle` that allows the inner value to be modified at runtime.
+    ///
+    /// [`Layer`]: crate::layer::Layer
+    /// [`Filter`]: crate::layer::Filter
+    pub fn new(inner: L) -> (Self, Handle<L, S>) {
+        let this = Self {
+            inner: Arc::new(RwLock::new(inner)),
+            _s: PhantomData,
+        };
+        let handle = this.handle();
+        (this, handle)
+    }
+
+    /// Returns a `Handle` that can be used to reload the wrapped [`Layer`] or [`Filter`].
+    ///
+    /// [`Layer`]: crate::layer::Layer
+    /// [`Filter`]: crate::filter::Filter
+    pub fn handle(&self) -> Handle<L, S> {
+        Handle {
+            inner: Arc::downgrade(&self.inner),
+            _s: PhantomData,
+        }
+    }
+}
+
+// ===== impl Handle =====
+
+impl<L, S> Handle<L, S> {
+    /// Replace the current [`Layer`] or [`Filter`] with the provided `new_value`.
+    ///
+    /// [`Handle::reload`] cannot be used with the [`Filtered`] layer; use
+    /// [`Handle::modify`] instead (see [this issue] for additional details).
+    ///
+    /// However, if the _only_ the [`Filter`]  needs to be modified, use
+    /// `reload::Layer` to wrap the `Filter` directly.
+    ///
+    /// [`Layer`]: crate::layer::Layer
+    /// [`Filter`]: crate::layer::Filter
+    /// [`Filtered`]: crate::filter::Filtered
+    ///
+    /// [this issue]: https://github.com/tokio-rs/tracing/issues/1629
+    pub fn reload(&self, new_value: impl Into<L>) -> Result<(), Error> {
+        self.modify(|layer| {
+            *layer = new_value.into();
+        })
+    }
+
+    /// Invokes a closure with a mutable reference to the current layer or filter,
+    /// allowing it to be modified in place.
+    pub fn modify(&self, f: impl FnOnce(&mut L)) -> Result<(), Error> {
+        let inner = self.inner.upgrade().ok_or(Error {
+            kind: ErrorKind::SubscriberGone,
+        })?;
+
+        let mut lock = try_lock!(inner.write(), else return Err(Error::poisoned()));
+        f(&mut *lock);
+        // Release the lock before rebuilding the interest cache, as that
+        // function will lock the new layer.
+        drop(lock);
+
+        callsite::rebuild_interest_cache();
+        Ok(())
+    }
+
+    /// Returns a clone of the layer or filter's current value if it still exists.
+    /// Otherwise, if the subscriber has been dropped, returns `None`.
+    pub fn clone_current(&self) -> Option<L>
+    where
+        L: Clone,
+    {
+        self.with_current(L::clone).ok()
+    }
+
+    /// Invokes a closure with a borrowed reference to the current layer or filter,
+    /// returning the result (or an error if the subscriber no longer exists).
+    pub fn with_current<T>(&self, f: impl FnOnce(&L) -> T) -> Result<T, Error> {
+        let inner = self.inner.upgrade().ok_or(Error {
+            kind: ErrorKind::SubscriberGone,
+        })?;
+        let inner = try_lock!(inner.read(), else return Err(Error::poisoned()));
+        Ok(f(&*inner))
+    }
+}
+
+impl<L, S> Clone for Handle<L, S> {
+    fn clone(&self) -> Self {
+        Handle {
+            inner: self.inner.clone(),
+            _s: PhantomData,
+        }
+    }
+}
+
+// ===== impl Error =====
+
+impl Error {
+    fn poisoned() -> Self {
+        Self {
+            kind: ErrorKind::Poisoned,
+        }
+    }
+
+    /// Returns `true` if this error occurred because the layer was poisoned by
+    /// a panic on another thread.
+    pub fn is_poisoned(&self) -> bool {
+        matches!(self.kind, ErrorKind::Poisoned)
+    }
+
+    /// Returns `true` if this error occurred because the `Subscriber`
+    /// containing the reloadable layer was dropped.
+    pub fn is_dropped(&self) -> bool {
+        matches!(self.kind, ErrorKind::SubscriberGone)
+    }
+}
+
+impl fmt::Display for Error {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        let msg = match self.kind {
+            ErrorKind::SubscriberGone => "subscriber no longer exists",
+            ErrorKind::Poisoned => "lock poisoned",
+        };
+        f.pad(msg)
+    }
+}
+
+impl error::Error for Error {}