feat: move Clock::timed method to tick

crates/cachet/src/fallback.rs

@@ -17,7 +17,6 @@ use tick::Clock;
 use crate::Error;
 use crate::cache::CacheName;
 use crate::refresh::TimeToRefresh;
-use crate::telemetry::ext::ClockExt;
 use crate::telemetry::{CacheActivity, CacheOperation, CacheTelemetry};
 
 /// Type alias for promotion predicate functions.
@@ -212,7 +211,7 @@ where
     ///
     /// Separated from [`get`](Self::get) to keep the hot path (primary hits) small.
     async fn get_from_fallback(&self, key: &K) -> Result<Option<CacheEntry<V>>, Error> {
-        let timed = self.inner.clock.timed_async(self.inner.fallback.get(key)).await;
+        let timed = self.inner.clock.timed(self.inner.fallback.get(key)).await;
         self.inner
             .telemetry
             .record(self.inner.name, CacheOperation::Get, CacheActivity::Fallback, timed.duration);
@@ -223,11 +222,7 @@ where
         if let Some(ref v) = fallback_value
             && self.inner.policy.should_promote(v)
         {
-            let timed_insert = self
-                .inner
-                .clock
-                .timed_async(self.inner.primary.insert(key.clone(), v.clone()))
-                .await;
+            let timed_insert = self.inner.clock.timed(self.inner.primary.insert(key.clone(), v.clone())).await;
             // Insert errors are intentionally swallowed - a failed promotion should not
             // fail the overall get. The CacheWrapper around the primary tier already
             // records an Error activity on insert failure.

crates/cachet/src/refresh.rs

@@ -18,7 +18,6 @@ use cachet_tier::{CacheEntry, CacheTier};
 use parking_lot::Mutex;
 
 use crate::fallback::{FallbackCache, FallbackCacheInner};
-use crate::telemetry::ext::ClockExt;
 use crate::telemetry::{CacheActivity, CacheOperation};
 
 /// Configuration for background cache refresh.
@@ -146,7 +145,7 @@ where
     F: CacheTier<K, V> + Send + Sync + 'static,
 {
     pub(crate) async fn fetch_and_promote(&self, key: K) {
-        let timed = self.clock.timed_async(self.fallback.get(&key)).await;
+        let timed = self.clock.timed(self.fallback.get(&key)).await;
 
         match timed.result {
             Ok(Some(value)) => self.handle_fallback_hit(key, value, timed.duration).await,
@@ -164,7 +163,7 @@ where
     }
 
     async fn promote_to_primary(&self, key: K, value: CacheEntry<V>) {
-        let timed = self.clock.timed_async(self.primary.insert(key, value)).await;
+        let timed = self.clock.timed(self.primary.insert(key, value)).await;
 
         match timed.result {
             Ok(()) => {

crates/cachet/src/telemetry/mod.rs

@@ -10,7 +10,6 @@
 pub(crate) mod attributes;
 pub(crate) mod cache;
 pub(crate) mod config;
-pub(crate) mod ext;
 #[cfg(any(feature = "metrics", test))]
 pub(crate) mod metrics;
 

crates/cachet/src/wrapper.rs

@@ -14,7 +14,6 @@ use cachet_tier::CacheTier;
 use tick::Clock;
 
 use crate::cache::CacheName;
-use crate::telemetry::ext::ClockExt;
 use crate::telemetry::{CacheActivity, CacheOperation, CacheTelemetry};
 use crate::{CacheEntry, Error};
 
@@ -124,7 +123,7 @@ where
     CT: CacheTier<K, V> + Send + Sync,
 {
     async fn get(&self, key: &K) -> Result<Option<CacheEntry<V>>, Error> {
-        let timed = self.clock.timed_async(self.inner.get(key)).await;
+        let timed = self.clock.timed(self.inner.get(key)).await;
         match timed.result {
             Ok(value) => Ok(self.handle_get_result(value, timed.duration)),
             Err(e) => {
@@ -137,7 +136,7 @@ where
 
     async fn insert(&self, key: K, mut entry: CacheEntry<V>) -> Result<(), Error> {
         entry.ensure_cached_at(self.clock.system_time());
-        let timed = self.clock.timed_async(self.inner.insert(key, entry)).await;
+        let timed = self.clock.timed(self.inner.insert(key, entry)).await;
         match &timed.result {
             Ok(()) => {
                 self.telemetry
@@ -155,7 +154,7 @@ where
     }
 
     async fn invalidate(&self, key: &K) -> Result<(), Error> {
-        let timed = self.clock.timed_async(self.inner.invalidate(key)).await;
+        let timed = self.clock.timed(self.inner.invalidate(key)).await;
         match &timed.result {
             Ok(()) => {
                 self.telemetry
@@ -173,7 +172,7 @@ where
     }
 
     async fn clear(&self) -> Result<(), Error> {
-        let timed = self.clock.timed_async(self.inner.clear()).await;
+        let timed = self.clock.timed(self.inner.clear()).await;
         match &timed.result {
             Ok(()) => {
                 self.telemetry

crates/tick/Cargo.toml

@@ -48,6 +48,7 @@ thread_aware.workspace = true
 tokio = { workspace = true, optional = true, features = ["time", "rt"] }
 
 [dev-dependencies]
+#internal
 ohno = { workspace = true, features = ["app-err"] }
 
 #external
@@ -96,6 +97,10 @@ required-features = ["test-util"]
 name = "interop_jiff"
 required-features = ["test-util"]
 
+[[example]]
+name = "timed_result"
+required-features = ["tokio"]
+
 [[bench]]
 name = "clock_bench"
 harness = false

crates/tick/examples/timed_result.rs

@@ -0,0 +1,25 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+//! This example demonstrates how to measure the execution time of an async
+//! operation using [`Clock::timed`] and [`TimedResult`].
+
+use tick::{Clock, TimedResult};
+
+#[tokio::main]
+async fn main() {
+    // Create a clock for the Tokio runtime.
+    let clock = Clock::new_tokio();
+
+    // Start some background work that returns a result after a delay.
+    let background_job = async {
+        clock.delay(std::time::Duration::from_millis(10)).await;
+        "Background job result"
+    };
+
+    // Use `Timed` to measure the time taken by the background job and capture its result.
+    let TimedResult { result, duration } = clock.timed(background_job).await;
+
+    // Print the result and the elapsed time.
+    println!("Result: {}, Elapsed time: {:?}", result, duration);
+}

crates/tick/src/clock.rs

@@ -7,6 +7,7 @@ use std::time::{Duration, Instant, SystemTime};
 use thread_aware::ThreadAware;
 use thread_aware::affinity::{MemoryAffinity, PinnedAffinity};
 
+use crate::Timed;
 use crate::state::ClockState;
 use crate::timers::TimerKey;
 
@@ -459,6 +460,35 @@ impl Clock {
         crate::Stopwatch::new(self)
     }
 
+    /// Wraps a future so that its execution time is measured.
+    ///
+    /// Returns a [`Timed`] future whose output is a [`TimedResult`][crate::TimedResult]
+    /// containing both the inner future's result and the elapsed duration.
+    ///
+    /// The measurement uses the same clock as the [`Stopwatch`][crate::Stopwatch],
+    /// so time can be controlled in tests via [`ClockControl`][crate::ClockControl].
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use tick::{Clock, TimedResult};
+    ///
+    /// # async fn timed_example(clock: &Clock) {
+    /// let TimedResult { result, duration } = clock.timed(async { 42 }).await;
+    /// println!("Result: {}, Duration: {:?}", result, duration);
+    /// assert_eq!(result, 42);
+    /// # }
+    /// ```
+    pub fn timed<F>(&self, f: F) -> Timed<F>
+    where
+        F: Future,
+    {
+        Timed {
+            inner: f,
+            watch: self.stopwatch(),
+        }
+    }
+
     pub(super) fn register_timer(&self, when: Instant, waker: Waker) -> TimerKey {
         match self.clock_state() {
             #[cfg(any(feature = "test-util", test))]
@@ -781,4 +811,58 @@ mod tests {
 
         insta::assert_debug_snapshot!(clock);
     }
+
+    #[tokio::test]
+    #[cfg_attr(miri, ignore)]
+    async fn timed_measures_duration() {
+        let control = ClockControl::new();
+        let clock = control.to_clock();
+
+        let timed = clock
+            .timed(async {
+                control.advance(Duration::from_millis(100));
+                42
+            })
+            .await;
+
+        assert_eq!(timed.result, 42);
+        assert_eq!(timed.duration, Duration::from_millis(100));
+    }
+
+    #[tokio::test]
+    #[cfg_attr(miri, ignore)]
+    async fn timed_handles_pending() {
+        use std::pin::Pin;
+        use std::sync::Arc;
+        use std::sync::atomic::{AtomicBool, Ordering};
+        use std::task::{Context, Poll};
+
+        /// A future that returns Pending on the first poll, then Ready on the second.
+        struct YieldOnce {
+            yielded: Arc<AtomicBool>,
+        }
+
+        impl std::future::Future for YieldOnce {
+            type Output = i32;
+            fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<i32> {
+                if self.yielded.swap(true, Ordering::SeqCst) {
+                    Poll::Ready(99)
+                } else {
+                    cx.waker().wake_by_ref();
+                    Poll::Pending
+                }
+            }
+        }
+
+        let control = ClockControl::new();
+        let clock = control.to_clock();
+
+        let timed = clock
+            .timed(YieldOnce {
+                yielded: Arc::new(AtomicBool::new(false)),
+            })
+            .await;
+
+        assert_eq!(timed.result, 99);
+    }
 }