Implement Default for tokio_timer::Handle (#553)

This patch implements `Default` for `tokio_timer::Handle`. It returns a
`Handle` instance that is not bound to a specific timer. Instead, it
will use the timer for the current execution context. This is the same
strategy used by `tokio_reactor::Handle`.

Fixes #547

tokio-timer/src/timer/entry.rs

@@ -1,6 +1,6 @@
 use Error;
 use atomic::AtomicU64;
-use timer::{Handle, Inner};
+use timer::{HandlePriv, Inner};
 
 use futures::Poll;
 use futures::task::AtomicTask;
@@ -121,7 +121,7 @@ const SHUTDOWN: *mut Entry = 1 as *mut _;
 // ===== impl Entry =====
 
 impl Entry {
-    pub fn new(when: u64, handle: Handle) -> Entry {
+    pub fn new(when: u64, handle: HandlePriv) -> Entry {
         assert!(when > 0 && when < u64::MAX);
 
         Entry {
@@ -137,7 +137,7 @@ impl Entry {
         }
     }
 
-    pub fn new_elapsed(handle: Handle) -> Entry {
+    pub fn new_elapsed(handle: HandlePriv) -> Entry {
         Entry {
             inner: handle.into_inner(),
             task: AtomicTask::new(),

tokio-timer/src/timer/handle.rs

@@ -4,6 +4,7 @@ use timer::{Registration, Inner};
 use tokio_executor::Enter;
 
 use std::cell::RefCell;
+use std::fmt;
 use std::sync::{Arc, Weak};
 use std::time::{Duration, Instant};
 
@@ -12,16 +13,39 @@ use std::time::{Duration, Instant};
 /// The `Handle` allows creating `Delay` instances that are driven by the
 /// associated timer.
 ///
-/// A `Handle` is obtained by calling [`Timer::handle`].
+/// A `Handle` is obtained by calling [`Timer::handle`], [`Handle::current`], or
+/// [`Handle::default`].
+///
+/// * [`Timer::handle`]: returns a handle associated with the specific timer.
+///   The handle will always reference the same timer.
+///
+/// * [`Handle::current`]: returns a handle to the timer for the execution
+///   context **at the time the function is called**. This function must be
+///   called from a runtime that has an associated timer or it will panic.
+///   The handle will always reference the same timer.
+///
+/// * [`Handle::default`]: returns a handle to the timer for the execution
+///   context **at the time the handle is used**. This function is safe to call
+///   at any time. The handle may reference different specific timer instances.
+///   Calling `Handle::default().delay(...)` is always equivalent to
+///   `Delay::new(...)`.
 ///
 /// [`Timer::handle`]: struct.Timer.html#method.handle
+/// [`Handle::current`]: #method.current
+/// [`Handle::default`]: #method.default
 #[derive(Debug, Clone)]
 pub struct Handle {
+    inner: Option<HandlePriv>,
+}
+
+/// Like `Handle` but never `None`.
+#[derive(Clone)]
+pub(crate) struct HandlePriv {
     inner: Weak<Inner>,
 }
 
 /// Tracks the timer for the current execution context.
-thread_local!(static CURRENT_TIMER: RefCell<Option<Handle>> = RefCell::new(None));
+thread_local!(static CURRENT_TIMER: RefCell<Option<HandlePriv>> = RefCell::new(None));
 
 /// Set the default timer for the duration of the closure.
 ///
@@ -57,8 +81,13 @@ where F: FnOnce(&mut Enter) -> R
     CURRENT_TIMER.with(|current| {
         {
             let mut current = current.borrow_mut();
+
             assert!(current.is_none(), "default Tokio timer already set \
                     for execution context");
+
+            let handle = handle.as_priv()
+                .unwrap_or_else(|| panic!("`handle` does not reference a timer"));
+
             *current = Some(handle.clone());
         }
 
@@ -68,7 +97,8 @@ where F: FnOnce(&mut Enter) -> R
 
 impl Handle {
     pub(crate) fn new(inner: Weak<Inner>) -> Handle {
-        Handle { inner }
+        let inner = HandlePriv { inner };
+        Handle { inner: Some(inner) }
     }
 
     /// Returns a handle to the current timer.
@@ -81,16 +111,33 @@ impl Handle {
     /// will return a `Handle` that does not reference a timer. `Delay`
     /// instances created with this handle will error.
     ///
+    /// See [type] level documentation for more ways to obtain a `Handle` value.
+    ///
     /// [`with_default`]: ../fn.with_default.html
+    /// [type]: #
     pub fn current() -> Handle {
-        Handle::try_current()
-            .unwrap_or(Handle { inner: Weak::new() })
+        let private = HandlePriv::try_current()
+            .unwrap_or_else(|_| {
+                HandlePriv { inner: Weak::new() }
+            });
+
+        Handle { inner: Some(private) }
     }
 
     /// Create a `Delay` driven by this handle's associated `Timer`.
     pub fn delay(&self, deadline: Instant) -> Delay {
-        let registration = Registration::new_with_handle(deadline, self.clone());
-        Delay::new_with_registration(deadline, registration)
+        match self.inner {
+            Some(ref handle_priv) => {
+                let registration = Registration::new_with_handle(
+                    deadline,
+                    handle_priv.clone());
+
+                Delay::new_with_registration(deadline, registration)
+            }
+            None => {
+                Delay::new(deadline)
+            }
+        }
     }
 
     /// Create a `Deadline` driven by this handle's associated `Timer`.
@@ -104,10 +151,22 @@ impl Handle {
         Interval::new_with_delay(self.delay(at), duration)
     }
 
+    fn as_priv(&self) -> Option<&HandlePriv> {
+        self.inner.as_ref()
+    }
+}
+
+impl Default for Handle {
+    fn default() -> Handle {
+        Handle { inner: None }
+    }
+}
+
+impl HandlePriv {
     /// Try to get a handle to the current timer.
     ///
     /// Returns `Err` if no handle is found.
-    pub(crate) fn try_current() -> Result<Handle, Error> {
+    pub(crate) fn try_current() -> Result<HandlePriv, Error> {
         CURRENT_TIMER.with(|current| {
             match *current.borrow() {
                 Some(ref handle) => Ok(handle.clone()),
@@ -126,3 +185,9 @@ impl Handle {
         self.inner
     }
 }
+
+impl fmt::Debug for HandlePriv {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        write!(f, "HandlePriv")
+    }
+}

tokio-timer/src/timer/mod.rs

@@ -38,6 +38,7 @@ mod now;
 mod registration;
 
 use self::entry::Entry;
+use self::handle::HandlePriv;
 use self::level::{Level, Expiration};
 
 pub use self::handle::{Handle, with_default};

tokio-timer/src/timer/registration.rs

@@ -1,5 +1,5 @@
 use Error;
-use timer::{Handle, Entry};
+use timer::{HandlePriv, Entry};
 
 use futures::Poll;
 
@@ -20,13 +20,13 @@ impl Registration {
         fn is_send<T: Send + Sync>() {}
         is_send::<Registration>();
 
-        match Handle::try_current() {
+        match HandlePriv::try_current() {
             Ok(handle) => Registration::new_with_handle(deadline, handle),
             Err(_) => Registration::new_error(),
         }
     }
 
-    pub fn new_with_handle(deadline: Instant, handle: Handle) -> Registration {
+    pub fn new_with_handle(deadline: Instant, handle: HandlePriv) -> Registration {
         let inner = match handle.inner() {
             Some(inner) => inner,
             None => return Registration::new_error(),

tokio-timer/tests/delay.rs

@@ -7,6 +7,7 @@ mod support;
 use support::*;
 
 use tokio_timer::*;
+use tokio_timer::timer::Handle;
 
 use futures::Future;
 
@@ -486,3 +487,19 @@ fn reset_future_delay_after_fire() {
         assert_ready!(delay);
     });
 }
+
+#[test]
+fn delay_with_default_handle() {
+    let handle = Handle::default();
+    let now = Instant::now();
+
+    let mut delay = handle.delay(now + ms(1));
+
+    mocked_with_now(now, |timer, _time| {
+        assert_not_ready!(delay);
+
+        turn(timer, ms(1));
+
+        assert_ready!(delay);
+    });
+}