+++ /dev/null
---- **AceTimer-3.0** provides a central facility for registering timers.
--- AceTimer supports one-shot timers and repeating timers. All timers are stored in an efficient
--- data structure that allows easy dispatching and fast rescheduling. Timers can be registered
--- or canceled at any time, even from within a running timer, without conflict or large overhead.\\
--- AceTimer is currently limited to firing timers at a frequency of 0.01s as this is what the WoW timer API
--- restricts us to.
---
--- All `:Schedule` functions will return a handle to the current timer, which you will need to store if you
--- need to cancel the timer you just registered.
---
--- **AceTimer-3.0** can be embeded into your addon, either explicitly by calling AceTimer:Embed(MyAddon) or by
--- specifying it as an embeded library in your AceAddon. All functions will be available on your addon object
--- and can be accessed directly, without having to explicitly call AceTimer itself.\\
--- It is recommended to embed AceTimer, otherwise you'll have to specify a custom `self` on all calls you
--- make into AceTimer.
--- @class file
--- @name AceTimer-3.0
--- @release $Id: AceTimer-3.0.lua 1119 2014-10-14 17:23:29Z nevcairiel $
-
-local MAJOR, MINOR = "AceTimer-3.0", 17 -- Bump minor on changes
-local AceTimer, oldminor = LibStub:NewLibrary(MAJOR, MINOR)
-
-if not AceTimer then return end -- No upgrade needed
-AceTimer.activeTimers = AceTimer.activeTimers or {} -- Active timer list
-local activeTimers = AceTimer.activeTimers -- Upvalue our private data
-
--- Lua APIs
-local type, unpack, next, error, select = type, unpack, next, error, select
--- WoW APIs
-local GetTime, C_TimerAfter = GetTime, C_Timer.After
-
-local function new(self, loop, func, delay, ...)
- if delay < 0.01 then
- delay = 0.01 -- Restrict to the lowest time that the C_Timer API allows us
- end
-
- local timer = {...}
- timer.object = self
- timer.func = func
- timer.looping = loop
- timer.argsCount = select("#", ...)
- timer.delay = delay
- timer.ends = GetTime() + delay
-
- activeTimers[timer] = timer
-
- -- Create new timer closure to wrap the "timer" object
- timer.callback = function()
- if not timer.cancelled then
- if type(timer.func) == "string" then
- -- We manually set the unpack count to prevent issues with an arg set that contains nil and ends with nil
- -- e.g. local t = {1, 2, nil, 3, nil} print(#t) will result in 2, instead of 5. This fixes said issue.
- timer.object[timer.func](timer.object, unpack(timer, 1, timer.argsCount))
- else
- timer.func(unpack(timer, 1, timer.argsCount))
- end
-
- if timer.looping and not timer.cancelled then
- -- Compensate delay to get a perfect average delay, even if individual times don't match up perfectly
- -- due to fps differences
- local time = GetTime()
- local delay = timer.delay - (time - timer.ends)
- -- Ensure the delay doesn't go below the threshold
- if delay < 0.01 then delay = 0.01 end
- C_TimerAfter(delay, timer.callback)
- timer.ends = time + delay
- else
- activeTimers[timer.handle or timer] = nil
- end
- end
- end
-
- C_TimerAfter(delay, timer.callback)
- return timer
-end
-
---- Schedule a new one-shot timer.
--- The timer will fire once in `delay` seconds, unless canceled before.
--- @param callback Callback function for the timer pulse (funcref or method name).
--- @param delay Delay for the timer, in seconds.
--- @param ... An optional, unlimited amount of arguments to pass to the callback function.
--- @usage
--- MyAddOn = LibStub("AceAddon-3.0"):NewAddon("MyAddOn", "AceTimer-3.0")
---
--- function MyAddOn:OnEnable()
--- self:ScheduleTimer("TimerFeedback", 5)
--- end
---
--- function MyAddOn:TimerFeedback()
--- print("5 seconds passed")
--- end
-function AceTimer:ScheduleTimer(func, delay, ...)
- if not func or not delay then
- error(MAJOR..": ScheduleTimer(callback, delay, args...): 'callback' and 'delay' must have set values.", 2)
- end
- if type(func) == "string" then
- if type(self) ~= "table" then
- error(MAJOR..": ScheduleTimer(callback, delay, args...): 'self' - must be a table.", 2)
- elseif not self[func] then
- error(MAJOR..": ScheduleTimer(callback, delay, args...): Tried to register '"..func.."' as the callback, but it doesn't exist in the module.", 2)
- end
- end
- return new(self, nil, func, delay, ...)
-end
-
---- Schedule a repeating timer.
--- The timer will fire every `delay` seconds, until canceled.
--- @param callback Callback function for the timer pulse (funcref or method name).
--- @param delay Delay for the timer, in seconds.
--- @param ... An optional, unlimited amount of arguments to pass to the callback function.
--- @usage
--- MyAddOn = LibStub("AceAddon-3.0"):NewAddon("MyAddOn", "AceTimer-3.0")
---
--- function MyAddOn:OnEnable()
--- self.timerCount = 0
--- self.testTimer = self:ScheduleRepeatingTimer("TimerFeedback", 5)
--- end
---
--- function MyAddOn:TimerFeedback()
--- self.timerCount = self.timerCount + 1
--- print(("%d seconds passed"):format(5 * self.timerCount))
--- -- run 30 seconds in total
--- if self.timerCount == 6 then
--- self:CancelTimer(self.testTimer)
--- end
--- end
-function AceTimer:ScheduleRepeatingTimer(func, delay, ...)
- if not func or not delay then
- error(MAJOR..": ScheduleRepeatingTimer(callback, delay, args...): 'callback' and 'delay' must have set values.", 2)
- end
- if type(func) == "string" then
- if type(self) ~= "table" then
- error(MAJOR..": ScheduleRepeatingTimer(callback, delay, args...): 'self' - must be a table.", 2)
- elseif not self[func] then
- error(MAJOR..": ScheduleRepeatingTimer(callback, delay, args...): Tried to register '"..func.."' as the callback, but it doesn't exist in the module.", 2)
- end
- end
- return new(self, true, func, delay, ...)
-end
-
---- Cancels a timer with the given id, registered by the same addon object as used for `:ScheduleTimer`
--- Both one-shot and repeating timers can be canceled with this function, as long as the `id` is valid
--- and the timer has not fired yet or was canceled before.
--- @param id The id of the timer, as returned by `:ScheduleTimer` or `:ScheduleRepeatingTimer`
-function AceTimer:CancelTimer(id)
- local timer = activeTimers[id]
-
- if not timer then
- return false
- else
- timer.cancelled = true
- activeTimers[id] = nil
- return true
- end
-end
-
---- Cancels all timers registered to the current addon object ('self')
-function AceTimer:CancelAllTimers()
- for k,v in pairs(activeTimers) do
- if v.object == self then
- AceTimer.CancelTimer(self, k)
- end
- end
-end
-
---- Returns the time left for a timer with the given id, registered by the current addon object ('self').
--- This function will return 0 when the id is invalid.
--- @param id The id of the timer, as returned by `:ScheduleTimer` or `:ScheduleRepeatingTimer`
--- @return The time left on the timer.
-function AceTimer:TimeLeft(id)
- local timer = activeTimers[id]
- if not timer then
- return 0
- else
- return timer.ends - GetTime()
- end
-end
-
-
--- ---------------------------------------------------------------------
--- Upgrading
-
--- Upgrade from old hash-bucket based timers to C_Timer.After timers.
-if oldminor and oldminor < 10 then
- -- disable old timer logic
- AceTimer.frame:SetScript("OnUpdate", nil)
- AceTimer.frame:SetScript("OnEvent", nil)
- AceTimer.frame:UnregisterAllEvents()
- -- convert timers
- for object,timers in pairs(AceTimer.selfs) do
- for handle,timer in pairs(timers) do
- if type(timer) == "table" and timer.callback then
- local newTimer
- if timer.delay then
- newTimer = AceTimer.ScheduleRepeatingTimer(timer.object, timer.callback, timer.delay, timer.arg)
- else
- newTimer = AceTimer.ScheduleTimer(timer.object, timer.callback, timer.when - GetTime(), timer.arg)
- end
- -- Use the old handle for old timers
- activeTimers[newTimer] = nil
- activeTimers[handle] = newTimer
- newTimer.handle = handle
- end
- end
- end
- AceTimer.selfs = nil
- AceTimer.hash = nil
- AceTimer.debug = nil
-elseif oldminor and oldminor < 17 then
- -- Upgrade from old animation based timers to C_Timer.After timers.
- AceTimer.inactiveTimers = nil
- AceTimer.frame = nil
- local oldTimers = AceTimer.activeTimers
- -- Clear old timer table and update upvalue
- AceTimer.activeTimers = {}
- activeTimers = AceTimer.activeTimers
- for handle, timer in pairs(oldTimers) do
- local newTimer
- -- Stop the old timer animation
- local duration, elapsed = timer:GetDuration(), timer:GetElapsed()
- timer:GetParent():Stop()
- if timer.looping then
- newTimer = AceTimer.ScheduleRepeatingTimer(timer.object, timer.func, duration, unpack(timer.args, 1, timer.argsCount))
- else
- newTimer = AceTimer.ScheduleTimer(timer.object, timer.func, duration - elapsed, unpack(timer.args, 1, timer.argsCount))
- end
- -- Use the old handle for old timers
- activeTimers[newTimer] = nil
- activeTimers[handle] = newTimer
- newTimer.handle = handle
- end
-
- -- Migrate transitional handles
- if oldminor < 13 and AceTimer.hashCompatTable then
- for handle, id in pairs(AceTimer.hashCompatTable) do
- local t = activeTimers[id]
- if t then
- activeTimers[id] = nil
- activeTimers[handle] = t
- t.handle = handle
- end
- end
- AceTimer.hashCompatTable = nil
- end
-end
-
--- ---------------------------------------------------------------------
--- Embed handling
-
-AceTimer.embeds = AceTimer.embeds or {}
-
-local mixins = {
- "ScheduleTimer", "ScheduleRepeatingTimer",
- "CancelTimer", "CancelAllTimers",
- "TimeLeft"
-}
-
-function AceTimer:Embed(target)
- AceTimer.embeds[target] = true
- for _,v in pairs(mixins) do
- target[v] = AceTimer[v]
- end
- return target
-end
-
--- AceTimer:OnEmbedDisable(target)
--- target (object) - target object that AceTimer is embedded in.
---
--- cancel all timers registered for the object
-function AceTimer:OnEmbedDisable(target)
- target:CancelAllTimers()
-end
-
-for addon in pairs(AceTimer.embeds) do
- AceTimer:Embed(addon)
-end