base: github.com/grailbio/base/status Index | Files

package status

import "github.com/grailbio/base/status"

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

Package Files

http.go status.go stream.go term.go term_linux.go

func Handler Uses

func Handler(s *Status) http.Handler

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

type Group Uses

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 Uses

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

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

func (*Group) Printf Uses

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 Uses

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 Uses

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 Uses

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 Uses

func (g *Group) Value() Value

Value returns the group's current value.

type Reporter Uses

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 Uses

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 Uses

func (r Reporter) Stop()

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

func (Reporter) Wrap Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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

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

func (*Status) Wait Uses

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 Uses

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 Uses

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 Uses

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

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

func (*Task) Printf Uses

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

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

func (*Task) Title Uses

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

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

func (*Task) Titlef Uses

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

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

func (*Task) Value Uses

func (t *Task) Value() Value

Value returns this tasks's current value.

type Value Uses

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).

Package status imports 14 packages (graph) and is imported by 7 packages. Updated 2019-12-01. Refresh now. Tools for package owners.