speedio

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 4, 2020 License: MIT Imports: 6 Imported by: 0

README

go-speedio

GitHub GoDoc

speedio is a Go package implementing bit rate limiting and bit rate measurement. It wraps an io.Reader or io.Writer object.

Usage

import (
	"fmt"
	"io/ioutil"
	"time"

	"github.com/tunabay/go-speedio"
)

func main() {

	// /dev/null writer with rate limit of 256 bit/s
	w, err := speedio.NewWriter(ioutil.Discard, 256)
	if err != nil {
		panic(err)
	}

	// print bit rate every 0.5 seconds
	go func() {
		for range time.Tick(time.Second / 2) {
			fmt.Println("bitrate:", w.BitRate())
		}
	}()

	// start measurement
	w.Start()
	time.Sleep(time.Second) // measurement resolution

	// write 160 bytes data, it will take about 5 seconds
	buf := make([]byte, 160)
	n, err := w.Write(buf)
	if err != nil {
		panic(err)
	}
	fmt.Println("written:", n)

	// close wrapper only (don't want to close /dev/null)
	if err := w.CloseSingle(); err != nil {
		panic(err)
	}

	// print total
	bc, et, br := w.Total()
	fmt.Println("total byte count:", bc)
	fmt.Println("elapsed time:", et)
	fmt.Println("total bit rate:", br)
}

Run in Go Playground

Documentation

License

go-speedio is available under the MIT license. See the LICENSE file for more information.

Documentation

Overview

Package speedio implements bit rate limiting and bit rate measurement. It wraps an io.Reader or io.Writer.

Index

Examples

Constants

View Source 
const MinMeterResolution time.Duration = time.Millisecond * 100

MinResolution is the minimum time resolution to measure bit rate.

Variables

View Source 
var DefaultLimiterConfig = &LimiterConfig{
	Resolution: time.Second,
	MaxWait:    time.Millisecond * 500,
}

DefaultLimiterConfig is the default configuration for bit rate limiting with 1s resolution and 500ms max-wait time. It means that the amount of data transferred in every 1s is limited, and the allowed amount of partial data is transferred every 500ms.

View Source 
var DefaultMeterConfig = &MeterConfig{
	Resolution: time.Millisecond * 500,
	Sample:     time.Second * 3,
}

DefaultMeterConfig is the default configuration for measurement with 500ms resolution and 3s sample duration. It means that the average bitrate for the last 3s is updated every 500ms.

Functions

This section is empty.

Types

type LimiterConfig 

type LimiterConfig struct {
	Resolution time.Duration
	MaxWait    time.Duration
}

LimiterConfig indicates the configuration parameter of bit rate limiting.

Resolution is the period for totaling the transfer amount to determine whether the bit rate is exceeded or not. For example, if the bit rate is 1 kbit/s and Resolution is 3s, if there is no transfer in the previous 2 seconds, transfer of 3 kbit is allowed in the next 1 second. However, when Resolution is 1s, the transfer allowed per second is always 1 kbit.

MaxWait is the maximum waiting time when the transfer exceeds the bit rate. After this MaxWait time elapses, only the portion that is allowed at that time is transferred.

type LimiterReader 

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

LimiterReader implements bit rate limiting for an io.Reader object.

func NewLimiterReader 

func NewLimiterReader(rd io.Reader, rate infounit.BitRate) (*LimiterReader, error)

NewLimiterReader creates a new LimiterReader with default configuration. The default configuration has a resolution of 1s and a max-wait duration of 500ms, which means that average bit rate for the last 1s is limited, and a partial reading is performed at least every 500ms.

func NewLimiterReaderWithConfig 

func NewLimiterReaderWithConfig(rd io.Reader, rate infounit.BitRate, conf *LimiterConfig) (*LimiterReader, error)

NewLimiterReaderWithConfig creates a new LimiterReader with the specified configuration. If conf is nil, the default configuration will be used.

func (*LimiterReader) Close 

func (r *LimiterReader) Close() error

Close closes the reader. If the underlying reader implements io.ReadCloser, its Close method is also called.

func (*LimiterReader) CloseSingle 

func (r *LimiterReader) CloseSingle() error

CloseSingle is the same as Close except that it does not close the underlying reader.

func (*LimiterReader) LimitingBitRate 

func (r *LimiterReader) LimitingBitRate() infounit.BitRate

LimitingBitRate returns the current limiting bit rate.

func (*LimiterReader) Read 

func (r *LimiterReader) Read(p []byte) (int, error)

Read reads data from the underlying reader into p. This may return shorter length than len(p). It may block for up to maxWait time.

func (*LimiterReader) SetBitRate 

