lua: give more control over timers

Now they can be paused and resumed.

Since pausing and disabling the timer is essentially the same underlying
operation, we also just provide one method for it.

mp.cancel_timer probably still works, but I'm considering this
deprecated, and it's removed from the manpage. (We didn't have a release
with this function yet, so no formal deprecation.)

DOCS/man/en/lua.rst

@@ -248,17 +248,29 @@ The ``mp`` module is preloaded, although it can be loaded manually with
 
     This is a one-shot timer: it will be removed when it's fired.
 
-    Returns a timer handle. See ``mp.cancel_timer``.
+    Returns a timer object. See ``mp.add_periodic_timer`` for details.
 
 ``mp.add_periodic_timer(seconds, fn)``
     Call the given function periodically. This is like ``mp.add_timeout``, but
     the timer is re-added after the function fn is run.
 
-    Returns a timer handle. See ``mp.cancel_timer``.
+    Returns a timer object. The timer object provides the following methods:
+
+        ``stop()``
+            Disable the timer. Does nothing if the timer is already disabled.
+            This will remember the current elapsed time when stopping, so that
+            ``resume()`` essentially unpauses the timer.
+
+        ``kill()``
+            Disable the timer. Resets the elapsed time.
+
+        ``resume()``
+            Restart the timer. If the timer was disabled with ``stop()``, this
+            will resume at the time it was stopped. If the timer was disabled
+            with ``kill()``, or if it's a previously fired one-shot timer (added
+            with ``add_timeout()``), this starts the timer from the beginning,
+            using the initially configured timeout.
 
-``mp.cancel_timer(t)``
-    Terminate the given timer. t is a timer handle (value returned by
-    ``mp.add_timeout`` or ``mp.add_periodic_timer``).
 
 ``mp.get_opt(key)``
     Return a setting from the ``--lua-opts`` option. It's up to the user and

player/lua/defaults.lua

@@ -144,6 +144,9 @@ end
 
 local timers = {}
 
+local timer_mt = {}
+timer_mt.__index = timer_mt
+
 function mp.add_timeout(seconds, cb)
     local t = mp.add_periodic_timer(seconds, cb)
     t.oneshot = true
@@ -155,15 +158,33 @@ function mp.add_periodic_timer(seconds, cb)
         timeout = seconds,
         cb = cb,
         oneshot = false,
-        next_deadline = mp.get_time() + seconds,
     }
-    timers[t] = t
+    setmetatable(t, timer_mt)
+    t:resume()
     return t
 end
 
-function mp.cancel_timer(t)
-    if t then
+function timer_mt.stop(t)
+    if timers[t] then
         timers[t] = nil
+        t.next_deadline = t.next_deadline - mp.get_time()
+    end
+end
+
+function timer_mt.kill(t)
+    timers[t] = nil
+    t.next_deadline = nil
+end
+mp.cancel_timer = timer_mt.kill
+
+function timer_mt.resume(t)
+    if not timers[t] then
+        local timeout = t.next_deadline
+        if timeout == nil then
+            timeout = t.timeout
+        end
+        t.next_deadline = mp.get_time() + timeout
+        timers[t] = t
     end
 end
 
@@ -186,17 +207,17 @@ local function process_timers()
         if not timer then
             return
         end
-        local wait = timer.next_deadline - mp.get_time()
+        local now = mp.get_time()
+        local wait = timer.next_deadline - now
         if wait > 0 then
             return wait
         else
             if timer.oneshot then
-                timers[timer] = nil
+                timer:kill()
+            else
+                timer.next_deadline = now + timer.timeout
             end
             timer.cb()
-            if not timer.oneshot then
-                timer.next_deadline = mp.get_time() + timer.timeout
-            end
         end
     end
 end