bufpipe

README

bufpipe

Simple golang implementation of the buffered io.Pipe replacement

Usage

package main

import (
    "fmt"
    "io"
    "os"
    "time"

    "github.com/illarion/bufpipe/v3"
)

func main() {
    // Create a new buffered pipe
    reader, writer := bufpipe.Pipe(bufpipe.Options{
        MaxSize: 1024,
        BlockWritesUntilFirstReadTimeout: time.Second * 5,
		BlockWritesOnFullBufferTimeout: time.Second * 5,
    })

    // Start a goroutine that writes to the pipe
    go func() {
        defer writer.Close()
        for i := 0; i < 10; i++ {
            fmt.Fprintf(writer, "Hello, world! %d\n", i)
            time.Sleep(time.Second)
        }
    }()

    // Read from the pipe
    io.Copy(os.Stdout, reader)
}

Options

• MaxSize - the maximum size of the buffer in bytes. Default is 0 - no limit.
• BlockWritesUntilFirstReadTimeout - if set, the writer will block until the first read from the reader or the timeout is reached. Default is 0 - no blocking, write immediately.
• BlockWritesOnFullBufferTimeout - if set, the writer will block until the buffer is not full or the timeout is reached. Default is 0 - immediately return ErrBufferFull if the buffer is full.

Errors

ErrBufferFull - returned when reader is slower than writer and there is no place to write ErrClosedPipe - returned if either reader or writer side is closed. ErrFirstReadTimeout - returned if the BlockWritesUntilFirstReadTimeout is reached.

License

See the LICENSE file for license rights and limitations (MIT).

Documentation

Index

• Variables
• func Pipe(options Options) (PipeReader, PipeWriter)
• type Options
• type PipeReader
• type PipeWriter

Variables

var (
	// ErrBufferFull is returned when the buffer is full
	ErrBufferFull = errors.New("bufpipe: buffer is full")
	// ErrClosedPipe is returned when the pipe is closed
	ErrClosedPipe = errors.New("bufpipe: closed pipe")
	// ErrFirstReadTimeout is returned when the pipe is set to block writes until the first read, but the timeout is reached
	ErrFirstReadTimeout = errors.New("bufpipe: write blocked because first read didn't happen until timeout")
)

Functions

func Pipe

func Pipe(options Options) (PipeReader, PipeWriter)

Pipe creates a buffered in-memory pipe. It can be used to connect code expecting an io.Reader with code expecting an io.Writer, but unlike io.Pipe it has internal buffer and can be used to pass data between goroutines without blocking.

Types

type Options

type Options struct {
	// MaxSize is the maximum size of the buffer. Write will return ErrBufferFull
	// if the buffer is full. If MaxSize is 0, buffer is unlimited. Default is 0.
	MaxSize int
	// BlockWritesUntilFirstReadTimeout if set to a non-zero value, Write will block until the first Read is called. This is useful
	// if you want to make sure that the reader is ready to read before writing to the pipe. Default is false.
	BlockWritesUntilFirstReadTimeout time.Duration
	// BlockWritesOnFullBufferTimeout if set to a non-zero value, Write will block until the buffer is emptied by some Read() calls.
	// This is useful if you want to make sure that the reader has read some data before writing more. Default is no timeout - return ErrBufferFull immediately.
	// Only works if MaxSize is set to a non-zero value. If the timeout is reached, Write will return ErrBufferFull
	BlockWritesOnFullBufferTimeout time.Duration
}

type PipeReader

type PipeReader interface {
	io.Reader
	io.Closer
}

type PipeWriter

type PipeWriter interface {
	io.Writer
	io.Closer
	Len() int
}