Documentation
¶
Overview ¶
Package annotation implements a state machine that constructs Milo annotation protobufs from a series of annotation commands.
The annotation state is represented by a State object. Annotation strings are appended to the State via Append(), causing the State to incorporate that annotation and advance. During state advancement, any number of the State's Callbacks may be invoked in response to changes that are made.
State is pure (not bound to any I/O). Users of a State should interact with it by implementing Callbacks.
Index ¶
- type Callbacks
- type Execution
- type State
- func (s *State) Append(annotation string) error
- func (s *State) CurrentStep() *Step
- func (s *State) Finish()
- func (s *State) LookupStep(name string) *Step
- func (s *State) LookupStepErr(name string) (*Step, error)
- func (s *State) ResolveStep(ms *annopb.Step) *Step
- func (s *State) RootStep() *Step
- func (s *State) SetCurrentStep(v *Step)
- type Step
- func (as *Step) AddLogdogStreamLink(server, label string, prefix, name types.StreamName)
- func (as *Step) AddStep(name string, legacy bool) *Step
- func (as *Step) AddText(text string) bool
- func (as *Step) AddURLLink(label, alias, url string)
- func (as *Step) BaseStream(name types.StreamName) types.StreamName
- func (as *Step) ClearSummary()
- func (as *Step) ClearText() bool
- func (as *Step) Close(closeTime *timestamppb.Timestamp) bool
- func (as *Step) LogEnd(label string)
- func (as *Step) LogLine(label, line string) bool
- func (as *Step) Name() string
- func (as *Step) Proto() *annopb.Step
- func (as *Step) SetNestLevel(l int) bool
- func (as *Step) SetProperty(name, value string) bool
- func (as *Step) SetSTDERRStream(st *annopb.LogdogStream) (updated bool)
- func (as *Step) SetSTDOUTStream(st *annopb.LogdogStream) (updated bool)
- func (as *Step) SetStatus(s annopb.Status, fd *annopb.FailureDetails) bool
- func (as *Step) SetSummary(value string) bool
- func (as *Step) Start(startTime *timestamppb.Timestamp) bool
- func (as *Step) String() string
- type UpdateType
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Callbacks ¶
type Callbacks interface {
// StepClosed is called when a Step has closed. An Updated callback will still
// be invoked.
StepClosed(*Step)
// Updated is called when a Step's state has been updated.
Updated(*Step, UpdateType)
// StepLogLine is called when a Step emits a log line.
StepLogLine(s *Step, stream types.StreamName, label, line string)
// StepLogEnd is called when a Step finishes emitting logs.
StepLogEnd(*Step, types.StreamName)
}
Callbacks is the set of callbacks that a State may invoke as it processes annotations.
type Execution ¶
Execution describes the high-level execution metadata.
func ProbeExecution ¶
ProbeExecution loads Execution parameters by probing the current runtime environment.
type State ¶
type State struct {
// LogNameBase is the base log stream name that is prepeneded to generated
// log streams.
LogNameBase types.StreamName
// Callbacks implements annotation callbacks. It may not be nil.
Callbacks Callbacks
// Execution is the supplied Execution. If nil, no execution details will be
// added to the generated annotation protos.
Execution *Execution
// Offline specifies whether parsing happens not at the same time as
// emitting. If true and CURRENT_TIMESTAMP annotations are not provided
// then step start/end times are left empty.
Offline bool
// Clock is the clock implementation to use for time information.
// Defaults to system time.
Clock clock.Clock
// contains filtered or unexported fields
}
State is the aggregate annotation state for a given annotation stream. It receives updates in the form of annotations added via Append, and can be serialized to an annotation state protobuf.
func (*State) Append ¶
Append adds an annotation to the state. If the state was updated, Append will return true.
The appended annotation should only contain the annotation text body, not any annotation indicators (e.g., "@@@") that surround it.
If the annotation is invalid or could not be added to the state, an error will be returned.
Steps and descriptions can be found at: https://chromium.googlesource.com/chromium/tools/build/+/master/scripts/ master/chromium_step.py
func (*State) CurrentStep ¶
CurrentStep returns the step referenced by the step cursor.
func (*State) Finish ¶
func (s *State) Finish()
Finish closes the top-level annotation state and any outstanding steps.
func (*State) LookupStep ¶
LookupStep returns the step with the supplied name, or nil if no such step exists.
If multiple steps share a name, this will return the latest registered step with that name.
func (*State) LookupStepErr ¶
LookupStepErr returns the step with the supplied name, or an error if no such step exists.
If multiple steps share a name, this will return the latest registered step with that name.
func (*State) ResolveStep ¶
ResolveStep returns the annotation package *Step corresponding to the supplied *annopb.Step. This is a reverse lookup operation.
If the supplied *annopb.Step is not registered with this annotation State, this function will return nil.
func (*State) SetCurrentStep ¶
SetCurrentStep sets the current step. If the supplied step is nil, the root step will be used.
The supplied step must already be registered with the State.
type Step ¶
type Step struct {
annopb.Step
// logNameBase is the LogDog stream name root for this step.
LogNameBase types.StreamName
// contains filtered or unexported fields
}
Step represents a single step.
func (*Step) AddLogdogStreamLink ¶
func (as *Step) AddLogdogStreamLink(server, label string, prefix, name types.StreamName)
AddLogdogStreamLink adds a LogDog stream link to this Step's links list.
func (*Step) AddURLLink ¶
AddURLLink adds a URL link to this Step's links list.
func (*Step) BaseStream ¶
func (as *Step) BaseStream(name types.StreamName) types.StreamName
BaseStream returns the supplied name prepended with this Step's base log name.
For example, if the base name is "foo/bar", BaseStream("baz") will return "foo/bar/baz".
func (*Step) ClearSummary ¶
func (as *Step) ClearSummary()
ClearSummary clears the step's summary text.
func (*Step) Close ¶
func (as *Step) Close(closeTime *timestamppb.Timestamp) bool
Close closes this step and any outstanding resources that it owns. If it is already closed, does not have side effects and returns false.
func (*Step) SetNestLevel ¶
SetNestLevel sets the nest level of this Step, and identifies its nesting parent.
If no parent could be found at level "l-1", the root step will become the parent.
func (*Step) SetProperty ¶
SetProperty sets a key/value property for this Step.
func (*Step) SetSTDERRStream ¶
func (as *Step) SetSTDERRStream(st *annopb.LogdogStream) (updated bool)
SetSTDERRStream sets the LogDog STDERR stream value, returning true if the Step was updated.
func (*Step) SetSTDOUTStream ¶
func (as *Step) SetSTDOUTStream(st *annopb.LogdogStream) (updated bool)
SetSTDOUTStream sets the LogDog STDOUT stream value, returning true if the Step was updated.
func (*Step) SetStatus ¶
SetStatus sets this step's component status.
If the status doesn't change, the supplied failure details will be ignored.
func (*Step) SetSummary ¶
SetSummary sets the Step's summary text.
The summary is implemented as the first line of step component text. If no summary is currently defined, one will be inserted; otherwise, the current summary will be replaced.
type UpdateType ¶
type UpdateType int
UpdateType is information sent to the Updated callback to indicate the nature of the update.
const ( // UpdateIterative indicates that a non-structural update occurred. UpdateIterative UpdateType = iota // UpdateStructural indicates that a structural update has occurred. A // structural update is one that affects the existence of or relationship of // the Steps in the annotation. UpdateStructural )
Source Files