progress

Documentation

Overview

Package progress provides support for displaying the progress of one or more operations. It also provides logging capabilities.

The core part of this package is the Tracker interface which is a combination of the Logger and Spinner interfaces. A Tracker allows for display progress and logging messages while one or more operations are being performed. Some convenience Tracker types are provided to make it easier to create Trackers. This package does not provide a Logger or Spinner implementation directly. Instead types implementing these interfaces can be provided by other packages and composed as necessary.

This package also provides the Run and RunParallel functions with allow running a single operation or multiple operations respectively while displaying progress and handling errors, cancellation, and timeouts.

Index

• func ContextWithTracker(ctx context.Context, t Tracker) context.Context
• func ContextWithTrackerUsingKey(ctx context.Context, t Tracker, key any) context.Context
• func DefaultConcurrency() int
• func Run(ctx context.Context, opts RunOptions, fn RunFunc) error
• func RunParallel(ctx context.Context, opts RunParallelOptions, fn RunParallelFunc) error
• func RunParallelT[T any](ctx context.Context, opts RunParallelOptions, fn RunParallelFuncT[T]) ([]T, error)
• func RunT[T any](ctx context.Context, opts RunOptions, fn RunFuncT[T]) (T, error)
• type Logger
• type NoopTracker
  • func (NoopTracker) Debug(string, ...any)
  • func (NoopTracker) Debugf(string, ...any)
  • func (NoopTracker) Error(string, ...any)
  • func (NoopTracker) Errorf(string, ...any)
  • func (NoopTracker) Inc()
  • func (NoopTracker) Info(string, ...any)
  • func (NoopTracker) Infof(string, ...any)
  • func (NoopTracker) Start(string, int)
  • func (NoopTracker) Stop()
  • func (NoopTracker) UpdateMessage(string)
  • func (NoopTracker) Warn(string, ...any)
  • func (NoopTracker) Warnf(string, ...any)
  • func (t NoopTracker) WithAttrs(...any) Logger
• type RunFunc
• type RunFuncT
• type RunOptions
• type RunParallelFunc
• type RunParallelFuncT
• type RunParallelOptions
• type Spinner
• type Tracker
  • func TrackerFromContext(ctx context.Context) Tracker
  • func TrackerFromContextUsingKey(ctx context.Context, key any) Tracker

Functions

func ContextWithTracker

func ContextWithTracker(ctx context.Context, t Tracker) context.Context

ContextWithTracker returns a new context with t added to it. The tracker can be retrieved later using TrackerFromContext.

func ContextWithTrackerUsingKey

func ContextWithTrackerUsingKey(ctx context.Context, t Tracker, key any) context.Context

ContextWithTrackerUsingKey is like ContextWithTracker but allows for using a custom key. This can be useful if you want to avoid using the default key to prevent clashes. The tracker can be retrieved later using TrackerFromContextUsingKey.

func DefaultConcurrency

func DefaultConcurrency() int

DefaultConcurrency returns default concurrency that should be used for parallel operations by using runtime.NumCPU.

func Run

func Run(ctx context.Context, opts RunOptions, fn RunFunc) error

Run runs fn. If ctx contains a Tracker, it will be used to display progress.

opts can be used to customize the behaviour of Run. See each option for more details.

func RunParallel

func RunParallel(ctx context.Context, opts RunParallelOptions, fn RunParallelFunc) error

RunParallel runs fn multiple times concurrently. If ctx contains a Tracker, it will be used to display progress. Each call to fn will happen in a separate goroutine. RunParallel will block until all calls to fn have returned.

opts can be used to customize the behaviour of RunParallel. See each option for more details.

func RunParallelT

func RunParallelT[T any](ctx context.Context, opts RunParallelOptions, fn RunParallelFuncT[T]) ([]T, error)

RunParallelT is like RunParallel but returns a slice containing all the return values from each run fn. The slice will be sorted based on the order the functions were called.

func RunT

func RunT[T any](ctx context.Context, opts RunOptions, fn RunFuncT[T]) (T, error)

RunT is like Run but returns a value.

Types

type Logger

type Logger interface {
	WithAttrs(args ...any) Logger

	Debugf(format string, args ...any)
	Infof(format string, args ...any)
	Warnf(format string, args ...any)
	Errorf(format string, args ...any)

	Debug(msg string, args ...any)
	Info(msg string, args ...any)
	Warn(msg string, args ...any)
	Error(msg string, args ...any)
}

Logger represents a structured logger that can log messages at different levels.

A logger should support the log levels of debug, info, warn, and error. These are implemented through the corresponding methods.

The WithAttrs method is used to create structured logs. It must return another Logger that will contain the given attributes when a creating logs. The arguments to WithAttrs are expected to be a set of key-pair values representing attributes.

logger.WithAttrs("id", id).Info(...)

type NoopTracker

type NoopTracker struct{}

NoopTracker is a Tracker that no-ops on every method.

func (NoopTracker) Debug

func (NoopTracker) Debug(string, ...any)

func (NoopTracker) Debugf

func (NoopTracker) Debugf(string, ...any)

