README
¶
iocontrol
-- import "github.com/aybabtme/iocontrol"
Package iocontrol offers io.Writer, io.Reader, io.WriterAt, and io.ReaderAt implementations that allow
one to measure and throttle the rate at which data is transferred.
Usage
const (
KiB = 1 << 10
MiB = 1 << 20
GiB = 1 << 30
)
Orders of magnitude of data, in kibibyte (powers of 2, or multiples of 1024). See https://en.wikipedia.org/wiki/Kibibyte.
Exposed Methods and Types
For all of the exposed functionality, there are versions for all of io.{Reader,Writer}At with intuitive naming conventions.
The io.{Reader,Writer} implementations are documented below.
func ThrottledReader
func ThrottledReader(r io.Reader, bytesPerSec int, maxBurst time.Duration) io.Reader
ThrottledReader ensures that reads to r never exceeds a specified rate of
bytes per second. The maxBurst duration changes how often the verification is
done. The smaller the value, the less bursty, but also the more overhead there
is to the throttling.
func ThrottledWriter
func ThrottledWriter(w io.Writer, bytesPerSec int, maxBurst time.Duration) io.Writer
ThrottledWriter ensures that writes to w never exceeds a specified rate of
bytes per second. The maxBurst duration changes how often the verification is
done. The smaller the value, the less bursty, but also the more overhead there
is to the throttling.
type MeasuredReader
type MeasuredReader struct {
}
MeasuredReader wraps a reader and tracks how many bytes are read to it.
func NewMeasuredReader
func NewMeasuredReader(r io.Reader) *MeasuredReader
NewMeasuredReader wraps a reader.
func (*MeasuredReader) BytesPer
func (m *MeasuredReader) BytesPer(perPeriod time.Duration) uint64
BytesPer tells the rate per period at which bytes were read since last measurement.
func (*MeasuredReader) BytesPerSec
func (m *MeasuredReader) BytesPerSec() uint64
BytesPerSec tells the rate per second at which bytes were read since last measurement.
func (*MeasuredReader) Read
func (m *MeasuredReader) Read(b []byte) (n int, err error)
func (*MeasuredReader) Total
func (m *MeasuredReader) Total() int
Total number of bytes that have been read.
type MeasuredWriter
type MeasuredWriter struct {
}
MeasuredWriter wraps a writer and tracks how many bytes are written to it.
func NewMeasuredWriter
func NewMeasuredWriter(w io.Writer) *MeasuredWriter
NewMeasuredWriter wraps a writer.
func (*MeasuredWriter) BytesPer
func (m *MeasuredWriter) BytesPer(perPeriod time.Duration) uint64
BytesPer tells the rate per period at which bytes were written since last measurement.
func (*MeasuredWriter) BytesPerSec
func (m *MeasuredWriter) BytesPerSec() uint64
BytesPerSec tells the rate per second at which bytes were written since last measurement.
func (*MeasuredWriter) Total
func (m *MeasuredWriter) Total() int
Total number of bytes that have been written.
func (*MeasuredWriter) Write
func (m *MeasuredWriter) Write(b []byte) (n int, err error)
Documentation
¶
Overview ¶
Package iocontrol offers `io.Writer` and `io.Reader` implementations that allow one to measure and throttle the rate at which data is transferred.
Index ¶
- Constants
- func Profile(w io.Writer, r io.Reader) (pw io.Writer, pr io.Reader, done func() TimeProfile)
- func ProfileSample(w io.Writer, r io.Reader, res time.Duration) (pw io.Writer, pr io.Reader, done func() SamplingProfile)
- type MeasuredReader
- type MeasuredReaderAt
- type MeasuredWriter
- type MeasuredWriterAt
- type ReaderPool
- type SamplingProfile
- type Throttler
- type ThrottlerReader
- type ThrottlerWriter
- type TimeProfile
- type WriterPool
Constants ¶
const ( KiB = 1 << 10 MiB = 1 << 20 GiB = 1 << 30 )
Orders of magnitude of data, in kibibyte (powers of 2, or multiples of 1024). See https://en.wikipedia.org/wiki/Kibibyte.
Variables ¶
This section is empty.
Functions ¶
func Profile ¶
Profile will wrap a writer and reader pair and profile where time is spent: writing or reading. The result is returned when the `done` func is called. The `done` func can be called multiple times.
There is a small performance overhead of ~µs per Read/Write call. This is negligible in most I/O workloads. If the overhead is too much for your needs, use the `ProfileSample` call.
func ProfileSample ¶
func ProfileSample(w io.Writer, r io.Reader, res time.Duration) (pw io.Writer, pr io.Reader, done func() SamplingProfile)
ProfileSample will wrap a writer and reader pair and collect samples of where time is spent: writing or reading. The result is an approximation that is returned when the `done` func is called. The `done` func can be called *only once*.
This call is not as precise as the `Profile` call, but the performance overhead is much reduced.
Types ¶
type MeasuredReader ¶
type MeasuredReader struct {
// contains filtered or unexported fields
}
MeasuredReader wraps a reader and tracks how many bytes are read to it.
func NewMeasuredReader ¶
func NewMeasuredReader(r io.Reader) *MeasuredReader
NewMeasuredReader wraps a reader.
func (*MeasuredReader) BytesPer ¶
func (m *MeasuredReader) BytesPer(perPeriod time.Duration) uint64
BytesPer tells the rate per period at which bytes were read since last measurement.
func (*MeasuredReader) BytesPerSec ¶
func (m *MeasuredReader) BytesPerSec() uint64
BytesPerSec tells the rate per second at which bytes were read since last measurement.
func (*MeasuredReader) Total ¶
func (m *MeasuredReader) Total() int
Total number of bytes that have been read.
type MeasuredReaderAt ¶
type MeasuredReaderAt struct {
// contains filtered or unexported fields
}
MeasuredReaderAt wraps an io.ReaderAt and tracks how many bytes are read from it.
func NewMeasuredReaderAt ¶
func NewMeasuredReaderAt(r io.ReaderAt) *MeasuredReaderAt
NewMeasuredReaderAt wraps a ReaderAt.
func (*MeasuredReaderAt) BytesPer ¶
func (m *MeasuredReaderAt) BytesPer(perPeriod time.Duration) uint64
BytesPer tells the rate per period at which bytes were read since last measurement.
func (*MeasuredReaderAt) BytesPerSec ¶
func (m *MeasuredReaderAt) BytesPerSec() uint64
BytesPerSec tells the rate per second at which bytes were read since last measurement.
func (*MeasuredReaderAt) ReadAt ¶
func (m *MeasuredReaderAt) ReadAt(p []byte, off int64) (n int, err error)
func (*MeasuredReaderAt) Total ¶
func (m *MeasuredReaderAt) Total() int
Total number of bytes that have been read.
type MeasuredWriter ¶
type MeasuredWriter struct {
// contains filtered or unexported fields
}
MeasuredWriter wraps a writer and tracks how many bytes are written to it.
func NewMeasuredWriter ¶
func NewMeasuredWriter(w io.Writer) *MeasuredWriter
NewMeasuredWriter wraps a writer.
func (*MeasuredWriter) BytesPer ¶
func (m *MeasuredWriter) BytesPer(perPeriod time.Duration) uint64
BytesPer tells the rate per period at which bytes were written since last measurement.
func (*MeasuredWriter) BytesPerSec ¶
func (m *MeasuredWriter) BytesPerSec() uint64
BytesPerSec tells the rate per second at which bytes were written since last measurement.
func (*MeasuredWriter) Total ¶
func (m *MeasuredWriter) Total() int
Total number of bytes that have been written.
type MeasuredWriterAt ¶
type MeasuredWriterAt struct {
// contains filtered or unexported fields
}
MeasuredWriterAt wraps an io.WriterAt and tracks how many bytes are written to it.
func NewMeasuredWriterAt ¶
func NewMeasuredWriterAt(w io.WriterAt) *MeasuredWriterAt
NewMeasuredWriterAt wraps a WriterAt.
func (*MeasuredWriterAt) BytesPer ¶
func (m *MeasuredWriterAt) BytesPer(perPeriod time.Duration) uint64
BytesPer tells the rate per period at which bytes were written since last measurement.
func (*MeasuredWriterAt) BytesPerSec ¶
func (m *MeasuredWriterAt) BytesPerSec() uint64
BytesPerSec tells the rate per second at which bytes were written since last measurement.
func (*MeasuredWriterAt) Total ¶
func (m *MeasuredWriterAt) Total() int
Total number of bytes that have been written.
type ReaderPool ¶
type ReaderPool struct {
// contains filtered or unexported fields
}
ReaderPool creates instances of iocontrol.ThrottlerReader that are managed such that they collectively do not exceed a certain rate.
The default value of ReaderPool is not to be used, create instances with `NewReaderPool`.
func NewReaderPool ¶
func NewReaderPool(maxRate int, maxBurst time.Duration) *ReaderPool
NewReaderPool creates a pool that ensures the writers it wraps will respect an overall maxRate, with maxBurst resolution. The semantics of the wrapped writers are the same as those of using a plain ThrottledReader.
func (*ReaderPool) Get ¶
func (pool *ReaderPool) Get(r io.Reader) (reader io.Reader, release func())
Get a throttled reader that wraps r.
func (*ReaderPool) Len ¶
func (pool *ReaderPool) Len() int
Len is the number of currently given out throttled readers.
func (*ReaderPool) SetRate ¶
func (pool *ReaderPool) SetRate(rate int) int
SetRate of the pool, updating each given out reader to respect the newly set rate. Returns the old rate.
type SamplingProfile ¶
type SamplingProfile struct {
TimeProfile
Reading int
Writing int
NotReading int
NotWriting int
}
SamplingProfile samples when a reader and a writer are blocked, or not. If sampled at a high enough resolution, the result should give a good approximation of the distribution of time. The results are not as precise as the result of `Profile`, but the performance overhead is much reduced.
type Throttler ¶
type Throttler interface {
// SetRate changes the rate at which the throttler allows reads or writes.
SetRate(perSec int)
}
type ThrottlerReader ¶
func ThrottledReader ¶
ThrottledReader ensures that reads to `r` never exceeds a specified rate of bytes per second. The `maxBurst` duration changes how often the verification is done. The smaller the value, the less bursty, but also the more overhead there is to the throttling.
type ThrottlerWriter ¶
func ThrottledWriter ¶
ThrottledWriter ensures that writes to `w` never exceeds a specified rate of bytes per second. The `maxBurst` duration changes how often the verification is done. The smaller the value, the less bursty, but also the more overhead there is to the throttling.
type TimeProfile ¶
TimeProfile contains information about the timings involved in the exchange of bytes between an io.Writer and io.Reader.
type WriterPool ¶
type WriterPool struct {
// contains filtered or unexported fields
}
WriterPool creates instances of iocontrol.ThrottlerWriter that are managed such that they collectively do not exceed a certain rate.
The default value of WriterPool is not to be used, create instances with `NewWriterPool`.
func NewWriterPool ¶
func NewWriterPool(maxRate int, maxBurst time.Duration) *WriterPool
NewWriterPool creates a pool that ensures the writers it wraps will respect an overall maxRate, with maxBurst resolution. The semantics of the wrapped writers are the same as those of using a plain ThrottledWriter.
func (*WriterPool) Get ¶
func (pool *WriterPool) Get(w io.Writer) (writer io.Writer, release func())
Get a throttled writer that wraps w.
func (*WriterPool) Len ¶
func (pool *WriterPool) Len() int
Len is the number of currently given out throttled writers.
func (*WriterPool) SetRate ¶
func (pool *WriterPool) SetRate(rate int) int
SetRate of the pool, updating each given out writer to respect the newly set rate. Returns the old rate.
Source Files