AceBucket-3.0

embeddable This library can be embedded into your addon as a mixin; list it when you create the addon and its methods become available directly on your addon object (via self).
Creating an addon object →

A bucket to catch events in. AceBucket-3.0 provides throttling of events that fire in bursts and your addon only needs to know about the full burst.

This Bucket implementation works as follows: Initially, no schedule is running, and its waiting for the first event to happen. The first event will start the bucket, and get the scheduler running, which will collect all events in the given interval. When that interval is reached, the bucket is pushed to the callback and a new schedule is started. When a bucket is empty after its interval, the scheduler is stopped, and the bucket is only listening for the next event to happen, basically back in its initial state.

In addition, the buckets collect information about the arg1 argument of the events that fire, and pass those as a table to your callback. This functionality was mostly designed for the UNIT_* events. The table will have the different values of arg1 as keys, and the number of occurrences as their value, e.g.

{ ["player"] = 2, ["target"] = 1, ["party1"] = 1 }

AceBucket-3.0 requires AceEvent-3.0 and AceTimer-3.0 to be available.

Example

MyAddon = LibStub("AceAddon-3.0"):NewAddon("BucketExample", "AceBucket-3.0")

function MyAddon:OnEnable()
    -- Register a bucket that listens to all the HP related events,
    -- and fires once per second
    self:RegisterBucketEvent({"UNIT_HEALTH", "UNIT_MAXHEALTH"}, 1, "UpdateHealth")
end

function MyAddon:UpdateHealth(units)
    if units.player then
        print("Your HP changed!")
    end
end

API Reference

Embed

method#

AceBucket:Embed(target)

Copies AceBucket's methods onto target so you can call them on it directly. See The :Embed method.

Parameters

Parameter	Type	Default	Description
target	table		Target object to embed AceBucket in.

Returns

Type	Description
table	The target object that was embedded.

RegisterBucketEvent

method#

AceBucket:RegisterBucketEvent(event, interval, callback?)

Register a Bucket for an event (or a set of events).

The first matching event starts the bucket and schedules a timer for interval seconds (via AceTimer-3.0). All events that fire during the interval are collected, and when the interval elapses the callback is fired once with a table mapping each distinct arg1 value to its number of occurrences (a nil arg1 is stored under the key "nil"). If the bucket collected events, a new interval is scheduled; if it was empty, the timer is stopped and the bucket waits for the next event. Requires AceEvent-3.0 and AceTimer-3.0 to be loaded.

Parameters

Parameter	Type	Default	Description
event	string | table		The event to listen for, or a table of events.
interval	number		The Bucket interval (burst interval), in seconds.
callback (optional)	function | methodname		The callback function, either as a function reference, or a string pointing to a method of the addon object. May be omitted only when event is a single string, in which case the event name is used as the method name.

Returns

Type	Description
string	The handle of the bucket (for unregistering).

Example

MyAddon:RegisterBucketEvent("BAG_UPDATE", 0.2, "UpdateBags")

function MyAddon:UpdateBags()
    -- do stuff
end

RegisterBucketMessage

method#

AceBucket:RegisterBucketMessage(message, interval, callback?)

Register a Bucket for an AceEvent-3.0 addon message (or a set of messages).

Behaves identically to RegisterBucketEvent, except it listens for AceEvent-3.0 inter-addon messages instead of game events. Bursts of messages within interval seconds are coalesced and delivered to callback as a single table keyed by the distinct arg1 values with their occurrence counts.

Parameters

Parameter	Type	Default	Description
message	string | table		The message to listen for, or a table of messages.
interval	number		The Bucket interval (burst interval), in seconds.
callback (optional)	function | methodname		The callback function, either as a function reference, or a string pointing to a method of the addon object. May be omitted only when message is a single string, in which case the message name is used as the method name.

Returns

Type	Description
string	The handle of the bucket (for unregistering).

Example

MyAddon:RegisterBucketMessage("SomeAddon_InformationMessage", 0.2, "ProcessData")

function MyAddon:ProcessData()
    -- do stuff
end

UnregisterBucket

method#

AceBucket:UnregisterBucket(handle)

Unregister any events and messages from the bucket and clear any remaining data.

Unregisters all events/messages the bucket was listening to, clears any data collected but not yet delivered, cancels the pending interval timer (if one is running), and recycles the internal bucket object for reuse.

Parameters

Parameter	Type	Default	Description
handle	string		The handle of the bucket as returned by RegisterBucketEvent or RegisterBucketMessage.

Example

function MyAddon:OnEnable()
    self.bucket = self:RegisterBucketEvent("BAG_UPDATE", 0.2, "UpdateBags")
end

function MyAddon:StopWatching()
    self:UnregisterBucket(self.bucket)
end

UnregisterAllBuckets

method#

AceBucket:UnregisterAllBuckets()

Unregister all buckets of the current addon object (or custom self). Iterates the registered buckets and calls UnregisterBucket on each one whose owner is this object; buckets belonging to other objects are left untouched. This is called automatically when an embedding addon is disabled.