solver

package
v0.14.0-rc2 Latest Latest
Warning

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

 Go to latest Published: Jun 6, 2024 License: Apache-2.0 Imports: 32 Imported by: 517

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var ErrNotFound = errors.Errorf("not found")

Functions

func CacheOptGetterOf added in v0.8.0 

func CacheOptGetterOf(ctx context.Context) func(includeAncestors bool, keys ...interface{}) map[interface{}]interface{}

func ProgressControllerFromContext added in v0.11.0 

func ProgressControllerFromContext(ctx context.Context) progress.Controller

func SplitResultProxy added in v0.11.0 

func SplitResultProxy(res ResultProxy) (ResultProxy, ResultProxy)

func WithCacheOptGetter added in v0.10.0 

func WithCacheOptGetter(ctx context.Context, getter func(includeAncestors bool, keys ...interface{}) map[interface{}]interface{}) context.Context

func WrapSlowCache added in v0.8.0 

func WrapSlowCache(err error, index Index, res Result) error

Types

type Builder 

type Builder interface {
	Build(ctx context.Context, e Edge) (CachedResultWithProvenance, error)
	InContext(ctx context.Context, f func(ctx context.Context, g session.Group) error) error
	EachValue(ctx context.Context, key string, fn func(interface{}) error) error
}

type CacheExportMode 

type CacheExportMode int

CacheExportMode is the type for setting cache exporting modes 

const (
	// CacheExportModeMin exports a topmost allowed vertex and its dependencies
	// that already have transferable layers
	CacheExportModeMin CacheExportMode = iota
	// CacheExportModeMax exports all possible non-root vertexes
	CacheExportModeMax
	// CacheExportModeRemoteOnly only exports vertexes that already have
	// transferable layers
	CacheExportModeRemoteOnly
)

type CacheExportOpt 

type CacheExportOpt struct {
	// ResolveRemotes can convert a build result to transferable objects
	ResolveRemotes func(context.Context, Result) ([]*Remote, error)
	// Mode defines a cache export algorithm
	Mode CacheExportMode
	// Session is the session group to client (for auth credentials etc)
	Session session.Group
	// CompressionOpt is an option to specify the compression of the object to load.
	// If specified, all objects that meet the option will be cached.
	CompressionOpt *compression.Config
	// ExportRoots defines if records for root vertexes should be exported.
	ExportRoots bool
	// IgnoreBacklinks defines if other cache chains for same result that did not
	// participate in the current build should be exported.
	IgnoreBacklinks bool
}

CacheExportOpt defines options for exporting build cache

type CacheExporter 

type CacheExporter interface {
	ExportTo(ctx context.Context, t CacheExporterTarget, opt CacheExportOpt) ([]CacheExporterRecord, error)
}

CacheExporter can export the artifacts of the build chain

type CacheExporterRecord 

type CacheExporterRecord interface {
	AddResult(vtx digest.Digest, index int, createdAt time.Time, result *Remote)
	LinkFrom(src CacheExporterRecord, index int, selector string)
}

CacheExporterRecord is a single object being exported

type CacheExporterTarget 

type CacheExporterTarget interface {
	// Add creates a new object record that we can then add results to and
	// connect to other records.
	Add(dgst digest.Digest) CacheExporterRecord

	// Visit marks a target as having been visited.
	Visit(target any)
	// Vistited returns true if a target has previously been marked as visited.
	Visited(target any) bool
}

CacheExporterTarget defines object capable of receiving exports 

type CacheInfoLink struct {
	Input    Index         `json:"Input,omitempty"`
	Output   Index         `json:"Output,omitempty"`
	Digest   digest.Digest `json:"Digest,omitempty"`
	Selector digest.Digest `json:"Selector,omitempty"`
}

CacheInfoLink is a link between two cache keys

type CacheKey 

type CacheKey struct {
	ID string
	// contains filtered or unexported fields
}

func NewCacheKey 

func NewCacheKey(dgst, vtx digest.Digest, output Index) *CacheKey

NewCacheKey creates a new cache key for a specific output index

func (*CacheKey) Deps 

func (ck *CacheKey) Deps() [][]CacheKeyWithSelector

func (*CacheKey) Digest 

func (ck *CacheKey) Digest() digest.Digest

func (*CacheKey) Output 

func (ck *CacheKey) Output() Index

func (*CacheKey) TraceFields added in v0.13.0 

