valve

README

Valve

Regulate and meter I/O streams in Go

Documentation

Index

• Constants
• type IO
  • func (o IO) String() string
• type Limit
  • func NewLimit(r io.Reader, rMax int64, w io.Writer, wMax int64) *Limit
  • func NewReadLimit(r io.Reader, rMax int64) *Limit
  • func NewReadWriteLimit(rw io.ReadWriter, rMax, wMax int64) *Limit
  • func NewWriteLimit(w io.Writer, wMax int64) *Limit
  • func (l *Limit) CanRead() bool
  • func (l *Limit) CanWrite() bool
  • func (l *Limit) Close() error
  • func (l *Limit) MakeReadLimitError(req, n int64) error
  • func (l *Limit) MakeWriteLimitError(req, n int64) error
  • func (l *Limit) MaxCount() (r, w int64)
  • func (l *Limit) MaxCountRead() int64
  • func (l *Limit) MaxCountWrite() int64
  • func (l *Limit) Read(p []byte) (n int, err error)
  • func (l *Limit) ReadFrom(r io.Reader) (n int64, err error)
  • func (l *Limit) RemainingCount() (r, w int64)
  • func (l *Limit) RemainingCountRead() int64
  • func (l *Limit) RemainingCountWrite() int64
  • func (l *Limit) SetMaxCount(r, w int64)
  • func (l *Limit) SetMaxCountRead(r int64)
  • func (l *Limit) SetMaxCountWrite(w int64)
  • func (l *Limit) Write(p []byte) (n int, err error)
  • func (l *Limit) WriteTo(w io.Writer) (n int64, err error)
• type LimitError
  • func (e LimitError) Error() string
• type Meter
  • func NewMeter(r io.Reader, w io.Writer) *Meter
  • func NewReadMeter(r io.Reader) *Meter
  • func NewReadWriteMeter(rw io.ReadWriter) *Meter
  • func NewWriteMeter(w io.Writer) *Meter
  • func (m *Meter) AddCount(r, w int64) (nr, nw int64)
  • func (m *Meter) AddCountRead(r int64) int64
  • func (m *Meter) AddCountWrite(w int64) int64
  • func (m *Meter) CanRead() bool
  • func (m *Meter) CanWrite() bool
  • func (m *Meter) Close() error
  • func (m *Meter) Count() (r, w int64)
  • func (m *Meter) CountRead() int64
  • func (m *Meter) CountWrite() int64
  • func (m *Meter) Read(p []byte) (n int, err error)
  • func (m *Meter) ReadFrom(r io.Reader) (n int64, err error)
  • func (m *Meter) ResetCount()
  • func (m *Meter) ResetCountRead()
  • func (m *Meter) ResetCountWrite()
  • func (m *Meter) SetCount(r, w int64)
  • func (m *Meter) SetCountRead(r int64)
  • func (m *Meter) SetCountWrite(w int64)
  • func (m *Meter) Write(p []byte) (n int, err error)
  • func (m *Meter) WriteTo(w io.Writer) (n int64, err error)

Constants

const Unlimited = -1

Types

type IO

type IO int

IO is a bitmask identifying types of I/O operations.

const (
	Read IO = 1 << iota
	Write
	Close

	// Commonly used combinations.
	ReadWrite = Read | Write

	// Sentinel values.
	NOP      IO = 0
	DEADBEEF IO = ^NOP
)

func (IO) String

func (o IO) String() string

type Limit

type Limit struct {
	*Meter
	// contains filtered or unexported fields
}

Limit restricts the total bytes read and written, through the underlying io.Reader and io.Writer interfaces, by governing I/O requests forwarded to an embedded Meter.

func NewLimit

func NewLimit(r io.Reader, rMax int64, w io.Writer, wMax int64) *Limit

NewLimit returns a new Limit that restricts the total bytes read from r and written to w to a maximum of rMax and wMax bytes, respectively.

func NewReadLimit

func NewReadLimit(r io.Reader, rMax int64) *Limit

NewReadLimit returns a new Limit that restricts the total bytes read from r to a maximum of rMax bytes.

func NewReadWriteLimit

