|
Asa@0
|
1 --- A bucket to catch events in. **AceBucket-3.0** provides throttling of events that fire in bursts and
|
|
Asa@0
|
2 -- your addon only needs to know about the full burst.
|
|
Asa@0
|
3 --
|
|
Asa@0
|
4 -- This Bucket implementation works as follows:\\
|
|
Asa@0
|
5 -- Initially, no schedule is running, and its waiting for the first event to happen.\\
|
|
Asa@0
|
6 -- The first event will start the bucket, and get the scheduler running, which will collect all
|
|
Asa@0
|
7 -- events in the given interval. When that interval is reached, the bucket is pushed to the
|
|
Asa@0
|
8 -- callback and a new schedule is started. When a bucket is empty after its interval, the scheduler is
|
|
Asa@0
|
9 -- stopped, and the bucket is only listening for the next event to happen, basically back in its initial state.
|
|
Asa@0
|
10 --
|
|
Asa@0
|
11 -- In addition, the buckets collect information about the "arg1" argument of the events that fire, and pass those as a
|
|
Asa@0
|
12 -- table to your callback. This functionality was mostly designed for the UNIT_* events.\\
|
|
Asa@0
|
13 -- The table will have the different values of "arg1" as keys, and the number of occurances as their value, e.g.\\
|
|
Asa@0
|
14 -- { ["player"] = 2, ["target"] = 1, ["party1"] = 1 }
|
|
Asa@0
|
15 --
|
|
Asa@0
|
16 -- **AceBucket-3.0** can be embeded into your addon, either explicitly by calling AceBucket:Embed(MyAddon) or by
|
|
Asa@0
|
17 -- specifying it as an embeded library in your AceAddon. All functions will be available on your addon object
|
|
Asa@0
|
18 -- and can be accessed directly, without having to explicitly call AceBucket itself.\\
|
|
Asa@0
|
19 -- It is recommended to embed AceBucket, otherwise you'll have to specify a custom `self` on all calls you
|
|
Asa@0
|
20 -- make into AceBucket.
|
|
Asa@0
|
21 -- @usage
|
|
Asa@0
|
22 -- MyAddon = LibStub("AceAddon-3.0"):NewAddon("BucketExample", "AceBucket-3.0")
|
|
Asa@0
|
23 --
|
|
Asa@0
|
24 -- function MyAddon:OnEnable()
|
|
Asa@0
|
25 -- -- Register a bucket that listens to all the HP related events,
|
|
Asa@0
|
26 -- -- and fires once per second
|
|
Asa@0
|
27 -- self:RegisterBucketEvent({"UNIT_HEALTH", "UNIT_MAXHEALTH"}, 1, "UpdateHealth")
|
|
Asa@0
|
28 -- end
|
|
Asa@0
|
29 --
|
|
Asa@0
|
30 -- function MyAddon:UpdateHealth(units)
|
|
Asa@0
|
31 -- if units.player then
|
|
Asa@0
|
32 -- print("Your HP changed!")
|
|
Asa@0
|
33 -- end
|
|
Asa@0
|
34 -- end
|
|
Asa@0
|
35 -- @class file
|
|
Asa@0
|
36 -- @name AceBucket-3.0.lua
|
|
Asa@0
|
37 -- @release $Id: AceBucket-3.0.lua 895 2009-12-06 16:28:55Z nevcairiel $
|
|
Asa@0
|
38
|
|
Asa@0
|
39 local MAJOR, MINOR = "AceBucket-3.0", 3
|
|
Asa@0
|
40 local AceBucket, oldminor = LibStub:NewLibrary(MAJOR, MINOR)
|
|
Asa@0
|
41
|
|
Asa@0
|
42 if not AceBucket then return end -- No Upgrade needed
|
|
Asa@0
|
43
|
|
Asa@0
|
44 AceBucket.buckets = AceBucket.buckets or {}
|
|
Asa@0
|
45 AceBucket.embeds = AceBucket.embeds or {}
|
|
Asa@0
|
46
|
|
Asa@0
|
47 -- the libraries will be lazyly bound later, to avoid errors due to loading order issues
|
|
Asa@0
|
48 local AceEvent, AceTimer
|
|
Asa@0
|
49
|
|
Asa@0
|
50 -- Lua APIs
|
|
Asa@0
|
51 local tconcat = table.concat
|
|
Asa@0
|
52 local type, next, pairs, select = type, next, pairs, select
|
|
Asa@0
|
53 local tonumber, tostring, rawset = tonumber, tostring, rawset
|
|
Asa@0
|
54 local assert, loadstring, error = assert, loadstring, error
|
|
Asa@0
|
55
|
|
Asa@0
|
56 -- Global vars/functions that we don't upvalue since they might get hooked, or upgraded
|
|
Asa@0
|
57 -- List them here for Mikk's FindGlobals script
|
|
Asa@0
|
58 -- GLOBALS: LibStub, geterrorhandler
|
|
Asa@0
|
59
|
|
Asa@0
|
60 local bucketCache = setmetatable({}, {__mode='k'})
|
|
Asa@0
|
61
|
|
Asa@0
|
62 --[[
|
|
Asa@0
|
63 xpcall safecall implementation
|
|
Asa@0
|
64 ]]
|
|
Asa@0
|
65 local xpcall = xpcall
|
|
Asa@0
|
66
|
|
Asa@0
|
67 local function errorhandler(err)
|
|
Asa@0
|
68 return geterrorhandler()(err)
|
|
Asa@0
|
69 end
|
|
Asa@0
|
70
|
|
Asa@0
|
71 local function CreateDispatcher(argCount)
|
|
Asa@0
|
72 local code = [[
|
|
Asa@0
|
73 local xpcall, eh = ...
|
|
Asa@0
|
74 local method, ARGS
|
|
Asa@0
|
75 local function call() return method(ARGS) end
|
|
Asa@0
|
76
|
|
Asa@0
|
77 local function dispatch(func, ...)
|
|
Asa@0
|
78 method = func
|
|
Asa@0
|
79 if not method then return end
|
|
Asa@0
|
80 ARGS = ...
|
|
Asa@0
|
81 return xpcall(call, eh)
|
|
Asa@0
|
82 end
|
|
Asa@0
|
83
|
|
Asa@0
|
84 return dispatch
|
|
Asa@0
|
85 ]]
|
|
Asa@0
|
86
|
|
Asa@0
|
87 local ARGS = {}
|
|
Asa@0
|
88 for i = 1, argCount do ARGS[i] = "arg"..i end
|
|
Asa@0
|
89 code = code:gsub("ARGS", tconcat(ARGS, ", "))
|
|
Asa@0
|
90 return assert(loadstring(code, "safecall Dispatcher["..argCount.."]"))(xpcall, errorhandler)
|
|
Asa@0
|
91 end
|
|
Asa@0
|
92
|
|
Asa@0
|
93 local Dispatchers = setmetatable({}, {__index=function(self, argCount)
|
|
Asa@0
|
94 local dispatcher = CreateDispatcher(argCount)
|
|
Asa@0
|
95 rawset(self, argCount, dispatcher)
|
|
Asa@0
|
96 return dispatcher
|
|
Asa@0
|
97 end})
|
|
Asa@0
|
98 Dispatchers[0] = function(func)
|
|
Asa@0
|
99 return xpcall(func, errorhandler)
|
|
Asa@0
|
100 end
|
|
Asa@0
|
101
|
|
Asa@0
|
102 local function safecall(func, ...)
|
|
Asa@0
|
103 return Dispatchers[select('#', ...)](func, ...)
|
|
Asa@0
|
104 end
|
|
Asa@0
|
105
|
|
Asa@0
|
106 -- FireBucket ( bucket )
|
|
Asa@0
|
107 --
|
|
Asa@0
|
108 -- send the bucket to the callback function and schedule the next FireBucket in interval seconds
|
|
Asa@0
|
109 local function FireBucket(bucket)
|
|
Asa@0
|
110 local received = bucket.received
|
|
Asa@0
|
111
|
|
Asa@0
|
112 -- we dont want to fire empty buckets
|
|
Asa@0
|
113 if next(received) then
|
|
Asa@0
|
114 local callback = bucket.callback
|
|
Asa@0
|
115 if type(callback) == "string" then
|
|
Asa@0
|
116 safecall(bucket.object[callback], bucket.object, received)
|
|
Asa@0
|
117 else
|
|
Asa@0
|
118 safecall(callback, received)
|
|
Asa@0
|
119 end
|
|
Asa@0
|
120
|
|
Asa@0
|
121 for k in pairs(received) do
|
|
Asa@0
|
122 received[k] = nil
|
|
Asa@0
|
123 end
|
|
Asa@0
|
124
|
|
Asa@0
|
125 -- if the bucket was not empty, schedule another FireBucket in interval seconds
|
|
Asa@0
|
126 bucket.timer = AceTimer.ScheduleTimer(bucket, FireBucket, bucket.interval, bucket)
|
|
Asa@0
|
127 else -- if it was empty, clear the timer and wait for the next event
|
|
Asa@0
|
128 bucket.timer = nil
|
|
Asa@0
|
129 end
|
|
Asa@0
|
130 end
|
|
Asa@0
|
131
|
|
Asa@0
|
132 -- BucketHandler ( event, arg1 )
|
|
Asa@0
|
133 --
|
|
Asa@0
|
134 -- callback func for AceEvent
|
|
Asa@0
|
135 -- stores arg1 in the received table, and schedules the bucket if necessary
|
|
Asa@0
|
136 local function BucketHandler(self, event, arg1)
|
|
Asa@0
|
137 if arg1 == nil then
|
|
Asa@0
|
138 arg1 = "nil"
|
|
Asa@0
|
139 end
|
|
Asa@0
|
140
|
|
Asa@0
|
141 self.received[arg1] = (self.received[arg1] or 0) + 1
|
|
Asa@0
|
142
|
|
Asa@0
|
143 -- if we are not scheduled yet, start a timer on the interval for our bucket to be cleared
|
|
Asa@0
|
144 if not self.timer then
|
|
Asa@0
|
145 self.timer = AceTimer.ScheduleTimer(self, FireBucket, self.interval, self)
|
|
Asa@0
|
146 end
|
|
Asa@0
|
147 end
|
|
Asa@0
|
148
|
|
Asa@0
|
149 -- RegisterBucket( event, interval, callback, isMessage )
|
|
Asa@0
|
150 --
|
|
Asa@0
|
151 -- event(string or table) - the event, or a table with the events, that this bucket listens to
|
|
Asa@0
|
152 -- interval(int) - time between bucket fireings
|
|
Asa@0
|
153 -- callback(func or string) - function pointer, or method name of the object, that gets called when the bucket is cleared
|
|
Asa@0
|
154 -- isMessage(boolean) - register AceEvent Messages instead of game events
|
|
Asa@0
|
155 local function RegisterBucket(self, event, interval, callback, isMessage)
|
|
Asa@0
|
156 -- try to fetch the librarys
|
|
Asa@0
|
157 if not AceEvent or not AceTimer then
|
|
Asa@0
|
158 AceEvent = LibStub:GetLibrary("AceEvent-3.0", true)
|
|
Asa@0
|
159 AceTimer = LibStub:GetLibrary("AceTimer-3.0", true)
|
|
Asa@0
|
160 if not AceEvent or not AceTimer then
|
|
Asa@0
|
161 error(MAJOR .. " requires AceEvent-3.0 and AceTimer-3.0", 3)
|
|
Asa@0
|
162 end
|
|
Asa@0
|
163 end
|
|
Asa@0
|
164
|
|
Asa@0
|
165 if type(event) ~= "string" and type(event) ~= "table" then error("Usage: RegisterBucket(event, interval, callback): 'event' - string or table expected.", 3) end
|
|
Asa@0
|
166 if not callback then
|
|
Asa@0
|
167 if type(event) == "string" then
|
|
Asa@0
|
168 callback = event
|
|
Asa@0
|
169 else
|
|
Asa@0
|
170 error("Usage: RegisterBucket(event, interval, callback): cannot omit callback when event is not a string.", 3)
|
|
Asa@0
|
171 end
|
|
Asa@0
|
172 end
|
|
Asa@0
|
173 if not tonumber(interval) then error("Usage: RegisterBucket(event, interval, callback): 'interval' - number expected.", 3) end
|
|
Asa@0
|
174 if type(callback) ~= "string" and type(callback) ~= "function" then error("Usage: RegisterBucket(event, interval, callback): 'callback' - string or function or nil expected.", 3) end
|
|
Asa@0
|
175 if type(callback) == "string" and type(self[callback]) ~= "function" then error("Usage: RegisterBucket(event, interval, callback): 'callback' - method not found on target object.", 3) end
|
|
Asa@0
|
176
|
|
Asa@0
|
177 local bucket = next(bucketCache)
|
|
Asa@0
|
178 if bucket then
|
|
Asa@0
|
179 bucketCache[bucket] = nil
|
|
Asa@0
|
180 else
|
|
Asa@0
|
181 bucket = { handler = BucketHandler, received = {} }
|
|
Asa@0
|
182 end
|
|
Asa@0
|
183 bucket.object, bucket.callback, bucket.interval = self, callback, tonumber(interval)
|
|
Asa@0
|
184
|
|
Asa@0
|
185 local regFunc = isMessage and AceEvent.RegisterMessage or AceEvent.RegisterEvent
|
|
Asa@0
|
186
|
|
Asa@0
|
187 if type(event) == "table" then
|
|
Asa@0
|
188 for _,e in pairs(event) do
|
|
Asa@0
|
189 regFunc(bucket, e, "handler")
|
|
Asa@0
|
190 end
|
|
Asa@0
|
191 else
|
|
Asa@0
|
192 regFunc(bucket, event, "handler")
|
|
Asa@0
|
193 end
|
|
Asa@0
|
194
|
|
Asa@0
|
195 local handle = tostring(bucket)
|
|
Asa@0
|
196 AceBucket.buckets[handle] = bucket
|
|
Asa@0
|
197
|
|
Asa@0
|
198 return handle
|
|
Asa@0
|
199 end
|
|
Asa@0
|
200
|
|
Asa@0
|
201 --- Register a Bucket for an event (or a set of events)
|
|
Asa@0
|
202 -- @param event The event to listen for, or a table of events.
|
|
Asa@0
|
203 -- @param interval The Bucket interval (burst interval)
|
|
Asa@0
|
204 -- @param callback The callback function, either as a function reference, or a string pointing to a method of the addon object.
|
|
Asa@0
|
205 -- @return The handle of the bucket (for unregistering)
|
|
Asa@0
|
206 -- @usage
|
|
Asa@0
|
207 -- MyAddon = LibStub("AceAddon-3.0"):NewAddon("MyAddon", "AceBucket-3.0")
|
|
Asa@0
|
208 -- MyAddon:RegisterBucketEvent("BAG_UPDATE", 0.2, "UpdateBags")
|
|
Asa@0
|
209 --
|
|
Asa@0
|
210 -- function MyAddon:UpdateBags()
|
|
Asa@0
|
211 -- -- do stuff
|
|
Asa@0
|
212 -- end
|
|
Asa@0
|
213 function AceBucket:RegisterBucketEvent(event, interval, callback)
|
|
Asa@0
|
214 return RegisterBucket(self, event, interval, callback, false)
|
|
Asa@0
|
215 end
|
|
Asa@0
|
216
|
|
Asa@0
|
217 --- Register a Bucket for an AceEvent-3.0 addon message (or a set of messages)
|
|
Asa@0
|
218 -- @param message The message to listen for, or a table of messages.
|
|
Asa@0
|
219 -- @param interval The Bucket interval (burst interval)
|
|
Asa@0
|
220 -- @param callback The callback function, either as a function reference, or a string pointing to a method of the addon object.
|
|
Asa@0
|
221 -- @return The handle of the bucket (for unregistering)
|
|
Asa@0
|
222 -- @usage
|
|
Asa@0
|
223 -- MyAddon = LibStub("AceAddon-3.0"):NewAddon("MyAddon", "AceBucket-3.0")
|
|
Asa@0
|
224 -- MyAddon:RegisterBucketEvent("SomeAddon_InformationMessage", 0.2, "ProcessData")
|
|
Asa@0
|
225 --
|
|
Asa@0
|
226 -- function MyAddon:ProcessData()
|
|
Asa@0
|
227 -- -- do stuff
|
|
Asa@0
|
228 -- end
|
|
Asa@0
|
229 function AceBucket:RegisterBucketMessage(message, interval, callback)
|
|
Asa@0
|
230 return RegisterBucket(self, message, interval, callback, true)
|
|
Asa@0
|
231 end
|
|
Asa@0
|
232
|
|
Asa@0
|
233 --- Unregister any events and messages from the bucket and clear any remaining data.
|
|
Asa@0
|
234 -- @param handle The handle of the bucket as returned by RegisterBucket*
|
|
Asa@0
|
235 function AceBucket:UnregisterBucket(handle)
|
|
Asa@0
|
236 local bucket = AceBucket.buckets[handle]
|
|
Asa@0
|
237 if bucket then
|
|
Asa@0
|
238 AceEvent.UnregisterAllEvents(bucket)
|
|
Asa@0
|
239 AceEvent.UnregisterAllMessages(bucket)
|
|
Asa@0
|
240
|
|
Asa@0
|
241 -- clear any remaining data in the bucket
|
|
Asa@0
|
242 for k in pairs(bucket.received) do
|
|
Asa@0
|
243 bucket.received[k] = nil
|
|
Asa@0
|
244 end
|
|
Asa@0
|
245
|
|
Asa@0
|
246 if bucket.timer then
|
|
Asa@0
|
247 AceTimer.CancelTimer(bucket, bucket.timer)
|
|
Asa@0
|
248 bucket.timer = nil
|
|
Asa@0
|
249 end
|
|
Asa@0
|
250
|
|
Asa@0
|
251 AceBucket.buckets[handle] = nil
|
|
Asa@0
|
252 -- store our bucket in the cache
|
|
Asa@0
|
253 bucketCache[bucket] = true
|
|
Asa@0
|
254 end
|
|
Asa@0
|
255 end
|
|
Asa@0
|
256
|
|
Asa@0
|
257 --- Unregister all buckets of the current addon object (or custom "self").
|
|
Asa@0
|
258 function AceBucket:UnregisterAllBuckets()
|
|
Asa@0
|
259 -- hmm can we do this more efficient? (it is not done often so shouldn't matter much)
|
|
Asa@0
|
260 for handle, bucket in pairs(AceBucket.buckets) do
|
|
Asa@0
|
261 if bucket.object == self then
|
|
Asa@0
|
262 AceBucket.UnregisterBucket(self, handle)
|
|
Asa@0
|
263 end
|
|
Asa@0
|
264 end
|
|
Asa@0
|
265 end
|
|
Asa@0
|
266
|
|
Asa@0
|
267
|
|
Asa@0
|
268
|
|
Asa@0
|
269 -- embedding and embed handling
|
|
Asa@0
|
270 local mixins = {
|
|
Asa@0
|
271 "RegisterBucketEvent",
|
|
Asa@0
|
272 "RegisterBucketMessage",
|
|
Asa@0
|
273 "UnregisterBucket",
|
|
Asa@0
|
274 "UnregisterAllBuckets",
|
|
Asa@0
|
275 }
|
|
Asa@0
|
276
|
|
Asa@0
|
277 -- Embeds AceBucket into the target object making the functions from the mixins list available on target:..
|
|
Asa@0
|
278 -- @param target target object to embed AceBucket in
|
|
Asa@0
|
279 function AceBucket:Embed( target )
|
|
Asa@0
|
280 for _, v in pairs( mixins ) do
|
|
Asa@0
|
281 target[v] = self[v]
|
|
Asa@0
|
282 end
|
|
Asa@0
|
283 self.embeds[target] = true
|
|
Asa@0
|
284 return target
|
|
Asa@0
|
285 end
|
|
Asa@0
|
286
|
|
Asa@0
|
287 function AceBucket:OnEmbedDisable( target )
|
|
Asa@0
|
288 target:UnregisterAllBuckets()
|
|
Asa@0
|
289 end
|
|
Asa@0
|
290
|
|
Asa@0
|
291 for addon in pairs(AceBucket.embeds) do
|
|
Asa@0
|
292 AceBucket:Embed(addon)
|
|
Asa@0
|
293 end
|