func (ck *CacheKey) TraceFields() map[string]any

type CacheKeyStorage 

type CacheKeyStorage interface {
	Exists(id string) bool
	Walk(fn func(id string) error) error

	WalkResults(id string, fn func(CacheResult) error) error
	Load(id string, resultID string) (CacheResult, error)
	AddResult(id string, res CacheResult) error
	Release(resultID string) error
	WalkIDsByResult(resultID string, fn func(string) error) error

	AddLink(id string, link CacheInfoLink, target string) error
	WalkLinks(id string, link CacheInfoLink, fn func(id string) error) error
	HasLink(id string, link CacheInfoLink, target string) bool
	WalkBacklinks(id string, fn func(id string, link CacheInfoLink) error) error
}

CacheKeyStorage is interface for persisting cache metadata

func NewInMemoryCacheStorage 

func NewInMemoryCacheStorage() CacheKeyStorage

type CacheKeyWithSelector 

type CacheKeyWithSelector struct {
	Selector digest.Digest
	CacheKey ExportableCacheKey
}

CacheKeyWithSelector combines a cache key with an optional selector digest. Used to limit the matches for dependency cache key.

func (CacheKeyWithSelector) TraceFields added in v0.13.0 

func (ck CacheKeyWithSelector) TraceFields() map[string]any
type CacheLink struct {
	Source   digest.Digest `json:",omitempty"`
	Input    Index         `json:",omitempty"`
	Output   Index         `json:",omitempty"`
	Base     digest.Digest `json:",omitempty"`
	Selector digest.Digest `json:",omitempty"`
}

CacheLink is a link between two cache records

type CacheManager 

type CacheManager interface {
	// ID is used to identify cache providers that are backed by same source
	// to avoid duplicate calls to the same provider.
	ID() string

	// Query searches for cache paths from one cache key to the output of a
	// possible match.
	Query(inp []CacheKeyWithSelector, inputIndex Index, dgst digest.Digest, outputIndex Index) ([]*CacheKey, error)
	Records(ctx context.Context, ck *CacheKey) ([]*CacheRecord, error)

	// Load loads a cache record into a result reference.
	Load(ctx context.Context, rec *CacheRecord) (Result, error)

	// Save saves a result based on a cache key
	Save(key *CacheKey, s Result, createdAt time.Time) (*ExportableCacheKey, error)
}

CacheManager determines if there is a result that matches the cache keys generated during the build that could be reused instead of fully reevaluating the vertex and its inputs. There can be multiple cache managers, and specific managers can be defined per vertex using `VertexOptions`.

func NewCacheManager 

func NewCacheManager(ctx context.Context, id string, storage CacheKeyStorage, results CacheResultStorage) CacheManager

NewCacheManager creates a new cache manager with specific storage backend

func NewCombinedCacheManager added in v0.6.1 

func NewCombinedCacheManager(cms []CacheManager, main CacheManager) CacheManager

func NewInMemoryCacheManager 

func NewInMemoryCacheManager() CacheManager

NewInMemoryCacheManager creates a new in-memory cache manager

type CacheMap 

type CacheMap struct {
	// Digest returns a checksum for the operation. The operation result can be
	// cached by a checksum that combines this digest and the cache keys of the
	// operation's inputs.
	//
	// For example, in LLB this digest is a manifest digest for OCI images, or
	// commit SHA for git sources.
	Digest digest.Digest

	// Deps contain optional selectors or content-based cache functions for its
	// inputs.
	Deps []struct {
		// Selector is a digest that is merged with the cache key of the input.
		// Selectors are not merged with the result of the `ComputeDigestFunc` for
		// this input.
		Selector digest.Digest

		// ComputeDigestFunc should return a digest for the input based on its return
		// value.
		//
		// For example, in LLB this is invoked to calculate the cache key based on
		// the checksum of file contents from input snapshots.
		ComputeDigestFunc ResultBasedCacheFunc

		// PreprocessFunc is a function that runs on an input before it is passed to op
		PreprocessFunc PreprocessFunc
	}

	// Opts specifies generic options that will be passed to cache load calls if/when
	// the key associated with this CacheMap is used to load a ref. It allows options
	// such as oci descriptor content providers and progress writers to be passed to
	// the cache. Opts should not have any impact on the computed cache key.
	Opts CacheOpts
}

CacheMap is a description for calculating the cache key of an operation.

