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};
     }
 }