func NewReadWriteLimit(rw io.ReadWriter, rMax, wMax int64) *Limit

NewReadWriteLimit returns a new Limit that restricts the total bytes read from and written to rw to a maximum of rMax and wMax bytes, respectively.

func NewWriteLimit

func NewWriteLimit(w io.Writer, wMax int64) *Limit

NewWriteLimit returns a new Limit that restricts the total bytes written to w to a maximum of wMax bytes.

func (*Limit) CanRead

func (l *Limit) CanRead() bool

CanRead returns true if the Limit is capable of reading bytes.

func (*Limit) CanWrite

func (l *Limit) CanWrite() bool

CanWrite returns true if the Limit is capable of writing bytes.

func (*Limit) Close

func (l *Limit) Close() error

Close closes the embedded Meter.

func (*Limit) MakeReadLimitError

func (l *Limit) MakeReadLimitError(req, n int64) error

MakeReadLimitError returns a LimitError describing a short read of n bytes after attempting to read req bytes.

func (*Limit) MakeWriteLimitError

func (l *Limit) MakeWriteLimitError(req, n int64) error

MakeWriteLimitError returns a LimitError describing a short write of n bytes after attempting to write req bytes.

func (*Limit) MaxCount

func (l *Limit) MaxCount() (r, w int64)

MaxCount returns the maximum bytes that may be read and written.

func (*Limit) MaxCountRead

func (l *Limit) MaxCountRead() int64

MaxCountRead returns the maximum bytes that may be read.

func (*Limit) MaxCountWrite

func (l *Limit) MaxCountWrite() int64

MaxCountWrite returns the maximum bytes that may be written.

func (*Limit) Read

func (l *Limit) Read(p []byte) (n int, err error)

Read reads bytes from the underlying io.Reader to p and increments the total bytes read by n until the total bytes read reaches the maximum limit.

See Meter for additional details.

func (*Limit) ReadFrom

func (l *Limit) ReadFrom(r io.Reader) (n int64, err error)

ReadFrom copies bytes from r to the underlying io.Writer and increments the total bytes written by n until the total bytes written reaches the maximum limit.

See Meter for additional details.

func (*Limit) RemainingCount

func (l *Limit) RemainingCount() (r, w int64)

RemainingCount returns the total bytes that may be read and written before exceeding their respective limits.

func (*Limit) RemainingCountRead

func (l *Limit) RemainingCountRead() int64

RemainingCountRead returns the total bytes that may be read before exceeding the read limit.

func (*Limit) RemainingCountWrite

func (l *Limit) RemainingCountWrite() int64

RemainingCountWrite returns the total bytes that may be written before exceeding the write limit.

func (*Limit) SetMaxCount

func (l *Limit) SetMaxCount(r, w int64)

SetMaxCount restricts the total bytes read and written to a maximum of r and w bytes, respectively.

func (*Limit) SetMaxCountRead

func (l *Limit) SetMaxCountRead(r int64)

SetMaxCountRead restricts the total bytes read to a maximum of r bytes.

func (*Limit) SetMaxCountWrite

func (l *Limit) SetMaxCountWrite(w int64)

SetMaxCountWrite restricts the total bytes written to a maximum of w bytes.

func (*Limit) Write

func (l *Limit) Write(p []byte) (n int, err error)

Write writes bytes from p to the underlying io.Writer and increments the total bytes written by n until the total bytes written reaches the maximum limit.

See Meter for additional details.

func (*Limit) WriteTo

func (l *Limit) WriteTo(w io.Writer) (n int64, err error)

WriteTo writes bytes from the underlying io.Reader to w and increments the total bytes read by n until the total bytes read reaches the maximum limit.

See Meter for additional details.

type LimitError

type LimitError struct {
	// Limit is the object that imposed the I/O limit.
	*Limit

	// Requested is the number of bytes requested for read/write.
	Requested int64
	// Accepted is the number of bytes successfully read/written.
	Accepted int64
	// contains filtered or unexported fields
}

LimitError is returned when a short read/write occurs due to a byte limit.

func (LimitError) Error

func (e LimitError) Error() string