type CacheOpts added in v0.8.0 

type CacheOpts map[interface{}]interface{}

type CacheRecord 

type CacheRecord struct {
	ID        string
	Size      int
	CreatedAt time.Time
	Priority  int
	// contains filtered or unexported fields
}

CacheRecord is an identifier for loading in cache

func (*CacheRecord) TraceFields added in v0.13.0 

func (ck *CacheRecord) TraceFields() map[string]any

type CacheResult 

type CacheResult struct {
	CreatedAt time.Time
	ID        string
}

CacheResult is a record for a single solve result

type CacheResultStorage 

type CacheResultStorage interface {
	Save(Result, time.Time) (CacheResult, error)
	Load(ctx context.Context, res CacheResult) (Result, error)
	LoadRemotes(ctx context.Context, res CacheResult, compression *compression.Config, s session.Group) ([]*Remote, error)
	Exists(ctx context.Context, id string) bool
}

CacheResultStorage is interface for converting cache metadata result to actual solve result

func NewInMemoryResultStorage 

func NewInMemoryResultStorage() CacheResultStorage

type CachedResult 

type CachedResult interface {
	Result
	CacheKeys() []ExportableCacheKey
}

CachedResult is a result connected with its cache key

func NewCachedResult 

func NewCachedResult(res Result, k []ExportableCacheKey) CachedResult

NewCachedResult combines a result and cache key into cached result

type CachedResultWithProvenance added in v0.11.0 

type CachedResultWithProvenance interface {
	CachedResult
	WalkProvenance(context.Context, func(ProvenanceProvider) error) error
}

type Edge 

type Edge struct {
	Index  Index
	Vertex Vertex
}

Edge is a connection point between vertexes. An edge references a specific output of a vertex's operation. Edges are used as inputs to other vertexes.

type ExportableCacheKey 

type ExportableCacheKey struct {
	*CacheKey
	Exporter CacheExporter
}

ExportableCacheKey is a cache key connected with an exporter that can export a chain of cacherecords pointing to that key

type Index 

type Index int

Index is an index value for the return array of an operation. Index starts counting from zero.

type Job 

type Job struct {
	SessionID string
	// contains filtered or unexported fields
}

func (*Job) Build 

func (j *Job) Build(ctx context.Context, e Edge) (CachedResultWithProvenance, error)

func (*Job) CloseProgress added in v0.11.0 

func (j *Job) CloseProgress()

func (*Job) Discard 

func (j *Job) Discard() error

func (*Job) EachValue 

func (j *Job) EachValue(ctx context.Context, key string, fn func(interface{}) error) error

func (*Job) InContext added in v0.8.0 

func (j *Job) InContext(ctx context.Context, f func(context.Context, session.Group) error) error

func (*Job) RegisterCompleteTime added in v0.11.0 

func (j *Job) RegisterCompleteTime() time.Time

func (*Job) SetValue 

func (j *Job) SetValue(key string, v interface{})

func (*Job) StartedTime added in v0.11.0 

func (j *Job) StartedTime() time.Time

func (*Job) Status 

func (j *Job) Status(ctx context.Context, ch chan *client.SolveStatus) error

func (*Job) UniqueID added in v0.11.0 

func (j *Job) UniqueID() string

type LoadedResult added in v0.4.0 

type LoadedResult struct {
	Result      Result
	CacheResult CacheResult
	CacheKey    *CacheKey
}

func (*LoadedResult) TraceFields added in v0.13.0 

func (r *LoadedResult) TraceFields() map[string]any

type Op 

type Op interface {
	// CacheMap returns structure describing how the operation is cached.
	// Currently only roots are allowed to return multiple cache maps per op.
	CacheMap(context.Context, session.Group, int) (*CacheMap, bool, error)

	// Exec runs an operation given results from previous operations.
	Exec(ctx context.Context, g session.Group, inputs []Result) (outputs []Result, err error)

	// Acquire acquires the necessary resources to execute the `Op`.
	Acquire(ctx context.Context) (release ReleaseFunc, err error)
}

Op defines how the solver can evaluate the properties of a vertex operation. An op is executed in the worker, and is retrieved from the vertex by the value of `vertex.Sys()`. The solver is configured with a resolve function to convert a `vertex.Sys()` into an `Op`.

type PreprocessFunc added in v0.8.0 

type PreprocessFunc func(context.Context, Result, session.Group) error

