1 2# fwd 3 import "github.com/philhofer/fwd" 4 5The `fwd` package provides a buffered reader 6and writer. Each has methods that help improve 7the encoding/decoding performance of some binary 8protocols. 9 10The `fwd.Writer` and `fwd.Reader` type provide similar 11functionality to their counterparts in `bufio`, plus 12a few extra utility methods that simplify read-ahead 13and write-ahead. I wrote this package to improve serialization 14performance for <a href="http://github.com/tinylib/msgp">http://github.com/tinylib/msgp</a>, 15where it provided about a 2x speedup over `bufio` for certain 16workloads. However, care must be taken to understand the semantics of the 17extra methods provided by this package, as they allow 18the user to access and manipulate the buffer memory 19directly. 20 21The extra methods for `fwd.Reader` are `Peek`, `Skip` 22and `Next`. `(*fwd.Reader).Peek`, unlike `(*bufio.Reader).Peek`, 23will re-allocate the read buffer in order to accommodate arbitrarily 24large read-ahead. `(*fwd.Reader).Skip` skips the next `n` bytes 25in the stream, and uses the `io.Seeker` interface if the underlying 26stream implements it. `(*fwd.Reader).Next` returns a slice pointing 27to the next `n` bytes in the read buffer (like `Peek`), but also 28increments the read position. This allows users to process streams 29in arbitrary block sizes without having to manage appropriately-sized 30slices. Additionally, obviating the need to copy the data from the 31buffer to another location in memory can improve performance dramatically 32in CPU-bound applications. 33 34`fwd.Writer` only has one extra method, which is `(*fwd.Writer).Next`, which 35returns a slice pointing to the next `n` bytes of the writer, and increments 36the write position by the length of the returned slice. This allows users 37to write directly to the end of the buffer. 38 39 40 41 42## Constants 43``` go 44const ( 45 // DefaultReaderSize is the default size of the read buffer 46 DefaultReaderSize = 2048 47) 48``` 49``` go 50const ( 51 // DefaultWriterSize is the 52 // default write buffer size. 53 DefaultWriterSize = 2048 54) 55``` 56 57 58 59## type Reader 60``` go 61type Reader struct { 62 // contains filtered or unexported fields 63} 64``` 65Reader is a buffered look-ahead reader 66 67 68 69 70 71 72 73 74 75### func NewReader 76``` go 77func NewReader(r io.Reader) *Reader 78``` 79NewReader returns a new *Reader that reads from 'r' 80 81 82### func NewReaderSize 83``` go 84func NewReaderSize(r io.Reader, n int) *Reader 85``` 86NewReaderSize returns a new *Reader that 87reads from 'r' and has a buffer size 'n' 88 89 90 91 92### func (\*Reader) BufferSize 93``` go 94func (r *Reader) BufferSize() int 95``` 96BufferSize returns the total size of the buffer 97 98 99 100### func (\*Reader) Buffered 101``` go 102func (r *Reader) Buffered() int 103``` 104Buffered returns the number of bytes currently in the buffer 105 106 107 108### func (\*Reader) Next 109``` go 110func (r *Reader) Next(n int) ([]byte, error) 111``` 112Next returns the next 'n' bytes in the stream. 113Unlike Peek, Next advances the reader position. 114The returned bytes point to the same 115data as the buffer, so the slice is 116only valid until the next reader method call. 117An EOF is considered an unexpected error. 118If an the returned slice is less than the 119length asked for, an error will be returned, 120and the reader position will not be incremented. 121 122 123 124### func (\*Reader) Peek 125``` go 126func (r *Reader) Peek(n int) ([]byte, error) 127``` 128Peek returns the next 'n' buffered bytes, 129reading from the underlying reader if necessary. 130It will only return a slice shorter than 'n' bytes 131if it also returns an error. Peek does not advance 132the reader. EOF errors are *not* returned as 133io.ErrUnexpectedEOF. 134 135 136 137### func (\*Reader) Read 138``` go 139func (r *Reader) Read(b []byte) (int, error) 140``` 141Read implements `io.Reader` 142 143 144 145### func (\*Reader) ReadByte 146``` go 147func (r *Reader) ReadByte() (byte, error) 148``` 149ReadByte implements `io.ByteReader` 150 151 152 153### func (\*Reader) ReadFull 154``` go 155func (r *Reader) ReadFull(b []byte) (int, error) 156``` 157ReadFull attempts to read len(b) bytes into 158'b'. It returns the number of bytes read into 159'b', and an error if it does not return len(b). 160EOF is considered an unexpected error. 161 162 163 164### func (\*Reader) Reset 165``` go 166func (r *Reader) Reset(rd io.Reader) 167``` 168Reset resets the underlying reader 169and the read buffer. 170 171 172 173### func (\*Reader) Skip 174``` go 175func (r *Reader) Skip(n int) (int, error) 176``` 177Skip moves the reader forward 'n' bytes. 178Returns the number of bytes skipped and any 179errors encountered. It is analogous to Seek(n, 1). 180If the underlying reader implements io.Seeker, then 181that method will be used to skip forward. 182 183If the reader encounters 184an EOF before skipping 'n' bytes, it 185returns io.ErrUnexpectedEOF. If the 186underlying reader implements io.Seeker, then 187those rules apply instead. (Many implementations 188will not return `io.EOF` until the next call 189to Read.) 190 191 192 193### func (\*Reader) WriteTo 194``` go 195func (r *Reader) WriteTo(w io.Writer) (int64, error) 196``` 197WriteTo implements `io.WriterTo` 198 199 200 201## type Writer 202``` go 203type Writer struct { 204 // contains filtered or unexported fields 205} 206``` 207Writer is a buffered writer 208 209 210 211 212 213 214 215 216 217### func NewWriter 218``` go 219func NewWriter(w io.Writer) *Writer 220``` 221NewWriter returns a new writer 222that writes to 'w' and has a buffer 223that is `DefaultWriterSize` bytes. 224 225 226### func NewWriterSize 227``` go 228func NewWriterSize(w io.Writer, size int) *Writer 229``` 230NewWriterSize returns a new writer 231that writes to 'w' and has a buffer 232that is 'size' bytes. 233 234 235 236 237### func (\*Writer) BufferSize 238``` go 239func (w *Writer) BufferSize() int 240``` 241BufferSize returns the maximum size of the buffer. 242 243 244 245### func (\*Writer) Buffered 246``` go 247func (w *Writer) Buffered() int 248``` 249Buffered returns the number of buffered bytes 250in the reader. 251 252 253 254### func (\*Writer) Flush 255``` go 256func (w *Writer) Flush() error 257``` 258Flush flushes any buffered bytes 259to the underlying writer. 260 261 262 263### func (\*Writer) Next 264``` go 265func (w *Writer) Next(n int) ([]byte, error) 266``` 267Next returns the next 'n' free bytes 268in the write buffer, flushing the writer 269as necessary. Next will return `io.ErrShortBuffer` 270if 'n' is greater than the size of the write buffer. 271Calls to 'next' increment the write position by 272the size of the returned buffer. 273 274 275 276### func (\*Writer) ReadFrom 277``` go 278func (w *Writer) ReadFrom(r io.Reader) (int64, error) 279``` 280ReadFrom implements `io.ReaderFrom` 281 282 283 284### func (\*Writer) Write 285``` go 286func (w *Writer) Write(p []byte) (int, error) 287``` 288Write implements `io.Writer` 289 290 291 292### func (\*Writer) WriteByte 293``` go 294func (w *Writer) WriteByte(b byte) error 295``` 296WriteByte implements `io.ByteWriter` 297 298 299 300### func (\*Writer) WriteString 301``` go 302func (w *Writer) WriteString(s string) (int, error) 303``` 304WriteString is analogous to Write, but it takes a string. 305 306 307 308 309 310 311 312 313 314- - - 315Generated by [godoc2md](http://godoc.org/github.com/davecheney/godoc2md)