Chapel: Should we change/rename the methods used to clear/reset/restart the stopwatch type?

[bradcray]

The current Timer type has a clear() method that sets the elapsed time to zero and does not affect whether the stopwatch is running or not (like a physical stopwatch, if it's stopped, it remains stopped; if it's running, it continues running). This issue asks whether that interface or behavior should change in some way or whether new routines/arguments should be added.

• should the current behavior or name of clear() change?
• should we add a way to both zero the elapsed time and stop the timer? (essentially, setting it back to its initial state)
  
  
  
  • we could do this via a new method (e.g., reset())
  
  
  • we could do this via a(n optional) argument to clear() (e.g., proc clear(stop: bool [= false]) { ... }
  
  
  • or both
  
  

[vasslitvinov]

I am OK either way. My preferred solution is to keep the current semantics and add an optional argument stop with the default value of false - primarily as a way to make the user aware of this detail.

[Added] Both names _clear_ and _reset_ are ambiguous w.r.t. changing the "running" state of the timer. So I am not excited about adding _reset()_. I am open to it though.

What I'd love to see is a one-step way to restart the timer from scratch:

• restart() method
• a param for the Timer type indicating whether start() always starts from scratch, false by default
• an argument for the start() whether to start from scratch

[gbtitus]

I was originally in favor of renaming clear() as reset() with no other changes, but the longer I mull this the less meaningful that breaking change seems. So now I think we ought to just leave it as it is.

[bradcray]

To me, reset() suggests "set things back to the way they were when the variable was declared" (which is to say, 0 elapsed time and not running) and I'm open to adding a method with that name and behavior. I'm less sold on having reset() do what clear() does today.

• restart() method

What do you want this method to do? (What does "restart the timer from scratch" mean? (my guess: stop() + clear() + start()?))

[vasslitvinov]

Right, restart() = stop() + clear() + start(). If the timer is not running, it would do clear() + start().

[lydia-duncan]

like a physical stopwatch, if it's stopped, it remains stopped; if it's running, it continues running

Not every stopwatch has this capacity, and if my memory serves, when they do, it takes slightly more effort to use it. The electronic stopwatch in my phone only supports:

• start
• pause (which is only available while the stopwatch is running)
• lap (which is only available while the stopwatch is running)
• resume (which is only available after pausing the stopwatch)
• reset (which does not start the stopwatch again, it only clears the time tracked. It is also only available after pausing the stopwatch)

I brought this topic up in our meeting because I personally find it confusing. My main trouble with the method as it currently stands is that when I see the name "clear" for a stopwatch, my expectation is that the stopwatch is not running immediately after it is called - it either stops the stopwatch and sets the tracked time to zero so that the stopwatch is ready to run again, or merely sets the tracked time to zero if it was not already running. "Clear" doesn't imply to me that the stopwatch would be running after the method returns at all.

I think the functionality it provides is valuable, but for myself, I mostly want a way to do either "reset" or "restart" separately from that method. Basically, I want to know the running state of my stopwatch as the result of the method call I am making, in case it's been a while since I started it, or in case it's unclear to me whether it was running or not (maybe there was an if statement, maybe I was doing something dumb in another thread but I know that thread is finished and so won't affect it again, maybe I passed the stopwatch to another function and don't know whether it stopped or started the stopwatch during its operation). While I think this is something I personally would plausibly want to do in a normal program, it's even more likely to happen in an interactive program.

I'm okay with additional arguments to already present functions, though that doesn't address my hesitancy with the name "clear" itself, which still gives me an immediate "that's wrong" reaction. I can live with "clear" having that functionality much more if I have a way to get what it provides while ensuring I always know the running state of my stopwatch instance. Put another way, if "clear" stays as is but I have a way of getting "reset" and "restart" without it, I will always use those ways and will just ignore "clear" as much as possible.

[bradcray]

Just to throw out a straw-person proposal, what if we had:

• stopwatch.reset() — clears the elapsed time and ensures the stopwatch is stopped (essentially, puts it back into the same state as when it was declared)
• stopwatch.restart() — clears the elapsed time and ensures the stopwatch is running
• stopwatch.clear() — works as it does today (rationale: fewer changes for existing code; nobody has ever complained about the behavior being problematic for them that I can recall; if you mis-guessed what it does and were to call stopwatch.start() afterwards, you'll get a warning which should make your mistake clear the first time you run your program).

My main hesitation about this proposal is that it complicates what has traditionally been a fairly simple interface, and I don't have any recollection of users suffering much from the current interface or having requested additional capabilities. But if it's the shortest path to reaching consensus here, I'm open to adding the two new routines.