README
¶
framed 
To install:
go get github.com/getlantern/framed
For docs:
godoc github.com/getlantern/framed
Documentation
¶
Overview ¶
Package framed provides an implementations of io.Writer and io.Reader that write and read whole frames only.
Frames are length-prefixed. The first two bytes are an unsigned 16 bit int stored in little-endian byte order indicating the length of the content. The remaining bytes are the actual content of the frame.
The use of a uint16 means that the maximum possible frame size (MaxFrameSize) is 65535.
The frame size can be increased to 4294967295 bytes by calling EnableBigFrames() on the corresponding Reader and Writer.
Index ¶
Constants ¶
const ( // FrameHeaderBits is the size of the frame header in bits FrameHeaderBits = 16 // FrameHeaderBitsBig is the size of the frame header in bits when big frames are enabled FrameHeaderBitsBig = 32 // FrameHeaderLength is the size of the frame header in bytes FrameHeaderLength = FrameHeaderBits / 8 // FrameHeaderLengthBig is the size of the frame header in bytes when big frames are enabled FrameHeaderLengthBig = FrameHeaderBitsBig / 8 // MaxFrameLength is the maximum possible size of a frame (not including the // length prefix) MaxFrameLength = 1<<FrameHeaderBits - 1 // MaxFrameLengthBigFrames is the maximum possible size of a frame (not // including the length prefix) when big frames are enabled. MaxFrameLengthBigFrames = 1<<FrameHeaderBitsBig - 1 )
Variables ¶
This section is empty.
Functions ¶
func NewHeaderPreservingBufferPool ¶
func NewHeaderPreservingBufferPool(maxSize int, width int, enableBigFrames bool) bpool.ByteSlicePool
NewHeaderPreservingBufferPool creates a BufferPool that leaves room at the beginning of buffers for the framed header. This allows use of the WriteAtomic() capability.
Types ¶
type Framed ¶
type Framed interface {
// EnableBigFrames enables support for frames up to 4294967295 bytes in length
// by using BigEndian byte order for the frame size and supporting expansion of
// the size header from 2 to 4 bytes.
EnableBigFrames(framed interface{})
// DisableThreadSafety disables thread safety on reading and writing.
DisableThreadSafety()
}
Framed is the common interface for framed Readers and Writers
type ReadWriteCloser ¶
ReadWriteCloser combines a Reader and a Writer on top of an underlying ReadWriteCloser.
func NewReadWriteCloser ¶
func NewReadWriteCloser(rwc io.ReadWriteCloser) *ReadWriteCloser
func (*ReadWriteCloser) DisableThreadSafety ¶
func (fr *ReadWriteCloser) DisableThreadSafety()
func (*ReadWriteCloser) EnableBigFrames ¶
func (fr *ReadWriteCloser) EnableBigFrames()
type Reader ¶
type Reader struct {
Stream io.Reader // the raw underlying connection
// contains filtered or unexported fields
}
A Reader enhances an io.ReadCloser to read data in contiguous frames. It implements the io.Reader interface, but unlike typical io.Readers it only returns whole frames.
A Reader also supports the ability to read frames using dynamically allocated buffers via the ReadFrame method.
func (*Reader) DisableThreadSafety ¶
func (fr *Reader) DisableThreadSafety()
func (*Reader) EnableBigFrames ¶
func (fr *Reader) EnableBigFrames()
func (*Reader) EnableBuffering ¶
EnableBuffering enables buffering of read data
type Writer ¶
type Writer struct {
Stream io.Writer // the raw underlying connection
// contains filtered or unexported fields
}
A Writer enhances an io.WriteCloser to write data in contiguous frames. It implements the io.Writer interface, but unlike typical io.Writers, it includes information that allows a corresponding Reader to read whole frames without them being fragmented.
A Writer also supports a method that writes multiple buffers to the underlying stream as a single frame.
func (*Writer) DisableThreadSafety ¶
func (fr *Writer) DisableThreadSafety()
func (*Writer) EnableBigFrames ¶
func (fr *Writer) EnableBigFrames()
func (*Writer) Write ¶
Write implements the Write method from io.Writer. It prepends a frame length header that allows the fr.Reader on the other end to read the whole frame.
func (*Writer) WriteAtomic ¶
WriteAtomic writes a the frame and its length header in a single write. This requires that the frame was read into a buffer obtained from a pool created with NewHeaderPreservingBufferPool().
Source Files