iocap: github.com/ryanuber/iocap Index | Examples | Files | Directories

package iocap

import "github.com/ryanuber/iocap"

Package iocap provides rate limiting for data streams using the familiar io.Reader and io.Writer interfaces.

Rates can be expressed in a few different units using helper functions:

rate := iocap.Kbps(512) // Kilobits/s
rate := iocap.Mbps(10)  // Megabits/s
rate := iocap.Gbps(1)   // Gigabits/s

Rates can also be described manually with any size or interval:

rate := iocap.RateOpts{
	Interval: time.Second,
	Size:     5 * 1024 * 1024, // 5MB/s
}

Readers and Writers are created by passing in an existing io.Reader or io.Writer along with a rate.

r = iocap.NewReader(r, rate)
w = iocap.NewWriter(w, rate)

Rate limits can be applied to multiple readers and/or writers by creating a rate limiting group for them.

// Create the shared group
g := iocap.NewGroup(rate)

// Pull a new reader and writer off of the group. Rate limits are now
// applied and enforced across both.
r = g.NewReader(r)
w = g.NewWriter(w)

Index

Examples

Package Files

bucket.go doc.go iocap.go

Constants

const (
    Kb  // Kilobit
    Mb  // Megabit
    Gb  // Gigabit
)

Variables

var (
    // The zero-value of RateOpts is used to indicate that no rate limit
    // should be applied to read/write operations.
    Unlimited = RateOpts{0, 0}
)

type Group Uses

type Group struct {
    // contains filtered or unexported fields
}

Group is used to group multiple readers and/or writers onto the same bucket, thus enforcing the rate limit across multiple independent processes.

Code:

// Create a rate limiting group.
rate := Kbps(512)
g := NewGroup(rate)

// Create a new reader and writer on the group.
buf := new(bytes.Buffer)
r := g.NewReader(buf)
w := g.NewWriter(buf)

// Reader and writer are rate limited together
n, err := w.Write([]byte("hello world!"))
if err != nil {
    fmt.Println(err)
    return
}
out := make([]byte, n)
_, err = r.Read(out)
if err != nil {
    fmt.Println(err)
    return
}

fmt.Println(string(out))

Output:

hello world!

func NewGroup Uses

func NewGroup(opts RateOpts) *Group

NewGroup creates a new rate limiting group with the specific rate.

func (*Group) NewReader Uses

func (g *Group) NewReader(src io.Reader) *Reader

NewReader creates and returns a new reader in the group.

func (*Group) NewWriter Uses

func (g *Group) NewWriter(dst io.Writer) *Writer

NewWriter creates and returns a new writer in the group.

func (*Group) SetRate Uses

func (g *Group) SetRate(opts RateOpts)

SetRate is used to dynamically update the rate options of the group.

type RateOpts Uses

type RateOpts struct {
    // Interval is the time period of the rate
    Interval time.Duration

    // Size is the number of bytes per interval
    Size int
}

RateOpts is used to encapsulate rate limiting options.

func Gbps Uses

func Gbps(n float64) RateOpts

Gbps returns a RateOpts configured for n gigabits per second.

func Kbps Uses

func Kbps(n float64) RateOpts

Kbps returns a RateOpts configured for n kilobits per second.

func Mbps Uses

func Mbps(n float64) RateOpts

Mbps returns a RateOpts configured for n megabits per second.

type Reader Uses

type Reader struct {
    // contains filtered or unexported fields
}

Reader implements the io.Reader interface and limits the rate at which bytes come off of the underlying source reader.

Code:

// Create a buffer to read from.
buf := bytes.NewBufferString("hello world!")

// Create the rate limited reader.
rate := Kbps(512)
r := NewReader(buf, rate)

// Read from the reader.
out := make([]byte, buf.Len())
n, err := r.Read(out)
if err != nil {
    fmt.Println(err)
    return
}

fmt.Println(n, string(out))

Output:

12 hello world!

func NewReader Uses

func NewReader(src io.Reader, opts RateOpts) *Reader

NewReader wraps src in a new rate limited reader.

func (*Reader) Read Uses

func (r *Reader) Read(p []byte) (n int, err error)

Read reads bytes off of the underlying source reader onto p with rate limiting. Reads until EOF or until p is filled.

func (*Reader) SetRate Uses

func (r *Reader) SetRate(opts RateOpts)

SetRate is used to dynamically set the rate options on the reader.

type Writer Uses

type Writer struct {
    // contains filtered or unexported fields
}

Writer implements the io.Writer interface and limits the rate at which bytes are written to the underlying writer.

Code:

// Create the buffer to write to.
buf := new(bytes.Buffer)

// Create the rate limited writer.
rate := Kbps(512)
r := NewWriter(buf, rate)

// Write data into the writer.
n, err := r.Write([]byte("hello world!"))
if err != nil {
    fmt.Println(err)
    return
}

fmt.Println(n, buf.String())

Output:

12 hello world!

func NewWriter Uses

func NewWriter(dst io.Writer, opts RateOpts) *Writer

NewWriter wraps dst in a new rate limited writer.

func (*Writer) SetRate Uses

func (w *Writer) SetRate(opts RateOpts)

SetRate is used to dynamically set the rate options on the writer.

func (*Writer) Write Uses

func (w *Writer) Write(p []byte) (n int, err error)

Write writes len(p) bytes onto the underlying io.Writer, respecting the configured rate limit options.

Directories

PathSynopsis
httpcapPackage httpcap provides rate limiting for HTTP handlers and response writers.
httpcap/mapperPackage mapper provides HTTP request mapping based on arbitrary criteria, including the raw HTTP request details.

Package iocap imports 3 packages (graph) and is imported by 1 packages. Updated 2018-06-25. Refresh now. Tools for package owners.