metrics: stabilize RuntimeMetrics::worker_count

This PR stabilizes a single metric API to start the process of stabilizing metrics.
Future work will continue to stabilize more metrics.

Refs: tokio-rs#6546

tokio/src/macros/cfg.rs

@@ -215,22 +215,41 @@ macro_rules! cfg_macros {
     }
 }
 
+// When running tests in loom, mocks are used instead of metrics.
 macro_rules! cfg_metrics {
     ($($item:item)*) => {
         $(
-            // For now, metrics is only disabled in loom tests.
-            // When stabilized, it might have a dedicated feature flag.
+            #[cfg(not(loom))]
+            $item
+        )*
+    }
+}
+
+// See https://github.com/tokio-rs/tokio/issues/6546, https://github.com/tokio-rs/tokio/issues/4073
+macro_rules! cfg_unstable_metrics {
+    ($($item:item)*) => {
+        $(
             #[cfg(all(tokio_unstable, not(loom)))]
             #[cfg_attr(docsrs, doc(cfg(tokio_unstable)))]
             $item
         )*
     }
 }
 
+macro_rules! cfg_not_unstable_metrics {
+    ($($item:item)*) => {
+        $(
+            #[cfg(any(not(tokio_unstable), loom))]
+            $item
+        )*
+    }
+}
+
+// Swap in mock metrics when loom is active
 macro_rules! cfg_not_metrics {
     ($($item:item)*) => {
         $(
-            #[cfg(not(all(tokio_unstable, not(loom))))]
+            #[cfg(loom)]
             $item
         )*
     }
@@ -487,6 +506,18 @@ macro_rules! cfg_unstable {
     };
 }
 
