gatedio

README

Golang GatedIO

The gatedio package provides tiny wrappers around the io.ReadWriter, io.Writer, and io.Reader interfaces to support concurrent usage and access across multiple goroutines.

This library is especially useful in tests where a bytes.Buffer may be used. Go's native bytes.Buffer is not safe across multiple goroutes and therefore must be wrapped in some kind of mutex.

Usage & Examples

API Package documentation can be found on GoDoc.

The gatedio.* functions can replace any io.Reader, io.Writer, or io.ReadWriter. This is especially useful in tests:

func TestSomething(t *testing.T) {
  buf := gatedio.NewBuffer(make(bytes.Buffer))

  go func() { buf.Write([]byte("a")) }()
  go func() { buf.Write([]byte("b")) }()
}

Please note, accessing the underlying data structure is still not safe across multiple goroutines without locking:

// This is not safe!
var b bytes.Buffer
buf := gatedio.NewBuffer(&b)

go func() { buf.Write([]byte("a")) }()

// This is still a race condition:
b.Len() // or b.Anything()

For these cases, it is better to use the GatedBytesBuffer:

buf := gatedio.BytesBuffer()

This implements all functions of a bytes.Buffer, but wraps all calls in a mutex for safe concurrent access.

Developing

To install, clone from GitHub:

$ git clone https://github.com/hashicorp/go-gatedio

Then install dependencies:

$ make updatedeps

Then test;

$ make test testrace

Documentation

Overview

gatedio provides wrappers around the io.ReadWriter, io.Writer, and io.Reader interfaces to support concurrent usage and access across multiple goroutines.

Index

• type Buffer
  • func NewBuffer(rw io.ReadWriter) *Buffer
  • func (gb *Buffer) Read(p []byte) (int, error)
  • func (gb *Buffer) Write(p []byte) (int, error)
• type ByteBuffer
  • func NewByteBuffer() *ByteBuffer
  • func (b *ByteBuffer) Bytes() []byte
  • func (b *ByteBuffer) Cap() int
  • func (b *ByteBuffer) Grow(n int)
  • func (b *ByteBuffer) Len() int
  • func (b *ByteBuffer) Next(n int) []byte
  • func (b *ByteBuffer) Read(p []byte) (int, error)
  • func (b *ByteBuffer) ReadByte() (byte, error)
  • func (b *ByteBuffer) ReadBytes(delim byte) ([]byte, error)
  • func (b *ByteBuffer) ReadFrom(r io.Reader) (int64, error)
  • func (b *ByteBuffer) ReadRune() (rune, int, error)
  • func (b *ByteBuffer) ReadString(delim byte) (string, error)
  • func (b *ByteBuffer) Reset()
  • func (b *ByteBuffer) String() string
  • func (b *ByteBuffer) Truncate(n int)
  • func (b *ByteBuffer) UnreadByte() error
  • func (b *ByteBuffer) UnreadRune() error
  • func (b *ByteBuffer) Write(p []byte) (int, error)
  • func (b *ByteBuffer) WriteByte(c byte) error
  • func (b *ByteBuffer) WriteRune(r rune) (int, error)
  • func (b *ByteBuffer) WriteString(s string) (int, error)
  • func (b *ByteBuffer) WriteTo(w io.Writer) (int64, error)
• type Reader
  • func NewReader(r io.Reader) *Reader
  • func (r *Reader) Read(p []byte) (int, error)
• type Writer
  • func NewWriter(w io.Writer) *Writer
  • func (w *Writer) Write(p []byte) (int, error)

Types

type Buffer

type Buffer struct {
	sync.Mutex
	// contains filtered or unexported fields
}

Buffer implements io.ReadWriter which can be passed to multiple concurrent goroutines. Buffer buffers all reads and writes using an internal mutex so that reading and writing to the buffer is safe.

func NewBuffer

func NewBuffer(rw io.ReadWriter) *Buffer

NewBuffer creates a new buffered io.ReadWriter.

func (*Buffer) Read

func (gb *Buffer) Read(p []byte) (int, error)

Read implements the io.Reader interface.

func (*Buffer) Write

func (gb *Buffer) Write(p []byte) (int, error)

Write implements the io.Writer interface.

type ByteBuffer

type ByteBuffer struct {
	sync.Mutex
	// contains filtered or unexported fields
}

ByteBuffer is a wrapper around a bytes.Buffer.

func NewByteBuffer

func NewByteBuffer() *ByteBuffer

