core: support no-std + alloc (#256)

* core: support `no-std` + `alloc`

Motivation

Users have expressed interest in using `tracing` on no_std platforms
with `liballoc`.

Solution

This branch adds `no_std` support to `tracing-core` by adding a `std`
feature flag (on by default) which can be disabled to use `libcore` +
`liballoc` instead of `libstd`.

When the `std` feature is disabled, `tracing-core` will use
`spin::Mutex` rather than `std::sync::Mutex`, and the thread-local
scoped dispatcher will be disabled (since it necessitates a defined OS
threading model, which may not exist on `no_std` platforms).

Refs: #213

Signed-off-by: Eliza Weisman <[email protected]>

Author: hawkw

azure-pipelines.yml

@@ -34,6 +34,8 @@ stages:
            displayName: "Test log support"
          - bash: cd tracing/test_static_max_level_features && cargo test
            displayName: "Test static max level features"
+         - bash: cd tracing-core && cargo test --no-default-features
+           displayName: "Test tracing-core no-std support"
      - job: custom_nightly
        pool:
          vmImage: ubuntu-16.04

tracing-core/Cargo.toml

@@ -26,10 +26,18 @@ categories = [
 keywords = ["logging", "tracing", "profiling"]
 edition = "2018"
 
+[features]
+default = ["std"]
+std = []
+
 [badges]
 azure-devops = { project = "tracing/tracing", pipeline = "tokio-rs.tracing", build = "1" }
 maintenance = { status = "actively-developed" }
 
 [dependencies]
 lazy_static = "1"
 
+[target.'cfg(not(feature = "std"))'.dependencies]
+spin = "0.5"
+lazy_static = { version = "1", features = ["spin_no_std"] }
+

tracing-core/README.md

@@ -46,11 +46,33 @@ The crate provides:
 In addition, it defines the global callsite registry and per-thread current
 dispatcher which other components of the tracing system rely on.
 
+## Usage
+
 Application authors will typically not use this crate directly. Instead, they
 will use the [`tracing`] crate, which provides a much more fully-featured
 API. However, this crate's API will change very infrequently, so it may be used
 when dependencies must be very stable.
 
+`Subscriber` implementations may depend on `tracing-core` rather than `tracing`,
+as the additional APIs provided by `tracing` are primarily useful for
+instrumenting libraries and applications, and are generally not necessary for
+`Subscriber` implementations.
+
+###  Crate Feature Flags
+
+The following crate feature flags are available:
+
+* `std`: Depend on the Rust standard library (enabled by default).
+
+   `no_std` users may disable this feature with `default-features = false`:
+
+  ```toml
+  [dependencies]
+  tracing-core = { version = "0.1.4", default-features = false }
+  ```
+
+  **Note**:`tracing-core`'s `no_std` support requires `liballoc`.
+
 [`tracing`]: ../tracing
 [`Span`]: https://docs.rs/tracing-core/0.1.3/tracing_core/span/struct.Span.html
 [`Event`]: https://docs.rs/tracing-core/0.1.3/tracing_core/event/struct.Event.html

tracing-core/src/callsite.rs

@@ -1,15 +1,16 @@
 //! Callsites represent the source locations from which spans or events
 //! originate.
-use crate::{
-    dispatcher::{self, Dispatch, Registrar},
-    subscriber::Interest,
-    Metadata,
-};
-use std::{
+use crate::stdlib::{
     fmt,
     hash::{Hash, Hasher},
     ptr,
     sync::Mutex,
+    vec::Vec,
+};
+use crate::{
+    dispatcher::{self, Dispatch, Registrar},
+    subscriber::Interest,
+    Metadata,
 };
 
 lazy_static! {

tracing-core/src/dispatcher.rs

@@ -68,6 +68,7 @@
 //! # let my_dispatch = dispatcher::Dispatch::new(my_subscriber);
 //! // no default subscriber
 //!
+//! # #[cfg(feature = "std")]
 //! dispatcher::with_default(&my_dispatch, || {
 //!     // my_subscriber is the default
 //! });
@@ -113,6 +114,10 @@
 //! # }
 //! ```
 //!
+//! **Note**: the thread-local scoped dispatcher (`with_default`) requires the
+//! Rust standard library. `no_std` users should use [`set_global_default`]
+//! instead.
+//!
 //! Finally, `tokio` users should note that versions of `tokio` >= 0.1.22
 //! support an `experimental-tracing` feature flag. When this flag is enabled,
 //! the `tokio` runtime's thread pool will automatically propagate the default
@@ -138,16 +143,21 @@ use crate::{
     Event, Metadata,
 };
 
-use std::{
+use crate::stdlib::{
     any::Any,
-    cell::{Cell, RefCell},
-    error, fmt,
+    fmt,
     sync::{
         atomic::{AtomicUsize, Ordering},
         Arc, Weak,
     },
 };
 
+#[cfg(feature = "std")]
+use crate::stdlib::{
+    cell::{Cell, RefCell},
+    error,
+};
+
 /// `Dispatch` trace data to a [`Subscriber`].
 ///
 /// [`Subscriber`]: ../subscriber/trait.Subscriber.html
@@ -156,6 +166,7 @@ pub struct Dispatch {
     subscriber: Arc<dyn Subscriber + Send + Sync>,
 }
 
+#[cfg(feature = "std")]
 thread_local! {
     static CURRENT_STATE: State = State {
         default: RefCell::new(Dispatch::none()),
@@ -171,6 +182,7 @@ const INITIALIZED: usize = 2;
 static mut GLOBAL_DISPATCH: Option<Dispatch> = None;
 
 /// The dispatch state of a thread.
+#[cfg(feature = "std")]
 struct State {
     /// This thread's current default dispatcher.
     default: RefCell<Dispatch>,
@@ -186,16 +198,22 @@ struct State {
 
 /// A guard that resets the current default dispatcher to the prior
 /// default dispatcher when dropped.
+#[cfg(feature = "std")]
 struct ResetGuard(Option<Dispatch>);
 
 /// Sets this dispatch as the default for the duration of a closure.
 ///
 /// The default dispatcher is used when creating a new [span] or
 /// [`Event`].
 ///
+/// **Note**: This function requires the Rust standard library. `no_std` users
+/// should use [`set_global_default`] instead.
+///
 /// [span]: ../span/index.html
 /// [`Subscriber`]: ../subscriber/trait.Subscriber.html
 /// [`Event`]: ../event/struct.Event.html
+/// [`set_global_default`]: ../fn.set_global_default.html
+#[cfg(feature = "std")]
 pub fn with_default<T>(dispatcher: &Dispatch, f: impl FnOnce() -> T) -> T {
     // When this guard is dropped, the default dispatcher will be reset to the
     // prior default. Using this (rather than simply resetting after calling
@@ -243,6 +261,7 @@ impl fmt::Display for SetGlobalDefaultError {
     }
 }
 
+#[cfg(feature = "std")]
 impl error::Error for SetGlobalDefaultError {}
 
 /// Executes a closure with a reference to this thread's current [dispatcher].
@@ -252,6 +271,7 @@ impl error::Error for SetGlobalDefaultError {}
 /// with `Dispatch::none` rather than the previously set dispatcher.
 ///
 /// [dispatcher]: ../dispatcher/struct.Dispatch.html
+#[cfg(feature = "std")]
 pub fn get_default<T, F>(mut f: F) -> T
 where
     F: FnMut(&Dispatch) -> T,
@@ -274,14 +294,10 @@ where
 
                 let mut default = state.default.borrow_mut();
 
-                if default.is::<NoSubscriber>() && GLOBAL_INIT.load(Ordering::SeqCst) == INITIALIZED
-                {
-                    // don't redo this call on the next check
-                    unsafe {
-                        *default = GLOBAL_DISPATCH
-                            .as_ref()
-                            .expect("invariant violated: GLOBAL_DISPATCH must be initialized before GLOBAL_INIT is set")
-                            .clone()
+                if default.is::<NoSubscriber>() {
+                    if let Some(global) = get_global() {
+                        // don't redo this call on the next check
+                        *default = global.clone();
                     }
                 }
                 f(&*default)
@@ -292,6 +308,34 @@ where
         .unwrap_or_else(|_| f(&Dispatch::none()))
 }
 
+/// Executes a closure with a reference to the current [dispatcher].
+///
+/// [dispatcher]: ../dispatcher/struct.Dispatch.html
+#[cfg(not(feature = "std"))]
+pub fn get_default<T, F>(mut f: F) -> T
+where
+    F: FnMut(&Dispatch) -> T,
+{
+    if let Some(d) = get_global() {
+        f(d)
+    } else {
+        f(&Dispatch::none())
+    }
+}
+
+fn get_global() -> Option<&'static Dispatch> {
+    if GLOBAL_INIT.load(Ordering::SeqCst) != INITIALIZED {
+        return None;
+    }
+    unsafe {
+        // This is safe given the invariant that setting the global dispatcher
+        // also sets `GLOBAL_INIT` to `INITIALIZED`.
+        Some(GLOBAL_DISPATCH.as_ref().expect(
+            "invariant violated: GLOBAL_DISPATCH must be initialized before GLOBAL_INIT is set",
+        ))
+    }
+}
+
 pub(crate) struct Registrar(Weak<dyn Subscriber + Send + Sync>);
 
 impl Dispatch {
@@ -568,6 +612,7 @@ impl Registrar {
 
 // ===== impl State =====
 
+#[cfg(feature = "std")]
 impl State {
     /// Replaces the current default dispatcher on this thread with the provided
     /// dispatcher.Any
@@ -588,6 +633,7 @@ impl State {
 
 // ===== impl ResetGuard =====
 
+#[cfg(feature = "std")]
 impl Drop for ResetGuard {
     #[inline]
     fn drop(&mut self) {
@@ -602,14 +648,15 @@ impl Drop for ResetGuard {
 #[cfg(test)]
 mod test {
     use super::*;
+    #[cfg(feature = "std")]
+    use crate::stdlib::sync::atomic::{AtomicUsize, Ordering};
     use crate::{
         callsite::Callsite,
         metadata::{Kind, Level, Metadata},
         span,
         subscriber::{Interest, Subscriber},
         Event,
     };
-    use std::sync::atomic::{AtomicUsize, Ordering};
 
     #[test]
     fn dispatch_is() {
@@ -642,6 +689,7 @@ mod test {
     }
 
     #[test]
+    #[cfg(feature = "std")]
     fn events_dont_infinite_loop() {
         // This test ensures that an event triggered within a subscriber
         // won't cause an infinite loop of events.
@@ -680,6 +728,7 @@ mod test {
     }
 
     #[test]
+    #[cfg(feature = "std")]
     fn spans_dont_infinite_loop() {
         // This test ensures that a span created within a subscriber
         // won't cause an infinite loop of new spans.
@@ -740,7 +789,10 @@ mod test {
             fn enter(&self, _: &span::Id) {}
             fn exit(&self, _: &span::Id) {}
         }
+        #[cfg(feature = "std")]
         struct TestSubscriberB;
+
+        #[cfg(feature = "std")]
         impl Subscriber for TestSubscriberB {
             fn enabled(&self, _: &Metadata<'_>) -> bool {
                 true
@@ -765,6 +817,7 @@ mod test {
             )
         });
 
+        #[cfg(feature = "std")]
         with_default(&Dispatch::new(TestSubscriberB), || {
             get_default(|current| {
                 assert!(

tracing-core/src/field.rs

@@ -38,7 +38,7 @@
 //! [`event`]:  ../subscriber/trait.Subscriber.html#method.record
 //! [`Visit`]: trait.Visit.html
 use crate::callsite;
-use std::{
+use crate::stdlib::{
     borrow::Borrow,
     fmt,
     hash::{Hash, Hasher},
@@ -670,6 +670,7 @@ impl_valid_len! {
 mod test {
     use super::*;
     use crate::metadata::{Kind, Level, Metadata};
+    use crate::stdlib::{borrow::ToOwned, string::String};
 
     struct TestCallsite1;
     static TEST_CALLSITE_1: TestCallsite1 = TestCallsite1;
@@ -770,7 +771,7 @@ mod test {
 
         struct MyVisitor;
         impl Visit for MyVisitor {
-            fn record_debug(&mut self, field: &Field, _: &dyn (::std::fmt::Debug)) {
+            fn record_debug(&mut self, field: &Field, _: &dyn (crate::stdlib::fmt::Debug)) {
                 assert_eq!(field.callsite(), TEST_META_1.callsite())
             }
         }
@@ -789,7 +790,7 @@ mod test {
         let valueset = fields.value_set(values);
         let mut result = String::new();
         valueset.record(&mut |_: &Field, value: &dyn fmt::Debug| {
-            use std::fmt::Write;
+            use crate::stdlib::fmt::Write;
             write!(&mut result, "{:?}", value).unwrap();
         });
         assert_eq!(result, "123".to_owned());

tracing-core/src/lib.rs

@@ -26,15 +26,36 @@
 //! In addition, it defines the global callsite registry and per-thread current
 //! dispatcher which other components of the tracing system rely on.
 //!
+//! ## Usage
+//!
 //! Application authors will typically not use this crate directly. Instead,
-//! they will use the `tracing` crate, which provides a much more
+//! they will use the [`tracing`] crate, which provides a much more
 //! fully-featured API. However, this crate's API will change very infrequently,
 //! so it may be used when dependencies must be very stable.
 //!
+//! `Subscriber` implementations may depend on `tracing-core` rather than
+//! `tracing`, as the additional APIs provided by `tracing` are primarily useful
+//! for instrumenting libraries and applications, and are generally not
+//! necessary for `Subscriber` implementations.
+//!
 //! The [`tokio-rs/tracing`] repository contains less stable crates designed to
 //! be used with the `tracing` ecosystem. It includes a collection of
 //! `Subscriber` implementations, as well as utility and adapter crates.
 //!
+//! ### Crate Feature Flags
+//!
+//! The following crate feature flags are available:
+//!
+//! * `std`: Depend on the Rust standard library (enabled by default).
+//!
+//!   `no_std` users may disable this feature with `default-features = false`:
+//!
+//!   ```toml
+//!   [dependencies]
+//!   tracing-core = { version = "0.1.4", default-features = false }
+//!   ```
+//!   **Note**:`tracing-core`'s `no_std` support requires `liballoc`.
+//!
 //! [`Span`]: span/struct.Span.html
 //! [`Event`]: event/struct.Event.html
 //! [`Subscriber`]: subscriber/trait.Subscriber.html
@@ -47,6 +68,11 @@
 //! [`Dispatch`]: dispatcher/struct.Dispatch.html
 //! [`tokio-rs/tracing`]: https://github.com/tokio-rs/tracing
 //! [`tracing`]: https://crates.io/crates/tracing
+#![cfg_attr(not(feature = "std"), no_std)]
+
+#[cfg(not(feature = "std"))]
+extern crate alloc;
+
 #[macro_use]
 extern crate lazy_static;
 
@@ -192,6 +218,7 @@ pub mod field;
 pub mod metadata;
 mod parent;
 pub mod span;
+pub(crate) mod stdlib;
 pub mod subscriber;
 
 pub use self::{