org.red5.server.stream

## Interface ITokenBucket

    public interface ITokenBucket

Basically token bucket is used to control the bandwidth used by a stream or a connection or a client. There's a background thread that distributes tokens to the buckets in the system according to the configuration of the bucket. The configuration includes how fast the tokens are distributed. When a stream, for example, needs to send out a packet, the packet's byte count is calculated and each byte corresponds to a token in the bucket. The stream is assigned a bucket and the tokens in the bucket are acquired before the packet can be sent out. So if the speed(or bandwidth) in configuration is low, the stream can't send out packets fast.

Author:
  The Red5 Project (red5@osflash.org), Steven Gong (steven.gong@gmail.com)

### Nested Class Summary

Nested Classes
`static interface` `ITokenBucket.ITokenBucketCallback` Callback for tocket bucket

### Method Summary

Methods
`boolean` `acquireToken(long tokenCount, long wait)` Acquire tokens amount of `tokenCount` waiting `wait` milliseconds if token not available.
`long` `acquireTokenBestEffort(long upperLimitCount)` Nonblockingly acquire token.
`boolean` `acquireTokenNonblocking(long tokenCount, ITokenBucket.ITokenBucketCallback callback)` Nonblockingly acquire token.
`long` `getCapacity()` Get the capacity of this bucket in Byte.
`double` `getSpeed()` The amount of tokens increased per millisecond.
`void` `reset()` Reset this token bucket.

### Method Detail

#### acquireToken

    boolean acquireToken(long tokenCount,
                       long wait)

Acquire tokens amount of `tokenCount` waiting `wait` milliseconds if token not available.

Parameters:
  `tokenCount` - The count of tokens to acquire.
  `wait` - Milliseconds to wait. `0` means no wait and any value below zero means wait forever.
Returns:
  `true` if successfully acquired or `false` if not acquired.

#### acquireTokenNonblocking

    boolean acquireTokenNonblocking(long tokenCount,
                                  ITokenBucket.ITokenBucketCallback callback)

Nonblockingly acquire token. If the token is not available and `task` is not null, the callback will be executed when the token is available. The tokens are not consumed automatically before callback, so it's recommended to acquire token again in callback function.

Parameters:
  `tokenCount` - Number of tokens
  `callback` - Callback
Returns:
  `true` if successfully acquired or `false` if not acquired.

#### acquireTokenBestEffort

    long acquireTokenBestEffort(long upperLimitCount)

Nonblockingly acquire token. The upper limit is specified. If not enough tokens are left in bucket, all remaining will be returned.

Parameters:
  `upperLimitCount` - Upper limit of aquisition
Returns:
  Remaining tokens from bucket

#### getCapacity

    long getCapacity()

Get the capacity of this bucket in Byte.

Returns:
  Capacity of this bucket in bytes

#### getSpeed

    double getSpeed()

The amount of tokens increased per millisecond.

Returns:
  Amount of tokens increased per millisecond.

#### reset

    void reset()

Reset this token bucket. All pending threads are woken up with `false` returned for acquiring token and callback is removed without calling back.