iothrottler

README

iothrottler

A Go package for throttling application IO (such as bandwidth).

Installation

If you have the Go Language installed type go get "github.com/efarrer/iothrottler"

Example

import (
	"bytes"
	"fmt"
	"io"
	"github.com/efarrer/iothrottler"
	"os"
)

// Basic usage of a IOThrottlerPool to throttle reading from a file 
func ExampleIOThrottlerPool() {
	// Construct a bandwidth throttling pool that's limited to 100 bytes per second
	pool := iothrottler.NewIOThrottlerPool(iothrottler.BytesPerSecond * 100)
	defer pool.ReleasePool()

	file, err := os.Open("/dev/zero")
	if err != nil {
		// handle error
		return
	}
	defer file.Close()

	throttledFile, err := pool.AddReader(file)
	if err != nil {
		// handle error
		return
	}

	var zeros bytes.Buffer

	copied, err := io.CopyN(&zeros, throttledFile, 200)
	if err != nil {
		// handle error
	}

	fmt.Printf("Copied %v bytes\n", copied)
	// Output: Copied 200 bytes
}

Documentation

Index

• Constants
• type Bandwidth
• type IOThrottlerPool
  • func NewIOThrottlerPool(bandwidth Bandwidth) *IOThrottlerPool
  • func (p *IOThrottlerPool) AddConn(conn net.Conn) (net.Conn, error)
  • func (p *IOThrottlerPool) AddReadWriter(readWriter io.ReadWriteCloser) (io.ReadWriteCloser, error)
  • func (p *IOThrottlerPool) AddReader(reader io.ReadCloser) (io.ReadCloser, error)
  • func (p *IOThrottlerPool) AddWriter(writer io.WriteCloser) (io.WriteCloser, error)
  • func (pool *IOThrottlerPool) ReleasePool()
  • func (pool *IOThrottlerPool) SetBandwidth(bandwith Bandwidth)

Examples

• IOThrottlerPool
• IOThrottlerPool.AddConn

Constants

const (
	// Bytes per second
	BytesPerSecond Bandwidth = 1
	// Kilobits per second
	Kbps = BytesPerSecond * (1024 / 8)
	// Megabits per second
	Mbps = Kbps * 1024
	// Gigabits per second
	Gbps = Mbps * 1024
	// Unlimited bandwidth
	Unlimited = math.MaxInt64
)

Types

type Bandwidth

type Bandwidth int64

The Bandwidth type represents a bandwidth quantity in bytes per second. Sub-byte per seconds values are not supported

type IOThrottlerPool

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

A pool for throttling IO

Example

Basic usage of a IOThrottlerPool to throttle reading from a file

package main

import (
	"bytes"
	"fmt"
	"io"
	"os"

	"github.com/efarrer/iothrottler"
)

func main() {
	// Construct a bandwidth throttling pool that's limited to 100 bytes per second
	pool := iothrottler.NewIOThrottlerPool(iothrottler.BytesPerSecond * 100)
	defer pool.ReleasePool()

	file, err := os.Open("/dev/zero")
	if err != nil {
		// handle error
		return
	}
	defer file.Close()

	throttledFile, err := pool.AddReader(file)
	if err != nil {
		// handle error
		return
	}

	var zeros bytes.Buffer

	copied, err := io.CopyN(&zeros, throttledFile, 200)
	if err != nil {
		// handle error
	}

	fmt.Printf("Copied %v bytes\n", copied)
}

Output:

Copied 200 bytes

func NewIOThrottlerPool

func NewIOThrottlerPool(bandwidth Bandwidth) *IOThrottlerPool

Construct a new IO throttling pool The bandwidth for this pool will be limited to 'bandwidth'

func (*IOThrottlerPool) AddConn

func (p *IOThrottlerPool) AddConn(conn net.Conn) (net.Conn, error)

Restrict the network connection to the bandwidth limitations of the IOThrottlerPool

Example

Throttle web requests using an IOThrottlerPool

package main

import (
	"fmt"
	"io/ioutil"
	"net"
	"net/http"

	"github.com/efarrer/iothrottler"
)

func main() {
	// Construct a bandwidth throttling pool that's limited to 30 kilobits per
	// second
	pool := iothrottler.NewIOThrottlerPool(iothrottler.Kbps * 30)
	defer pool.ReleasePool()

	// Create our own Dial function that will be used for the http connection
	throttledDial := func(nt, addr string) (c net.Conn, err error) {
		conn, err := net.Dial(nt, addr)
		if err != nil {
			return nil, err
		}

		return pool.AddConn(conn)
	}

	// Create a transport that will use our throttled Dial function
	tr := &http.Transport{
		Proxy: http.ProxyFromEnvironment,
		Dial:  throttledDial,
	}

	// Download the page
	client := &http.Client{Transport: tr}
	resp, err := client.Get("http://www.google.com")
	if err != nil {
		// handle error
		return
	}
	defer resp.Body.Close()

	// Read the entire contents of the body
	_, err = ioutil.ReadAll(resp.Body)
	if err != nil {
		// handle error
		return
	}

	fmt.Println("Downloaded www.google.com")
}

Output:

Downloaded www.google.com

func (*IOThrottlerPool) AddReadWriter

func (p *IOThrottlerPool) AddReadWriter(readWriter io.ReadWriteCloser) (io.ReadWriteCloser, error)

Add a io.ReadWriteCloser to the pool. The returned io.ReadWriteCloser shares the IOThrottlerPool's bandwidth with other items in the pool.

func (*IOThrottlerPool) AddReader

func (p *IOThrottlerPool) AddReader(reader io.ReadCloser) (io.ReadCloser, error)

Add a io.ReadCloser to the pool. The returned io.ReadCloser shares the IOThrottlerPool's bandwidth with other items in the pool.

func (*IOThrottlerPool) AddWriter

func (p *IOThrottlerPool) AddWriter(writer io.WriteCloser) (io.WriteCloser, error)

Add a io.WriteCloser to the pool. The returned io.WriteCloser shares the IOThrottlerPool's bandwidth with other items in the pool.

func (*IOThrottlerPool) ReleasePool

func (pool *IOThrottlerPool) ReleasePool()

Release the IOThrottlerPool all bandwidth

func (*IOThrottlerPool) SetBandwidth

func (pool *IOThrottlerPool) SetBandwidth(bandwith Bandwidth)

Sets the IOThrottlerPool's bandwith rate