ioshape

README

Go Traffic Shaper

The repository provides ioshape package shapes I/O traffic using token-bucket algorithm. It is used for creating bandwidth limiting applications, needing traffic limiting or throttling or prioritization.

Examples

Limit copy operation simply

It limits copy operation to 2 MBps.

    n, err := ioshape.CopyRate(dst, src, 2*1024*1024)

Limit multiple operations with bucket

It limits two copy operation to 3MBps totally. Traffic will be balanced equally.

    bucket := ioshape.NewBucketRate(3*1024*1024)
    var wg sync.WaitGroup
    wg.Add(1)
    go func() {
        ioshape.CopyB(dst1, src1, bucket)
        wg.Done()
    }()
    wg.Add(1)
    go func() {
        ioshape.CopyB(dst2, src2, bucket)
        wg.Done()
    }()
    wg.Wait()
    bucket.Stop() // its necessary to free resources

Limit multiple operations with burst and priority

It limits three copy operation to 5MBps totally. Traffic will be balanced with given priorities.

    bucket := ioshape.NewBucket()
    rate := 5*1024*1024 // the rate is 5MBps
    burst := rate*10 // the burst is ten times of the rate
    bucket.Set(rate, burst)
    var wg sync.WaitGroup
    wg.Add(1)
    go func() {
        rr1 := &ioshape.Reader{R: src1, B: bucket, Pr: 0} // highest priority
        io.Copy(dst1, rr1)
        wg.Done()
    }
    wg.Add(1)
    go func() {
        rr2 := &ioshape.Reader{R: src2, B: bucket, Pr: 15} // lowest priority
        io.Copy(dst2, rr2)
        wg.Done()
    }
    wg.Add(1)
    go func() {
        rr3 := &ioshape.Reader{R: src3, B: bucket, Pr: 2} // higher priority
        io.Copy(dst3, rr3)
        wg.Done()
    }
    wg.Wait()
    bucket.Stop()

Documentation

Overview

Package ioshape provides I/O structures and functions for Traffic Shaping using token-bucket algorithm.

Index

• Variables
• func CopyB(dst io.Writer, src io.Reader, b *Bucket) (written int64, err error)
• func CopyBN(dst io.Writer, src io.Reader, b *Bucket, n int64) (written int64, err error)
• func CopyRate(dst io.Writer, src io.Reader, rate int64) (written int64, err error)
• func CopyRateN(dst io.Writer, src io.Reader, rate int64, n int64) (written int64, err error)
• type Bucket
  • func NewBucket() (bu *Bucket)
  • func NewBucketRate(rate int64) (bu *Bucket)
  • func (bu *Bucket) Set(rate, burst int64)
  • func (bu *Bucket) SetRate(rate int64)
  • func (bu *Bucket) Stop()
• type Reader
  • func (rr *Reader) Read(p []byte) (n int, err error)
• type Writer
  • func (wr *Writer) Write(p []byte) (n int, err error)

Variables

var ErrOutOfRange = errors.New("out of range")

ErrOutOfRange is the error used for the result of r/w is out of range.

Functions

func CopyB

func CopyB(dst io.Writer, src io.Reader, b *Bucket) (written int64, err error)

CopyB is identical to io.Copy except that it shapes traffic by b *Bucket.

func CopyBN

func CopyBN(dst io.Writer, src io.Reader, b *Bucket, n int64) (written int64, err error)

CopyBN is identical to io.CopyN except that it shapes traffic by b *Bucket.

func CopyRate

func CopyRate(dst io.Writer, src io.Reader, rate int64) (written int64, err error)

CopyRate is identical to io.Copy except that it shapes traffic with rate in bytes per second.

func CopyRateN

func CopyRateN(dst io.Writer, src io.Reader, rate int64, n int64) (written int64, err error)

CopyRateN is identical to io.CopyN except that it shapes traffic with rate in bytes per second.

Types

type Bucket

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

Bucket shapes traffic by given rate, burst and Reader/Writer priorities.

func NewBucket

func NewBucket() (bu *Bucket)

NewBucket returns a new Bucket.

func NewBucketRate

func NewBucketRate(rate int64) (bu *Bucket)

NewBucketRate returns a new Bucket and sets rate.

func (*Bucket) Set

func (bu *Bucket) Set(rate, burst int64)

Set sets buckets rate and burst in bytes per second. The burst should be greater or equal than the rate. Otherwise burst will be equal rate.

func (*Bucket) SetRate

func (bu *Bucket) SetRate(rate int64)

SetRate sets rate and burst to the rate in bytes per second.

func (*Bucket) Stop

func (bu *Bucket) Stop()

Stop turns off a bucket. After Stop, bucket won't shape traffic. Stop must be call to free resources, after the bucket doesn't be needing.

type Reader

type Reader struct {
	R  io.Reader // underlying reader
	B  *Bucket   // bucket
	Pr int       // priority
}

Reader is a traffic shaper struct that implements io.Reader interface. A Reader reads from R by B. Priority changes between 0(highest) and 15(lowest).

func (*Reader) Read

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

Read reads from R by b.

type Writer

type Writer struct {
	W  io.Writer // underlying reader
	B  *Bucket   // bucket
	Pr int       // priority
}

Writer is a traffic shaper struct that implements io.Writer interface. A Writer writes to W by B. Priority changes between 0(highest) and 15(lowest).

func (*Writer) Write

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

Write writes to W by b.