+macro_rules! cfg_net_and_unstable {
+    ($($item:item)*) => {
+        $(
+            #[cfg(tokio_unstable)]
+            #[cfg_attr(docsrs, doc(cfg(tokio_unstable)))]
+            #[cfg(feature = "net")]
+            #[cfg_attr(docsrs, doc(cfg(feature = "net")))]
+            $item
+        )*
+    };
+}
+
 macro_rules! cfg_not_trace {
     ($($item:item)*) => {
         $(

tokio/src/runtime/blocking/pool.rs

@@ -40,7 +40,7 @@ impl SpawnerMetrics {
         self.num_idle_threads.load(Ordering::Relaxed)
     }
 
-    cfg_metrics! {
+    cfg_unstable_metrics! {
         fn queue_depth(&self) -> usize {
             self.queue_depth.load(Ordering::Relaxed)
         }
@@ -474,7 +474,7 @@ impl Spawner {
     }
 }
 
-cfg_metrics! {
+cfg_unstable_metrics! {
     impl Spawner {
         pub(crate) fn num_threads(&self) -> usize {
             self.inner.metrics.num_threads()

tokio/src/runtime/builder.rs

@@ -956,7 +956,7 @@ impl Builder {
         }
     }
 
-    cfg_metrics! {
+    cfg_unstable_metrics! {
         /// Enables tracking the distribution of task poll times.
         ///
         /// Task poll times are not instrumented by default as doing so requires

tokio/src/runtime/coop.rs

@@ -197,7 +197,7 @@ cfg_coop! {
     }
 
     cfg_rt! {
-        cfg_metrics! {
+        cfg_unstable_metrics! {
             #[inline(always)]
             fn inc_budget_forced_yield_count() {
                 let _ = context::with_current(|handle| {
@@ -206,7 +206,7 @@ cfg_coop! {
             }
         }
 
-        cfg_not_metrics! {
+        cfg_not_unstable_metrics! {
             #[inline(always)]
             fn inc_budget_forced_yield_count() {}
         }

tokio/src/runtime/handle.rs

@@ -401,6 +401,17 @@ cfg_metrics! {
     impl Handle {
         /// Returns a view that lets you get information about how the runtime
         /// is performing.
+        ///
+        /// # Examples
+        /// ```
+        /// use tokio::runtime::Handle;
+        ///
+        /// #[tokio::main]
+        /// async fn main() {
+        ///   let metrics = Handle::current().metrics();
+        ///   println!("The runtime has {} workers", metrics.num_workers());
+        /// }
+        /// ```
         pub fn metrics(&self) -> RuntimeMetrics {
             RuntimeMetrics::new(self.clone())
         }

tokio/src/runtime/io/metrics.rs

@@ -17,7 +17,7 @@ cfg_not_rt_and_metrics_and_net! {
 
 cfg_net! {
     cfg_rt! {
-        cfg_metrics! {
+        cfg_unstable_metrics! {
             pub(crate) use crate::runtime::IoDriverMetrics;
         }
     }

tokio/src/runtime/metrics/mod.rs

@@ -9,27 +9,35 @@
 #![allow(clippy::module_inception)]
 
 cfg_metrics! {
-    mod batch;
-    pub(crate) use batch::MetricsBatch;
-
-    mod histogram;
-    pub(crate) use histogram::{Histogram, HistogramBatch, HistogramBuilder};
-    #[allow(unreachable_pub)] // rust-lang/rust#57411
-    pub use histogram::HistogramScale;
-
     mod runtime;
-    #[allow(unreachable_pub)] // rust-lang/rust#57411
     pub use runtime::RuntimeMetrics;
 
-    mod scheduler;
-    pub(crate) use scheduler::SchedulerMetrics;
+    cfg_unstable_metrics! {
+        mod batch;
+        pub(crate) use batch::MetricsBatch;
+
+        mod histogram;
+        pub(crate) use histogram::{HistogramBatch, HistogramBuilder, Histogram};
+
+        mod scheduler;
+        pub(crate) use scheduler::SchedulerMetrics;
+
+        mod worker;
+        pub(crate) use worker::WorkerMetrics;
+
+        cfg_net_and_unstable! {
+            mod io;
+            pub(crate) use io::IoDriverMetrics;
+        }
+
+        #[allow(unreachable_pub)] // rust-lang/rust#57411
+        pub use histogram::HistogramScale;
+    }
 
-    mod worker;
-    pub(crate) use worker::WorkerMetrics;
+    cfg_not_unstable_metrics! {
+        mod mock;
 
-    cfg_net! {
-        mod io;
-        pub(crate) use io::IoDriverMetrics;
+        pub(crate) use mock::{SchedulerMetrics, WorkerMetrics, MetricsBatch, HistogramBuilder};
     }
 }
 

tokio/src/runtime/metrics/runtime.rs

@@ -1,9 +1,5 @@
 use crate::runtime::Handle;
 
-use std::ops::Range;
-use std::sync::atomic::Ordering::Relaxed;
-use std::time::Duration;
-
 /// Handle to the runtime's metrics.
 ///
 /// This handle is internally reference-counted and can be freely cloned. A
@@ -15,6 +11,12 @@ pub struct RuntimeMetrics {
     handle: Handle,
 }
 
+cfg_unstable_metrics! {
+    use std::time::Duration;
+    use std::sync::atomic::Ordering::Relaxed;
+    use std::ops::Range;
+}
+
 impl RuntimeMetrics {
     pub(crate) fn new(handle: Handle) -> RuntimeMetrics {
         RuntimeMetrics { handle }
@@ -43,6 +45,8 @@ impl RuntimeMetrics {
         self.handle.inner.num_workers()
     }
 
+    cfg_unstable_metrics! {
+
     /// Returns the number of additional threads spawned by the runtime.
     ///
     /// The number of workers is set by configuring `max_blocking_threads` on
@@ -833,10 +837,13 @@ impl RuntimeMetrics {
     pub fn blocking_queue_depth(&self) -> usize {
         self.handle.inner.blocking_queue_depth()
     }
+    }
 }
 
 cfg_net! {
     impl RuntimeMetrics {
+        cfg_unstable_metrics! {
+
         /// Returns the number of file descriptors that have been registered with the
         /// runtime's I/O driver.
         ///
@@ -921,4 +928,5 @@ cfg_net! {
                 .unwrap_or(0)
         }
     }
+    }
 }

tokio/src/runtime/mod.rs

@@ -388,21 +388,21 @@ cfg_rt! {
     mod thread_id;
     pub(crate) use thread_id::ThreadId;
 
+    pub(crate) mod metrics;
     cfg_metrics! {
-        mod metrics;
-        pub use metrics::{RuntimeMetrics, HistogramScale};
+        pub use metrics::RuntimeMetrics;
 
-        pub(crate) use metrics::{MetricsBatch, SchedulerMetrics, WorkerMetrics, HistogramBuilder};
+        cfg_unstable_metrics! {
+            pub use metrics::HistogramScale;
 
-        cfg_net! {
-        pub(crate) use metrics::IoDriverMetrics;
+            cfg_net! {
+                pub(crate) use metrics::IoDriverMetrics;
+            }
         }
     }
 
-    cfg_not_metrics! {
-        pub(crate) mod metrics;
-        pub(crate) use metrics::{SchedulerMetrics, WorkerMetrics, MetricsBatch, HistogramBuilder};
-    }
+    pub(crate) use metrics::{MetricsBatch, SchedulerMetrics, WorkerMetrics, HistogramBuilder};
+
 
     /// After thread starts / before thread stops
     type Callback = std::sync::Arc<dyn Fn() + Send + Sync>;

tokio/src/runtime/runtime.rs

@@ -455,6 +455,14 @@ impl Runtime {
     pub fn shutdown_background(self) {
         self.shutdown_timeout(Duration::from_nanos(0));
     }
+
+    cfg_metrics! {
+        /// Returns a view that lets you get information about how the runtime
+        /// is performing.
+        pub fn metrics(&self) -> crate::runtime::RuntimeMetrics {
+            self.handle.metrics()
+        }
+    }
 }
 
 #[allow(clippy::single_match)] // there are comments in the error branch, so we don't want if-let
@@ -486,13 +494,3 @@ impl Drop for Runtime {
 impl std::panic::UnwindSafe for Runtime {}
 
 impl std::panic::RefUnwindSafe for Runtime {}
-
-cfg_metrics! {
-    impl Runtime {
-        /// Returns a view that lets you get information about how the runtime
-        /// is performing.
-        pub fn metrics(&self) -> crate::runtime::RuntimeMetrics {
-            self.handle.metrics()
-        }
-    }
-}

tokio/src/runtime/scheduler/current_thread/mod.rs

@@ -502,7 +502,7 @@ impl Handle {
     }
 }
 
-cfg_metrics! {
+cfg_unstable_metrics! {
     impl Handle {
         pub(crate) fn scheduler_metrics(&self) -> &SchedulerMetrics {
             &self.shared.scheduler_metrics

tokio/src/runtime/scheduler/inject.rs

@@ -16,7 +16,7 @@ cfg_rt_multi_thread! {
     mod rt_multi_thread;
 }
 
-cfg_metrics! {
+cfg_unstable_metrics! {
     mod metrics;
 }
 

tokio/src/runtime/scheduler/mod.rs

@@ -164,8 +164,6 @@ cfg_rt! {
     }
 
     cfg_metrics! {
-        use crate::runtime::{SchedulerMetrics, WorkerMetrics};
-
         impl Handle {
             pub(crate) fn num_workers(&self) -> usize {
                 match self {
@@ -176,6 +174,13 @@ cfg_rt! {
                     Handle::MultiThreadAlt(handle) => handle.num_workers(),
                 }
             }
+        }
+    }
+
+    cfg_unstable_metrics! {
+        use crate::runtime::{SchedulerMetrics, WorkerMetrics};
+        impl Handle {
+
 
             pub(crate) fn num_blocking_threads(&self) -> usize {
                 match_flavor!(self, Handle(handle) => handle.num_blocking_threads())

tokio/src/runtime/scheduler/multi_thread/handle.rs

@@ -9,9 +9,7 @@ use crate::util::RngSeedGenerator;
 
 use std::fmt;
 
-cfg_metrics! {
-    mod metrics;
-}
+mod metrics;
 
 cfg_taskdump! {
     mod taskdump;

tokio/src/runtime/scheduler/multi_thread/handle/metrics.rs

@@ -1,12 +1,13 @@
 use super::Handle;
 
-use crate::runtime::{SchedulerMetrics, WorkerMetrics};
-
 impl Handle {
     pub(crate) fn num_workers(&self) -> usize {
         self.shared.worker_metrics.len()
     }
+}
 
+cfg_unstable_metrics! {
+impl Handle {
     pub(crate) fn num_blocking_threads(&self) -> usize {
         self.blocking_spawner.num_threads()
     }
@@ -19,11 +20,11 @@ impl Handle {
         self.shared.owned.active_tasks_count()
     }
 
-    pub(crate) fn scheduler_metrics(&self) -> &SchedulerMetrics {
+    pub(crate) fn scheduler_metrics(&self) -> &crate::runtime::SchedulerMetrics {
         &self.shared.scheduler_metrics
     }
 
-    pub(crate) fn worker_metrics(&self, worker: usize) -> &WorkerMetrics {
+    pub(crate) fn worker_metrics(&self, worker: usize) -> &crate::runtime::WorkerMetrics {
         &self.shared.worker_metrics[worker]
     }
 
@@ -39,3 +40,4 @@ impl Handle {
         self.blocking_spawner.queue_depth()
     }
 }
+}

tokio/src/runtime/scheduler/multi_thread/queue.rs

@@ -546,7 +546,7 @@ impl<T> Steal<T> {
     }
 }
 
-cfg_metrics! {
+cfg_unstable_metrics! {
     impl<T> Steal<T> {
         pub(crate) fn len(&self) -> usize {
             self.0.len() as _