ChatThrottleLib

ChatThrottleLib is a small, embeddable library by Mikk that keeps outbound chat and addon communication from exceeding the output rate limit in WoW that otherwise causes players to disconnect from the server. It also has a number of features that will help you make your addon communication run smoother!

Benefits of using ChatThrottleLib:

• You keep players from getting disconnected when your addon sends too much data
• You can easily prioritize your traffic in three priorities
• Communication to different peers is handled as individual flows. A long stream of data to "Alice" doesn't interrupt short bursts of traffic to "Bob".
• All AddOns using ChatThrottleLib use the same queues, so multiple addons can't cause an overload. Priorities ensure that real-time traffic is still real-time.

ChatThrottleLib throughput sample

ChatThrottleLib does:

• Round-robin traffic shaping of different communication paths
• Prioritization of messages according to three predefined priorities: "BULK", "NORMAL" and "ALERT"
• NO queueing of traffic needlessly. No lag is introduced until it needs to be.

== ChatThrottleLib APIs ==

=== ChatThrottleLib:SendChatMessage ===

ChatThrottleLib:SendChatMessage("prio", "prefix",   "text", "chattype", "language", "destination");

prio

String - "BULK", "NORMAL" or "ALERT".

prefix

String - a unique identifier for your addon (or class of traffic)

The following parameters are the same as the SendChatMessage() API:

text

String - the text to be sent

chattype

String - "SAY", "WHISPER", "CHANNEL", etc...

language

String or nil

destination

String or nil - Used for WHISPER, CHANNEL..

=== ChatThrottleLib:SendAddonMessage ===

ChatThrottleLib:SendAddonMessage("prio",    "prefix", "text", "chattype");

prio

String - "BULK", "NORMAL", or "ALERT".

The following parameters are the same as the SendAddonMessage() API:

prefix

String - a unique identifier for your addon (or class of traffic)

text

String - the text to be sent

chattype

String - "PARTY", "RAID", "GUILD", "BATTLEGROUND"

== Notes on outbound rate ==

The World of Warcraft servers will disconnect you if you generate too much output. This is not limited to chat output; any type of output can cause it. Some of you may have noticed that holding down your right mouse button and wiggling it wildly for an extended time can kick you off.

In my own testing, I've found that a data rate of 3000 CPS will cause a disconnect if sustained for more than a few seconds. There seems to be an input buffer of something along the lines of 32KBytes serverside. Filling it would be what causes the kick.

A total output of 2000 CPS seems safe.

ChatThrottleLib will allow bursts of up to 8000 bytes and after that throttle its output to 1000 CPS, to allow room for actual game events.

ChatThrottleLib will also assume that there's a 40-byte overhead associated with sending messages, so if you're sending "hi", it will count as 42 bytes for traffic shaping purposes. It's fairly unscientific, I'm assuming it's fair estimate of source + destination + chattype + some envisioned protocol overhead.

40 bytes seems a bit on the low side for sending data, possibly because the sender is not included, but it seems about right on the receiving end from measuring actual network traffic (excluding ethernet+IP+TCP headers).

== Throttling algorithms ==

There are two types of traffic shaping going on in ChatThrottleLib.

=== Per-stream shaping ===

Each prefix + chattype (+ destination) tuple is treated as a separate stream. Streams output is simply round-robined, i.e. they get the same amount of messages per second. Not necessarily the same CPS though. Doing full-out data rate shaping seemed like unnecessary overhead for very little gain.

=== Prioritization ===

Traffic in the three priorities will be fully data rate shaped so that the net output stays at 1000 CPS. Higher priorities do not force lower priority traffic out of the way utterly. In a fully loaded system (with full output in all priorities), each priority gets 1/3rd of the available bandwidth.

It is fully balanced. Examples of attempted transmit rates and actual output results:

• BULK 500 CPS. NORMAL 500 CPS. ALERT 200 CPS
  • Bulk gets 400
  • Normal gets 400
  • Alert gets 200

• BULK 1500 CPS. NORMAL 200 CPS. ALERT 500 CPS
  • Bulk gets 400
  • Normal gets 200
  • Alert gets 400

• BULK 1200 CPS. NORMAL 0 CPS. ALERT 100 CPS
  • Bulk gets 900
  • Normal gets 0
  • Alert gets 100

• BULK 0 CPS. NORMAL 500 CPS. ALERT 400 CPS
  • Bulk gets 0
  • Normal gets 500
  • Alert gets 400

== How to use ChatThrottleLib ==

• Download ChatThrottleLib from wowinterface.com.

• Copy ChatThrottleLib.lua into your addon directory

• Add "ChatThrottleLib.lua" to your .toc file

You're done, and can now use ChatThrottleLib:SendChatMessage and ChatThrottleLib:SendAddonMessage to send your messages!

The library has built-in checks for if it has already been loaded, and avoids loading again if so.

If your addon has a newer version of the library than one that has already been loaded, it will replace the old version.