README
¶
Buffer
Usage
The following buffers provide simple unique behaviours which when composed can create complex buffering strategies. For use with github.com/djherbis/nio for Buffered io.Pipe and io.Copy implementations.
For example:
import (
"github.com/djherbis/buffer"
"github.com/djherbis/nio"
"io/ioutil"
)
// Buffer 32KB to Memory, after that buffer to 100MB chunked files
buf := buffer.NewUnboundedBuffer(32*1024, 100*1024*1024)
nio.Copy(w, r, buf) // Reads from r, writes to buf, reads from buf writes to w (concurrently).
// Buffer 32KB to Memory, discard overflow
buf = buffer.NewSpill(32*1024, ioutil.Discard)
nio.Copy(w, r, buf)
Supported Buffers
Bounded Buffers
Memory: Wrapper for bytes.Buffer
File: File-based buffering. The file never exceeds Cap() in length, no matter how many times its written/read from. It accomplishes this by "wrapping" around the fixed max-length file when the data gets too long but there is available freed space at the beginning of the file. The caller is responsible for closing and deleting the file when done.
import (
"ioutil"
"os"
"github.com/djherbis/buffer"
)
// Create a File-based Buffer with max size 100MB
file, err := ioutil.TempFile("", "buffer")
if err != nil {
return err
}
defer os.Remove(file.Name())
defer file.Close()
buf := buffer.NewFile(100*1024*1024, file)
// A simpler way:
pool := buffer.NewFilePool(100*1024*1024, "") // "" -- use temp dir
buf, err := pool.Get() // allocate the buffer
if err != nil {
return err
}
defer pool.Put(buf) // close and remove the allocated file for the buffer
Multi: A fixed length linked-list of buffers. Each buffer reads from the next buffer so that all the buffered data is shifted upwards in the list when reading. Writes are always written to the first buffer in the list whose Len() < Cap().
import (
"github.com/djherbis/buffer"
)
mem := buffer.New(32*1024)
file := buffer.NewFile(100*1024*1024, someFileObj)) // you'll need to manage Open(), Close() and Delete someFileObj
// Buffer composed of 32KB of memory, and 100MB of file.
buf := buffer.NewMulti(mem, file)
Unbounded Buffers
Partition: A queue of buffers. Writes always go to the last buffer in the queue. If all buffers are full, a new buffer is "pushed" to the end of the queue (generated by a user-given function). Reads come from the first buffer, when the first buffer is emptied it is "popped" off the queue.
import (
"github.com/djherbis/buffer"
)
// Create 32 KB sized-chunks of memory as needed to expand/contract the buffer size.
buf := buffer.NewPartition(buffer.NewMemPool(32*1024))
// Create 100 MB sized-chunks of files as needed to expand/contract the buffer size.
buf = buffer.NewPartition(buffer.NewFilePool(100*1024*1024, ""))
Ring: A single buffer which begins overwriting the oldest buffered data when it reaches its capacity.
import (
"github.com/djherbis/buffer"
)
// Create a File-based Buffer with max size 100MB
file := buffer.NewFile(100*1024*1024, someFileObj) // you'll need to Open(), Close() and Delete someFileObj.
// If buffered data exceeds 100MB, overwrite oldest data as new data comes in
buf := buffer.NewRing(file) // requires BufferAt interface.
Spill: A single buffer which when full, writes the overflow to a given io.Writer. -> Note that it will actually "spill" whenever there is an error while writing, this should only be a "full" error.
import (
"github.com/djherbis/buffer"
"github.com/djherbis/nio"
"io/ioutil"
)
// Buffer 32KB to Memory, discard overflow
buf := buffer.NewSpill(32*1024, ioutil.Discard)
nio.Copy(w, r, buf)
Empty Buffer
Discard: Reads always return EOF, writes goto ioutil.Discard.
import (
"github.com/djherbis/buffer"
)
// Reads will return io.EOF, writes will return success (nil error, full write) but no data was written.
buf := buffer.Discard
Custom Buffers
Feel free to implement your own buffer, just meet the required interface (Buffer/BufferAt) and compose away!
// Buffer Interface used by Multi and Partition
type Buffer interface {
Len() int64
Cap() int64
io.Reader
io.Writer
Reset()
}
// BufferAt interface used by Ring
type BufferAt interface {
Buffer
io.ReaderAt
io.WriterAt
}
Installation
go get github.com/djherbis/buffer
Documentation
¶
Overview ¶
Package buffer implements a series of Buffers which can be composed to implement complicated buffering strategies
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Buffer ¶
type Buffer interface {
Len() int64 // How much data is Buffered in bytes
Cap() int64 // How much data can be Buffered at once in bytes.
io.Reader // Read() will read from the top of the buffer [io.EOF if empty]
io.Writer // Write() will write to the end of the buffer [io.ErrShortWrite if not enough space]
Reset() // Truncates the buffer, Len() == 0.
}
Buffer is used to Write() data which will be Read() later.
var Discard Buffer = discard{}
Discard is a Buffer which writes to ioutil.Discard and read's return 0, io.EOF. All of its methods are concurrent safe.
func NewMulti ¶
NewMulti returns a Buffer which is the logical concatenation of the passed buffers. The data in the buffers is shifted such that there is no non-empty buffer following a non-full buffer, this process is also run after every Read. If no buffers are passed, the returned Buffer is nil.
func NewPartition ¶
NewPartition returns a Buffer which uses a Pool to extend or shrink its size as needed. It automatically allocates new buffers with pool.Get() to extend is length, and pool.Put() to release unused buffers as it shrinks.
func NewRing ¶
NewRing returns a Ring Buffer from a BufferAt. It overwrites old data in the Buffer when needed (when its full).
func NewSpill ¶
NewSpill returns a Buffer which writes data to w when there's an error writing to buf. Such as when buf is full, or the disk is full, etc.
func NewSwap ¶
NewSwap creates a Buffer which writes to a until you write past a.Cap() then it io.Copy's from a to b and writes to b. Once the Buffer is empty again, it starts over writing to a. Note that if b.Cap() <= a.Cap() it will cause a panic, b is expected to be larger in order to accommodate writes past a.Cap().
func NewUnboundedBuffer ¶
NewUnboundedBuffer returns a Buffer which buffers "mem" bytes to memory and then creates file's of size "file" to buffer above "mem" bytes.
type BufferAt ¶
BufferAt is a buffer which supports io.ReaderAt and io.WriterAt
func NewMultiAt ¶
NewMultiAt returns a BufferAt which is the logical concatenation of the passed BufferAts. The data in the buffers is shifted such that there is no non-empty buffer following a non-full buffer, this process is also run after every Read. If no buffers are passed, the returned Buffer is nil.
func NewPartitionAt ¶ added in v1.1.0
NewPartitionAt returns a BufferAt which uses a PoolAt to extend or shrink its size as needed. It automatically allocates new buffers with pool.Get() to extend is length, and pool.Put() to release unused buffers as it shrinks.
func NewSwapAt ¶
NewSwapAt creates a BufferAt which writes to a until you write past a.Cap() then it io.Copy's from a to b and writes to b. Once the Buffer is empty again, it starts over writing to a. Note that if b.Cap() <= a.Cap() it will cause a panic, b is expected to be larger in order to accommodate writes past a.Cap().
type File ¶
type File interface {
Name() string
Stat() (fi os.FileInfo, err error)
io.ReaderAt
io.WriterAt
Close() error
}
File is used as the backing resource for a the NewFile BufferAt.
type List ¶
type List []Buffer
List is a slice of Buffers, it's the backing for NewPartition
type ListAt ¶ added in v1.1.0
type ListAt []BufferAt
ListAt is a slice of BufferAt's, it's the backing for NewPartitionAt
type Pool ¶
type Pool interface {
Get() (Buffer, error) // Allocate a Buffer
Put(buf Buffer) error // Release or Reuse a Buffer
}
Pool provides a way to Allocate and Release Buffer objects Pools mut be concurrent-safe for calls to Get() and Put().
func NewFilePool ¶
NewFilePool returns a Pool, Get() returns a file-based buffer of max size N. Put() closes and deletes the underlying file for the buffer. Get() may return an error if it fails to create a file for the buffer. Put() may return an error if it fails to delete the file.
func NewMemPool ¶
NewMemPool returns a Pool, Get() returns an in memory buffer of max size N. Put() returns the buffer to the pool after resetting it. Get() and Put() errors will always be nil.
type PoolAt ¶ added in v1.1.0
type PoolAt interface {
Get() (BufferAt, error) // Allocate a BufferAt
Put(buf BufferAt) error // Release or Reuse a BufferAt
}
PoolAt provides a way to Allocate and Release BufferAt objects PoolAt's mut be concurrent-safe for calls to Get() and Put().
func NewFilePoolAt ¶ added in v1.1.0
NewFilePoolAt returns a PoolAt, Get() returns a file-based buffer of max size N. Put() closes and deletes the underlying file for the buffer. Get() may return an error if it fails to create a file for the buffer. Put() may return an error if it fails to delete the file.
func NewMemPoolAt ¶ added in v1.1.0
NewMemPoolAt returns a PoolAt, Get() returns an in memory buffer of max size N. Put() returns the buffer to the pool after resetting it. Get() and Put() errors will always be nil.
Source Files
Directories