diff options
Diffstat (limited to 'src/libstd')
| -rw-r--r-- | src/libstd/io/timer.rs | 76 |
1 files changed, 68 insertions, 8 deletions
diff --git a/src/libstd/io/timer.rs b/src/libstd/io/timer.rs index 78b8e55c651..67b6d3c476c 100644 --- a/src/libstd/io/timer.rs +++ b/src/libstd/io/timer.rs @@ -96,12 +96,39 @@ impl Timer { } /// Creates a oneshot receiver which will have a notification sent when - /// `msecs` milliseconds has elapsed. This does *not* block the current - /// task, but instead returns immediately. + /// `msecs` milliseconds has elapsed. + /// + /// This does *not* block the current task, but instead returns immediately. /// /// Note that this invalidates any previous receiver which has been created /// by this timer, and that the returned receiver will be invalidated once - /// the timer is destroyed (when it falls out of scope). + /// the timer is destroyed (when it falls out of scope). In particular, if + /// this is called in method-chaining style, the receiver will be + /// invalidated at the end of that statement, and all `recv` calls will + /// fail. + /// + /// # Example + /// + /// ```rust + /// use std::io::timer::Timer; + /// + /// let mut timer = Timer::new().unwrap(); + /// let ten_milliseconds = timer.oneshot(10); + /// + /// for _ in range(0, 100) { /* do work */ } + /// + /// // blocks until 10 ms after the `oneshot` call + /// ten_milliseconds.recv(); + /// ``` + /// + /// ```rust + /// use std::io::timer::Timer; + /// + /// // Incorrect, method chaining-style: + /// let mut five_ms = Timer::new().unwrap().oneshot(5); + /// // The timer object was destroyed, so this will always fail: + /// // five_ms.recv() + /// ``` pub fn oneshot(&mut self, msecs: u64) -> Receiver<()> { let (tx, rx) = channel(); self.obj.oneshot(msecs, box TimerCallback { tx: tx }); @@ -109,14 +136,47 @@ impl Timer { } /// Creates a receiver which will have a continuous stream of notifications - /// being sent every `msecs` milliseconds. This does *not* block the - /// current task, but instead returns immediately. The first notification - /// will not be received immediately, but rather after `msec` milliseconds - /// have passed. + /// being sent every `msecs` milliseconds. + /// + /// This does *not* block the current task, but instead returns + /// immediately. The first notification will not be received immediately, + /// but rather after `msec` milliseconds have passed. /// /// Note that this invalidates any previous receiver which has been created /// by this timer, and that the returned receiver will be invalidated once - /// the timer is destroyed (when it falls out of scope). + /// the timer is destroyed (when it falls out of scope). In particular, if + /// this is called in method-chaining style, the receiver will be + /// invalidated at the end of that statement, and all `recv` calls will + /// fail. + /// + /// # Example + /// + /// ```rust + /// use std::io::timer::Timer; + /// + /// let mut timer = Timer::new().unwrap(); + /// let ten_milliseconds = timer.periodic(10); + /// + /// for _ in range(0, 100) { /* do work */ } + /// + /// // blocks until 10 ms after the `periodic` call + /// ten_milliseconds.recv(); + /// + /// for _ in range(0, 100) { /* do work */ } + /// + /// // blocks until 20 ms after the `periodic` call (*not* 10ms after the + /// // previous `recv`) + /// ten_milliseconds.recv(); + /// ``` + /// + /// ```rust + /// use std::io::timer::Timer; + /// + /// // Incorrect, method chaining-style. + /// let mut five_ms = Timer::new().unwrap().periodic(5); + /// // The timer object was destroyed, so this will always fail: + /// // five_ms.recv() + /// ``` pub fn periodic(&mut self, msecs: u64) -> Receiver<()> { let (tx, rx) = channel(); self.obj.period(msecs, box TimerCallback { tx: tx }); |