func (NoopTracker) Error

func (NoopTracker) Error(string, ...any)

func (NoopTracker) Errorf

func (NoopTracker) Errorf(string, ...any)

func (NoopTracker) Inc

func (NoopTracker) Inc()

func (NoopTracker) Info

func (NoopTracker) Info(string, ...any)

func (NoopTracker) Infof

func (NoopTracker) Infof(string, ...any)

func (NoopTracker) Start

func (NoopTracker) Start(string, int)

func (NoopTracker) Stop

func (NoopTracker) Stop()

func (NoopTracker) UpdateMessage

func (NoopTracker) UpdateMessage(string)

func (NoopTracker) Warn

func (NoopTracker) Warn(string, ...any)

func (NoopTracker) Warnf

func (NoopTracker) Warnf(string, ...any)

func (NoopTracker) WithAttrs

func (t NoopTracker) WithAttrs(...any) Logger

type RunFunc

type RunFunc func(ctx context.Context) error

RunFunc is a function run by Run. ctx should be passed to any operations that take a Context to ensure that timeouts and cancellations are propagated.

type RunFuncT

type RunFuncT[T any] func(ctx context.Context) (T, error)

RunFuncT is like RunFunc but allows returning a value.

type RunOptions

type RunOptions struct {
	// Message is the message that will be passed to Tracker.Start.
	// If omitted no message will be written by the Tracker.
	Message string
	// Count is the count passed to Tracker.Start to track the number of operations.
	// Run will not automatically increment the progress count, instead it is
	// up to the RunFunc to call Tracker.Inc.
	// If omitted it will be 0, i.e. no count.
	Count int
	// Timeout sets a timeout after which the running function will be cancelled.
	// Defaults to 10min if omitted.
	Timeout time.Duration
	// TrackerKey can be used to specify a custom context key for retrieving a Tracker.
	// This should be used if ContextWithTrackerUsingKey was used.
	// If omitted, the default key will be used.
	TrackerKey any
}

RunOptions is used to customize how Run behaves. All fields are optional and have defaults.

type RunParallelFunc

type RunParallelFunc func(ctx context.Context, i int) error

RunParallelFunc is a function run by RunParallel. ctx should be passed to any operations that take a Context to ensure that timeouts and cancellations are propagated.

i is the the index of this function invocation.

type RunParallelFuncT

type RunParallelFuncT[T any] func(ctx context.Context, i int) (T, error)

RunParallelFuncT is like RunParallelFunc but allows returning a value.

type RunParallelOptions

type RunParallelOptions struct {
	// Message is the message that will be passed to Tracker.Start.
	// If omitted no message will be written by the Tracker.
	Message string
	// Count is the number of times the function will be run.
	// It is passed to Tracker.Start to keep track of progress.
	// If omitted or explicitly set to 0, RunParallel will no-op.
	Count int
	// Concurrency controls how many goroutines can run concurrently.
	// Defaults to runtime.NumCPU if omitted.
	Concurrency int
	// CancelOnError determines how RunParallel should behave if a function returns an error.
	//
	// If true, Run will cancel all other running functions when it receives an error and
	// return that first error. Note that RunParallel will still wait for all running functions
	// to complete. This way you can guarantee that when RunParallel returns all concurrent operations
	// have stopped.
	//
	// If false, RunParallel will let the other functions continue and will return an errors.List
	// containing any errors from each function.
	//
	// This option only applies if Count > 1.
	CancelOnError bool
	// Timeout sets a timeout after which any running functions will be cancelled.
	// Defaults to 10min if omitted.
	Timeout time.Duration
	// TrackerKey can be used to specify a custom context key for retrieving a Tracker.
	// This should be used if ContextWithTrackerUsingKey was used.
	// If omitted, the default key will be used.
	TrackerKey any
}

RunParallelOptions is used to customize how RunParallel behaves. All fields are optional and have defaults.

type Spinner

type Spinner interface {
	Start(msg string, count int)
	Stop()
	Inc()
	UpdateMessage(msg string)
}

Spinner represents a type that can display the progress of an operation using an animation along with a message.

The Inc and UpdateMessage methods must be safe to call across multiple goroutines.

type Tracker

type Tracker interface {
	Logger
	Spinner
}

Tracker combines the Logger and Spinner interfaces. It provides the necessary functionality for tracking the progress of operations by displaying a spinner animation, as well as providing log messages. A Tracker should allow logging messages while the spinner animation is running.

func TrackerFromContext

func TrackerFromContext(ctx context.Context) Tracker

TrackerFromContext returns the Tracker from ctx.

If no Tracker exists in ctx, a no-op Tracker will be returned. Thus, the returned Tracker will never be nil, and it is always safe to call methods on it.

func TrackerFromContextUsingKey

func TrackerFromContextUsingKey(ctx context.Context, key any) Tracker

TrackerFromContextUsingKey is like TrackerFromContext but allows for using a custom key. It should be used if ContextWithTrackerUsingKey was used to create a context with a custom key.

If a value exists in the context for the given key but is not a Tracker, the function will panic.