func (r *LimiterReader) SetBitRate(rate infounit.BitRate) error

SetBitRate sets a new limiting bit rate.

type LimiterWriter 

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

LimiterWriter implements bit rate limiting for an io.Writer object.

func NewLimiterWriter 

func NewLimiterWriter(wr io.Writer, rate infounit.BitRate) (*LimiterWriter, error)

NewLimiterWriter creates a new LimiterWriter with default configuration. The default configuration has a resolution of 1s and a max-wait duration of 500ms, which means that average bit rate for the last 1s is limited, and a partial writing is performed at least every 500ms.

func NewLimiterWriterWithConfig 

func NewLimiterWriterWithConfig(wr io.Writer, rate infounit.BitRate, conf *LimiterConfig) (*LimiterWriter, error)

NewLimiterWriterWithConfig creates a new LimiterWriter with the specified configuration. If conf is nil, the default configuration will be used.

func (*LimiterWriter) Close 

func (w *LimiterWriter) Close() error

Close closes the writer. If the underlying writer implements io.WriteCloser, its Close method is also called.

func (*LimiterWriter) CloseSingle 

func (w *LimiterWriter) CloseSingle() error

CloseSingle is the same as Close except that it does not close the underlying writer.

func (*LimiterWriter) LimitingBitRate 

func (w *LimiterWriter) LimitingBitRate() infounit.BitRate

LimitingBitRate returns the current limiting bit rate.

func (*LimiterWriter) SetBitRate 

func (w *LimiterWriter) SetBitRate(rate infounit.BitRate) error

SetBitRate sets a new limiting bit rate.

func (*LimiterWriter) Write 

func (w *LimiterWriter) Write(p []byte) (int, error)

Write writes len(p) bytes from p to the underlying writer. It blocks until all the data in p is written, but it does not just wait until all the data is written. It repeatedly writes part of the divided p to the underlying writer.

type MeterConfig 

type MeterConfig struct {
	Resolution time.Duration
	Sample     time.Duration // must be an integral multiple of Resolution
}

MeterConfig indicates the configuration parameter of bit rate measurement.

Resolution is how often the bitrate is updated. Shorter resolutions increase measurement overhead and memory usage. Longer resolutions increase measurement delay. For example, with a 10s resolution, the bit rate is 0 for the first 10 seconds.

Sample is the length of the most recent period for which the simple moving average bit rate is calculated. It must be an integral multiple of Resolution for accurate measurements. Also, it must be at least twice the Resolution. Longer sample periods increase memory usage for measurements.

type MeterReader 

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

MeterReader implements bit rate measurement for an io.Reader object.

func NewMeterReader 

func NewMeterReader(rd io.Reader) *MeterReader

NewMeterReader creates a new MeterReader with default configuration. The default configuration has a resolution of 500ms and a sample duration of 3s, which means that average bit rate for the last 3s is updated every 500ms.

func NewMeterReaderWithConfig 

func NewMeterReaderWithConfig(rd io.Reader, conf *MeterConfig) (*MeterReader, error)

NewMeterReaderWithConfig creates a new MeterReader with the specified configuration. If conf is nil, the default configuration will be used.

func (*MeterReader) BitRate 

func (r *MeterReader) BitRate() infounit.BitRate

BitRate calculates and returns the bit rate in the most recent sampling period.

func (*MeterReader) Close 

func (r *MeterReader) Close() error

Close closes the reader, which means that it ends the bit rate calculation period. If the underlying reader implements io.ReadCloser, its Close method is also called.

func (*MeterReader) CloseAt 

func (r *MeterReader) CloseAt(tc time.Time) error

CloseAt is the same as Close, except that it uses time specified as the end time.

func (*MeterReader) CloseSingle 

func (r *MeterReader) CloseSingle() error

CloseSingle is the same as Close except that it does not close the underlying reader.

func (*MeterReader) CloseSingleAt 

func (r *MeterReader) CloseSingleAt(tc time.Time) error

CloseSingleAt is the same as CloseAt except that it does not close the underlying reader.

func (*MeterReader) Read 

func (r *MeterReader) Read(p []byte) (int, error)

Read reads data from the underlying reader into p. io.EOF does not automatically stop the measurement. It is caller's responsibility to call Close after receiving io.EOF to record the measurement end time.

func (*MeterReader) Start 

func (r *MeterReader) Start()

Start starts the measurement. Calling this Start is optional, and normally it is started automatically at the first read. This is used to adjust the transfer start time for bit rate calculation.

func (*MeterReader) StartAt 

func (r *MeterReader) StartAt(tc time.Time)

StartAt starts the measurement at specified time. This is used to adjust the transfer start time for bit rate calculation.

