From 2a329ec3ab31381a439ec06da512355034dec8b5 Mon Sep 17 00:00:00 2001 From: Jeremy Fitzhardinge Date: Mon, 13 Sep 2021 10:53:19 -0700 Subject: [PATCH] chore: docs and tests cleanups(#1556) * small doc cleanups * subscriber: Use NoSubscriber in Layer tests No need for another no-op subscriber. * subscriber: add some compile-time tests for dyn Layer Make sure that `Box>` and `Arc>` meet all the constraints to be actually usable. --- tracing-core/src/subscriber.rs | 4 +-- tracing-subscriber/src/fmt/writer.rs | 22 ++++++++---- tracing-subscriber/src/layer/tests.rs | 48 ++++++++++++--------------- tracing/src/lib.rs | 3 +- tracing/src/span.rs | 3 +- 5 files changed, 42 insertions(+), 38 deletions(-) diff --git a/tracing-core/src/subscriber.rs b/tracing-core/src/subscriber.rs index 6e943808fd..f6113a0add 100644 --- a/tracing-core/src/subscriber.rs +++ b/tracing-core/src/subscriber.rs @@ -564,10 +564,10 @@ impl Interest { } } -/// A no-op [`Subscriber`] +/// A no-op [`Subscriber`]. /// /// [`NoSubscriber`] implements the [`Subscriber`] trait by never being enabled, -/// never being interested in any callsite, and drops all spans and events. +/// never being interested in any callsite, and dropping all spans and events. #[derive(Debug, Copy, Clone)] pub struct NoSubscriber(()); diff --git a/tracing-subscriber/src/fmt/writer.rs b/tracing-subscriber/src/fmt/writer.rs index 23dafaf4d7..c91ed70164 100644 --- a/tracing-subscriber/src/fmt/writer.rs +++ b/tracing-subscriber/src/fmt/writer.rs @@ -319,7 +319,7 @@ pub trait MakeWriterExt: MakeWriter { /// determine if a writer should be produced for a given span or event. /// /// If the predicate returns `false`, the wrapped [`MakeWriter`]'s - /// [`make_writer_for`][mwf] will return [`OptionalWriter::none`]. + /// [`make_writer_for`][mwf] will return [`OptionalWriter::none`][own]. /// Otherwise, it calls the wrapped [`MakeWriter`]'s /// [`make_writer_for`][mwf] method, and returns the produced writer. /// @@ -384,6 +384,7 @@ pub trait MakeWriterExt: MakeWriter { /// /// [`Metadata`]: tracing_core::Metadata /// [mwf]: MakeWriter::make_writer_for + /// [own]: EitherWriter::none fn with_filter(self, filter: F) -> WithFilter where Self: Sized, @@ -449,7 +450,7 @@ pub trait MakeWriterExt: MakeWriter { /// Combines `self` with another type implementing [`MakeWriter`], returning /// a new [`MakeWriter`] that calls `other`'s [`make_writer`] if `self`'s - /// `make_writer` returns [`OptionalWriter::none`]. + /// `make_writer` returns [`OptionalWriter::none`][own]. /// /// # Examples /// @@ -469,6 +470,7 @@ pub trait MakeWriterExt: MakeWriter { /// ``` /// /// [`make_writer`]: MakeWriter::make_writer + /// [own]: EitherWriter::none fn or_else(self, other: B) -> OrElse where Self: MakeWriter> + Sized, @@ -585,13 +587,15 @@ pub struct WithMinLevel { /// A [`MakeWriter`] combinator that wraps a [`MakeWriter`] with a predicate for /// span and event [`Metadata`], so that the [`MakeWriter::make_writer_for`] -/// method returns [`OptionalWriter::some`] when the predicate returns `true`, -/// and [`OptionalWriter::none`] when the predicate returns `false`. +/// method returns [`OptionalWriter::some`][ows] when the predicate returns `true`, +/// and [`OptionalWriter::none`][own] when the predicate returns `false`. /// /// This is returned by the [`MakeWriterExt::with_filter`] method. See the /// method documentation for details. /// /// [`Metadata`]: tracing_core::Metadata +/// [ows]: EitherWriter::some +/// [own]: EitherWriter::none #[derive(Copy, Clone, Debug, Eq, PartialEq)] pub struct WithFilter { make: M, @@ -600,10 +604,12 @@ pub struct WithFilter { /// Combines a [`MakeWriter`] that returns an [`OptionalWriter`] with another /// [`MakeWriter`], so that the second [`MakeWriter`] is used when the first -/// [`MakeWriter`] returns [`OptionalWriter::none`]. +/// [`MakeWriter`] returns [`OptionalWriter::none`][own]. /// /// This is returned by the [`MakeWriterExt::or_else] method. See the /// method documentation for details. +/// +/// [own]: EitherWriter::none #[derive(Copy, Clone, Debug, Eq, PartialEq)] pub struct OrElse { inner: A, @@ -818,12 +824,13 @@ impl From> for OptionalWriter { impl WithMaxLevel { /// Wraps the provided [`MakeWriter`] with a maximum [`Level`], so that it - /// returns [`OptionalWriter::none`] for spans and events whose level is + /// returns [`OptionalWriter::none`][own] for spans and events whose level is /// more verbose than the maximum level. /// /// See [`MakeWriterExt::with_max_level`] for details. /// /// [`Level`]: tracing_core::Level + /// [own]: EitherWriter::none pub fn new(make: M, level: tracing_core::Level) -> Self { Self { make, level } } @@ -851,12 +858,13 @@ impl MakeWriter for WithMaxLevel { impl WithMinLevel { /// Wraps the provided [`MakeWriter`] with a minimum [`Level`], so that it - /// returns [`OptionalWriter::none`] for spans and events whose level is + /// returns [`OptionalWriter::none`][own] for spans and events whose level is /// less verbose than the maximum level. /// /// See [`MakeWriterExt::with_min_level`] for details. /// /// [`Level`]: tracing_core::Level + /// [own]: EitherWriter::none pub fn new(make: M, level: tracing_core::Level) -> Self { Self { make, level } } diff --git a/tracing-subscriber/src/layer/tests.rs b/tracing-subscriber/src/layer/tests.rs index 68ac956a37..34c91a7c86 100644 --- a/tracing-subscriber/src/layer/tests.rs +++ b/tracing-subscriber/src/layer/tests.rs @@ -1,26 +1,5 @@ use super::*; - -pub(crate) struct NopSubscriber; - -impl Subscriber for NopSubscriber { - fn register_callsite(&self, _: &'static Metadata<'static>) -> Interest { - Interest::never() - } - - fn enabled(&self, _: &Metadata<'_>) -> bool { - false - } - - fn new_span(&self, _: &span::Attributes<'_>) -> span::Id { - span::Id::from_u64(1) - } - - fn record(&self, _: &span::Id, _: &span::Record<'_>) {} - fn record_follows_from(&self, _: &span::Id, _: &span::Id) {} - fn event(&self, _: &Event<'_>) {} - fn enter(&self, _: &span::Id) {} - fn exit(&self, _: &span::Id) {} -} +use tracing_core::subscriber::NoSubscriber; #[derive(Debug)] pub(crate) struct NopLayer; @@ -64,16 +43,19 @@ impl Subscriber for StringSubscriber { } fn assert_subscriber(_s: impl Subscriber) {} +fn assert_layer(_l: &impl Layer) {} #[test] fn layer_is_subscriber() { - let s = NopLayer.with_subscriber(NopSubscriber); + let s = NopLayer.with_subscriber(NoSubscriber::default()); assert_subscriber(s) } #[test] fn two_layers_are_subscriber() { - let s = NopLayer.and_then(NopLayer).with_subscriber(NopSubscriber); + let s = NopLayer + .and_then(NopLayer) + .with_subscriber(NoSubscriber::default()); assert_subscriber(s) } @@ -82,10 +64,24 @@ fn three_layers_are_subscriber() { let s = NopLayer .and_then(NopLayer) .and_then(NopLayer) - .with_subscriber(NopSubscriber); + .with_subscriber(NoSubscriber::default()); assert_subscriber(s) } +#[test] +fn box_layer_is_layer() { + let l: Box + Send + Sync> = Box::new(NopLayer); + assert_layer(&l); + l.with_subscriber(NoSubscriber::default()); +} + +#[test] +fn arc_layer_is_layer() { + let l: Arc + Send + Sync> = Arc::new(NopLayer); + assert_layer(&l); + l.with_subscriber(NoSubscriber::default()); +} + #[test] fn downcasts_to_subscriber() { let s = NopLayer @@ -102,7 +98,7 @@ fn downcasts_to_layer() { let s = StringLayer("layer_1".into()) .and_then(StringLayer2("layer_2".into())) .and_then(StringLayer3("layer_3".into())) - .with_subscriber(NopSubscriber); + .with_subscriber(NoSubscriber::default()); let layer = ::downcast_ref::(&s).expect("layer 1 should downcast"); assert_eq!(&layer.0, "layer_1"); let layer = diff --git a/tracing/src/lib.rs b/tracing/src/lib.rs index 94e60c4ca5..cce23d5046 100644 --- a/tracing/src/lib.rs +++ b/tracing/src/lib.rs @@ -19,7 +19,6 @@ //! The `tracing` crate provides the APIs necessary for instrumenting libraries //! and applications to emit trace data. //! -//! *Compiler support: [requires `rustc` 1.42+][msrv]* //! //! [msrv]: #supported-rust-versions //! # Core Concepts @@ -118,7 +117,7 @@ //! tracing = "0.1" //! ``` //! -//! *Compiler support: requires rustc 1.39+* +//! *Compiler support: [requires `rustc` 1.42+][msrv]* //! //! ## Recording Spans and Events //! diff --git a/tracing/src/span.rs b/tracing/src/span.rs index 8e7fadcf15..c04ec07080 100644 --- a/tracing/src/span.rs +++ b/tracing/src/span.rs @@ -1021,7 +1021,8 @@ impl Span { /// [`INFO`]: crate::Level::INFO /// [`DEBUG`]: crate::Level::DEBUG /// [async tasks]: std::task - /// [`instrument`]: crate::instrument::Instrument + /// [`instrument`]: crate::instrument::Instrument::instrument + /// [`in_current_span`]: crate::instrument::Instrument::in_current_span pub fn or_current(self) -> Self { if self.is_disabled() { return Self::current();