package pool

Import Path
	github.com/libp2p/go-buffer-pool (on go.dev)

Dependency Relation
	imports 5 packages, and imported by 11 packages

Involved Source Files

	    buffer.go
	  d pool.go
		Package pool provides a sync.Pool equivalent that buckets incoming
		requests to one of 32 sub-pools, one for each power of 2, 0-32.
		
			import (pool "github.com/libp2p/go-buffer-pool")
			var p pool.BufferPool
		
			small := make([]byte, 1024)
			large := make([]byte, 4194304)
			p.Put(small)
			p.Put(large)
		
			small2 := p.Get(1024)
			large2 := p.Get(4194304)
			fmt.Println("small2 len:", len(small2))
			fmt.Println("large2 len:", len(large2))
		
			// Output:
			// small2 len: 1024
			// large2 len: 4194304

	    writer.go
Package-Level Type Names (total 3)

	/* sort by: alphabet | popularity */
	 type Buffer (struct)
		Buffer is a buffer like bytes.Buffer that:
		
		1. Uses a buffer pool.
		2. Frees memory on read.
		
		If you only have a few buffers and read/write at a steady rate, *don't* use
		this package, it'll be slower.
		
		However:
		
		1. If you frequently create/destroy buffers, this implementation will be
		   significantly nicer to the allocator.
		2. If you have many buffers with bursty traffic, this implementation will use
		   significantly less memory.

		Fields (only one)
			Pool *BufferPool
				Pool is the buffer pool to use. If nil, this Buffer will use the
				global buffer pool.

		Methods (total 15)
			(*Buffer) Bytes() []byte
				Bytes returns the slice of bytes currently buffered in the Buffer.
				
				The buffer returned by Bytes is valid until the next call grow, truncate,
				read, or write. Really, just don't touch the Buffer until you're done with
				the return value of this function.

			(*Buffer) Cap() int
				Cap returns the current capacity of the buffer.
				
				Note: Buffer *may* re-allocate when writing (or growing by) `n` bytes even if
				`Cap() < Len() + n` to avoid excessive copying.

			(*Buffer) Grow(n int)
				Grow grows the internal buffer such that `n` bytes can be written without
				reallocating.

			(*Buffer) Len() int
				Len returns the number of bytes that can be read from this buffer.

			(*Buffer) Next(n int) []byte
				Next is an alternative to `Read` that returns a byte slice instead of taking
				one.
				
				The returned byte slice is valid until the next read, write, grow, or
				truncate.

			(*Buffer) Read(buf []byte) (int, error)
				Read reads at most `len(buf)` bytes from the internal buffer into the given
				buffer.

			(*Buffer) ReadByte() (byte, error)
				ReadByte reads a single byte from the Buffer.

			(*Buffer) ReadFrom(r io.Reader) (int64, error)
				ReadFrom reads from the given reader into the buffer.

			(*Buffer) Reset()
				Reset is equivalent to Truncate(0).

			(*Buffer) String() string
				String returns the string representation of the buffer.
				
				It returns `<nil>` the buffer is a nil pointer.

			(*Buffer) Truncate(n int)
				Truncate truncates the Buffer.
				
				Panics if `n > b.Len()`.
				
				This function may free memory by shrinking the internal buffer.

			(*Buffer) Write(buf []byte) (int, error)
				Write writes the byte slice to the buffer.

			(*Buffer) WriteByte(c byte) error
				WriteByte writes a single byte to the Buffer.

			(*Buffer) WriteString(buf string) (int, error)
				WriteString writes a string to the buffer.
				
				This function is identical to Write except that it allows one to write a
				string directly without allocating an intermediate byte slice.

			(*Buffer) WriteTo(w io.Writer) (int64, error)
				WriteTo copies from the buffer into the given writer until the buffer is
				empty.

		Implements (at least 20)
			*Buffer : github.com/apache/arrow-go/v18/internal/hashing.ByteSlice
			*Buffer : github.com/gobwas/ws.HandshakeHeader
			*Buffer : github.com/klauspost/compress/flate.Reader
			*Buffer : github.com/miekg/dns.Writer
			*Buffer : github.com/quic-go/quic-go/quicvarint.Reader
			*Buffer : github.com/quic-go/quic-go/quicvarint.Writer
			*Buffer : compress/flate.Reader
			*Buffer : expvar.Var
			*Buffer : fmt.Stringer
			*Buffer : google.golang.org/protobuf/encoding/protodelim.Reader
			*Buffer : gorm.io/gorm/clause.Writer
			*Buffer : internal/bisect.Writer
			*Buffer : io.ByteReader
			*Buffer : io.ByteWriter
			*Buffer : io.Reader
			*Buffer : io.ReaderFrom
			*Buffer : io.ReadWriter
			*Buffer : io.StringWriter
			*Buffer : io.Writer
			*Buffer : io.WriterTo
		As Outputs Of (at least 2)
			func NewBuffer(buf []byte) *Buffer
			func NewBufferString(buf string) *Buffer

	 type BufferPool (struct)
		BufferPool is a pool to handle cases of reusing elements of varying sizes. It
		maintains 32 internal pools, for each power of 2 in 0-32.
		
		You should generally just call the package level Get and Put methods or use
		the GlobalPool BufferPool instead of constructing your own.
		
		You MUST NOT copy Pool after using.

		Methods (total 2)
			(*BufferPool) Get(length int) []byte
				Get retrieves a buffer of the appropriate length from the buffer pool or
				allocates a new one. Get may choose to ignore the pool and treat it as empty.
				Callers should not assume any relation between values passed to Put and the
				values returned by Get.
				
				If no suitable buffer exists in the pool, Get creates one.

			(*BufferPool) Put(buf []byte)
				Put adds x to the pool.

		As Inputs Of (at least 6)
			func github.com/libp2p/go-msgio.NewReaderSizeWithPool(r io.Reader, maxMessageSize int, p *BufferPool) msgio.ReadCloser
			func github.com/libp2p/go-msgio.NewReaderWithPool(r io.Reader, p *BufferPool) msgio.ReadCloser
			func github.com/libp2p/go-msgio.NewVarintReaderSizeWithPool(r io.Reader, maxMessageSize int, p *BufferPool) msgio.ReadCloser
			func github.com/libp2p/go-msgio.NewVarintReaderWithPool(r io.Reader, p *BufferPool) msgio.ReadCloser
			func github.com/libp2p/go-msgio.NewVarintWriterWithPool(w io.Writer, p *BufferPool) msgio.WriteCloser
			func github.com/libp2p/go-msgio.NewWriterWithPool(w io.Writer, p *BufferPool) msgio.WriteCloser
		As Types Of (only one)
			  var GlobalPool *BufferPool

	 type Writer (struct)
		Writer is a buffered writer that returns its internal buffer in a pool when
		not in use.

		Fields (only one)
			W io.Writer
		Methods (total 9)
			(*Writer) Available() int
				Available returns the amount buffer space available.

			(*Writer) Buffered() int
				Buffered returns the amount of data buffered.

			(*Writer) Close() error
				Close flushes the underlying writer and closes it if it implements the
				io.Closer interface.
				
				Note: Close() closes the writer even if Flush() fails to avoid leaking system
				resources. If you want to make sure Flush() succeeds, call it first.

			(*Writer) Flush() error
				Flush flushes the write buffer, if any, and returns it to the pool.

			(*Writer) Size() int
				Size returns the size of the underlying buffer.

			(*Writer) Write(b []byte) (int, error)
				Write writes the given byte slice to the underlying connection.
				
				Note: Write won't return the write buffer to the pool even if it ends up
				being empty after the write. You must call Flush() to do that.

			(*Writer) WriteByte(b byte) error
				WriteByte writes a single byte.

			(*Writer) WriteRune(r rune) (int, error)
				WriteRune writes a single rune, returning the number of bytes written.

			(*Writer) WriteString(s string) (int, error)
				WriteString writes a string, returning the number of bytes written.

		Implements (at least 13)
			*Writer : github.com/apache/thrift/lib/go/thrift.Flusher
			*Writer : github.com/gogo/protobuf/proto.Sizer
			*Writer : github.com/miekg/dns.Writer
			*Writer : github.com/prometheus/common/expfmt.Closer
			*Writer : github.com/quic-go/quic-go/quicvarint.Writer
			*Writer : github.com/yuin/goldmark/util.BufWriter
			*Writer : gorm.io/gorm/clause.Writer
			*Writer : internal/bisect.Writer
			*Writer : io.ByteWriter
			*Writer : io.Closer
			*Writer : io.StringWriter
			*Writer : io.WriteCloser
			*Writer : io.Writer