NewByteBuffer returns a wrapper around a bytes.Buffer that is safe to use across concurrent goroutines.

func (*ByteBuffer) Bytes

func (b *ByteBuffer) Bytes() []byte

Bytes wraps a mutex around the underlying bytes.Buffer function call.

func (*ByteBuffer) Cap

func (b *ByteBuffer) Cap() int

Cap wraps a mutex around the underlying bytes.Buffer function call.

func (*ByteBuffer) Grow

func (b *ByteBuffer) Grow(n int)

Grow wraps a mutex around the underlying bytes.Buffer function call.

func (*ByteBuffer) Len

func (b *ByteBuffer) Len() int

Len wraps a mutex around the underlying bytes.Buffer function call.

func (*ByteBuffer) Next

func (b *ByteBuffer) Next(n int) []byte

Next wraps a mutex around the underlying bytes.Buffer function call.

func (*ByteBuffer) Read

func (b *ByteBuffer) Read(p []byte) (int, error)

Read wraps a mutex around the underlying bytes.Buffer function call.

func (*ByteBuffer) ReadByte

func (b *ByteBuffer) ReadByte() (byte, error)

ReadByte wraps a mutex around the underlying bytes.Buffer function call.

func (*ByteBuffer) ReadBytes

func (b *ByteBuffer) ReadBytes(delim byte) ([]byte, error)

ReadBytes wraps a mutex around the underlying bytes.Buffer function call.

func (*ByteBuffer) ReadFrom

func (b *ByteBuffer) ReadFrom(r io.Reader) (int64, error)

ReadFrom wraps a mutex around the underlying bytes.Buffer function call.

func (*ByteBuffer) ReadRune

func (b *ByteBuffer) ReadRune() (rune, int, error)

ReadRune wraps a mutex around the underlying bytes.Buffer function call.

func (*ByteBuffer) ReadString

func (b *ByteBuffer) ReadString(delim byte) (string, error)

ReadString wraps a mutex around the underlying bytes.Buffer function call.

func (*ByteBuffer) Reset

func (b *ByteBuffer) Reset()

Reset wraps a mutex around the underlying bytes.Buffer function call.

func (*ByteBuffer) String

func (b *ByteBuffer) String() string

String wraps a mutex around the underlying bytes.Buffer function call.

func (*ByteBuffer) Truncate

func (b *ByteBuffer) Truncate(n int)

Truncate wraps a mutex around the underlying bytes.Buffer function call.

func (*ByteBuffer) UnreadByte

func (b *ByteBuffer) UnreadByte() error

UnreadByte wraps a mutex around the underlying bytes.Buffer function call.

func (*ByteBuffer) UnreadRune

func (b *ByteBuffer) UnreadRune() error

UnreadRune wraps a mutex around the underlying bytes.Buffer function call.

func (*ByteBuffer) Write

func (b *ByteBuffer) Write(p []byte) (int, error)

Write wraps a mutex around the underlying bytes.Buffer function call.

func (*ByteBuffer) WriteByte

func (b *ByteBuffer) WriteByte(c byte) error

WriteByte wraps a mutex around the underlying bytes.Buffer function call.

func (*ByteBuffer) WriteRune

func (b *ByteBuffer) WriteRune(r rune) (int, error)

WriteRune wraps a mutex around the underlying bytes.Buffer function call.

func (*ByteBuffer) WriteString

func (b *ByteBuffer) WriteString(s string) (int, error)

WriteString wraps a mutex around the underlying bytes.Buffer function call.

func (*ByteBuffer) WriteTo

func (b *ByteBuffer) WriteTo(w io.Writer) (int64, error)

WriteTo wraps a mutex around the underlying bytes.Buffer function call.

type Reader

type Reader struct {
	sync.Mutex
	// contains filtered or unexported fields
}

Reader implements io.Reader which can be passed to multiple concurrent goroutines. Reader buffers all reads using an internal mutex so that reading from the buffer is safe.

func NewReader

func NewReader(r io.Reader) *Reader

NewReader creates a new buffered io.Reader.

func (*Reader) Read

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

Read implements the io.Reader interface.

type Writer

type Writer struct {
	sync.Mutex
	// contains filtered or unexported fields
}

Writer implements io.Writer which can be passed to multiple concurrent goroutines. Writer buffers all writes using an internal mutex so that writing to the buffer is safe.

func NewWriter

func NewWriter(w io.Writer) *Writer

NewWriter creates a new buffered io.Writer.

func (*Writer) Write

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

Write implements the io.Writer interface.