Asa@0: --- A bucket to catch events in. **AceBucket-3.0** provides throttling of events that fire in bursts and
Asa@0: -- your addon only needs to know about the full burst.
Asa@0: -- 
Asa@0: -- This Bucket implementation works as follows:\\
Asa@0: --   Initially, no schedule is running, and its waiting for the first event to happen.\\
Asa@0: --   The first event will start the bucket, and get the scheduler running, which will collect all
Asa@0: --   events in the given interval. When that interval is reached, the bucket is pushed to the 
Asa@0: --   callback and a new schedule is started. When a bucket is empty after its interval, the scheduler is 
Asa@0: --   stopped, and the bucket is only listening for the next event to happen, basically back in its initial state.
Asa@0: -- 
Asa@0: -- In addition, the buckets collect information about the "arg1" argument of the events that fire, and pass those as a 
Asa@0: -- table to your callback. This functionality was mostly designed for the UNIT_* events.\\
Asa@0: -- The table will have the different values of "arg1" as keys, and the number of occurances as their value, e.g.\\
Asa@0: --   { ["player"] = 2, ["target"] = 1, ["party1"] = 1 }
Asa@0: --
Asa@0: -- **AceBucket-3.0** can be embeded into your addon, either explicitly by calling AceBucket:Embed(MyAddon) or by 
Asa@0: -- specifying it as an embeded library in your AceAddon. All functions will be available on your addon object
Asa@0: -- and can be accessed directly, without having to explicitly call AceBucket itself.\\
Asa@0: -- It is recommended to embed AceBucket, otherwise you'll have to specify a custom `self` on all calls you
Asa@0: -- make into AceBucket.
Asa@0: -- @usage
Asa@0: -- MyAddon = LibStub("AceAddon-3.0"):NewAddon("BucketExample", "AceBucket-3.0")
Asa@0: -- 
Asa@0: -- function MyAddon:OnEnable()
Asa@0: --   -- Register a bucket that listens to all the HP related events, 
Asa@0: --   -- and fires once per second
Asa@0: --   self:RegisterBucketEvent({"UNIT_HEALTH", "UNIT_MAXHEALTH"}, 1, "UpdateHealth")
Asa@0: -- end
Asa@0: --
Asa@0: -- function MyAddon:UpdateHealth(units)
Asa@0: --   if units.player then
Asa@0: --     print("Your HP changed!")
Asa@0: --   end
Asa@0: -- end
Asa@0: -- @class file
Asa@0: -- @name AceBucket-3.0.lua
Asa@0: -- @release $Id: AceBucket-3.0.lua 895 2009-12-06 16:28:55Z nevcairiel $
Asa@0: 
Asa@0: local MAJOR, MINOR = "AceBucket-3.0", 3
Asa@0: local AceBucket, oldminor = LibStub:NewLibrary(MAJOR, MINOR)
Asa@0: 
Asa@0: if not AceBucket then return end -- No Upgrade needed
Asa@0: 
Asa@0: AceBucket.buckets = AceBucket.buckets or {}
Asa@0: AceBucket.embeds = AceBucket.embeds or {}
Asa@0: 
Asa@0: -- the libraries will be lazyly bound later, to avoid errors due to loading order issues
Asa@0: local AceEvent, AceTimer
Asa@0: 
Asa@0: -- Lua APIs
Asa@0: local tconcat = table.concat
Asa@0: local type, next, pairs, select = type, next, pairs, select
Asa@0: local tonumber, tostring, rawset = tonumber, tostring, rawset
Asa@0: local assert, loadstring, error = assert, loadstring, error
Asa@0: 
Asa@0: -- Global vars/functions that we don't upvalue since they might get hooked, or upgraded
Asa@0: -- List them here for Mikk's FindGlobals script
Asa@0: -- GLOBALS: LibStub, geterrorhandler
Asa@0: 
Asa@0: local bucketCache = setmetatable({}, {__mode='k'})
Asa@0: 
Asa@0: --[[
Asa@0: 	 xpcall safecall implementation
Asa@0: ]]
Asa@0: local xpcall = xpcall
Asa@0: 
Asa@0: local function errorhandler(err)
Asa@0: 	return geterrorhandler()(err)
Asa@0: end
Asa@0: 
Asa@0: local function CreateDispatcher(argCount)
Asa@0: 	local code = [[
Asa@0: 		local xpcall, eh = ...
Asa@0: 		local method, ARGS
Asa@0: 		local function call() return method(ARGS) end
Asa@0: 	
Asa@0: 		local function dispatch(func, ...)
Asa@0: 			 method = func
Asa@0: 			 if not method then return end
Asa@0: 			 ARGS = ...
Asa@0: 			 return xpcall(call, eh)
Asa@0: 		end
Asa@0: 	
Asa@0: 		return dispatch
Asa@0: 	]]
Asa@0: 	
Asa@0: 	local ARGS = {}
Asa@0: 	for i = 1, argCount do ARGS[i] = "arg"..i end
Asa@0: 	code = code:gsub("ARGS", tconcat(ARGS, ", "))
Asa@0: 	return assert(loadstring(code, "safecall Dispatcher["..argCount.."]"))(xpcall, errorhandler)
Asa@0: end
Asa@0: 
Asa@0: local Dispatchers = setmetatable({}, {__index=function(self, argCount)
Asa@0: 	local dispatcher = CreateDispatcher(argCount)
Asa@0: 	rawset(self, argCount, dispatcher)
Asa@0: 	return dispatcher
Asa@0: end})
Asa@0: Dispatchers[0] = function(func)
Asa@0: 	return xpcall(func, errorhandler)
Asa@0: end
Asa@0:  
Asa@0: local function safecall(func, ...)
Asa@0: 	return Dispatchers[select('#', ...)](func, ...)
Asa@0: end
Asa@0: 
Asa@0: -- FireBucket ( bucket )
Asa@0: --
Asa@0: -- send the bucket to the callback function and schedule the next FireBucket in interval seconds
Asa@0: local function FireBucket(bucket)
Asa@0: 	local received = bucket.received
Asa@0: 	
Asa@0: 	-- we dont want to fire empty buckets
Asa@0: 	if next(received) then
Asa@0: 		local callback = bucket.callback
Asa@0: 		if type(callback) == "string" then
Asa@0: 			safecall(bucket.object[callback], bucket.object, received)
Asa@0: 		else
Asa@0: 			safecall(callback, received)
Asa@0: 		end
Asa@0: 		
Asa@0: 		for k in pairs(received) do
Asa@0: 			received[k] = nil
Asa@0: 		end
Asa@0: 		
Asa@0: 		-- if the bucket was not empty, schedule another FireBucket in interval seconds
Asa@0: 		bucket.timer = AceTimer.ScheduleTimer(bucket, FireBucket, bucket.interval, bucket)
Asa@0: 	else -- if it was empty, clear the timer and wait for the next event
Asa@0: 		bucket.timer = nil
Asa@0: 	end
Asa@0: end
Asa@0: 
Asa@0: -- BucketHandler ( event, arg1 )
Asa@0: -- 
Asa@0: -- callback func for AceEvent
Asa@0: -- stores arg1 in the received table, and schedules the bucket if necessary
Asa@0: local function BucketHandler(self, event, arg1)
Asa@0: 	if arg1 == nil then
Asa@0: 		arg1 = "nil"
Asa@0: 	end
Asa@0: 	
Asa@0: 	self.received[arg1] = (self.received[arg1] or 0) + 1
Asa@0: 	
Asa@0: 	-- if we are not scheduled yet, start a timer on the interval for our bucket to be cleared
Asa@0: 	if not self.timer then
Asa@0: 		self.timer = AceTimer.ScheduleTimer(self, FireBucket, self.interval, self)
Asa@0: 	end
Asa@0: end
Asa@0: 
Asa@0: -- RegisterBucket( event, interval, callback, isMessage )
Asa@0: --
Asa@0: -- event(string or table) - the event, or a table with the events, that this bucket listens to
Asa@0: -- interval(int) - time between bucket fireings
Asa@0: -- callback(func or string) - function pointer, or method name of the object, that gets called when the bucket is cleared
Asa@0: -- isMessage(boolean) - register AceEvent Messages instead of game events
Asa@0: local function RegisterBucket(self, event, interval, callback, isMessage)
Asa@0: 	-- try to fetch the librarys
Asa@0: 	if not AceEvent or not AceTimer then 
Asa@0: 		AceEvent = LibStub:GetLibrary("AceEvent-3.0", true)
Asa@0: 		AceTimer = LibStub:GetLibrary("AceTimer-3.0", true)
Asa@0: 		if not AceEvent or not AceTimer then
Asa@0: 			error(MAJOR .. " requires AceEvent-3.0 and AceTimer-3.0", 3)
Asa@0: 		end
Asa@0: 	end
Asa@0: 	
Asa@0: 	if type(event) ~= "string" and type(event) ~= "table" then error("Usage: RegisterBucket(event, interval, callback): 'event' - string or table expected.", 3) end
Asa@0: 	if not callback then
Asa@0: 		if type(event) == "string" then
Asa@0: 			callback = event
Asa@0: 		else
Asa@0: 			error("Usage: RegisterBucket(event, interval, callback): cannot omit callback when event is not a string.", 3)
Asa@0: 		end
Asa@0: 	end
Asa@0: 	if not tonumber(interval) then error("Usage: RegisterBucket(event, interval, callback): 'interval' - number expected.", 3) end
Asa@0: 	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: 	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: 	
Asa@0: 	local bucket = next(bucketCache)
Asa@0: 	if bucket then
Asa@0: 		bucketCache[bucket] = nil
Asa@0: 	else
Asa@0: 		bucket = { handler = BucketHandler, received = {} }
Asa@0: 	end
Asa@0: 	bucket.object, bucket.callback, bucket.interval = self, callback, tonumber(interval)
Asa@0: 	
Asa@0: 	local regFunc = isMessage and AceEvent.RegisterMessage or AceEvent.RegisterEvent
Asa@0: 	
Asa@0: 	if type(event) == "table" then
Asa@0: 		for _,e in pairs(event) do
Asa@0: 			regFunc(bucket, e, "handler")
Asa@0: 		end
Asa@0: 	else
Asa@0: 		regFunc(bucket, event, "handler")
Asa@0: 	end
Asa@0: 	
Asa@0: 	local handle = tostring(bucket)
Asa@0: 	AceBucket.buckets[handle] = bucket
Asa@0: 	
Asa@0: 	return handle
Asa@0: end
Asa@0: 
Asa@0: --- Register a Bucket for an event (or a set of events)
Asa@0: -- @param event The event to listen for, or a table of events.
Asa@0: -- @param interval The Bucket interval (burst interval)
Asa@0: -- @param callback The callback function, either as a function reference, or a string pointing to a method of the addon object.
Asa@0: -- @return The handle of the bucket (for unregistering)
Asa@0: -- @usage
Asa@0: -- MyAddon = LibStub("AceAddon-3.0"):NewAddon("MyAddon", "AceBucket-3.0")
Asa@0: -- MyAddon:RegisterBucketEvent("BAG_UPDATE", 0.2, "UpdateBags")
Asa@0: -- 
Asa@0: -- function MyAddon:UpdateBags()
Asa@0: --   -- do stuff
Asa@0: -- end
Asa@0: function AceBucket:RegisterBucketEvent(event, interval, callback)
Asa@0: 	return RegisterBucket(self, event, interval, callback, false)
Asa@0: end
Asa@0: 
Asa@0: --- Register a Bucket for an AceEvent-3.0 addon message (or a set of messages)
Asa@0: -- @param message The message to listen for, or a table of messages.
Asa@0: -- @param interval The Bucket interval (burst interval)
Asa@0: -- @param callback The callback function, either as a function reference, or a string pointing to a method of the addon object.
Asa@0: -- @return The handle of the bucket (for unregistering)
Asa@0: -- @usage
Asa@0: -- MyAddon = LibStub("AceAddon-3.0"):NewAddon("MyAddon", "AceBucket-3.0")
Asa@0: -- MyAddon:RegisterBucketEvent("SomeAddon_InformationMessage", 0.2, "ProcessData")
Asa@0: -- 
Asa@0: -- function MyAddon:ProcessData()
Asa@0: --   -- do stuff
Asa@0: -- end
Asa@0: function AceBucket:RegisterBucketMessage(message, interval, callback)
Asa@0: 	return RegisterBucket(self, message, interval, callback, true)
Asa@0: end
Asa@0: 
Asa@0: --- Unregister any events and messages from the bucket and clear any remaining data.
Asa@0: -- @param handle The handle of the bucket as returned by RegisterBucket*
Asa@0: function AceBucket:UnregisterBucket(handle)
Asa@0: 	local bucket = AceBucket.buckets[handle]
Asa@0: 	if bucket then
Asa@0: 		AceEvent.UnregisterAllEvents(bucket)
Asa@0: 		AceEvent.UnregisterAllMessages(bucket)
Asa@0: 		
Asa@0: 		-- clear any remaining data in the bucket
Asa@0: 		for k in pairs(bucket.received) do
Asa@0: 			bucket.received[k] = nil
Asa@0: 		end
Asa@0: 		
Asa@0: 		if bucket.timer then
Asa@0: 			AceTimer.CancelTimer(bucket, bucket.timer)
Asa@0: 			bucket.timer = nil
Asa@0: 		end
Asa@0: 		
Asa@0: 		AceBucket.buckets[handle] = nil
Asa@0: 		-- store our bucket in the cache
Asa@0: 		bucketCache[bucket] = true
Asa@0: 	end
Asa@0: end
Asa@0: 
Asa@0: --- Unregister all buckets of the current addon object (or custom "self").
Asa@0: function AceBucket:UnregisterAllBuckets()
Asa@0: 	-- hmm can we do this more efficient? (it is not done often so shouldn't matter much)
Asa@0: 	for handle, bucket in pairs(AceBucket.buckets) do
Asa@0: 		if bucket.object == self then
Asa@0: 			AceBucket.UnregisterBucket(self, handle)
Asa@0: 		end
Asa@0: 	end
Asa@0: end
Asa@0: 
Asa@0: 
Asa@0: 
Asa@0: -- embedding and embed handling
Asa@0: local mixins = {
Asa@0: 	"RegisterBucketEvent",
Asa@0: 	"RegisterBucketMessage", 
Asa@0: 	"UnregisterBucket",
Asa@0: 	"UnregisterAllBuckets",
Asa@0: } 
Asa@0: 
Asa@0: -- Embeds AceBucket into the target object making the functions from the mixins list available on target:..
Asa@0: -- @param target target object to embed AceBucket in
Asa@0: function AceBucket:Embed( target )
Asa@0: 	for _, v in pairs( mixins ) do
Asa@0: 		target[v] = self[v]
Asa@0: 	end
Asa@0: 	self.embeds[target] = true
Asa@0: 	return target
Asa@0: end
Asa@0: 
Asa@0: function AceBucket:OnEmbedDisable( target )
Asa@0: 	target:UnregisterAllBuckets()
Asa@0: end
Asa@0: 
Asa@0: for addon in pairs(AceBucket.embeds) do
Asa@0: 	AceBucket:Embed(addon)
Asa@0: end