func (*MeterReader) Total 

func (r *MeterReader) Total() (infounit.ByteCount, time.Duration, infounit.BitRate)

Total returns the data transfer amount, elapsed time, and bit rate in the entire period from start. When it is called after being closed, it always returns the same statistics from start to close.

type MeterWriter 

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

MeterWriter implements bit rate measurement for an io.Writer object.

func NewMeterWriter 

func NewMeterWriter(wr io.Writer) *MeterWriter

NewMeterWriter creates a new MeterWriter with default configuration. The default configuration has a resolution of 500ms and a sample duration of 3s, which means that average bit rate for the last 3s is updated every 500ms.

func NewMeterWriterWithConfig 

func NewMeterWriterWithConfig(wr io.Writer, conf *MeterConfig) (*MeterWriter, error)

NewMeterWriterWithConfig creates a new MeterWriter with the specified configuration. If conf is nil, the default configuration will be used.

func (*MeterWriter) BitRate 

func (w *MeterWriter) BitRate() infounit.BitRate

BitRate calculates and returns the bit rate in the most recent sampling period.

func (*MeterWriter) Close 

func (w *MeterWriter) Close() error

Close closes the writer, which means that it ends the bit rate calculation period. If the underlying writer implements io.WriteCloser, its Close method is also called.

func (*MeterWriter) CloseAt 

func (w *MeterWriter) CloseAt(tc time.Time) error

CloseAt is the same as Close, except that it uses time specified as the end time.

func (*MeterWriter) CloseSingle 

func (w *MeterWriter) CloseSingle() error

CloseSingle is the same as Close except that it does not close the underlying writer.

func (*MeterWriter) CloseSingleAt 

func (w *MeterWriter) CloseSingleAt(tc time.Time) error

CloseSingleAt is the same as CloseAt except that it does not close the underlying writer.

func (*MeterWriter) Start 

func (w *MeterWriter) Start()

Start starts the measurement. Calling this Start is optional, and normally it is started automatically at the first write. This is used to adjust the transfer start time for bit rate calculation.

func (*MeterWriter) StartAt 

func (w *MeterWriter) StartAt(tc time.Time)

StartAt starts the measurement at specified time. This is used to adjust the transfer start time for bit rate calculation.

func (*MeterWriter) Total 

func (w *MeterWriter) Total() (infounit.ByteCount, time.Duration, infounit.BitRate)

Total returns the data transfer amount, elapsed time, and bit rate in the entire period from start. When it is called after being closed, it always returns the same statistics from start to close.

func (*MeterWriter) Write 

func (w *MeterWriter) Write(p []byte) (int, error)

Write writes len(p) bytes from p to the underlying writer. It is caller's responsibility to call Close after writing all data to record the measurement end time.

type Reader 

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

Reader implements both bit rate limiting and bit rate measurement for an io.Reader object. If only one of limiting or measurement is needed, it is recommended to use LimiterReader or MeterReader instead. In fact, Reader is just a concatenation of LimiterReader and MeterReader.

func NewReader 

func NewReader(rd io.Reader, rate infounit.BitRate) (*Reader, error)

NewReader creates a new Reader with default configurations.

func NewReaderWithConfig 

func NewReaderWithConfig(rd io.Reader, rate infounit.BitRate, lconf *LimiterConfig, mconf *MeterConfig) (*Reader, error)

NewReaderWithConfig creates a new Reader with the specified configurations. If conf is nil, the default configuration will be used.

func (*Reader) BitRate 

func (w *Reader) BitRate() infounit.BitRate

BitRate calculates and returns the bit rate in the most recent sampling period.

func (*Reader) Close 

func (w *Reader) Close() error

Close closes the reader. If the underlying reader implements io.ReadCloser, its Close method is also called.

func (*Reader) CloseAt 

func (w *Reader) CloseAt(tc time.Time) error

CloseAt is the same as Close, except that it uses time specified as the end time.

func (*Reader) CloseSingle 

func (w *Reader) CloseSingle() error

CloseSingle is the same as Close except that it does not close the underlying reader.

func (*Reader) CloseSingleAt 

func (w *Reader) CloseSingleAt(tc time.Time) error

CloseSingleAt is the same as CloseAt except that it does not close the underlying reader.

func (*Reader) LimitingBitRate 

func (w *Reader) LimitingBitRate() infounit.BitRate

LimitingBitRate returns the current effective limiting bit rate.

func (*Reader) Read 

func (w *Reader) Read(p []byte) (int, error)

Read reads data from the underlying reader into p. This may return shorter length than len(p). It may block for up to maxWait time. io.EOF does not automatically stop the measurement. It is caller's responsibility to call Close after receiving io.EOF to record the measurement end time.

