Documentation

Overview

    Package common contains widely used CV utilities & types.

    Index

    Constants

    View Source
    const (
    	// MaxTriggerAge limits CV operation only to most recently triggered CLs.
    	//
    	// In particular, this reduces Gerrit querying to CLs modified since
    	// (now-MaxTriggerAge).
    	MaxTriggerAge = 24 * 7 * time.Hour
    )

    Variables

    This section is empty.

    Functions

    func CLIDsAsInt64s

    func CLIDsAsInt64s(ids []CLID) []int64

      CLIDsAsInt64s returns proto representation of CLIDs.

      func DifferenceSorted

      func DifferenceSorted(a, b []int64) []int64

        DifferenceSorted returns all int64s in the first slice and not the second.

        Both slices must be sorted. Doesn't modify input slices.

        func LogError

        func LogError(ctx context.Context, err error, omitStackTraceFor ...error)

          LogError is errors.Log with CV-specific package filtering.

          Logs entire error stack with ERROR severity by default. Logs just error with WARNING severity iff one of error's leaf nodes matches at least one of the given list of `omitStackTraceFor` errors. This is useful if TQ handler is known to frequently fail this way.

          omitStackTraceFor must contain only unwrapped errors.

          func MostSevereError

          func MostSevereError(err error) error

            MostSevereError returns the most severe error in order of non-transient => transient => nil.

            Walks over potentially recursive errors.MultiError errors only.

            Returns only singular errors or nil if input was nil.

            func ProjectOffset

            func ProjectOffset(kind string, pollInterval time.Duration, luciProject string) time.Duration

              ProjectOffset deterministically chooses an offset per LUCI project in [1..pollInterval) range aimining for uniform distribution across projects.

              Kind purpose is to de-sync project offsets for different purposes.

              func TQifyError

              func TQifyError(ctx context.Context, err error, omitStackTraceFor ...error) error

                TQifyError does final error processing before returning from a TQ handler.

                * logs error with LogError unless one of error's leaf nodes matches at least
                  one of omitStackTraceFor, in which case no log is emitted at all since
                  server/tq will emit a line, too.
                * non-transient errors are tagged with tq.Fatal to avoid retries.
                

                omitStackTraceFor must contain only unwrapped errors.

                func UnionSorted

                func UnionSorted(a, b []int64) []int64

                  UnionSorted returns sorted unique int64s from two slices.

                  Both slices must be sorted and unique. Doesn't modify input slices.

                  func UniqueSorted

                  func UniqueSorted(v []int64) []int64

                    UniqueSorted sorts & removes duplicates in place.

                    Returns the potentially shorter slice.

                    Types

                    type CLID

                    type CLID int64

                      CLID is a unique ID of a CL used internally in CV.

                      It's just 8 bytes long and is thus much shorter than ExternalID, which reduces CPU & RAM & storage costs of CL graphs for multi-CL Runs.

                      type CLIDs

                      type CLIDs []CLID

                        CLIDs is a convenience type to facilitate handling of a slice of CLID.

                        func (*CLIDs) Dedupe

                        func (p *CLIDs) Dedupe()

                          Dedupe removes duplicates in place.

                          Note: Does not perserve original order.

                          type RunID

                          type RunID string

                            RunID is an unique RunID to identify a Run in CV.

                            RunID is string like `luciProject/timeComponent-1-hexHashDigest` consisting of 7 parts:

                            1. The LUCI Project that this Run belongs to.
                               Purpose: separates load on Datastore from different projects.
                            2. `/` separator.
                            3. (`endOfTheWorld` - CreateTime) in ms precision, left-padded with zeros
                               to 13 digits. See `Run.CreateTime` Doc.
                               Purpose: ensures queries by default orders runs of the same project by
                               most recent first.
                            4. `-` separator.
                            5. Digest version (see part 7).
                            6. `-` separator.
                            7. A hex digest string uniquely identifying the set of CLs involved in
                               this Run.
                               Purpose: ensures two simultaneously started Runs in the same project
                               won't have the same RunID.
                            

                            func MakeRunID

                            func MakeRunID(luciProject string, createTime time.Time, digestVersion int, clsDigest []byte) RunID

                            func (RunID) LUCIProject

                            func (id RunID) LUCIProject() string

                              LUCIProject this Run belongs to.

                              type RunIDs

                              type RunIDs []RunID

                                RunIDs is a convenience type to facilitate handling of run RunIDs.

                                func MakeRunIDs

                                func MakeRunIDs(ids ...string) RunIDs

                                  MakeRunIDs returns RunIDs from list of strings.

                                  func (RunIDs) ContainsSorted

                                  func (ids RunIDs) ContainsSorted(id RunID) bool

                                    ContainsSorted returns true if ids contain the given one.

                                    func (*RunIDs) DelSorted

                                    func (p *RunIDs) DelSorted(id RunID) bool

                                      DelSorted removes the given ID if it exists.

                                      DelSorted is a pointer receiver method, because it modifies slice itself.

                                      func (RunIDs) DifferenceSorted

                                      func (a RunIDs) DifferenceSorted(b RunIDs) RunIDs

                                        DifferenceSorted returns all IDs in this slice and not the other one.

                                        Both slices must be sorted. Doesn't modify input slices.

                                        func (RunIDs) Equal

                                        func (ids RunIDs) Equal(other RunIDs) bool

                                          Equal checks if two assumed-to-be-sorted slices are equal.

                                          func (*RunIDs) InsertSorted

                                          func (p *RunIDs) InsertSorted(id RunID)

                                            InsertSorted adds given ID if not yet exists to the list keeping list sorted.

                                            InsertSorted is a pointer receiver method, because it modifies slice itself.

                                            func (RunIDs) Len

                                            func (ids RunIDs) Len() int

                                            func (RunIDs) Less

                                            func (ids RunIDs) Less(i, j int) bool

                                              sort.Interface copy-pasta.

                                              func (RunIDs) Set

                                              func (ids RunIDs) Set() map[RunID]struct{}

                                                Set returns a new set of run IDs.

                                                func (RunIDs) Swap

                                                func (ids RunIDs) Swap(i, j int)

                                                func (RunIDs) WithoutSorted

                                                func (ids RunIDs) WithoutSorted(exclude RunIDs) RunIDs

                                                  WithoutSorted returns a subsequence of IDs without excluded IDs.

                                                  Both this and the excluded slices must be sorted.

                                                  If this and excluded IDs are disjoint, return this slice. Otherwise, returns a copy without excluded IDs.