48 lines
1.9 KiB
Text
48 lines
1.9 KiB
Text
[](http://godoc.org/github.com/ChimeraCoder/tokenbucket)
|
|
|
|
tokenbucket
|
|
====================
|
|
|
|
This package provides an implementation of [Token bucket](https://en.wikipedia.org/wiki/Token_bucket) scheduling in Go. It is useful for implementing rate-limiting, traffic shaping, or other sorts of scheduling that depend on bandwidth constraints.
|
|
|
|
|
|
Example
|
|
------------
|
|
|
|
|
|
To create a new bucket, specify a capacity (how many tokens can be stored "in the bank"), and a rate (how often a new token is added).
|
|
|
|
````go
|
|
|
|
// Create a new bucket
|
|
// Allow a new action every 5 seconds, with a maximum of 3 "in the bank"
|
|
bucket := tokenbucket.NewBucket(3, 5 * time.Second)
|
|
````
|
|
|
|
This bucket should be shared between any functions that share the same constraints. (These functions may or may not run in separate goroutines).
|
|
|
|
|
|
Anytime a regulated action is performed, spend a token.
|
|
|
|
````go
|
|
// To perform a regulated action, we must spend a token
|
|
// RegulatedAction will not be performed until the bucket contains enough tokens
|
|
<-bucket.SpendToken(1)
|
|
RegulatedAction()
|
|
````
|
|
|
|
`SpendToken` returns immediately. Reading from the channel that it returns will block until the action has "permission" to continue (ie, until there are enough tokens in the bucket).
|
|
|
|
|
|
(The channel that `SpendToken` returns is of type `error`. For now, the value will always be `nil`, so it can be ignored.)
|
|
|
|
|
|
|
|
####License
|
|
|
|
`tokenbucket` is free software provided under version 3 of the LGPL license.
|
|
|
|
|
|
Software that uses `tokenbucket` may be released under *any* license, as long as the source code for `tokenbucket` (including any modifications) are made available under the LGPLv3 license.
|
|
|
|
You do not need to release the rest of the software under the LGPL, or any free/open-source license, for that matter (though we would encourage you to do so!).
|