func (*Reader) SetBitRate 

func (w *Reader) SetBitRate(rate infounit.BitRate) error

SetBitRate sets a new bit rate limiting.

func (*Reader) Start 

func (w *Reader) Start()

Start starts the measurement. Calling this Start is optional, and normally it is started automatically at the first read. This is used to adjust the transfer start time for bit rate calculation.

func (*Reader) StartAt 

func (w *Reader) StartAt(tc time.Time)

StartAt starts the measurement at specified time. This is used to adjust the transfer start time for bit rate calculation.

func (*Reader) Total 

func (w *Reader) Total() (infounit.ByteCount, time.Duration, infounit.BitRate)

Total returns the data transfer amount, elapsed time, and bit rate in the entire period from start. When it is called after being closed, it always returns the same statistics from start to close.

type Writer 

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

Writer implements both bit rate limiting and bit rate measurement for an io.Writer object. If only one of limiting or measurement is needed, it is recommended to use LimiterWriter or MeterWriter instead. In fact, Writer is just a concatenation of LimiterWriter and MeterWriter.

Example (DevNull) 
package main

import (
	"fmt"
	"io/ioutil"
	"time"

	"github.com/tunabay/go-speedio"
)

func main() {

	// /dev/null writer with rate limit of 256 bit/s
	w, err := speedio.NewWriter(ioutil.Discard, 256)
	if err != nil {
		panic(err)
	}

	// print bit rate every 0.5 seconds
	go func() {
		for range time.Tick(time.Second / 2) {
			fmt.Println("bitrate:", w.BitRate())
		}
	}()

	// start measurement
	w.Start()
	time.Sleep(time.Second) // measurement resolution

	// write 160 bytes data, it will take about 5 seconds
	buf := make([]byte, 160)
	n, err := w.Write(buf)
	if err != nil {
		panic(err)
	}
	fmt.Println("written:", n)

	// close wrapper only (don't want to close /dev/null)
	if err := w.CloseSingle(); err != nil {
		panic(err)
	}

	// print total
	bc, et, br := w.Total()
	fmt.Println("total byte count:", bc)
	fmt.Println("elapsed time:", et)
	fmt.Println("total bit rate:", br)
}

func NewWriter 

func NewWriter(wr io.Writer, rate infounit.BitRate) (*Writer, error)

NewWriter creates a new Writer with default configurations.

func NewWriterWithConfig 

func NewWriterWithConfig(wr io.Writer, rate infounit.BitRate, lconf *LimiterConfig, mconf *MeterConfig) (*Writer, error)

NewWriterWithConfig creates a new Writer with the specified configurations. If conf is nil, the default configuration will be used.

func (*Writer) BitRate 

func (w *Writer) BitRate() infounit.BitRate

BitRate calculates and returns the bit rate in the most recent sampling period.

func (*Writer) Close 

func (w *Writer) Close() error

Close closes the writer. If the underlying writer implements io.WriteCloser, its Close method is also called.

func (*Writer) CloseAt 

func (w *Writer) CloseAt(tc time.Time) error

CloseAt is the same as Close, except that it uses time specified as the end time.

func (*Writer) CloseSingle 

func (w *Writer) CloseSingle() error

CloseSingle is the same as Close except that it does not close the underlying writer.

func (*Writer) CloseSingleAt 

func (w *Writer) CloseSingleAt(tc time.Time) error

CloseSingleAt is the same as CloseAt except that it does not close the underlying writer.

func (*Writer) LimitingBitRate 

func (w *Writer) LimitingBitRate() infounit.BitRate

LimitingBitRate returns the current effective limiting bit rate.

func (*Writer) SetBitRate 

func (w *Writer) SetBitRate(rate infounit.BitRate) error

SetBitRate sets a new bit rate limiting.

func (*Writer) Start 

func (w *Writer) Start()

Start starts the measurement. Calling this Start is optional, and normally it is started automatically at the first write. This is used to adjust the transfer start time for bit rate calculation.

func (*Writer) StartAt 

func (w *Writer) StartAt(tc time.Time)

StartAt starts the measurement at specified time. This is used to adjust the transfer start time for bit rate calculation.

func (*Writer) Total 

func (w *Writer) Total() (infounit.ByteCount, time.Duration, infounit.BitRate)

Total returns the data transfer amount, elapsed time, and bit rate in the entire period from start. When it is called after being closed, it always returns the same statistics from start to close.

func (*Writer) Write 

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

Write writes len(p) bytes from p to the underlying writer. It blocks until all the data in p is written, but it does not just wait until all the data is written. It repeatedly writes part of the divided p to the underlying writer.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.