Repository files navigation

import "github.com/philhofer/fwd"

• Overview
• Index

Package fwd provides a buffered readerand writer. Each has methods that help improvethe encoding/decoding performance of some binaryprotocols.

TheWriter andReader type provide similarfunctionality to their counterparts inbufio, plusa few extra utility methods that simplify read-aheadand write-ahead. I wrote this package to improve serializationperformance forgithub.com/tinylib/msgp,where it provided about a 2x speedup overbufio for certainworkloads. However, care must be taken to understand the semantics of theextra methods provided by this package, as they allowthe user to access and manipulate the buffer memorydirectly.

The extra methods forfwd.Reader arePeek,SkipandNext.(*fwd.Reader).Peek, unlike(*bufio.Reader).Peek,will re-allocate the read buffer in order to accommodate arbitrarilylarge read-ahead.(*fwd.Reader).Skip skips the nextn bytesin the stream, and uses theio.Seeker interface if the underlyingstream implements it.(*fwd.Reader).Next returns a slice pointingto the nextn bytes in the read buffer (likePeek), but alsoincrements the read position. This allows users to process streamsin arbitrary block sizes without having to manage appropriately-sizedslices. Additionally, obviating the need to copy the data from thebuffer to another location in memory can improve performance dramaticallyin CPU-bound applications.

fwd.Writer only has one extra method, which is(*fwd.Writer).Next, whichreturns a slice pointing to the nextn bytes of the writer, and incrementsthe write position by the length of the returned slice. This allows usersto write directly to the end of the buffer.

Because it uses the unsafe package, there are theoreticallyno promises about forward or backward portability.

To stay compatible with tinygo 0.32, unsafestr() has been updatedto use unsafe.Slice() as suggested byhttps://tinygo.org/docs/guides/compatibility, which also requiredbumping go.mod to require at least go 1.20.

• Constants
• type Reader
  • func NewReader(r io.Reader) *Reader
  • func NewReaderBuf(r io.Reader, buf []byte) *Reader
  • func NewReaderSize(r io.Reader, n int) *Reader
  • func (r *Reader) BufferSize() int
  • func (r *Reader) Buffered() int
  • func (r *Reader) Next(n int) ([]byte, error)
  • func (r *Reader) Peek(n int) ([]byte, error)
  • func (r *Reader) Read(b []byte) (int, error)
  • func (r *Reader) ReadByte() (byte, error)
  • func (r *Reader) ReadFull(b []byte) (int, error)
  • func (r *Reader) Reset(rd io.Reader)
  • func (r *Reader) Skip(n int) (int, error)
  • func (r *Reader) WriteTo(w io.Writer) (int64, error)
• type Writer
  • func NewWriter(w io.Writer) *Writer
  • func NewWriterBuf(w io.Writer, buf []byte) *Writer
  • func NewWriterSize(w io.Writer, n int) *Writer
  • func (w *Writer) BufferSize() int
  • func (w *Writer) Buffered() int
  • func (w *Writer) Flush() error
  • func (w *Writer) Next(n int) ([]byte, error)
  • func (w *Writer) ReadFrom(r io.Reader) (int64, error)
  • func (w *Writer) Write(p []byte) (int, error)
  • func (w *Writer) WriteByte(b byte) error
  • func (w *Writer) WriteString(s string) (int, error)

const (// DefaultReaderSize is the default size of the read bufferDefaultReaderSize=2048)

const (// DefaultWriterSize is the// default write buffer size.DefaultWriterSize=2048)

typeReaderstruct {// contains filtered or unexported fields}

Reader is a buffered look-ahead reader

funcNewReader(r io.Reader)*Reader

NewReader returns a new *Reader that reads from 'r'

funcNewReaderSize(r io.Reader,nint)*Reader

NewReaderSize returns a new *Reader thatreads from 'r' and has a buffer size 'n'

func (r*Reader)BufferSize()int

BufferSize returns the total size of the buffer

func (r*Reader)Buffered()int

Buffered returns the number of bytes currently in the buffer

func (r*Reader)Next(nint) ([]byte,error)

Next returns the next 'n' bytes in the stream.Unlike Peek, Next advances the reader position.The returned bytes point to the samedata as the buffer, so the slice isonly valid until the next reader method call.An EOF is considered an unexpected error.If an the returned slice is less than thelength asked for, an error will be returned,and the reader position will not be incremented.

func (r*Reader)Peek(nint) ([]byte,error)

Peek returns the next 'n' buffered bytes,reading from the underlying reader if necessary.It will only return a slice shorter than 'n' bytesif it also returns an error. Peek does not advancethe reader. EOF errors arenot returned asio.ErrUnexpectedEOF.

func (r*Reader)Read(b []byte) (int,error)

Read implementsio.Reader.

func (r*Reader)ReadByte() (byte,error)

ReadByte implementsio.ByteReader.

func (r*Reader)ReadFull(b []byte) (int,error)

ReadFull attempts to read len(b) bytes into'b'. It returns the number of bytes read into'b', and an error if it does not return len(b).EOF is considered an unexpected error.

func (r*Reader)Reset(rd io.Reader)

Reset resets the underlying readerand the read buffer.

func (r*Reader)Skip(nint) (int,error)

Skip moves the reader forward 'n' bytes.Returns the number of bytes skipped and anyerrors encountered. It is analogous to Seek(n, 1).If the underlying reader implements io.Seeker, thenthat method will be used to skip forward.

If the reader encountersan EOF before skipping 'n' bytes, itreturnsio.ErrUnexpectedEOF. If theunderlying reader implementsio.Seeker, thenthose rules apply instead. (Many implementationswill not returnio.EOF until the next callto Read).

func (r*Reader)WriteTo(w io.Writer) (int64,error)

WriteTo implementsio.WriterTo.

typeWriterstruct {// contains filtered or unexported fields}

Writer is a buffered writer

funcNewWriter(w io.Writer)*Writer

NewWriter returns a new writerthat writes to 'w' and has a bufferthat isDefaultWriterSize bytes.

funcNewWriterBuf(w io.Writer,buf []byte)*Writer

NewWriterBuf returns a new writerthat writes to 'w' and has 'buf' as a buffer.'buf' is not used when has smaller capacity than 18,custom buffer is allocated instead.

funcNewWriterSize(w io.Writer,nint)*Writer

NewWriterSize returns a new writer thatwrites to 'w' and has a buffer size 'n'.

func (w*Writer)BufferSize()int

BufferSize returns the maximum size of the buffer.

func (w*Writer)Buffered()int

Buffered returns the number of buffered bytesin the reader.

func (w*Writer)Flush()error

Flush flushes any buffered bytesto the underlying writer.

func (w*Writer)Next(nint) ([]byte,error)

Next returns the next 'n' free bytesin the write buffer, flushing the writeras necessary. Next will returnio.ErrShortBufferif 'n' is greater than the size of the write buffer.Calls to 'next' increment the write position bythe size of the returned buffer.

func (w*Writer)ReadFrom(r io.Reader) (int64,error)

ReadFrom implementsio.ReaderFrom

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

Write implementsio.Writer

func (w*Writer)WriteByte(bbyte)error

WriteByte implementsio.ByteWriter

func (w*Writer)WriteString(sstring) (int,error)

WriteString is analogous to Write, but it takes a string.

Generated bygodoc2md