tercio@0: --- **AceTimer-3.0** provides a central facility for registering timers.
tercio@0: -- AceTimer supports one-shot timers and repeating timers. All timers are stored in an efficient
tercio@0: -- data structure that allows easy dispatching and fast rescheduling. Timers can be registered
tercio@0: -- or canceled at any time, even from within a running timer, without conflict or large overhead.\\
tercio@0: -- AceTimer is currently limited to firing timers at a frequency of 0.01s. This constant may change
tercio@0: -- in the future, but for now it's required as animations with lower frequencies are buggy.
tercio@0: --
tercio@0: -- All `:Schedule` functions will return a handle to the current timer, which you will need to store if you
tercio@0: -- need to cancel the timer you just registered.
tercio@0: --
tercio@0: -- **AceTimer-3.0** can be embeded into your addon, either explicitly by calling AceTimer:Embed(MyAddon) or by
tercio@0: -- specifying it as an embeded library in your AceAddon. All functions will be available on your addon object
tercio@0: -- and can be accessed directly, without having to explicitly call AceTimer itself.\\
tercio@0: -- It is recommended to embed AceTimer, otherwise you'll have to specify a custom `self` on all calls you
tercio@0: -- make into AceTimer.
tercio@0: -- @class file
tercio@0: -- @name AceTimer-3.0
tercio@0: -- @release $Id: AceTimer-3.0.lua 1079 2013-02-17 19:56:06Z funkydude $
tercio@0: 
tercio@0: local MAJOR, MINOR = "AceTimer-3.0", 16 -- Bump minor on changes
tercio@0: local AceTimer, oldminor = LibStub:NewLibrary(MAJOR, MINOR)
tercio@0: 
tercio@0: if not AceTimer then return end -- No upgrade needed
tercio@0: 
tercio@0: AceTimer.frame = AceTimer.frame or CreateFrame("Frame", "AceTimer30Frame") -- Animation parent
tercio@0: AceTimer.inactiveTimers = AceTimer.inactiveTimers or {}                    -- Timer recycling storage
tercio@0: AceTimer.activeTimers = AceTimer.activeTimers or {}                        -- Active timer list
tercio@0: 
tercio@0: -- Lua APIs
tercio@0: local type, unpack, next, error, pairs, tostring, select = type, unpack, next, error, pairs, tostring, select
tercio@0: 
tercio@0: -- Upvalue our private data
tercio@0: local inactiveTimers = AceTimer.inactiveTimers
tercio@0: local activeTimers = AceTimer.activeTimers
tercio@0: 
tercio@0: local function OnFinished(self)
tercio@0: 	local id = self.id
tercio@0: 	if type(self.func) == "string" then
tercio@0: 		-- We manually set the unpack count to prevent issues with an arg set that contains nil and ends with nil
tercio@0: 		-- e.g. local t = {1, 2, nil, 3, nil} print(#t) will result in 2, instead of 5. This fixes said issue.
tercio@0: 		self.object[self.func](self.object, unpack(self.args, 1, self.argsCount))
tercio@0: 	else
tercio@0: 		self.func(unpack(self.args, 1, self.argsCount))
tercio@0: 	end
tercio@0: 
tercio@0: 	-- If the id is different it means that the timer was already cancelled
tercio@0: 	-- and has been used to create a new timer during the OnFinished callback.
tercio@0: 	if not self.looping and id == self.id then
tercio@0: 		activeTimers[self.id] = nil
tercio@0: 		self.args = nil
tercio@0: 		inactiveTimers[self] = true
tercio@0: 	end
tercio@0: end
tercio@0: 
tercio@0: local function new(self, loop, func, delay, ...)
tercio@0: 	local timer = next(inactiveTimers)
tercio@0: 	if timer then
tercio@0: 		inactiveTimers[timer] = nil
tercio@0: 	else
tercio@0: 		local anim = AceTimer.frame:CreateAnimationGroup()
tercio@0: 		timer = anim:CreateAnimation()
tercio@0: 		timer:SetScript("OnFinished", OnFinished)
tercio@0: 	end
tercio@0: 
tercio@0: 	-- Very low delays cause the animations to fail randomly.
tercio@0: 	-- A limited resolution of 0.01 seems reasonable.
tercio@0: 	if delay < 0.01 then
tercio@0: 		delay = 0.01
tercio@0: 	end
tercio@0: 
tercio@0: 	timer.object = self
tercio@0: 	timer.func = func
tercio@0: 	timer.looping = loop
tercio@0: 	timer.args = {...}
tercio@0: 	timer.argsCount = select("#", ...)
tercio@0: 
tercio@0: 	local anim = timer:GetParent()
tercio@0: 	if loop then
tercio@0: 		anim:SetLooping("REPEAT")
tercio@0: 	else
tercio@0: 		anim:SetLooping("NONE")
tercio@0: 	end
tercio@0: 	timer:SetDuration(delay)
tercio@0: 
tercio@0: 	local id = tostring(timer.args)
tercio@0: 	timer.id = id
tercio@0: 	activeTimers[id] = timer
tercio@0: 
tercio@0: 	anim:Play()
tercio@0: 	return id
tercio@0: end
tercio@0: 
tercio@0: --- Schedule a new one-shot timer.
tercio@0: -- The timer will fire once in `delay` seconds, unless canceled before.
tercio@0: -- @param callback Callback function for the timer pulse (funcref or method name).
tercio@0: -- @param delay Delay for the timer, in seconds.
tercio@0: -- @param ... An optional, unlimited amount of arguments to pass to the callback function.
tercio@0: -- @usage
tercio@0: -- MyAddOn = LibStub("AceAddon-3.0"):NewAddon("MyAddOn", "AceTimer-3.0")
tercio@0: --
tercio@0: -- function MyAddOn:OnEnable()
tercio@0: --   self:ScheduleTimer("TimerFeedback", 5)
tercio@0: -- end
tercio@0: --
tercio@0: -- function MyAddOn:TimerFeedback()
tercio@0: --   print("5 seconds passed")
tercio@0: -- end
tercio@0: function AceTimer:ScheduleTimer(func, delay, ...)
tercio@0: 	if not func or not delay then
tercio@0: 		error(MAJOR..": ScheduleTimer(callback, delay, args...): 'callback' and 'delay' must have set values.", 2)
tercio@0: 	end
tercio@0: 	if type(func) == "string" then
tercio@0: 		if type(self) ~= "table" then
tercio@0: 			error(MAJOR..": ScheduleTimer(callback, delay, args...): 'self' - must be a table.", 2)
tercio@0: 		elseif not self[func] then
tercio@0: 			error(MAJOR..": ScheduleTimer(callback, delay, args...): Tried to register '"..func.."' as the callback, but it doesn't exist in the module.", 2)
tercio@0: 		end
tercio@0: 	end
tercio@0: 	return new(self, nil, func, delay, ...)
tercio@0: end
tercio@0: 
tercio@0: --- Schedule a repeating timer.
tercio@0: -- The timer will fire every `delay` seconds, until canceled.
tercio@0: -- @param callback Callback function for the timer pulse (funcref or method name).
tercio@0: -- @param delay Delay for the timer, in seconds.
tercio@0: -- @param ... An optional, unlimited amount of arguments to pass to the callback function.
tercio@0: -- @usage
tercio@0: -- MyAddOn = LibStub("AceAddon-3.0"):NewAddon("MyAddOn", "AceTimer-3.0")
tercio@0: --
tercio@0: -- function MyAddOn:OnEnable()
tercio@0: --   self.timerCount = 0
tercio@0: --   self.testTimer = self:ScheduleRepeatingTimer("TimerFeedback", 5)
tercio@0: -- end
tercio@0: --
tercio@0: -- function MyAddOn:TimerFeedback()
tercio@0: --   self.timerCount = self.timerCount + 1
tercio@0: --   print(("%d seconds passed"):format(5 * self.timerCount))
tercio@0: --   -- run 30 seconds in total
tercio@0: --   if self.timerCount == 6 then
tercio@0: --     self:CancelTimer(self.testTimer)
tercio@0: --   end
tercio@0: -- end
tercio@0: function AceTimer:ScheduleRepeatingTimer(func, delay, ...)
tercio@0: 	if not func or not delay then
tercio@0: 		error(MAJOR..": ScheduleRepeatingTimer(callback, delay, args...): 'callback' and 'delay' must have set values.", 2)
tercio@0: 	end
tercio@0: 	if type(func) == "string" then
tercio@0: 		if type(self) ~= "table" then
tercio@0: 			error(MAJOR..": ScheduleRepeatingTimer(callback, delay, args...): 'self' - must be a table.", 2)
tercio@0: 		elseif not self[func] then
tercio@0: 			error(MAJOR..": ScheduleRepeatingTimer(callback, delay, args...): Tried to register '"..func.."' as the callback, but it doesn't exist in the module.", 2)
tercio@0: 		end
tercio@0: 	end
tercio@0: 	return new(self, true, func, delay, ...)
tercio@0: end
tercio@0: 
tercio@0: --- Cancels a timer with the given id, registered by the same addon object as used for `:ScheduleTimer`
tercio@0: -- Both one-shot and repeating timers can be canceled with this function, as long as the `id` is valid
tercio@0: -- and the timer has not fired yet or was canceled before.
tercio@0: -- @param id The id of the timer, as returned by `:ScheduleTimer` or `:ScheduleRepeatingTimer`
tercio@0: function AceTimer:CancelTimer(id)
tercio@0: 	local timer = activeTimers[id]
tercio@0: 	if not timer then return false end
tercio@0: 
tercio@0: 	local anim = timer:GetParent()
tercio@0: 	anim:Stop()
tercio@0: 
tercio@0: 	activeTimers[id] = nil
tercio@0: 	timer.args = nil
tercio@0: 	inactiveTimers[timer] = true
tercio@0: 	return true
tercio@0: end
tercio@0: 
tercio@0: --- Cancels all timers registered to the current addon object ('self')
tercio@0: function AceTimer:CancelAllTimers()
tercio@0: 	for k,v in pairs(activeTimers) do
tercio@0: 		if v.object == self then
tercio@0: 			AceTimer.CancelTimer(self, k)
tercio@0: 		end
tercio@0: 	end
tercio@0: end
tercio@0: 
tercio@0: --- Returns the time left for a timer with the given id, registered by the current addon object ('self').
tercio@0: -- This function will return 0 when the id is invalid.
tercio@0: -- @param id The id of the timer, as returned by `:ScheduleTimer` or `:ScheduleRepeatingTimer`
tercio@0: -- @return The time left on the timer.
tercio@0: function AceTimer:TimeLeft(id)
tercio@0: 	local timer = activeTimers[id]
tercio@0: 	if not timer then return 0 end
tercio@0: 	return timer:GetDuration() - timer:GetElapsed()
tercio@0: end
tercio@0: 
tercio@0: 
tercio@0: -- ---------------------------------------------------------------------
tercio@0: -- Upgrading
tercio@0: 
tercio@0: -- Upgrade from old hash-bucket based timers to animation timers
tercio@0: if oldminor and oldminor < 10 then
tercio@0: 	-- disable old timer logic
tercio@0: 	AceTimer.frame:SetScript("OnUpdate", nil)
tercio@0: 	AceTimer.frame:SetScript("OnEvent", nil)
tercio@0: 	AceTimer.frame:UnregisterAllEvents()
tercio@0: 	-- convert timers
tercio@0: 	for object,timers in pairs(AceTimer.selfs) do
tercio@0: 		for handle,timer in pairs(timers) do
tercio@0: 			if type(timer) == "table" and timer.callback then
tercio@0: 				local id
tercio@0: 				if timer.delay then
tercio@0: 					id = AceTimer.ScheduleRepeatingTimer(timer.object, timer.callback, timer.delay, timer.arg)
tercio@0: 				else
tercio@0: 					id = AceTimer.ScheduleTimer(timer.object, timer.callback, timer.when - GetTime(), timer.arg)
tercio@0: 				end
tercio@0: 				-- change id to the old handle
tercio@0: 				local t = activeTimers[id]
tercio@0: 				activeTimers[id] = nil
tercio@0: 				activeTimers[handle] = t
tercio@0: 				t.id = handle
tercio@0: 			end
tercio@0: 		end
tercio@0: 	end
tercio@0: 	AceTimer.selfs = nil
tercio@0: 	AceTimer.hash = nil
tercio@0: 	AceTimer.debug = nil
tercio@0: elseif oldminor and oldminor < 13 then
tercio@0: 	for handle, id in pairs(AceTimer.hashCompatTable) do
tercio@0: 		local t = activeTimers[id]
tercio@0: 		if t then
tercio@0: 			activeTimers[id] = nil
tercio@0: 			activeTimers[handle] = t
tercio@0: 			t.id = handle
tercio@0: 		end
tercio@0: 	end
tercio@0: 	AceTimer.hashCompatTable = nil
tercio@0: end
tercio@0: 
tercio@0: -- upgrade existing timers to the latest OnFinished
tercio@0: for timer in pairs(inactiveTimers) do
tercio@0: 	timer:SetScript("OnFinished", OnFinished)
tercio@0: end
tercio@0: 
tercio@0: for _,timer in pairs(activeTimers) do
tercio@0: 	timer:SetScript("OnFinished", OnFinished)
tercio@0: end
tercio@0: 
tercio@0: -- ---------------------------------------------------------------------
tercio@0: -- Embed handling
tercio@0: 
tercio@0: AceTimer.embeds = AceTimer.embeds or {}
tercio@0: 
tercio@0: local mixins = {
tercio@0: 	"ScheduleTimer", "ScheduleRepeatingTimer",
tercio@0: 	"CancelTimer", "CancelAllTimers",
tercio@0: 	"TimeLeft"
tercio@0: }
tercio@0: 
tercio@0: function AceTimer:Embed(target)
tercio@0: 	AceTimer.embeds[target] = true
tercio@0: 	for _,v in pairs(mixins) do
tercio@0: 		target[v] = AceTimer[v]
tercio@0: 	end
tercio@0: 	return target
tercio@0: end
tercio@0: 
tercio@0: -- AceTimer:OnEmbedDisable(target)
tercio@0: -- target (object) - target object that AceTimer is embedded in.
tercio@0: --
tercio@0: -- cancel all timers registered for the object
tercio@0: function AceTimer:OnEmbedDisable(target)
tercio@0: 	target:CancelAllTimers()
tercio@0: end
tercio@0: 
tercio@0: for addon in pairs(AceTimer.embeds) do
tercio@0: 	AceTimer:Embed(addon)
tercio@0: end