type ProvenanceProvider added in v0.11.0 

type ProvenanceProvider interface {
	IsProvenanceProvider()
}

type ReleaseFunc added in v0.9.0 

type ReleaseFunc func()

type Remote 

type Remote struct {
	Descriptors []ocispecs.Descriptor
	Provider    content.InfoReaderProvider
}

Remote is a descriptor or a list of stacked descriptors that can be pulled from a content provider TODO: add closer to keep referenced data from getting deleted

type ResolveOpFunc 

type ResolveOpFunc func(Vertex, Builder) (Op, error)

ResolveOpFunc finds an Op implementation for a Vertex

type Result 

type Result interface {
	ID() string
	Release(context.Context) error
	Sys() interface{}
	Clone() Result
}

Result is an abstract return value for a solve

type ResultBasedCacheFunc 

type ResultBasedCacheFunc func(context.Context, Result, session.Group) (digest.Digest, error)

type ResultProxy added in v0.7.0 

type ResultProxy interface {
	ID() string
	Result(context.Context) (CachedResult, error)
	Release(context.Context) error
	Definition() *pb.Definition
	Provenance() interface{}
}

type SharedCachedResult 

type SharedCachedResult struct {
	*SharedResult
	CachedResult
}

func NewSharedCachedResult 

func NewSharedCachedResult(res CachedResult) *SharedCachedResult

func (*SharedCachedResult) Clone 

func (r *SharedCachedResult) Clone() Result

func (*SharedCachedResult) CloneCachedResult added in v0.8.2 

func (r *SharedCachedResult) CloneCachedResult() CachedResult

func (*SharedCachedResult) Release 

func (r *SharedCachedResult) Release(ctx context.Context) error

type SharedResult 

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

SharedResult is a result that can be cloned

func NewSharedResult 

func NewSharedResult(main Result) *SharedResult

func (*SharedResult) Clone 

func (r *SharedResult) Clone() Result

func (*SharedResult) Release 

func (r *SharedResult) Release(ctx context.Context) error

type SlowCacheError added in v0.8.0 

type SlowCacheError struct {
	Index  Index
	Result Result
	// contains filtered or unexported fields
}

func (*SlowCacheError) ToSubject added in v0.8.0 

func (e *SlowCacheError) ToSubject() errdefs.IsSolve_Subject

func (*SlowCacheError) Unwrap added in v0.8.0 

func (e *SlowCacheError) Unwrap() error

type Solver 

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

Solver provides a shared graph of all the vertexes currently being processed. Every vertex that is being solved needs to be loaded into job first. Vertex operations are invoked and progress tracking happens through jobs.

func NewSolver 

func NewSolver(opts SolverOpt) *Solver

func (*Solver) Close 

func (jl *Solver) Close()

func (*Solver) Get 

func (jl *Solver) Get(id string) (*Job, error)

func (*Solver) NewJob 

func (jl *Solver) NewJob(id string) (*Job, error)

type SolverOpt 

type SolverOpt struct {
	ResolveOpFunc ResolveOpFunc
	DefaultCache  CacheManager
}

type Vertex 

type Vertex interface {
	// Digest returns a checksum of the definition up to the vertex including
	// all of its inputs.
	Digest() digest.Digest

	// Sys returns an object used to resolve the executor for this vertex.
	// In LLB solver, this value would be of type `llb.Op`.
	Sys() interface{}

	// Options return metadata associated with the vertex that doesn't change the
	// definition or equality check of it.
	Options() VertexOptions

	// Inputs returns an array of edges the vertex depends on. An input edge is
	// a vertex and an index from the returned array of results from an executor
	// returned by Sys(). A vertex may have zero inputs.
	Inputs() []Edge

	Name() string
}

Vertex is a node in a build graph. It defines an interface for a content-addressable operation and its inputs.

type VertexOptions 

type VertexOptions struct {
	IgnoreCache  bool
	CacheSources []CacheManager
	Description  map[string]string // text values with no special meaning for solver
	ExportCache  *bool
	// WorkerConstraint
	ProgressGroup *pb.ProgressGroup
}

VertexOptions define optional metadata for a vertex that doesn't change the definition or equality check of it. These options are not contained in the vertex digest.

Source Files

View all Source files

Directories

Path Synopsis
internal
pipe
errdefs
file
mounts
ops
ops/fileoptypes
ops/opsutils
proc
provenance
provenance/types

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.