Package-Level Functions (total 4)

	 func Get(length int) []byte
		Get retrieves a buffer of the appropriate length from the global buffer pool
		(or allocates a new one).

	 func NewBuffer(buf []byte) *Buffer
		NewBuffer constructs a new buffer initialized to `buf`.
		Unlike `bytes.Buffer`, we *copy* the buffer but don't reuse it (to ensure
		that we *only* use buffers from the pool).

	 func NewBufferString(buf string) *Buffer
		NewBufferString is identical to NewBuffer *except* that it allows one to
		initialize the buffer from a string (without having to allocate an
		intermediate bytes slice).

	 func Put(slice []byte)
		Put returns a buffer to the global buffer pool.


Package-Level Variables (only one)

	  var GlobalPool *BufferPool
		GlobalPool is a static Pool for reusing byteslices of various sizes.


Package-Level Constants (total 3)

	const MaxLength = 2147483647
		MaxLength is the maximum length of an element that can be added to the Pool.

	const MinRead = 512
		MinRead is the minimum slice size passed to a Read call by
		Buffer.ReadFrom. As long as the Buffer has at least MinRead bytes beyond
		what is required to hold the contents of r, ReadFrom will not grow the
		underlying buffer.

	const WriterBufferSize = 4096

The pages are generated with Golds v0.8.2. (GOOS=linux GOARCH=amd64)
Golds is a Go 101 project developed by Tapir Liu.
PR and bug reports are welcome and can be submitted to the issue list.
Please follow @zigo_101 (reachable from the left QR code) to get the latest news of Golds.