PR #38 changes #1

examples/multi_input.rs

@@ -12,11 +12,11 @@ fn main() {
         .target(Stream::to_stdout())
         .metrics();
 
-    // will output metrics twice, once with "cool.yeah" prefix and once with "cool.ouch" prefix.
+    // will output metrics twice, once with "both.yeah" prefix and once with "both.ouch" prefix.
     let same_type_metrics = MultiInput::new()
         .target(Stream::to_stderr().named("yeah"))
         .target(Stream::to_stderr().named("ouch"))
-        .named("cool")
+        .named("both")
         .metrics();
 
     loop {

examples/multi_output.rs

@@ -12,11 +12,11 @@ fn main() {
         .target(Stream::to_stdout())
         .metrics();
 
-    // will output metrics twice, once with "cool.yeah" prefix and once with "cool.ouch" prefix.
+    // will output metrics twice, once with "both.yeah" prefix and once with "both.ouch" prefix.
     let same_type_metrics = MultiOutput::new()
         .target(Stream::to_stderr().named("yeah"))
         .target(Stream::to_stderr().named("ouch"))
-        .named("out_both").metrics();
+        .named("both").metrics();
 
     loop {
         different_type_metrics.new_metric("counter_a".into(), InputKind::Counter).write(123, labels![]);

src/cache/cache_in.rs

@@ -10,12 +10,14 @@ use core::error;
 use std::sync::{Arc, RwLock};
 
 /// Wrap an input with a metric definition cache.
-/// This can provide performance benefits for metrics that are dynamically defined at runtime.
-/// Caching is useless if all metrics are statically declared.
+/// This can provide performance benefits for metrics that are dynamically defined at runtime on each access.
+/// Caching is useless if all metrics are statically declared
+/// or instantiated programmatically in advance and referenced by a long living variable.
 pub trait CachedInput: Input + Send + Sync + 'static + Sized {
     /// Wrap an input with a metric definition cache.
-    /// This can provide performance benefits for metrics that are dynamically defined at runtime.
-    /// Caching is useless if all metrics are statically declared.
+    /// This can provide performance benefits for metrics that are dynamically defined at runtime on each access.
+    /// Caching is useless if all metrics are statically declared
+    /// or instantiated programmatically in advance and referenced by a long living variable.
     fn cached(self, max_size: usize) -> InputCache {
         InputCache::wrap(self, max_size)
     }

src/cache/cache_out.rs

@@ -12,12 +12,14 @@ use std::sync::{Arc, RwLock};
 use std::rc::Rc;
 
 /// Wrap an output with a metric definition cache.
-/// This can provide performance benefits for metrics that are dynamically defined at runtime.
-/// Caching is useless if all metrics are statically declared.
+/// This can provide performance benefits for metrics that are dynamically defined at runtime on each access.
+/// Caching is useless if all metrics are statically declared
+/// or instantiated programmatically in advance and referenced by a long living variable.
 pub trait CachedOutput: Output + Send + Sync + 'static + Sized {
     /// Wrap an output with a metric definition cache.
-    /// This can provide performance benefits for metrics that are dynamically defined at runtime.
-    /// Caching is useless if all metrics are statically declared.
+    /// This can provide performance benefits for metrics that are dynamically defined at runtime on each access.
+    /// Caching is useless if all metrics are statically declared
+    /// or instantiated programmatically in advance and referenced by a long living variable.
     fn cached(self, max_size: usize) -> OutputCache {
         OutputCache::wrap(self, max_size)
     }

src/core/mod.rs

@@ -30,7 +30,7 @@ pub mod test {
 
     #[test]
     fn test_to_void() {
-        let c = void::Void::metrics().metrics();
+        let c = void::Void::new().metrics();
         let m = c.new_metric("test".into(), input::InputKind::Marker);
         m.write(33, labels![]);
     }

src/core/void.rs

@@ -7,7 +7,7 @@ use std::sync::Arc;
 
 lazy_static! {
     /// The reference instance identifying an uninitialized metric config.
-    pub static ref VOID_INPUT: Arc<InputDyn + Send + Sync> = Arc::new(Void::metrics());
+    pub static ref VOID_INPUT: Arc<InputDyn + Send + Sync> = Arc::new(Void::new());
 
     /// The reference instance identifying an uninitialized metric scope.
     pub static ref NO_METRIC_SCOPE: Arc<InputScope + Send + Sync> = VOID_INPUT.input_dyn();
@@ -17,9 +17,6 @@ lazy_static! {
 #[derive(Clone)]
 pub struct Void {}
 
-/// Discard metrics output.
-#[derive(Clone)]
-pub struct VoidInput {}
 
 /// Discard metrics output.
 #[derive(Clone)]
@@ -27,7 +24,13 @@ pub struct VoidOutput {}
 
 impl Void {
     /// Void metrics builder.
+    #[deprecated(since="0.7.2", note="Use new()")]
     pub fn metrics() -> Self {
+        Self::new()
+    }
+
+    /// Void metrics builder.
+    pub fn new() -> Self {
         Void {}
     }
 }

src/lib.rs

@@ -34,6 +34,7 @@ pub use core::output::{Output, OutputDyn, OutputScope, OutputMetric};
 pub use core::scheduler::{ScheduleFlush, CancelHandle};
 pub use core::locking::LockingOutput;
 pub use core::error::{Result};
+pub use core::void::{Void};
 pub use core::clock::{TimeHandle};
 pub use core::label::{Labels, AppLabel, ThreadLabel};