progress

README

progress

io.Reader and io.Writer with progress and remaining time estimation.

Usage

ctx := context.Background()

// get a reader and the total expected number of bytes
s := `Now that's what I call progress`
size := len(s)
r := progress.NewReader(strings.NewReader(s))

// Start a goroutine printing progress
go func() {
	ctx := context.Background()
	progressChan := progress.NewTicker(ctx, r, size, 1*time.Second)
	for p := range progressChan {
		fmt.Printf("\r%v remaining...", p.Remaining().Round(time.Second))
	}
	fmt.Println("\rdownload is completed")
}()

// use the Reader as normal
if _, err := io.Copy(dest, r); err != nil {
	log.Fatalln(err)
}

1. Wrap an io.Reader or io.Writer with NewReader and NewWriter respectively
2. Capture the total number of expected bytes
3. Use progress.NewTicker to get a channel on which progress updates will be sent
4. Start a Goroutine to periodically check the progress, and do something with it - like log it
5. Use the readers and writers as normal

Documentation

Overview

Package progress provides io.Reader and io.Writer with progress and remaining time estimation.

ctx := context.Background()

// get a reader and the total expected number of bytes
s := `Now that's what I call progress`
size := len(s)
r := progress.NewReader(strings.NewReader(s))

// Start a goroutine printing progress
go func() {
    ctx := context.Background()
    progressChan := progress.NewTicker(ctx, r, size, 1*time.Second)
    for p := range progressChan {
    	fmt.Printf("\r%v remaining...", p.Remaining().Round(time.Second))
    }
    fmt.Println("\rdownload is completed")
}()

// use the Reader as normal
if _, err := io.Copy(dest, r); err != nil {
	log.Fatalln(err)
}

Index

• func NewTicker(ctx context.Context, counter Counter, size int64, d time.Duration) <-chan Progress
• type Counter
• type Progress
  • func (p Progress) Complete() bool
  • func (p Progress) Estimated() time.Time
  • func (p Progress) N() int64
  • func (p Progress) Percent() float64
  • func (p Progress) Remaining() time.Duration
  • func (p Progress) Size() int64
• type Reader
  • func NewReader(r io.Reader) *Reader
  • func (r *Reader) Err() error
  • func (r *Reader) N() int64
  • func (r *Reader) Read(p []byte) (n int, err error)
• type Writer
  • func NewWriter(w io.Writer) *Writer
  • func (w *Writer) Err() error
  • func (w *Writer) N() int64
  • func (w *Writer) Write(p []byte) (n int, err error)

Functions

func NewTicker

func NewTicker(ctx context.Context, counter Counter, size int64, d time.Duration) <-chan Progress

NewTicker gets a channel on which ticks of Progress are sent at duration d intervals until the operation is complete at which point the channel is closed. The counter is either a Reader or Writer (or any type that can report its progress). The size is the total number of expected bytes being read or written. If the context cancels the operation, the channel is closed.

Types

type Counter

type Counter interface {
	// N gets the current count value.
	// For readers and writers, this is the number of bytes
	// read or written.
	// For other contexts, the number may be anything.
	N() int64
	// Err gets the last error from the Reader or Writer.
	// When the process is finished, this will be io.EOF.
	Err() error
}

Counter counts bytes. Both Reader and Writer are Counter types.

type Progress

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

Progress represents a moment of progress.

func (Progress) Complete

func (p Progress) Complete() bool

Complete gets whether the operation is complete or not. Always returns false if the Size is unknown (-1).

func (Progress) Estimated

func (p Progress) Estimated() time.Time

Estimated gets the time at which the operation is expected to finish. Use Remaining to get a Duration. Estimated().IsZero() is true if no estimate is available.

func (Progress) N

func (p Progress) N() int64

N gets the total number of bytes read or written so far.

func (Progress) Percent

func (p Progress) Percent() float64

Percent calculates the percentage complete.

func (Progress) Remaining

func (p Progress) Remaining() time.Duration

Remaining gets the amount of time until the operation is expected to be finished. Use Estimated to get a fixed completion time. Returns -1 if no estimate is available.

func (Progress) Size

func (p Progress) Size() int64

Size gets the total number of bytes that are expected to be read or written.

type Reader

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

Reader counts the bytes read through it.

func NewReader

func NewReader(r io.Reader) *Reader

NewReader makes a new Reader that counts the bytes read through it.

func (*Reader) Err

func (r *Reader) Err() error

Err gets the last error from the Reader.

func (*Reader) N

func (r *Reader) N() int64

N gets the number of bytes that have been read so far.

func (*Reader) Read

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

type Writer

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

Writer counts the bytes written through it.

func NewWriter

func NewWriter(w io.Writer) *Writer

NewWriter gets a Writer that counts the number of bytes written.

func (*Writer) Err

func (w *Writer) Err() error

Err gets the last error from the Writer.

func (*Writer) N

func (w *Writer) N() int64

N gets the number of bytes that have been written so far.

func (*Writer) Write

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