progress

Documentation

Overview

Package progress exposes utilities to asynchronously monitor and display processing progress.

Package progress exposes utilities to asynchronously monitor and display processing progress.

Index

• Constants
• type Bar
  • func (pb *Bar) Start()
  • func (pb *Bar) Stop()
• type BarWriter
  • func NewBarWriter(w io.Writer, waitTime time.Duration, barLength int, isBytes bool) *BarWriter
  • func (manager *BarWriter) Attach(name string, progressor Progressor)
  • func (manager *BarWriter) Detach(name string)
  • func (manager *BarWriter) Start()
  • func (manager *BarWriter) Stop()
• type CountProgressor
  • func NewCounter(max int64) *CountProgressor
  • func (c *CountProgressor) Inc(amount int64)
  • func (c *CountProgressor) Progress() (int64, int64)
  • func (c *CountProgressor) Set(amount int64)
• type Manager
• type Progressor
• type Updateable

Constants

const (
	DefaultWaitTime = 3 * time.Second
	BarFilling      = "#"
	BarEmpty        = "."
	BarLeft         = "["
	BarRight        = "]"
)

const GridPadding = 2

Types

type Bar

type Bar struct {
	// Name is an identifier printed along with the bar
	Name string
	// BarLength is the number of characters used to print the bar
	BarLength int

	// IsBytes denotes whether byte-specific formatting (kB, MB, GB) should
	// be applied to the numeric output
	IsBytes bool

	// Watching is the object that implements the Progressor to expose the
	// values necessary for calculation
	Watching Progressor

	// Writer is where the Bar is written out to
	Writer io.Writer
	// WaitTime is the time to wait between writing the bar
	WaitTime time.Duration
	// contains filtered or unexported fields
}

Bar is a tool for concurrently monitoring the progress of a task with a simple linear ASCII visualization

func (*Bar) Start

func (pb *Bar) Start()

Start starts the Bar goroutine. Once Start is called, a bar will be written to the given Writer at regular intervals. The goroutine can only be stopped manually using the Stop() method. The Bar must be set up before calling this. Panics if Start has already been called.

func (*Bar) Stop

func (pb *Bar) Stop()

Stop kills the Bar goroutine, stopping it from writing. Generally called as

myBar.Start()
defer myBar.Stop()

to stop leakage Stop() needs to be synchronous in order that when pb.Stop() is called all of the rendering has completed

type BarWriter

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

BarWriter implements Manager. It periodically prints the status of all of its progressors in the form of pretty progress bars. It handles thread-safe synchronized progress bar writing, so that its progressors are written in a group at a given interval. It maintains insertion order when printing, such that new bars appear at the bottom of the group.

func NewBarWriter

func NewBarWriter(w io.Writer, waitTime time.Duration, barLength int, isBytes bool) *BarWriter

NewBarWriter returns an initialized BarWriter with the given bar length and byte-formatting toggle, waiting the given duration between writes

func (*BarWriter) Attach

func (manager *BarWriter) Attach(name string, progressor Progressor)

Attach registers the given progressor with the manager

func (*BarWriter) Detach

func (manager *BarWriter) Detach(name string)

Detach removes the progressor with the given name from the manager. Insert order is maintained for consistent ordering of the printed bars.

func (*BarWriter) Start

func (manager *BarWriter) Start()

Start kicks of the timed batch writing of progress bars.

func (*BarWriter) Stop

func (manager *BarWriter) Stop()

Stop ends the main manager goroutine, stopping the manager's bars from being rendered.

type CountProgressor

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

CountProgressor is an implementation of Progressor that uses

func NewCounter

func NewCounter(max int64) *CountProgressor

NewCounter constructs a CountProgressor with a given maximum count.

func (*CountProgressor) Inc

func (c *CountProgressor) Inc(amount int64)

Inc atomically increments the counter by the given amount.

func (*CountProgressor) Progress

func (c *CountProgressor) Progress() (int64, int64)

Progress returns the current and maximum values of the counter.

func (*CountProgressor) Set

func (c *CountProgressor) Set(amount int64)

Set atomically sets the counter to a given number.

type Manager

type Manager interface {
	// Attach registers the progressor with the manager under the given name.
	// Any call to Attach must have a matching call to Detach.
	Attach(name string, progressor Progressor)

	// Detach removes the progressor with the given name from the manager
	Detach(name string)
}

Manager is an interface which tools can use to registers progressors which track the progress of any arbitrary operation.

type Progressor

type Progressor interface {
	// Progress returns a pair of integers: the amount completed and the total
	// amount to reach 100%. This method is called by progress.Bar to determine
	// what percentage to display.
	Progress() (current, max int64)
}

Progressor can be implemented to allow an object to hook up to a progress.Bar.

type Updateable

type Updateable interface {
	Progressor

	// Inc increments the current progress counter by the given amount.
	Inc(amount int64)

	// Set sets the progress counter to the given amount.
	Set(amount int64)
}

Updateable is a Progressor which also exposes the ability for the progressing value to be updated.