README

progress GoDoc Build Status Go Report Card

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
Expand ▾ Collapse ▴

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

    Constants

    This section is empty.

    Variables

    This section is empty.

    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)

                                      Directories

                                      Path Synopsis
                                      example