recyclable

README

recyclable

import "codeberg.org/mgkeller/go-recyclable"

• Overview
• Index
• Examples

Overview

Package recyclable provides the recyclable.BufferPool, which is a never-ending font of recyclable.Buffer, a multiuse buffer that very reusable, supports re-reading the contained buffer, and when Close()d, will return home to its BufferPool for reuse.

Example :

HOWTO implement a goro-safe BufferPool for Buffers

// BufferPool allows us to have a never-ending font of Buffers.
// If the Pool is empty, a new one is created. If there is one someone put
// back, then it is returned. Saves on allocs like crazy. <3
rPool := NewBufferPool()

// Let's grab a Buffer
rb := rPool.Get()

// And immediately reset the value, as we can't trust it to be empty
rb.Reset([]byte("Hello World"))

// Unlike most buffers, we can re-read it:
for i := 0; i < 10; i++ {
    if string(rb.Bytes()) != "Hello World" {
        panic("OMG! Can't reread?!!!")
    }
}

// Or get the string value, if you prefer (and know it's safe)
for i := 0; i < 10; i++ {
    if rb.String() != "Hello World" {
        panic("OMG! Can't reread?!!!")
    }
}

// Appending to it as an io.Writer works as well
io.WriteString(rb, ", nice day?")
if string(rb.Bytes()) != "Hello World, nice day?" {
    panic("OMG! Append failed?!")
}

// Lastly, when you're all done, just close it.
rb.Close() // and it will go back into the Pool.
// Please don't use it anymore. Get a fresh one.

rb = rPool.Get() // See, not hard?
defer rb.Close() // Just remember to close it, unless you're passing it elsewhere

/* HINTS:
* Makes awesome ``http.Request.Body``s, especially since they get automatically ``.Close()``d when done with
* Replaces ``bytes.Buffer`` and ``bytes.Reader`` for most uses
* Isa Stringer and an error
* As a Writer and a Reader can be used in pipes and elsewhere
    * You can also pipe them to themselves, but that is a very bad idea unless you love watching OOMs
*/

Index

• Variables
• type Buffer
  • func NewBuffer(home *BufferPool, bytes []byte) *Buffer
  • func (r *Buffer) Bytes() []byte
  • func (r *Buffer) Close() error
  • func (r *Buffer) Error() string
  • func (r *Buffer) ResetFromLimitedReader(reader io.Reader, max int64) error
  • func (r *Buffer) ResetFromReader(reader io.Reader)
  • func (r *Buffer) String() string
  • func (r *Buffer) Write(p []byte) (n int, err error)
• type BufferPool
  • func NewBufferPool() *BufferPool
  • func (p *BufferPool) Get() *Buffer
  • func (p *BufferPool) Put(b *Buffer)

Examples

• Package

Package files

buffer.go bufferpool.go

Variables

var ErrTooLarge = errors.New("read byte count too large")

ErrTooLarge is returned when ResetFromLimitedReader is used and the supplied Reader writes too much

type Buffer

type Buffer struct {
    bytes.Reader
    // contains filtered or unexported fields
}

Buffer is an io.Reader, io.ReadCloser, io.ReaderAt, io.Writer, io.WriteCloser, io.WriterTo, io.Seeker, io.ByteScanner, io.RuneScanner, and more! It's designed to work in coordination with a BufferPool for recycling, and it's .Close() method puts itself back in the Pool it came from

func NewBuffer

func NewBuffer(home *BufferPool, bytes []byte) *Buffer

NewBuffer returns a Buffer with a proper home. Generally calling BufferPool.Get() is preferable to calling this directly.

func (*Buffer) Bytes

func (r *Buffer) Bytes() []byte

Bytes returns the contents of the buffer, and sets the seek pointer back to the beginning

func (*Buffer) Close

func (r *Buffer) Close() error

Close puts itself back in the Pool it came from. This should absolutely never be called more than once per Buffer life. Implements io.Closer (also io.ReadCloser and io.WriteCloser)

func (*Buffer) Error

func (r *Buffer) Error() string

Error returns the contents of the buffer as a string. Implements “error“

func (*Buffer) ResetFromLimitedReader

func (r *Buffer) ResetFromLimitedReader(reader io.Reader, max int64) error

ResetFromLimitedReader performs a Reset() using the contents of the supplied Reader as the new content, up to at most max bytes, returning ErrTooLarge if it's over. The error is not terminal, and the buffer may continue to be used, understanding the contents will be limited

func (*Buffer) ResetFromReader

func (r *Buffer) ResetFromReader(reader io.Reader)

ResetFromReader performs a Reset() using the contents of the supplied Reader as the new content

func (*Buffer) String

func (r *Buffer) String() string

String returns the contents of the buffer as a string, and sets the seek pointer back to the beginning

func (*Buffer) Write

func (r *Buffer) Write(p []byte) (n int, err error)

Writer adds the bytes the written to the buffer. Implements “io.Writer“

type BufferPool

type BufferPool struct {
    // contains filtered or unexported fields
}

BufferPool is a self-managing pool of Buffers

func NewBufferPool

func NewBufferPool() *BufferPool

NewBufferPool returns an initialized BufferPool

func (*BufferPool) Get

func (p *BufferPool) Get() *Buffer

Get will return an existing Buffer or a new one if the pool is empty. REMEMBER to Reset the Buffer and don't just start using it, as it may very well have old data in it!

func (*BufferPool) Put

func (p *BufferPool) Put(b *Buffer)

Put returns a Buffer to the pool. Generally calling Buffer.Close() is preferable to calling this directly.

