Documentation
¶
Overview ¶
Package buildqueue provides a basic build queue for objects identified by UUID. An object is buildable if it implements GetUUID(). An object can build itself if it implements the Builder interface.
Objects with identical UUID will never be built in parallel. The build queue will maintain a set of worker threads which will build objects in parallel.
When an object is already queued to be built not being being built yet, any further build request will be ignored.
When an object is being actively built and a new build request is enqueued, the build request will deferred. It will be scheduled into the build queue when the currently ongoing build of that same object has completed.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type BuildNotification ¶
type BuildNotification <-chan bool
BuildNotification is a channel to receive the status of a build. The channel will receive true if the build was successful. The channel is buffered and is guaranteed to only be written to exactly once and is then immediately closed. It is up to the caller of Enqueue() to decide whether to read on the channel or not.
type BuildQueue ¶
type BuildQueue struct {
// contains filtered or unexported fields
}
BuildQueue is a queueing system for builds
func NewBuildQueue ¶
func NewBuildQueue(name string) *BuildQueue
NewBuildQueue returns a new build queue
func (*BuildQueue) Drain ¶
func (q *BuildQueue) Drain(b Buildable) bool
Drain will drain the queue from any running or scheduled builds of a Buildable. If a build is running, the function will block for the build to complete. It is the responsibility of the caller that the Buildable does not get re-scheduled during the draining. Returns true if waiting was required.
func (*BuildQueue) Enqueue ¶
func (q *BuildQueue) Enqueue(b Builder) BuildNotification
Enqueue schedules Builder for building. A channel is returned to provide the ability to wait for the build to complete and check for success or failure.
A regular build fullfils the following build guarantees:
- The same Buildable, i.e. the same UUID, will not be built in parallel on multiple workers.
- The order in which regular builds are enqueued is maintained in the build order across different Buildables. If the same Buildable is enqueued multiple times, the buils are automatically folded together until the build is executed. This means in practise that a specific Buildable can only be in the build queue once.
- In the presence of preemptive, exclusive builds, regular builds get a fair chance to run but preemptive builds always preempt any queued, not yet running regular build.
func (*BuildQueue) PreemptExclusive ¶
func (q *BuildQueue) PreemptExclusive(b Builder) BuildNotification
PreemptExclusive enqueues a build at the front of the queue and provides exclusive build access. All other builds enqueued via Enqueue() PreemptExclusive() have to finish before the exclusive build is executed. The exclusive build will then be the only build executed until it finishes.
If an exclusive build for the same UUID is already enqueued but not yet running, the build will be folded into the already scheduled build but both notification channels will be notified.
func (*BuildQueue) Remove ¶
func (q *BuildQueue) Remove(b Buildable)
Remove removes the builder from the queue.
func (*BuildQueue) Stop ¶
func (q *BuildQueue) Stop()
Stop stops the build queue and terminates all workers
type Buildable ¶
type Buildable interface {
// GetUUID must return a unique UUID of the object
GetUUID() string
}
Buildable is an object that is buildable
type Builder ¶
type Builder interface {
Buildable
// BuildQueued is called every time a builder is enqueued
BuildQueued()
// BuildsDequeued is called when a scheduled builder has been dequeued
// for building or has been cancelled. The nbuilds accounts for the
// number of builders folded together while the builder was queued.
BuildsDequeued(nbuilds int, cancelled bool)
// Build must build the Buildable. When a builder was cancelled,
// Build() will not be called. When a builder is folded into an
// existing builder, Build() is only called on the first builder.
Build() error
}
Builder is an object that can build itself. A builder must also be Buildable
Source Files