Switch from must_* to try_* naming convetion in functions (#1)

CHANGELOG.md

@@ -6,6 +6,20 @@ All user visible changes to this project will be documented in this file. This p
 
 
 
+## [0.3.0] · 2022-12-??
+[0.3.0]: /../../tree/v0.3.0
+
+[Diff](/../../compare/v0.2.0...v0.3.0)
+
+### BC Breaks
+
+- Switched functions naming convention from `must_*` for panicking to `try_*` for fallible. ([#1])
+
+[#1]: /../../pull/1
+
+
+
+
 ## [0.2.0] · 2022-12-08
 [0.2.0]: /../../tree/v0.2.0
 

README.md

@@ -47,15 +47,15 @@ To satisfy the [`metrics::Recorder`]'s requirement of allowing changing metrics
 
 ```rust
 // By default `prometheus::default_registry()` is used.
-let recorder = metrics_prometheus::must_install();
+let recorder = metrics_prometheus::install();
 
 // Either use `metrics` crate interfaces.
 metrics::increment_counter!("count", "whose" => "mine", "kind" => "owned");
 metrics::increment_counter!("count", "whose" => "mine", "kind" => "ref");
 metrics::increment_counter!("count", "kind" => "owned", "whose" => "dummy");
 
 // Or construct and provide `prometheus` metrics directly.
-recorder.register_metric(prometheus::Gauge::new("value", "help")?)?;
+recorder.register_metric(prometheus::Gauge::new("value", "help")?);
 
 let report = prometheus::TextEncoder::new()
     .encode_to_string(&prometheus::default_registry().gather())?;
@@ -132,29 +132,29 @@ Since [`prometheus`] crate validates the metrics format very strictly, not every
 
 - Metric names cannot be namespaced with dots (and should follow [Prometheus] format).
   ```rust,should_panic
-  metrics_prometheus::must_install();
+  metrics_prometheus::install();
 
   // panics: 'queries.count' is not a valid metric name
   metrics::increment_counter!("queries.count");
   ```
 
 - The same metric should use always the same set of labels:
   ```rust,should_panic
-  metrics_prometheus::must_install();
+  metrics_prometheus::install();
 
   metrics::increment_counter!("count");
   // panics: Inconsistent label cardinality, expect 0 label values, but got 1
   metrics::increment_counter!("count", "whose" => "mine");
   ```
   ```rust,should_panic
-  metrics_prometheus::must_install();
+  metrics_prometheus::install();
 
   metrics::increment_counter!("count", "kind" => "owned");
   // panics: label name kind missing in label map
   metrics::increment_counter!("count", "whose" => "mine");
   ```
   ```rust,should_panic
-  metrics_prometheus::must_install();
+  metrics_prometheus::install();
 
   metrics::increment_counter!("count", "kind" => "owned");
   // panics: Inconsistent label cardinality, expect 1 label values, but got 2
@@ -163,7 +163,7 @@ Since [`prometheus`] crate validates the metrics format very strictly, not every
 
 - The same name cannot be used for different types of metrics:
   ```rust,should_panic
-  metrics_prometheus::must_install();
+  metrics_prometheus::install();
 
   metrics::increment_counter!("count");
   // panics: Duplicate metrics collector registration attempted
@@ -172,7 +172,7 @@ Since [`prometheus`] crate validates the metrics format very strictly, not every
 
 - Any metric registered in a [`prometheus::Registry`] directly, without using [`metrics`] or this crate interfaces, is not usable via [`metrics`] facade and will cause a [`prometheus::Error`].
   ```rust,should_panic
-  metrics_prometheus::must_install();
+  metrics_prometheus::install();
   
   prometheus::default_registry()
       .register(Box::new(prometheus::Gauge::new("value", "help")?))?;
@@ -196,7 +196,7 @@ use metrics_prometheus::failure::strategy;
 
 metrics_prometheus::Recorder::builder()
     .with_failure_strategy(strategy::NoOp)
-    .must_build_and_install();
+    .build_and_install();
 
 // `prometheus::Error` is ignored inside.
 metrics::increment_counter!("invalid.name");

src/lib.rs

@@ -151,14 +151,14 @@ use thiserror as _;
 #[doc(inline)]
 pub use self::{metric::Metric, recorder::Recorder};
 
-/// Installs a default [`Recorder`] (backed by the
+/// Tries to install a default [`Recorder`] (backed by the
 /// [`prometheus::default_registry()`]) as [`metrics::recorder()`].
 ///
 /// # Errors
 ///
 /// If the [`Recorder`] fails to be installed as [`metrics::recorder()`].
-pub fn install() -> Result<Recorder, metrics::SetRecorderError> {
-    Recorder::builder().build_and_install()
+pub fn try_install() -> Result<Recorder, metrics::SetRecorderError> {
+    Recorder::builder().try_build_and_install()
 }
 
 /// Installs a default [`Recorder`] (backed by the
@@ -170,8 +170,8 @@ pub fn install() -> Result<Recorder, metrics::SetRecorderError> {
 // We do intentionally omit `#[must_use]` here, as we don't want to force
 // library users using the returned `Recorder` directly.
 #[allow(clippy::must_use_candidate)]
-pub fn must_install() -> Recorder {
-    Recorder::builder().must_build_and_install()
+pub fn install() -> Recorder {
+    Recorder::builder().build_and_install()
 }
 
 /// Ad hoc polymorphism for accepting either a reference or an owned function

src/recorder/mod.rs

@@ -21,15 +21,15 @@ pub use metrics_util::layers::Layer;
 /// # Example
 ///
 /// ```rust
-/// let recorder = metrics_prometheus::must_install();
+/// let recorder = metrics_prometheus::install();
 ///
 /// // Either use `metrics` crate interfaces.
 /// metrics::increment_counter!("count", "whose" => "mine", "kind" => "owned");
 /// metrics::increment_counter!("count", "whose" => "mine", "kind" => "ref");
 /// metrics::increment_counter!("count", "kind" => "owned", "whose" => "dummy");
 ///
 /// // Or construct and provide `prometheus` metrics directly.
-/// recorder.register_metric(prometheus::Gauge::new("value", "help")?)?;
+/// recorder.try_register_metric(prometheus::Gauge::new("value", "help")?)?;
 ///
 /// let report = prometheus::TextEncoder::new()
 ///     .encode_to_string(&prometheus::default_registry().gather())?;
@@ -128,7 +128,7 @@ pub use metrics_util::layers::Layer;
 ///
 /// metrics_prometheus::Recorder::builder()
 ///     .with_failure_strategy(strategy::Panic)
-///     .must_build_and_install();
+///     .build_and_install();
 ///
 /// metrics::increment_counter!("count", "kind" => "owned");
 /// // This panics, as such labeling is not allowed by `prometheus` crate.
@@ -195,7 +195,7 @@ impl<S> Recorder<S> {
     ///
     /// let recorder = metrics_prometheus::Recorder::builder()
     ///     .with_failure_strategy(strategy::Panic)
-    ///     .must_build_and_install();
+    ///     .build_and_install();
     ///
     /// let counter = prometheus::IntCounter::new("value", "help")?;
     /// recorder.registry().register(Box::new(counter))?;
@@ -209,7 +209,7 @@ impl<S> Recorder<S> {
         &self.storage.prometheus
     }
 
-    /// Registers the provided [`prometheus`] `metric` in the underlying
+    /// Tries to register the provided [`prometheus`] `metric` in the underlying
     /// [`prometheus::Registry`] in the way making it usable via this
     /// [`Recorder`] (and, so, [`metrics`] crate interfaces).
     ///
@@ -226,14 +226,14 @@ impl<S> Recorder<S> {
     /// # Example
     ///
     /// ```rust
-    /// let recorder = metrics_prometheus::must_install();
+    /// let recorder = metrics_prometheus::install();
     ///
     /// let counter = prometheus::IntCounterVec::new(
     ///     prometheus::opts!("value", "help"),
     ///     &["whose", "kind"],
     /// )?;
     ///
-    /// recorder.register_metric(counter.clone())?;
+    /// recorder.try_register_metric(counter.clone())?;
     ///
     /// counter.with_label_values(&["mine", "owned"]).inc();
     /// counter.with_label_values(&["foreign", "ref"]).inc_by(2);
@@ -279,7 +279,7 @@ impl<S> Recorder<S> {
     /// );
     /// # Ok::<_, prometheus::Error>(())
     /// ```
-    pub fn register_metric<M>(&self, metric: M) -> prometheus::Result<()>
+    pub fn try_register_metric<M>(&self, metric: M) -> prometheus::Result<()>
     where
         M: metric::Bundled + prometheus::core::Collector,
         <M as metric::Bundled>::Bundle:
@@ -307,14 +307,14 @@ impl<S> Recorder<S> {
     /// # Example
     ///
     /// ```rust
-    /// let recorder = metrics_prometheus::must_install();
+    /// let recorder = metrics_prometheus::install();
     ///
     /// let gauge = prometheus::GaugeVec::new(
     ///     prometheus::opts!("value", "help"),
     ///     &["whose", "kind"],
     /// )?;
     ///
-    /// recorder.must_register_metric(gauge.clone());
+    /// recorder.register_metric(gauge.clone());
     ///
     /// gauge.with_label_values(&["mine", "owned"]).inc();
     /// gauge.with_label_values(&["foreign", "ref"]).set(2.0);
@@ -360,15 +360,15 @@ impl<S> Recorder<S> {
     /// );
     /// # Ok::<_, prometheus::Error>(())
     /// ```
-    pub fn must_register_metric<M>(&self, metric: M)
+    pub fn register_metric<M>(&self, metric: M)
     where
         M: metric::Bundled + prometheus::core::Collector,
         <M as metric::Bundled>::Bundle:
             prometheus::core::Collector + Clone + 'static,
         storage::Mutable:
             storage::GetCollection<<M as metric::Bundled>::Bundle>,
     {
-        self.register_metric(metric).unwrap_or_else(|e| {
+        self.try_register_metric(metric).unwrap_or_else(|e| {
             panic!("failed to register `prometheus` metric: {e}")
         });
     }
@@ -516,7 +516,7 @@ impl<S, L> Builder<S, L> {
     ///
     /// metrics_prometheus::Recorder::builder()
     ///     .with_registry(&custom)
-    ///     .must_build_and_install();
+    ///     .build_and_install();
     ///
     /// metrics::increment_counter!("count");
     ///
@@ -564,7 +564,7 @@ impl<S, L> Builder<S, L> {
     ///
     /// metrics_prometheus::Recorder::builder()
     ///     .with_failure_strategy(strategy::NoOp)
-    ///     .must_build_and_install();
+    ///     .build_and_install();
     ///
     /// metrics::increment_counter!("invalid.name");
     ///
@@ -583,7 +583,7 @@ impl<S, L> Builder<S, L> {
         }
     }
 
-    /// Registers the provided [`prometheus`] `metric` in the underlying
+    /// Tries to register the provided [`prometheus`] `metric` in the underlying
     /// [`prometheus::Registry`] in the way making it usable via the created
     /// [`Recorder`] (and, so, [`metrics`] crate interfaces).
     ///
@@ -603,8 +603,8 @@ impl<S, L> Builder<S, L> {
     /// let gauge = prometheus::Gauge::new("value", "help")?;
     ///
     /// metrics_prometheus::Recorder::builder()
-    ///     .with_metric(gauge.clone())?
-    ///     .must_build_and_install();
+    ///     .try_with_metric(gauge.clone())?
+    ///     .build_and_install();
     ///
     /// gauge.inc();
     ///
@@ -635,7 +635,7 @@ impl<S, L> Builder<S, L> {
     /// );
     /// # Ok::<_, prometheus::Error>(())
     /// ```
-    pub fn with_metric<M>(self, metric: M) -> prometheus::Result<Self>
+    pub fn try_with_metric<M>(self, metric: M) -> prometheus::Result<Self>
     where
         M: metric::Bundled + prometheus::core::Collector,
         <M as metric::Bundled>::Bundle:
@@ -667,8 +667,8 @@ impl<S, L> Builder<S, L> {
     /// let counter = prometheus::IntCounter::new("value", "help")?;
     ///
     /// metrics_prometheus::Recorder::builder()
-    ///     .with_must_metric(counter.clone())
-    ///     .must_build_and_install();
+    ///     .with_metric(counter.clone())
+    ///     .build_and_install();
     ///
     /// counter.inc();
     ///
@@ -699,20 +699,20 @@ impl<S, L> Builder<S, L> {
     /// );
     /// # Ok::<_, prometheus::Error>(())
     /// ```
-    pub fn with_must_metric<M>(self, metric: M) -> Self
+    pub fn with_metric<M>(self, metric: M) -> Self
     where
         M: metric::Bundled + prometheus::core::Collector,
         <M as metric::Bundled>::Bundle:
             prometheus::core::Collector + Clone + 'static,
         storage::Mutable:
             storage::GetCollection<<M as metric::Bundled>::Bundle>,
     {
-        self.with_metric(metric).unwrap_or_else(|e| {
+        self.try_with_metric(metric).unwrap_or_else(|e| {
             panic!("failed to register `prometheus` metric: {e}")
         })
     }
 
-    /// Builds a [`Recorder`] out of this [`Builder`] and installs it as
+    /// Builds a [`Recorder`] out of this [`Builder`] and tries to install it as
     /// [`metrics::recorder()`].
     ///
     /// # Errors
@@ -730,11 +730,11 @@ impl<S, L> Builder<S, L> {
     ///
     /// let res = metrics_prometheus::Recorder::builder()
     ///     .with_registry(&custom)
-    ///     .with_metric(prometheus::IntCounter::new("count", "help")?)?
-    ///     .with_metric(prometheus::Gauge::new("value", "help")?)?
+    ///     .try_with_metric(prometheus::IntCounter::new("count", "help")?)?
+    ///     .try_with_metric(prometheus::Gauge::new("value", "help")?)?
     ///     .with_failure_strategy(strategy::Panic)
     ///     .with_layer(FilterLayer::from_patterns(["ignored"]))
-    ///     .build_and_install();
+    ///     .try_build_and_install();
     /// assert!(res.is_ok(), "cannot install `Recorder`: {}", res.unwrap_err());
     ///
     /// metrics::increment_counter!("count");
@@ -774,7 +774,7 @@ impl<S, L> Builder<S, L> {
     /// );
     /// # Ok::<_, prometheus::Error>(())
     /// ```
-    pub fn build_and_install(
+    pub fn try_build_and_install(
         self,
     ) -> Result<Recorder<S>, metrics::SetRecorderError>
     where
@@ -812,11 +812,11 @@ impl<S, L> Builder<S, L> {
     ///
     /// let recorder = metrics_prometheus::Recorder::builder()
     ///     .with_registry(custom)
-    ///     .with_metric(prometheus::IntCounter::new("count", "help")?)?
-    ///     .with_metric(prometheus::Gauge::new("value", "help")?)?
+    ///     .try_with_metric(prometheus::IntCounter::new("count", "help")?)?
+    ///     .try_with_metric(prometheus::Gauge::new("value", "help")?)?
     ///     .with_failure_strategy(strategy::Panic)
     ///     .with_layer(FilterLayer::from_patterns(["ignored"]))
-    ///     .must_build_and_install();
+    ///     .build_and_install();
     ///
     /// metrics::increment_counter!("count");
     /// metrics::increment_gauge!("value", 3.0);
@@ -855,13 +855,13 @@ impl<S, L> Builder<S, L> {
     /// );
     /// # Ok::<_, prometheus::Error>(())
     /// ```
-    pub fn must_build_and_install(self) -> Recorder<S>
+    pub fn build_and_install(self) -> Recorder<S>
     where
         S: failure::Strategy + Clone,
         L: Layer<Recorder<S>>,
         <L as Layer<Recorder<S>>>::Output: metrics::Recorder + 'static,
     {
-        self.build_and_install().unwrap_or_else(|e| {
+        self.try_build_and_install().unwrap_or_else(|e| {
             panic!(
                 "failed to install `metrics_prometheus::Recorder` as \
                  `metrics::recorder()`: {e}",
@@ -882,7 +882,7 @@ impl<S, H, T> Builder<S, layer::Stack<H, T>> {
     /// metrics_prometheus::Recorder::builder()
     ///     .with_layer(FilterLayer::from_patterns(["ignored"]))
     ///     .with_layer(FilterLayer::from_patterns(["skipped"]))
-    ///     .must_build_and_install();
+    ///     .build_and_install();
     ///
     /// metrics::increment_counter!("ignored_counter");
     /// metrics::increment_counter!("reported_counter");