README

Go Traffic Shaper

GoDoc

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()
Expand ▾ Collapse ▴

Documentation

Overview

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

    Index

    Constants

    This section is empty.

    Variables

    View Source
    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.