Merge pull request #67 from metrics-rs/clean-up-api

Bunch of API cleanup.

Author: tobz

.github/workflows/ci.yml

@@ -99,7 +99,7 @@ jobs:
       uses: actions-rs/cargo@v1
       with:
         command: doc
-        args: --all-features --workspace --exclude=metrics-observer --no-deps
+        args: --all-features --workspace --no-deps
   bench:
     name: Bench ${{ matrix.os }}
     runs-on: ${{ matrix.os }}
@@ -126,5 +126,5 @@ jobs:
         alert-threshold: '10%'
         comment-on-alert: true
         fail-on-alert: true
-        alert-comment-cc-users: '@metrics-rs/maintainers'
+        alert-comment-cc-users: '@tobz'
         auto-push: ${{ github.ref == 'refs/heads/main' }}

CHANGELOG.md

@@ -9,72 +9,84 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 ## [Unreleased] - ReleaseDate
 
 ### Changed
+
 - Documentation has been updated to reflect that `quanta` does not track time across system
   suspends.
-- Updated the calibration logic to add an offset to the reference base time that is used to scale
-  source measurements in TSC mode.  Simply put, the "synchronization" -- how close `Clock::now` is
-  to the underlying monotonic clock, if you called both at the very same moment -- has been improved
-  by a substantial amount on average.
 - Fixed a panic in the calibration loop if a certain edge case with TSC measurements is encountered.
+- Updated a unit test that was frequently flaky to be more precise.
 
 ### Removed
+
 - `Instant::as_u64` has been removed.  As it provided direct access to an value that could
   fundamentally change from version-to-version, it felt like time to remove that footgun and push
   users more towards the API that mimics `std::time`.
 - `Clock::upkeep` has been removed.  It doesn't need to exist on `Clock` directly, as we have had
   the `quanta::set_recent` free function for a while now, and was just duplicating that.
+- `Clock::start` and `Clock::end` have been removed. They saw limited usage and overall just added somewhat needless API
+  clutter given that users who are looking to do ultra-precise timing will either want more control or use another
+  technique such as instruction counting.
 
 ## [0.9.3] - 2021-09-16
 
 ### Added