String returns a string representation of the LimitError.

type Meter

type Meter struct {
	io.Reader
	io.Writer
	// contains filtered or unexported fields
}

Meter records the total bytes read and written, through the underlying io.Reader and io.Writer given at construction, using any of the following interfaces:

• io.Reader (read)
• io.ReaderFrom (write)
• io.Writer (write)
• io.WriterTo (read)

Constructors also exist for read-only, write-only, and read-write Meters. Methods without an underlying interface return io.ErrClosedPipe.

Meter also implements the io.Closer interface. Closing a Meter closes each underlying interface that implements io.Closer.

func NewMeter

func NewMeter(r io.Reader, w io.Writer) *Meter

NewMeter returns a new Meter that counts the total bytes read from r and written to w.

func NewReadMeter

func NewReadMeter(r io.Reader) *Meter

NewReadMeter returns a new Meter that counts the total bytes read from r.

func NewReadWriteMeter

func NewReadWriteMeter(rw io.ReadWriter) *Meter

NewReadWriteMeter returns a new Meter that counts the total bytes read from and written to rw.

func NewWriteMeter

func NewWriteMeter(w io.Writer) *Meter

NewWriteMeter returns a new Meter that counts the total bytes written to w.

func (*Meter) AddCount

func (m *Meter) AddCount(r, w int64) (nr, nw int64)

AddCount increments the total bytes read by r and written by w and returns the new byte counts.

func (*Meter) AddCountRead

func (m *Meter) AddCountRead(r int64) int64

AddCountRead increments the total bytes read by r and returns the new byte count.

func (*Meter) AddCountWrite

func (m *Meter) AddCountWrite(w int64) int64

AddCountWrite increments the total bytes written by w and returns the new byte count.

func (*Meter) CanRead

func (m *Meter) CanRead() bool

CanRead returns true if the Meter is capable of reading bytes.

func (*Meter) CanWrite

func (m *Meter) CanWrite() bool

CanWrite returns true if the Meter is capable of writing bytes.

func (*Meter) Close

func (m *Meter) Close() error

Close closes each underlying interface that implements io.Closer.

See io.Closer for details.

func (*Meter) Count

func (m *Meter) Count() (r, w int64)

Count returns the total bytes read and written.

func (*Meter) CountRead

func (m *Meter) CountRead() int64

CountRead returns the total bytes read.

func (*Meter) CountWrite

func (m *Meter) CountWrite() int64

CountWrite returns the total bytes written.

func (*Meter) Read

func (m *Meter) Read(p []byte) (n int, err error)

Read reads bytes from the underlying io.Reader to p and increments the total bytes read by n.

See io.Reader for details.

func (*Meter) ReadFrom

func (m *Meter) ReadFrom(r io.Reader) (n int64, err error)

ReadFrom copies bytes from r to the underlying io.Writer and increments the total bytes written by n.

See io.ReaderFrom for details.

func (*Meter) ResetCount

func (m *Meter) ResetCount()

ResetCount sets the total bytes read and written to zero.

func (*Meter) ResetCountRead

func (m *Meter) ResetCountRead()

ResetCountRead sets the total bytes read to zero.

func (*Meter) ResetCountWrite

func (m *Meter) ResetCountWrite()

ResetCountWrite sets the total bytes written to zero.

func (*Meter) SetCount

func (m *Meter) SetCount(r, w int64)

SetCount sets the total bytes read to r and written to w.

func (*Meter) SetCountRead

func (m *Meter) SetCountRead(r int64)

SetCountRead sets the total bytes read to r.

func (*Meter) SetCountWrite

func (m *Meter) SetCountWrite(w int64)

SetCountWrite sets the total bytes written to w.

func (*Meter) Write

func (m *Meter) Write(p []byte) (n int, err error)

Write writes bytes from p to the underlying io.Writer and increments the total bytes written by n.

See io.Writer for details.

func (*Meter) WriteTo

func (m *Meter) WriteTo(w io.Writer) (n int64, err error)

WriteTo copies bytes from the underlying io.Reader to w and increments the total bytes read by n.

See io.WriterTo for details.