Documentation
¶
Overview ¶
Package queue provides a run queue implementation. The queue is a double-ended queue (deque) that allows for efficient adding and removing of elements from both ends. The queue is used to manage the order of Terragrunt runs.
The algorithm for populating the queue is as follows:
- Given a list of discovered configurations, start with an empty queue.
- Sort configurations alphabetically to ensure deterministic ordering of independent items.
- For each discovered configuration: a. If the configuration has no dependencies, append it to the queue. b. Otherwise, find the position after its last dependency. c. Among items that depend on the same dependency, maintain alphabetical order.
The resulting queue will have: - Configurations with no dependencies at the front - Configurations with dependents are ordered after their dependencies - Alphabetical ordering only between items that share the same dependencies
During operations like applies, entries will be dequeued from the front of the queue and run. During operations like destroys, entries will be dequeued from the back of the queue and run. This ensures that dependencies are satisfied in both cases: - For applies: Dependencies (front) are run before their dependents (back) - For destroys: Dependents (back) are run before their dependencies (front)
Index ¶
- type Entries
- type Entry
- type Queue
- func (q *Queue) Components() component.Components
- func (q *Queue) EntryByPath(path string) *Entry
- func (q *Queue) FailEntry(e *Entry)
- func (q *Queue) Finished() bool
- func (q *Queue) GetReadyWithDependencies(l log.Logger) []*Entry
- func (q *Queue) RemainingDeps(e *Entry) int
- func (q *Queue) SetEntryStatus(e *Entry, status Status)
- func (q *Queue) SetUnitsMap(unitsMap map[string]*component.Unit)
- type Status
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Entry ¶ added in v0.77.14
type Entry struct {
// Component is the Terragrunt configuration associated with this entry. It contains all metadata about the unit/stack,
// including its path, dependencies, and discovery context (such as the command being run).
Component component.Component
// Status represents the current lifecycle state of this entry in the queue. It tracks whether the entry is pending,
// blocked, ready, running, succeeded, or failed. Status is updated as dependencies are resolved and as execution progresses.
Status Status
}
Entry represents a node in the execution queue/DAG. Each Entry corresponds to a single Terragrunt configuration and tracks its execution status and relationships to other entries in the queue.
func (*Entry) UpdateBlocked ¶ added in v0.77.14
UpdateBlocked updates the status of the entry to blocked, if it is blocked. An entry is blocked if:
- It is an "up" command (none of destroy, apply -destroy or plan -destroy) and it has dependencies that are not ready.
- It is a "down" command (destroy, apply -destroy or plan -destroy) and it has dependents that are not ready.
If the entry isn't blocked, then it is marked as unsorted, and is ready to be sorted.
type Queue ¶
type Queue struct {
// Entries is a list of entries in the queue.
Entries Entries
// FailFast, if set to true, causes the queue to fail fast if any entry fails.
FailFast bool
// IgnoreDependencyOrder, if set to true, causes the queue to ignore dependencies when fetching ready entries.
// When enabled, GetReadyWithDependencies will return all entries with StatusReady, regardless of dependency status.
IgnoreDependencyOrder bool
// IgnoreDependencyErrors, if set to true, allows scheduling and running entries even if their
// dependencies failed. Additionally, failures will not propagate EarlyExit to dependents/dependencies.
IgnoreDependencyErrors bool
// contains filtered or unexported fields
}
func NewQueue ¶
func NewQueue(discovered component.Components) (*Queue, error)
NewQueue creates a new queue from a list of discovered configurations. The queue is populated with the correct Terragrunt run order.
Discovered configurations will be sorted based on two criteria:
The discovery context of the configuration: - If the configuration is for an "up" command (none of destroy, apply -destroy or plan -destroy), it will be inserted at the front of the queue, before its dependencies. - Otherwise, it is considered a "down" command, and will be inserted at the back of the queue, after its dependents.
The name of the configuration. Configurations of the same "level" are sorted alphabetically.
Passing configurations that haven't been checked for cycles in their dependency graph is unsafe. If any cycles are present, the queue construction will halt after N iterations, where N is the number of discovered configs, and throw an error.
func (*Queue) Components ¶ added in v0.91.3
func (q *Queue) Components() component.Components
Components returns the queue components.
func (*Queue) EntryByPath ¶ added in v0.83.0
EntryByPath returns the entry with the given config path, or nil if not found.
func (*Queue) FailEntry ¶ added in v0.83.0
FailEntry marks the entry as failed and updates related entries if needed. For up commands, this marks entries that come after this one as early exit. For destroy/down commands, this marks entries that come before this one as early exit. Use only for failure transitions. For other status changes, set Status directly.
func (*Queue) Finished ¶ added in v0.83.0
Finished checks if all entries in the queue are in a terminal state (i.e., not pending, blocked, ready, or running).
func (*Queue) GetReadyWithDependencies ¶ added in v0.83.0
GetReadyWithDependencies returns all entries that are ready to run and have all dependencies completed (or no dependencies).
func (*Queue) RemainingDeps ¶ added in v0.83.0
RemainingDeps Helper to calculate remaining dependencies for an entry.
func (*Queue) SetEntryStatus ¶ added in v0.87.6
SetEntryStatus safely sets the status of an entry with proper synchronization.
If the entry is already in a terminal state (StatusSucceeded, StatusFailed, or StatusEarlyExit), this operation is a no-op. This prevents race conditions where a concurrent success could overwrite an early-exit status set by fail-fast mode.
Source Files