+
 - CI tests for MIPS/ARM. ([#55](https://github.com/metrics-rs/quanta/pull/55))
 
 ### Changed
+
 - Fixed compilation issue with `Mock` on MIPS/ARM. ([#55](https://github.com/metrics-rs/quanta/pull/55))
 - Simplified how TSC/RDTSC suppoort is detected, which should avoid some situations where it was
   assumed to be present, but actually was not. ([#57](https://github.com/metrics-rs/quanta/pull/57))
 
 ## [0.9.2] - 2021-08-25
 
 ### Changed
+
 - Pinned `crossbeam-utils` to `v0.8.5` where `AtomicCell::fetch_update` was introduced to fix, which
   fixes broken builds where Cargo chooses a version between `0.8.0` and `0.8.5`.
 - Update `raw-cpuid` to `10.2` and `average` to `0.13`.
 
 ## [0.9.1] - 2021-08-12
 
 ### Changed
+
 - Switched from `atomic-shim` to `crossbeam-utils` for better cross-platform atomic support. ([#52](https://github.com/metrics-rs/quanta/pull/52))
 
 ## [0.9.0] - 2021-06-17
 
 ### Added
+
 - Support for WASM/WASI targets. ([#45](https://github.com/metrics-rs/quanta/pull/45))
 
 ## [0.8.0] - 2021-06-07
 
 ### Removed
+
 - `Instant::as_unix_duration` as it was added in error.
 - `metrics` feature flag as `metrics-core` is no longer a relevant crate.
 
 ## [0.7.2] - 2021-01-25
 ### Changed
+
 - Bumped dependency on `raw-cpuid` to `9.0` in order to deal with a [RustSec
   advisory](https://rustsec.org/advisories/RUSTSEC-2021-0013).
 
 ## [0.7.1] - 2021-01-24
 ### Fixed
+
 - Incorrect method visibility for non-SSE2 implementation of `Counter`.
   ([#38](https://github.com/metrics-rs/quanta/issues/38))
 
 ## [0.7.0] - 2021-01-03
 ### Changed
+
 - MSRV bumped to 1.45.0.
 - `Clock::now` takes `&self` instead of `&mut self`.
 - Fixed a bug where a failure to spawn the upkeep thread would not allow subsequent attempts to
   spawn the upkeep thread to proceed.
 
 ### Added
+
 - New methods --`Instant::now` and `Instant::recent` for getting the current and recent time,
   respectively.
 - New free function `quanta::with_clock` for setting an override on the current thread that affects
@@ -84,36 +96,43 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [0.6.5] - 2020-09-16
 ### Changed
+
 - Fixed a bug with not being able to start the upkeep thread at all.
   ([#29](https://github.com/metrics-rs/quanta/issues/29))
 
 ## [0.6.4] - 2020-08-27
 ### Added
+
 - Add `Instant::as_unix_duration` to get the duration of time since the Unix epoch from an
   `Instant`.
   ### Changed
 - Remove `clocksource` from dependencies and tests as it no longer compiles on stable or nightly.
 
 ## [0.6.3] - 2020-08-03
 ### Changed
+
 - Publicly expose `Clock::upkeep` for advanced use cases.
 - Relax constraints around checking for multiple sockets.
   ([#25](https://github.com/metrics-rs/quanta/issues/25))
 
 ## [0.6.2] - 2020-07-20
 ### Added
+
 - Add support for MIPS/PowerPC. ([#23](https://github.com/metrics-rs/quanta/pull/23))
 
 ## [0.6.1] - 2020-07-13
 ### Added
+
 - Publicly expose the `Error` type returned by `Upkeep::start`.
 
 ## [0.6.0] - 2020-07-06
+
 This version of `quanta` was a massive overhaul of man areas of the API and internals, which was
 done in a single PR: ([#19](https://github.com/metrics-rs/quanta/pull/19)).  You can read the PR
 description for the finer details.  All changes below are part of the aforementioned PR.
 
 ### Changed
+
 - `Clock::now` now returns a monotonic value in all cases.
 - No longer possible to get a negative value from `Clock::delta`.
 - Calibration is no longer a fixed one second loop, and will complete when it detects it has a
@@ -124,15 +143,18 @@ description for the finer details.  All changes below are part of the aforementi
 
 ## [0.5.2] - 2020-05-01
 ### Changed
+
 - Fix the logic to figure out when calibration is required.
   ([#14](https://github.com/metrics-rs/quanta/pull/14))
 
 ## [0.5.1] - 2020-04-11
 ### Changed
+
 - Small tweak to the docs.
 
 ## [0.5.0] - 2020-04-11
 ### Changed
+
 - Switch to `mach` for macOS/iOS as it was deprecated in `libc`.
   ([#12](https://github.com/metrics-rs/quanta/pull/12))
 - Switch to `core::arch` for instrinics, and drop the feature flagged configuration to use it.
@@ -141,15 +163,18 @@ description for the finer details.  All changes below are part of the aforementi
 
 ## [0.4.0] - 2020-02-20
 ### Changed
+
 - Differentiate between raw and scaled time by adding a new `Instant` type.
   ([#10](https://github.com/metrics-rs/quanta/pull/10))
 
 ## [0.2.0] - 2019-03-10
 ### Changed
+
 - Fixed support for Windows.  It was in a bad way, but actually works correctly now!
 - Switched to Azure Pipelines CI + Cirrus CI, including formatting, tests, and benchmarks, for
   Linux, macOS, Windows, and FreeBSD.
 
 ## [0.1.0] - 2019-01-14
 ### Added
+
 - Initial commit.

benches/timing.rs

@@ -26,26 +26,6 @@ fn time_quanta_raw_scaled(b: &mut Bencher) {
     b.iter(|| clock.scaled(clock.raw()))
 }
 
-fn time_quanta_start(b: &mut Bencher) {
-    let clock = Clock::new();
-    b.iter(|| clock.start())
-}
-
-fn time_quanta_start_scaled(b: &mut Bencher) {
-    let clock = Clock::new();
-    b.iter(|| clock.scaled(clock.start()))
-}
-
-fn time_quanta_end(b: &mut Bencher) {
-    let clock = Clock::new();
-    b.iter(|| clock.end())
-}
-
-fn time_quanta_end_scaled(b: &mut Bencher) {
-    let clock = Clock::new();
-    b.iter(|| clock.scaled(clock.end()))
-}
-
 fn time_instant_delta(b: &mut Bencher) {
     b.iter(|| {
         let start = StdInstant::now();
@@ -72,15 +52,6 @@ fn time_quanta_now_delta(b: &mut Bencher) {
     })
 }
 
-fn time_quanta_start_end_delta(b: &mut Bencher) {
-    let clock = Clock::new();
-    b.iter(|| {
-        let start = clock.start();
-        let end = clock.end();
-        clock.delta(start, end)
-    })
-}
-
 fn time_quanta_recent(b: &mut Bencher) {
     let clock = Clock::new();
     b.iter(|| clock.recent())
@@ -104,11 +75,6 @@ fn benchmark(c: &mut Criterion) {
     q_group.bench_function("quanta_raw", time_quanta_raw);
     q_group.bench_function("quanta_raw_scaled", time_quanta_raw_scaled);
     q_group.bench_function("quanta_raw_delta", time_quanta_raw_delta);
-    q_group.bench_function("quanta_start", time_quanta_start);
-    q_group.bench_function("quanta_start_scaled", time_quanta_start_scaled);
-    q_group.bench_function("quanta_end", time_quanta_end);
-    q_group.bench_function("quanta_end_scaled", time_quanta_end_scaled);
-    q_group.bench_function("quanta_start/end_delta", time_quanta_start_end_delta);
     q_group.bench_function("quanta_recent", time_quanta_recent);
     q_group.bench_function("quanta_instant_recent", time_quanta_instant_recent);
     q_group.finish();

src/clocks/counter.rs

@@ -1,34 +1,13 @@
 #[cfg(all(target_arch = "x86_64", target_feature = "sse2"))]
-use core::arch::x86_64::{__rdtscp, _mm_lfence, _rdtsc};
+use core::arch::x86_64::_rdtsc;
 
 #[derive(Clone, Debug, Default)]
 pub struct Counter;
 
 #[cfg(all(target_arch = "x86_64", target_feature = "sse2"))]
 impl Counter {
     pub fn now(&self) -> u64 {
-        unsafe {
-            //_mm_lfence();
-            _rdtsc()
-        }
-    }
-
-    pub fn start(&self) -> u64 {
-        unsafe {
-            _mm_lfence();
-            let result = _rdtsc();
-            _mm_lfence();
-            result
-        }
-    }
-
-    pub fn end(&self) -> u64 {
-        let mut aux: u32 = 0;
-        unsafe {
-            let result = __rdtscp(&mut aux as *mut _);
-            _mm_lfence();
-            result
-        }
+        unsafe { _rdtsc() }
     }
 }
 
@@ -37,12 +16,4 @@ impl Counter {
     pub fn now(&self) -> u64 {
         panic!("can't use counter without TSC support");
     }
-
-    pub fn start(&self) -> u64 {
-        panic!("can't use counter without TSC support");
-    }
-
-    pub fn end(&self) -> u64 {
-        panic!("can't use counter without TSC support");
-    }
 }

src/clocks/monotonic/unix.rs

@@ -14,14 +14,14 @@ impl Monotonic {
 
         // LINT JUSTIFICATION:
         //
-        // We really don't ever except to actually _get_ negative values from `clock_gettime`, but
+        // We really don't ever expect to actually _get_ negative values from `clock_gettime`, but
         // given the types, it's technically possible.  This is due to the fact that `tv_sec` is
         // supposed to be `time_t`, which Unix/POSIX-compliant systems implement as a signed number.
         // Accordingly, `tv_nsec` follows suit using a signed number.
         //
         // Given the adjustments made by NTP to clocks like CLOCK_MONOTONIC, and that
         // CLOCK_MONOTONIC can be anchored to an arbitrary point, and a whole skew of other
-        // scenarios where it could be modified... it's technicaly possibler to get back valid
+        // scenarios where it could be modified... it's technicaly possible to get back valid
         // negative values.  If we did math between `timespec` objects, the delta should be valid,
         // even with negative numbers.
         //

src/clocks/monotonic/wasm.rs

@@ -12,7 +12,7 @@ impl Monotonic {
             .performance()
             .expect(WASM_MISSING_WINDOW_PERF)
             .now();
-        // window.performance.now returns the time in milliseconds
+        // `window.performance.now()` returns the time in milliseconds.
         return f64::trunc(now * 1000.0) as u64;
     }
 }