luci: go.chromium.org/luci/luciexe/host/buildmerge Index | Files

package buildmerge

import "go.chromium.org/luci/luciexe/host/buildmerge"

Package buildmerge implements the build.proto tracking and merging logic for luciexe host applications.

You probably want to use `go.chromium.org/luci/luciexe/host` instead.

This package is separate from luciexe/host to avoid unnecessary entaglement with butler/logdog; All the logic here is implemented to avoid:

* interacting with the environment
* interacting with butler/logdog (except by implementing callbacks for
  those, but only acting on simple datastructures/proto messages)
* handling errors in any 'brutal' ways (all errors in this package are
  handled by reporting them directly in the data structures that this
  package manipulates).

This is done to simplify testing (as much as it can be) by concentrating all the environment stuff into luciexe/host, and all the 'pure' functional stuff here (search "imperative shell, functional core").

Index

Package Files

agent.go build.go build_state.go

type Agent Uses

type Agent struct {
    // MergedBuildC is the channel of all the merged builds generated by this
    // Agent.
    //
    // The rate at which Agent merges Builds is governed by the consumption of
    // this channel; Consuming it slowly will have Agent merge less frequently,
    // and consuming it rapidly will have Agent merge more frequently.
    //
    // The last build before the channel closes will always be the final state of
    // all builds at the time this Agent was Close()'d.
    MergedBuildC <-chan *bbpb.Build

    // Wait on this channel for the Agent to drain. Will only drain after calling
    // Close() at least once.
    DrainC <-chan struct{}
    // contains filtered or unexported fields
}

Agent holds all the logic around merging build.proto streams.

func New Uses

func New(ctx context.Context, userNamespace types.StreamName, base *bbpb.Build, calculateURLs CalcURLFn) *Agent

New returns a new Agent.

Args:

* ctx - used for logging, clock and cancelation. When canceled, the Agent
  will cease sending updates on MergedBuildC, but you must still invoke
  Agent.Close() in order to clean up all resources associated with the
  Agent.
* userNamespace - The logdog namespace (with a trailing slash) under which
  we should monitor streams.
* base - The "model" Build message that all generated builds should start
  with. All build proto streams will be merged onto a copy of this message.
  Any Output.Log's which have non-absolute URLs will have their Url and
  ViewUrl absolutized relative to userNamespace using calculateURLs.
* calculateURLs - A function to calculate Log.Url and Log.ViewUrl values.
  Should be a pure function.

The following fields will be merged into `base` from the user controlled build.proto stream(s):

Steps
SummaryMarkdown
Status
StatusDetails
UpdateTime
Tags
EndTime
Output

The frequency of updates from this Agent is governed by how quickly the caller consumes from Agent.MergedBuildC.

func (*Agent) Attach Uses

func (a *Agent) Attach(b *butler.Butler)

Attach should be called once to attach this to a Butler.

This must be done before the butler receives any build.proto streams.

func (*Agent) Close Uses

func (a *Agent) Close()

Close causes the Agent to stop collecting data, emit a final merged build, and then shut down all internal routines.

type CalcURLFn Uses

type CalcURLFn func(namespaceSlash, streamName types.StreamName) (url, viewUrl string)

CalcURLFn is a stateless function which can calculate the absolute url and viewUrl from a given logdog namespace (with trailing slash) and streamName.

Package buildmerge imports 23 packages (graph) and is imported by 2 packages. Updated 2019-12-14. Refresh now. Tools for package owners.