net.kano.joscar.snaccmd.conn
Class RateClassInfo

java.lang.Object
  net.kano.joscar.snaccmd.conn.RateClassInfo

public class RateClassInfo
extends java.lang.Object

A data structure containing rate limiting information for a specific "class" of SNAC commands.

Introduction to Rates

A rate class identifies a set of SNAC commands and limitations on how fast any sequence of those commands can be sent to the server. For example, one rate class normally contains the outgoing ICBM command and the info request command. You may have noticed that sometimes WinAIM will tell you you can't look at someone's info because your rate is too high; this is why. Gaim, of course, simply tells you to stop talking so fast. Good one, Gaim.

The RateClassInfo Fields

windowSize

The number of previously sent commands that will be included in the calculation of your current "rate average" (this value varies from rate class to rate class; normally ranges from 10 to 60)

currentAvg

Your current "rate average," which attempts to resemble a moving average of the times between each of your last windowSize commands

warnAvg

The "rate average" that will put you into the yellow part of WinAIM's rate limiting bar (normally 5000 ms)

limitedAvg

The "rate average" under which you will be "rate limited" until your rate average is back above clearAvg (normally 4000 ms)

clearAvg

The "rate average" above which you will stop being rate limited, if you are currently limited; this is normally equal to warnAvg plus 100 ms, or 5100 ms

disconnectAvg

The "rate average" below which you will be disconnected from the server (normally 3000 ms)

max

The maximum value for a rate average (normally 6000 ms)

Handling Rate-Related SNAC Commands

The values described above can be used to keep an accurate rate average for a rate class as follows:

Upon initial connection, the average should be ignored: all commands can be sent as quickly as possible until a RateAck is sent.

Upon receiving a RateInfoCmd, the current rate for each rate class within should be set to that rate class's maximum rate average. Note that a current average is sent, but should be ignored in the initial RateInfoCmd.

Upon receiving a RateChange, nothing must be modified (unless the maximum rate average has been decreased and the current rate is now above it). You may want to set your current average to the given "current average," but this is not advised, as the rate change command may have been sent in response to a command sent several commands ago (due to network lag). A good way to do this might be to only set your rate average to the given "current average" only if the given current average is lower than your client's computed average. This should be the most conservative and thus reliable way to handle rate changes.

Computing the Current Rate

Now the important part: how to compute the current average for a rate class.

The current average for a rate class is computed cumulatively. Essentially, the algorithm goes like this:

void computeNewAvg(long lastSent, long oldAvg,
            RateClassInfo rateClassInfo) {
    long curTime = System.currentTimeMillis();
    long diff = curTime - lastSent;

    long winSize = rateClassInfo.getWindowSize();
    long maxAvg = rateClassInfo.getMax();

    currentAvg = ((currentAvg * (winSize - 1))
            + diff) / winSize;

    if (currentAvg > maxAvg) currentAvg = maxAvg;
}
 

Using such an algorithm produces results almost exactly consistent with the "current averages" sent in RateChange packets, often within a margin of one or two milliseconds (out of an average of 5000 ms or lower). (This margin of error is surely due to network traffic and not an error in the algorithm's above implementation.)

Being "Rate Limited"

If commands are sent so fast as to bring the current rate average below the limited average, the server will send a RateChange with a change code of RateChange#CODE_LIMITED. After this happens, all of the commands sent in the associated rate class will be ignored by the server until the rate reaches the "clear average", at which point a RateChange with a change code of RateChange#CODE_LIMIT_CLEARED may be sent (though it is not usually sent). Once the average is above the clear average, however, all is back to normal, as if limiting had never taken place.

Constructor Summary

RateClassInfo(int rateClass, long windowSize, long clearAvg, long warnAvg, long limitedAvg, long disconnectAvg, long currentAvg, long max)
Creates a new rate class information block with the given properties.

RateClassInfo(int rateClass, long windowSize, long clearAvg, long warnAvg, long limitedAvg, long disconnectAvg, long currentAvg, long max, java.util.Collection<? extends CmdType> cmds)
Creates a new rate class information block with the given properties.

RateClassInfo(int rateClass, long windowSize, long clearAvg, long warnAvg, long limitedAvg, long disconnectAvg, long currentAvg, long max, long timeSinceLastCommand, int currentState)

RateClassInfo(int rateClass, long windowSize, long clearAvg, long warnAvg, long limitedAvg, long disconnectAvg, long currentAvg, long max, long lastTime, int currentState, java.util.Collection<? extends CmdType> cmds)