---

Generated by godoc2md

Documentation

Overview

Package recyclable provides the recyclable.BufferPool, which is a never-ending font of recyclable.Buffer, a multiuse buffer that very reusable, supports re-reading the contained buffer, and when Close()d, will return home to its BufferPool for reuse.

Example

HOWTO implement a goro-safe BufferPool for Buffers

// BufferPool allows us to have a never-ending font of Buffers.
// If the Pool is empty, a new one is created. If there is one someone put
// back, then it is returned. Saves on allocs like crazy. <3
rPool := NewBufferPool()

// Let's grab a Buffer
rb := rPool.Get()

// And immediately reset the value, as we can't trust it to be empty
rb.Reset([]byte("Hello World"))

// Unlike most buffers, we can re-read it:
for i := 0; i < 10; i++ {
	if string(rb.Bytes()) != "Hello World" {
		panic("OMG! Can't reread?!!!")
	}
}

// Or get the string value, if you prefer (and know it's safe)
for i := 0; i < 10; i++ {
	if rb.String() != "Hello World" {
		panic("OMG! Can't reread?!!!")
	}
}

// Appending to it as an io.Writer works as well
io.WriteString(rb, ", nice day?")
if string(rb.Bytes()) != "Hello World, nice day?" {
	panic("OMG! Append failed?!")
}

// Lastly, when you're all done, just close it.
rb.Close() // and it will go back into the Pool.
// Please don't use it anymore. Get a fresh one.

rb = rPool.Get() // See, not hard?
defer rb.Close() // Just remember to close it, unless you're passing it elsewhere

/* HINTS:
* Makes awesome ``http.Request.Body``s, especially since they get automatically ``.Close()``d when done with
* Replaces ``bytes.Buffer`` and ``bytes.Reader`` for most uses
* Isa Stringer and an error
* As a Writer and a Reader can be used in pipes and elsewhere
  * You can also pipe them to themselves, but that is a very bad idea unless you love watching OOMs
*/

Index

• Variables
• type Buffer
  • func NewBuffer(home *BufferPool, bytes []byte) *Buffer
  • func (r *Buffer) Bytes() []byte
  • func (r *Buffer) Close() error
  • func (r *Buffer) Error() string
  • func (r *Buffer) ResetFromLimitedReader(reader io.Reader, max int64) error
  • func (r *Buffer) ResetFromReader(reader io.Reader)
  • func (r *Buffer) String() string
  • func (r *Buffer) Write(p []byte) (n int, err error)
• type BufferPool
  • func NewBufferPool() *BufferPool
  • func (p *BufferPool) Get() *Buffer
  • func (p *BufferPool) Put(b *Buffer)

Examples

• Package

Variables

var ErrTooLarge = errors.New("read byte count too large")

ErrTooLarge is returned when ResetFromLimitedReader is used and the supplied Reader writes too much

Types

type Buffer

type Buffer struct {
	bytes.Reader
	// contains filtered or unexported fields
}

Buffer is an io.Reader, io.ReadCloser, io.ReaderAt, io.Writer, io.WriteCloser, io.WriterTo, io.Seeker, io.ByteScanner, io.RuneScanner, and more! It's designed to work in coordination with a BufferPool for recycling, and it's `.Close()` method puts itself back in the Pool it came from

func NewBuffer

func NewBuffer(home *BufferPool, bytes []byte) *Buffer

NewBuffer returns a Buffer with a proper home. Generally calling BufferPool.Get() is preferable to calling this directly.

func (*Buffer) Bytes

func (r *Buffer) Bytes() []byte

Bytes returns the contents of the buffer, and sets the seek pointer back to the beginning

func (*Buffer) Close

func (r *Buffer) Close() error

Close puts itself back in the Pool it came from. This should absolutely **never** be called more than once per Buffer life. Implements `io.Closer` (also `io.ReadCloser` and `io.WriteCloser`)

func (*Buffer) Error

func (r *Buffer) Error() string

Error returns the contents of the buffer as a string. Implements “error“

func (*Buffer) ResetFromLimitedReader

func (r *Buffer) ResetFromLimitedReader(reader io.Reader, max int64) error

ResetFromLimitedReader performs a Reset() using the contents of the supplied Reader as the new content, up to at most max bytes, returning ErrTooLarge if it's over. The error is not terminal, and the buffer may continue to be used, understanding the contents will be limited

func (*Buffer) ResetFromReader

func (r *Buffer) ResetFromReader(reader io.Reader)

ResetFromReader performs a Reset() using the contents of the supplied Reader as the new content

func (*Buffer) String

func (r *Buffer) String() string

String returns the contents of the buffer as a string, and sets the seek pointer back to the beginning

func (*Buffer) Write

func (r *Buffer) Write(p []byte) (n int, err error)

Writer adds the bytes the written to the buffer. Implements “io.Writer“

type BufferPool

type BufferPool struct {
	// contains filtered or unexported fields
}

BufferPool is a self-managing pool of Buffers

func NewBufferPool

func NewBufferPool() *BufferPool

NewBufferPool returns an initialized BufferPool

func (*BufferPool) Get

func (p *BufferPool) Get() *Buffer

Get will return an existing Buffer or a new one if the pool is empty. REMEMBER to Reset the Buffer and don't just start using it, as it may very well have old data in it!

func (*BufferPool) Put

func (p *BufferPool) Put(b *Buffer)

Put returns a Buffer to the pool. Generally calling Buffer.Close() is preferable to calling this directly.