status

package
v0.0.0-...-44c758a Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Feb 23, 2024 License: Apache-2.0 Imports: 14 Imported by: 0

Documentation

Overview

Package status provides facilities for reporting statuses from a number of tasks working towards a common goal. The toplevel Status represents the status for the whole job; it in turn comprises a number of groups; each group has 0 or more tasks.

Tasks (and groups) may be updated via their Print[f] functions; reporters receive notifications when updates have been made.

Package status also includes a standard console reporter that formats nice status screens when the output is a terminal, or else issues periodic status updates.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Handler

func Handler(s *Status) http.Handler

Handler returns a HTTP handler that renders a simple plain-text status snapshot of s on each request.

Types

type Group

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

A Group is a collection of tasks, working toward a common goal. Groups are persistent: they have no beginning or end; they have a "toplevel" status that can be updated.

func (*Group) Print

func (g *Group) Print(v ...interface{})

Print formats a status as fmt.Sprint and sets it as the group's status.

func (*Group) Printf

func (g *Group) Printf(format string, args ...interface{})

Printf formats a status as fmt.Sprintf and sets it as the group's status.

func (*Group) Start

func (g *Group) Start(v ...interface{}) *Task

Start creates a new task associated with this group and returns it. The task's initial title is formatted from the provided arguments as fmt.Sprint.

func (*Group) Startf

func (g *Group) Startf(format string, args ...interface{}) *Task

Startf creates a new task associated with tihs group and returns it. The task's initial title is formatted from the provided arguments as fmt.Sprintf.

func (*Group) Tasks

func (g *Group) Tasks() []*Task

Tasks returns a snapshot of the group's currently active tasks. Expired tasks are garbage collected on calls to Tasks. Tasks are returned in the order of creation: the oldest is always first.

func (*Group) Value

func (g *Group) Value() Value

Value returns the group's current value.

type Reporter

type Reporter chan req

Reporter displays regular updates of a Status. When updates are displayed on a terminal, each update replaces the previous, so only one update remains visible at a time. Otherwise update snapshots are written periodically.

func (Reporter) Go

func (r Reporter) Go(w io.Writer, status *Status)

Go starts the Reporter's service routine, and will write regular updates to the provided writer.

func (Reporter) Stop

func (r Reporter) Stop()

Stop halts rendering of status updates; writes to writers returned by Wrap are still serviced.

func (Reporter) Wrap

func (r Reporter) Wrap(w io.Writer) io.Writer

Wrap returns a writer whose writes are serviced by the reporter and written to the underlying writer w. Wrap is used to allow an application to write to the same set of file descriptors as are used to render status updates. This permits the reporter's terminal handling code to properly write log messages while also rendering regular status updates.

type Status

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

Status represents a toplevel status object. A status comprises a number of groups which in turn comprise a number of sub-tasks.

func (*Status) Group

func (s *Status) Group(v ...interface{}) *Group

Group creates and returns a new group named by the provided arguments as formatted by fmt.Sprint. If the group already exists, it is returned.

func (*Status) Groupf

func (s *Status) Groupf(format string, args ...interface{}) *Group

Groupf creates and returns a new group named by the provided arguments as formatted by fmt.Sprintf. If the group already exists, it is returned.

func (*Status) Groups

func (s *Status) Groups() []*Group

Groups returns a snapshot of the status groups. Groups maintains a consistent order of returned groups: when a group cohort first appears, it is returned in arbitrary order; each cohort is appended to the last, and the order of all groups is remembered across invocations.

func (*Status) Marshal

func (s *Status) Marshal(w io.Writer) error

Marshal writes s in a human-readable format to w.

func (*Status) Wait

func (s *Status) Wait(v int) <-chan int

Wait returns a channel that is blocked until the version of status data is greater than the provided version. When the status version exceeds v, it is written to the channel and then closed.

This allows status observers to implement a simple loop that coalesces updates:

v := -1
for {
	v = <-status.Wait(v)
	groups := status.Groups()
	// ... process groups
}

type Task

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

A Task is a single unit of work. It has a title, a beginning and an end time, and may receive zero or more status updates throughout its lifetime.

func (*Task) Done

func (t *Task) Done()

Done sets the completion time of the task to the current time. Tasks should not be updated after a call to Done; they will be discarded by the group after a timeout.

func (*Task) Print

func (t *Task) Print(v ...interface{})

Print formats a message as fmt.Sprint and updates the task's status.

func (*Task) Printf

func (t *Task) Printf(format string, args ...interface{})

Printf formats a message as fmt.Sprintf and updates the task's status.

func (*Task) Title

func (t *Task) Title(v ...interface{})

Title formats a title as fmt.Sprint, and updates the task's title.

func (*Task) Titlef

func (t *Task) Titlef(format string, args ...interface{})

Titlef formats a title as fmt.Sprintf, and updates the task's title.

func (*Task) Value

func (t *Task) Value() Value

Value returns this tasks's current value.

type Value

type Value struct {
	Title, Status string
	Begin, End    time.Time
	LastBegin     time.Time
	Count         int
}

Value is a task or group status at a point in time, it includes a title, status, as well as its start and stop times (undefined for groups).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL