Tracking issue for Duration::span

[alexcrichton]

This is a tracking issue for the unstable duration_span feature of the standard library. Known open questions are:

• Is this the right place for this API?
• Is this the right name?
• Should the closure be able to return a value?
• Should various other system clocks be exposed?

[SimonSapin]

Some previous discussion in rust-lang/rfcs#1243:

• It’s probably not the right place, just like std::usize is not the right place for Iterator::count even though it returns a usize.
• I don’t have a strong opinion on the name. timeit was suggested. Maybe time_it is closer to usual naming conventions?
• Allowing the closure to return a value makes the API awkward if the duration is also a return value. The closure can assign to a close-over variable if needed.
• I don’t know about differences between clocks. I kinda like not having a to make an uninformed choice, so at least there should be a clear default. (Probably one that is most appropriate for benchmarking.)

One thing is that the reason field:

    #[unstable(feature = "duration_span",
               reason = "unsure if this is the right API or whether it should \
                         wait for a more general \"moment in time\" \
                         abstraction")]

seems to suggest that Duration::span could be removed entirely. IMO even if a "moment in time" abstraction is added, typing let duration = { let start = now(); f(); now() - start }; every time gets tedious very quickly, and a closure-based API should still be provided.

[SimonSapin]

I suggest either:

1. Moving Duration::span to a free function std::time::span and stabilize in 1.5;

2. Or moving it to an associated function of a new std::time::Timer type like this:

   #[derive(Copy, Clone)]
   pub struct Timer {
       start_t: SteadyTime,
   }
   
   impl Timer {
       pub fn start() -> Timer {
           Timer {
               start_t: SteadyTime::now(),
           }
       }
   
       pub fn stop(&self) -> Duration {
           &SteadyTime::now() - &self.start_t
       }
   
       pub fn span<F>(f: F) -> Duration where F: FnOnce() {
           let timer = Timer::start();
           f();
           timer.stop()
       }
   }

   (Stability markers omitted for brevity.)

   The idea is to generalize span to cases where the start and end point are not necessarily in the same stack frame, so a closure doesn’t work. Admittedly, this is theoretical. (I haven’t actually needed this myself so far.)

[rustonaut]

I don't think span is the right name it sounds like it would span a new thread to run and (time) measure the closure.

It is documented as Runs a closure, returning the duration.. so maybe run_and_measure or just measure would be better.

I also agree that it is kind of misplaced. The options provided by @SimonSapin do look good, through maybe a full Timer class is more suited for a small Library (witch also might have some more complex Timers, like hierarchical ones).

[SimonSapin]

Agreed on changing the span name to something else. Python has a timeit module and function, but measure is ok too.

This "full class" is really just an opaque data type to encapsulate a start timestamp. Maybe we can just expose SteadyTime instead (adding Clone and maybe Copy to the existing now() -> SteadyTime method and Sub impl as its only API).

[Ms2ger]

Allowing the closure to return a value makes the API awkward if the duration is also a return value. The closure can assign to a close-over variable if needed.

Assigning to a closed-over variable is pretty ugly too, unfortunately.

[softprops]

If stablized, it may be useful to return a tuple of both the result of the closure run and the duration.

let (value, duration) = Duration::span(thunk) 

[softprops]

Alt name suggestion Duration::elapsed

[alexcrichton]

Nominating for 1.6 discussion

[alexcrichton]

🔔 This issue is now entering its cycle-long final comment period for deprecation 🔔

It's likely that rust-lang/rfcs#1288 will land during this cycle in which case using Instant to measure time will be the "more correct" way to do so. This function will not be deprecated, however, until Instant has landed.