|
tercio@0
|
1 --- **AceTimer-3.0** provides a central facility for registering timers.
|
|
tercio@0
|
2 -- AceTimer supports one-shot timers and repeating timers. All timers are stored in an efficient
|
|
tercio@0
|
3 -- data structure that allows easy dispatching and fast rescheduling. Timers can be registered
|
|
tercio@0
|
4 -- or canceled at any time, even from within a running timer, without conflict or large overhead.\\
|
|
tercio@5
|
5 -- AceTimer is currently limited to firing timers at a frequency of 0.01s as this is what the WoW timer API
|
|
tercio@5
|
6 -- restricts us to.
|
|
tercio@0
|
7 --
|
|
tercio@0
|
8 -- All `:Schedule` functions will return a handle to the current timer, which you will need to store if you
|
|
tercio@0
|
9 -- need to cancel the timer you just registered.
|
|
tercio@0
|
10 --
|
|
tercio@0
|
11 -- **AceTimer-3.0** can be embeded into your addon, either explicitly by calling AceTimer:Embed(MyAddon) or by
|
|
tercio@0
|
12 -- specifying it as an embeded library in your AceAddon. All functions will be available on your addon object
|
|
tercio@0
|
13 -- and can be accessed directly, without having to explicitly call AceTimer itself.\\
|
|
tercio@0
|
14 -- It is recommended to embed AceTimer, otherwise you'll have to specify a custom `self` on all calls you
|
|
tercio@0
|
15 -- make into AceTimer.
|
|
tercio@0
|
16 -- @class file
|
|
tercio@0
|
17 -- @name AceTimer-3.0
|
|
tercio@5
|
18 -- @release $Id: AceTimer-3.0.lua 1119 2014-10-14 17:23:29Z nevcairiel $
|
|
tercio@0
|
19
|
|
tercio@5
|
20 local MAJOR, MINOR = "AceTimer-3.0", 17 -- Bump minor on changes
|
|
tercio@0
|
21 local AceTimer, oldminor = LibStub:NewLibrary(MAJOR, MINOR)
|
|
tercio@0
|
22
|
|
tercio@0
|
23 if not AceTimer then return end -- No upgrade needed
|
|
tercio@5
|
24 AceTimer.activeTimers = AceTimer.activeTimers or {} -- Active timer list
|
|
tercio@5
|
25 local activeTimers = AceTimer.activeTimers -- Upvalue our private data
|
|
tercio@0
|
26
|
|
tercio@0
|
27 -- Lua APIs
|
|
tercio@5
|
28 local type, unpack, next, error, select = type, unpack, next, error, select
|
|
tercio@5
|
29 -- WoW APIs
|
|
tercio@5
|
30 local GetTime, C_TimerAfter = GetTime, C_Timer.After
|
|
tercio@0
|
31
|
|
tercio@5
|
32 local function new(self, loop, func, delay, ...)
|
|
tercio@5
|
33 if delay < 0.01 then
|
|
tercio@5
|
34 delay = 0.01 -- Restrict to the lowest time that the C_Timer API allows us
|
|
tercio@0
|
35 end
|
|
tercio@0
|
36
|
|
tercio@5
|
37 local timer = {...}
|
|
tercio@0
|
38 timer.object = self
|
|
tercio@0
|
39 timer.func = func
|
|
tercio@0
|
40 timer.looping = loop
|
|
tercio@0
|
41 timer.argsCount = select("#", ...)
|
|
tercio@5
|
42 timer.delay = delay
|
|
tercio@5
|
43 timer.ends = GetTime() + delay
|
|
tercio@0
|
44
|
|
tercio@5
|
45 activeTimers[timer] = timer
|
|
tercio@5
|
46
|
|
tercio@5
|
47 -- Create new timer closure to wrap the "timer" object
|
|
tercio@5
|
48 timer.callback = function()
|
|
tercio@5
|
49 if not timer.cancelled then
|
|
tercio@5
|
50 if type(timer.func) == "string" then
|
|
tercio@5
|
51 -- We manually set the unpack count to prevent issues with an arg set that contains nil and ends with nil
|
|
tercio@5
|
52 -- e.g. local t = {1, 2, nil, 3, nil} print(#t) will result in 2, instead of 5. This fixes said issue.
|
|
tercio@5
|
53 timer.object[timer.func](timer.object, unpack(timer, 1, timer.argsCount))
|
|
tercio@5
|
54 else
|
|
tercio@5
|
55 timer.func(unpack(timer, 1, timer.argsCount))
|
|
tercio@5
|
56 end
|
|
tercio@5
|
57
|
|
tercio@5
|
58 if timer.looping and not timer.cancelled then
|
|
tercio@5
|
59 -- Compensate delay to get a perfect average delay, even if individual times don't match up perfectly
|
|
tercio@5
|
60 -- due to fps differences
|
|
tercio@5
|
61 local time = GetTime()
|
|
tercio@5
|
62 local delay = timer.delay - (time - timer.ends)
|
|
tercio@5
|
63 -- Ensure the delay doesn't go below the threshold
|
|
tercio@5
|
64 if delay < 0.01 then delay = 0.01 end
|
|
tercio@5
|
65 C_TimerAfter(delay, timer.callback)
|
|
tercio@5
|
66 timer.ends = time + delay
|
|
tercio@5
|
67 else
|
|
tercio@5
|
68 activeTimers[timer.handle or timer] = nil
|
|
tercio@5
|
69 end
|
|
tercio@5
|
70 end
|
|
tercio@0
|
71 end
|
|
tercio@0
|
72
|
|
tercio@5
|
73 C_TimerAfter(delay, timer.callback)
|
|
tercio@5
|
74 return timer
|
|
tercio@0
|
75 end
|
|
tercio@0
|
76
|
|
tercio@0
|
77 --- Schedule a new one-shot timer.
|
|
tercio@0
|
78 -- The timer will fire once in `delay` seconds, unless canceled before.
|
|
tercio@0
|
79 -- @param callback Callback function for the timer pulse (funcref or method name).
|
|
tercio@0
|
80 -- @param delay Delay for the timer, in seconds.
|
|
tercio@0
|
81 -- @param ... An optional, unlimited amount of arguments to pass to the callback function.
|
|
tercio@0
|
82 -- @usage
|
|
tercio@0
|
83 -- MyAddOn = LibStub("AceAddon-3.0"):NewAddon("MyAddOn", "AceTimer-3.0")
|
|
tercio@0
|
84 --
|
|
tercio@0
|
85 -- function MyAddOn:OnEnable()
|
|
tercio@0
|
86 -- self:ScheduleTimer("TimerFeedback", 5)
|
|
tercio@0
|
87 -- end
|
|
tercio@0
|
88 --
|
|
tercio@0
|
89 -- function MyAddOn:TimerFeedback()
|
|
tercio@0
|
90 -- print("5 seconds passed")
|
|
tercio@0
|
91 -- end
|
|
tercio@0
|
92 function AceTimer:ScheduleTimer(func, delay, ...)
|
|
tercio@0
|
93 if not func or not delay then
|
|
tercio@0
|
94 error(MAJOR..": ScheduleTimer(callback, delay, args...): 'callback' and 'delay' must have set values.", 2)
|
|
tercio@0
|
95 end
|
|
tercio@0
|
96 if type(func) == "string" then
|
|
tercio@0
|
97 if type(self) ~= "table" then
|
|
tercio@0
|
98 error(MAJOR..": ScheduleTimer(callback, delay, args...): 'self' - must be a table.", 2)
|
|
tercio@0
|
99 elseif not self[func] then
|
|
tercio@0
|
100 error(MAJOR..": ScheduleTimer(callback, delay, args...): Tried to register '"..func.."' as the callback, but it doesn't exist in the module.", 2)
|
|
tercio@0
|
101 end
|
|
tercio@0
|
102 end
|
|
tercio@0
|
103 return new(self, nil, func, delay, ...)
|
|
tercio@0
|
104 end
|
|
tercio@0
|
105
|
|
tercio@0
|
106 --- Schedule a repeating timer.
|
|
tercio@0
|
107 -- The timer will fire every `delay` seconds, until canceled.
|
|
tercio@0
|
108 -- @param callback Callback function for the timer pulse (funcref or method name).
|
|
tercio@0
|
109 -- @param delay Delay for the timer, in seconds.
|
|
tercio@0
|
110 -- @param ... An optional, unlimited amount of arguments to pass to the callback function.
|
|
tercio@0
|
111 -- @usage
|
|
tercio@0
|
112 -- MyAddOn = LibStub("AceAddon-3.0"):NewAddon("MyAddOn", "AceTimer-3.0")
|
|
tercio@0
|
113 --
|
|
tercio@0
|
114 -- function MyAddOn:OnEnable()
|
|
tercio@0
|
115 -- self.timerCount = 0
|
|
tercio@0
|
116 -- self.testTimer = self:ScheduleRepeatingTimer("TimerFeedback", 5)
|
|
tercio@0
|
117 -- end
|
|
tercio@0
|
118 --
|
|
tercio@0
|
119 -- function MyAddOn:TimerFeedback()
|
|
tercio@0
|
120 -- self.timerCount = self.timerCount + 1
|
|
tercio@0
|
121 -- print(("%d seconds passed"):format(5 * self.timerCount))
|
|
tercio@0
|
122 -- -- run 30 seconds in total
|
|
tercio@0
|
123 -- if self.timerCount == 6 then
|
|
tercio@0
|
124 -- self:CancelTimer(self.testTimer)
|
|
tercio@0
|
125 -- end
|
|
tercio@0
|
126 -- end
|
|
tercio@0
|
127 function AceTimer:ScheduleRepeatingTimer(func, delay, ...)
|
|
tercio@0
|
128 if not func or not delay then
|
|
tercio@0
|
129 error(MAJOR..": ScheduleRepeatingTimer(callback, delay, args...): 'callback' and 'delay' must have set values.", 2)
|
|
tercio@0
|
130 end
|
|
tercio@0
|
131 if type(func) == "string" then
|
|
tercio@0
|
132 if type(self) ~= "table" then
|
|
tercio@0
|
133 error(MAJOR..": ScheduleRepeatingTimer(callback, delay, args...): 'self' - must be a table.", 2)
|
|
tercio@0
|
134 elseif not self[func] then
|
|
tercio@0
|
135 error(MAJOR..": ScheduleRepeatingTimer(callback, delay, args...): Tried to register '"..func.."' as the callback, but it doesn't exist in the module.", 2)
|
|
tercio@0
|
136 end
|
|
tercio@0
|
137 end
|
|
tercio@0
|
138 return new(self, true, func, delay, ...)
|
|
tercio@0
|
139 end
|
|
tercio@0
|
140
|
|
tercio@0
|
141 --- Cancels a timer with the given id, registered by the same addon object as used for `:ScheduleTimer`
|
|
tercio@0
|
142 -- Both one-shot and repeating timers can be canceled with this function, as long as the `id` is valid
|
|
tercio@0
|
143 -- and the timer has not fired yet or was canceled before.
|
|
tercio@0
|
144 -- @param id The id of the timer, as returned by `:ScheduleTimer` or `:ScheduleRepeatingTimer`
|
|
tercio@0
|
145 function AceTimer:CancelTimer(id)
|
|
tercio@0
|
146 local timer = activeTimers[id]
|
|
tercio@0
|
147
|
|
tercio@5
|
148 if not timer then
|
|
tercio@5
|
149 return false
|
|
tercio@5
|
150 else
|
|
tercio@5
|
151 timer.cancelled = true
|
|
tercio@5
|
152 activeTimers[id] = nil
|
|
tercio@5
|
153 return true
|
|
tercio@5
|
154 end
|
|
tercio@0
|
155 end
|
|
tercio@0
|
156
|
|
tercio@0
|
157 --- Cancels all timers registered to the current addon object ('self')
|
|
tercio@0
|
158 function AceTimer:CancelAllTimers()
|
|
tercio@0
|
159 for k,v in pairs(activeTimers) do
|
|
tercio@0
|
160 if v.object == self then
|
|
tercio@0
|
161 AceTimer.CancelTimer(self, k)
|
|
tercio@0
|
162 end
|
|
tercio@0
|
163 end
|
|
tercio@0
|
164 end
|
|
tercio@0
|
165
|
|
tercio@0
|
166 --- Returns the time left for a timer with the given id, registered by the current addon object ('self').
|
|
tercio@0
|
167 -- This function will return 0 when the id is invalid.
|
|
tercio@0
|
168 -- @param id The id of the timer, as returned by `:ScheduleTimer` or `:ScheduleRepeatingTimer`
|
|
tercio@0
|
169 -- @return The time left on the timer.
|
|
tercio@0
|
170 function AceTimer:TimeLeft(id)
|
|
tercio@0
|
171 local timer = activeTimers[id]
|
|
tercio@5
|
172 if not timer then
|
|
tercio@5
|
173 return 0
|
|
tercio@5
|
174 else
|
|
tercio@5
|
175 return timer.ends - GetTime()
|
|
tercio@5
|
176 end
|
|
tercio@0
|
177 end
|
|
tercio@0
|
178
|
|
tercio@0
|
179
|
|
tercio@0
|
180 -- ---------------------------------------------------------------------
|
|
tercio@0
|
181 -- Upgrading
|
|
tercio@0
|
182
|
|
tercio@5
|
183 -- Upgrade from old hash-bucket based timers to C_Timer.After timers.
|
|
tercio@0
|
184 if oldminor and oldminor < 10 then
|
|
tercio@0
|
185 -- disable old timer logic
|
|
tercio@0
|
186 AceTimer.frame:SetScript("OnUpdate", nil)
|
|
tercio@0
|
187 AceTimer.frame:SetScript("OnEvent", nil)
|
|
tercio@0
|
188 AceTimer.frame:UnregisterAllEvents()
|
|
tercio@0
|
189 -- convert timers
|
|
tercio@0
|
190 for object,timers in pairs(AceTimer.selfs) do
|
|
tercio@0
|
191 for handle,timer in pairs(timers) do
|
|
tercio@0
|
192 if type(timer) == "table" and timer.callback then
|
|
tercio@5
|
193 local newTimer
|
|
tercio@0
|
194 if timer.delay then
|
|
tercio@5
|
195 newTimer = AceTimer.ScheduleRepeatingTimer(timer.object, timer.callback, timer.delay, timer.arg)
|
|
tercio@0
|
196 else
|
|
tercio@5
|
197 newTimer = AceTimer.ScheduleTimer(timer.object, timer.callback, timer.when - GetTime(), timer.arg)
|
|
tercio@0
|
198 end
|
|
tercio@5
|
199 -- Use the old handle for old timers
|
|
tercio@5
|
200 activeTimers[newTimer] = nil
|
|
tercio@5
|
201 activeTimers[handle] = newTimer
|
|
tercio@5
|
202 newTimer.handle = handle
|
|
tercio@0
|
203 end
|
|
tercio@0
|
204 end
|
|
tercio@0
|
205 end
|
|
tercio@0
|
206 AceTimer.selfs = nil
|
|
tercio@0
|
207 AceTimer.hash = nil
|
|
tercio@0
|
208 AceTimer.debug = nil
|
|
tercio@5
|
209 elseif oldminor and oldminor < 17 then
|
|
tercio@5
|
210 -- Upgrade from old animation based timers to C_Timer.After timers.
|
|
tercio@5
|
211 AceTimer.inactiveTimers = nil
|
|
tercio@5
|
212 AceTimer.frame = nil
|
|
tercio@5
|
213 local oldTimers = AceTimer.activeTimers
|
|
tercio@5
|
214 -- Clear old timer table and update upvalue
|
|
tercio@5
|
215 AceTimer.activeTimers = {}
|
|
tercio@5
|
216 activeTimers = AceTimer.activeTimers
|
|
tercio@5
|
217 for handle, timer in pairs(oldTimers) do
|
|
tercio@5
|
218 local newTimer
|
|
tercio@5
|
219 -- Stop the old timer animation
|
|
tercio@5
|
220 local duration, elapsed = timer:GetDuration(), timer:GetElapsed()
|
|
tercio@5
|
221 timer:GetParent():Stop()
|
|
tercio@5
|
222 if timer.looping then
|
|
tercio@5
|
223 newTimer = AceTimer.ScheduleRepeatingTimer(timer.object, timer.func, duration, unpack(timer.args, 1, timer.argsCount))
|
|
tercio@5
|
224 else
|
|
tercio@5
|
225 newTimer = AceTimer.ScheduleTimer(timer.object, timer.func, duration - elapsed, unpack(timer.args, 1, timer.argsCount))
|
|
tercio@0
|
226 end
|
|
tercio@5
|
227 -- Use the old handle for old timers
|
|
tercio@5
|
228 activeTimers[newTimer] = nil
|
|
tercio@5
|
229 activeTimers[handle] = newTimer
|
|
tercio@5
|
230 newTimer.handle = handle
|
|
tercio@0
|
231 end
|
|
tercio@0
|
232
|
|
tercio@5
|
233 -- Migrate transitional handles
|
|
tercio@5
|
234 if oldminor < 13 and AceTimer.hashCompatTable then
|
|
tercio@5
|
235 for handle, id in pairs(AceTimer.hashCompatTable) do
|
|
tercio@5
|
236 local t = activeTimers[id]
|
|
tercio@5
|
237 if t then
|
|
tercio@5
|
238 activeTimers[id] = nil
|
|
tercio@5
|
239 activeTimers[handle] = t
|
|
tercio@5
|
240 t.handle = handle
|
|
tercio@5
|
241 end
|
|
tercio@5
|
242 end
|
|
tercio@5
|
243 AceTimer.hashCompatTable = nil
|
|
tercio@5
|
244 end
|
|
tercio@0
|
245 end
|
|
tercio@0
|
246
|
|
tercio@0
|
247 -- ---------------------------------------------------------------------
|
|
tercio@0
|
248 -- Embed handling
|
|
tercio@0
|
249
|
|
tercio@0
|
250 AceTimer.embeds = AceTimer.embeds or {}
|
|
tercio@0
|
251
|
|
tercio@0
|
252 local mixins = {
|
|
tercio@0
|
253 "ScheduleTimer", "ScheduleRepeatingTimer",
|
|
tercio@0
|
254 "CancelTimer", "CancelAllTimers",
|
|
tercio@0
|
255 "TimeLeft"
|
|
tercio@0
|
256 }
|
|
tercio@0
|
257
|
|
tercio@0
|
258 function AceTimer:Embed(target)
|
|
tercio@0
|
259 AceTimer.embeds[target] = true
|
|
tercio@0
|
260 for _,v in pairs(mixins) do
|
|
tercio@0
|
261 target[v] = AceTimer[v]
|
|
tercio@0
|
262 end
|
|
tercio@0
|
263 return target
|
|
tercio@0
|
264 end
|
|
tercio@0
|
265
|
|
tercio@0
|
266 -- AceTimer:OnEmbedDisable(target)
|
|
tercio@0
|
267 -- target (object) - target object that AceTimer is embedded in.
|
|
tercio@0
|
268 --
|
|
tercio@0
|
269 -- cancel all timers registered for the object
|
|
tercio@0
|
270 function AceTimer:OnEmbedDisable(target)
|
|
tercio@0
|
271 target:CancelAllTimers()
|
|
tercio@0
|
272 end
|
|
tercio@0
|
273
|
|
tercio@0
|
274 for addon in pairs(AceTimer.embeds) do
|
|
tercio@0
|
275 AceTimer:Embed(addon)
|
|
tercio@0
|
276 end
|
