bufpipe

README

bufpipe: Buffered Pipe

The buffered version of io.Pipe. It's safe for concurrent use.

How does it differ from io.Pipe?

Writes never block because the pipe has variable-sized buffer.

r, w := bufpipe.New(nil)
io.WriteString(w, "abc") // No blocking.
io.WriteString(w, "def") // No blocking, too.
w.Close()
io.Copy(os.Stdout, r)
// Output: abcdef

Playground

How does it differ from bytes.Buffer?

Reads block if the internal buffer is empty until the writer is closed.

r, w := bufpipe.New(nil)

done := make(chan struct{})
go func() {
	io.Copy(os.Stdout, r) // The reads block until the writer is closed.
	done <- struct{}{}
}()

io.WriteString(w, "abc")
io.WriteString(w, "def")
w.Close()
<-done
// Output: abcdef

Playground

Contribution

Generate CREDITS

The CREDITS file are generated by gocredits. Update it when the dependencies are changed.

$ gocredits > CREDITS

Documentation

Overview

Package bufpipe provides a IO pipe, has variable-sized buffer.

Example

package main

import (
	"io"
	"os"

	"github.com/acomagu/bufpipe"
)

func main() {
	r, w := bufpipe.New(nil)

	done := make(chan struct{})
	go func() {
		io.Copy(os.Stdout, r)
		done <- struct{}{}
	}()

	io.WriteString(w, "abc")
	io.WriteString(w, "def")
	w.Close()
	<-done
}

Output:

abcdef

Index

• Variables
• func New(buf []byte) (*PipeReader, *PipeWriter)
• type PipeReader
  • func (r *PipeReader) Close() error
  • func (r *PipeReader) CloseWithError(err error) error
  • func (r *PipeReader) Read(data []byte) (int, error)
• type PipeWriter
  • func (w *PipeWriter) Close() error
  • func (w *PipeWriter) CloseWithError(err error) error
  • func (w *PipeWriter) Write(data []byte) (int, error)

Examples

• Package

Variables

var ErrClosedPipe = errors.New("bufpipe: read/write on closed pipe")

ErrClosedPipe is the error used for read or write operations on a closed pipe.

Functions

func New

func New(buf []byte) (*PipeReader, *PipeWriter)

New creates a synchronous pipe using buf as its initial contents. It can be used to connect code expecting an io.Reader with code expecting an io.Writer.

Unlike io.Pipe, writes never block because the internal buffer has variable size. Reads block only when the buffer is empty.

It is safe to call Read and Write in parallel with each other or with Close. Parallel calls to Read and parallel calls to Write are also safe: the individual calls will be gated sequentially.

The new pipe takes ownership of buf, and the caller should not use buf after this call. New is intended to prepare a PipeReader to read existing data. It can also be used to set the initial size of the internal buffer for writing. To do that, buf should have the desired capacity but a length of zero.

Types

type PipeReader

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

A PipeReader is the read half of a pipe.

func (*PipeReader) Close

func (r *PipeReader) Close() error

Close closes the reader; subsequent writes from the write half of the pipe will return error ErrClosedPipe.

func (*PipeReader) CloseWithError

func (r *PipeReader) CloseWithError(err error) error

CloseWithError closes the reader; subsequent writes to the write half of the pipe will return the error err.

func (*PipeReader) Read

func (r *PipeReader) Read(data []byte) (int, error)

Read implements the standard Read interface: it reads data from the pipe, reading from the internal buffer, otherwise blocking until a writer arrives or the write end is closed. If the write end is closed with an error, that error is returned as err; otherwise err is io.EOF.

type PipeWriter

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

A PipeWriter is the write half of a pipe.

func (*PipeWriter) Close

func (w *PipeWriter) Close() error

Close closes the writer; subsequent reads from the read half of the pipe will return io.EOF once the internal buffer get empty.

func (*PipeWriter) CloseWithError

func (w *PipeWriter) CloseWithError(err error) error

Close closes the writer; subsequent reads from the read half of the pipe will return err once the internal buffer get empty.

func (*PipeWriter) Write

func (w *PipeWriter) Write(data []byte) (int, error)

Write implements the standard Write interface: it writes data to the internal buffer. If the read end is closed with an error, that err is returned as err; otherwise err is ErrClosedPipe.