7 "github.com/hashicorp/terraform/addrs"
8 "github.com/zclconf/go-cty/cty"
11 // SyncState is a wrapper around State that provides concurrency-safe access to
12 // various common operations that occur during a Terraform graph walk, or other
13 // similar concurrent contexts.
15 // When a SyncState wrapper is in use, no concurrent direct access to the
16 // underlying objects is permitted unless the caller first acquires an explicit
17 // lock, using the Lock and Unlock methods. Most callers should _not_
18 // explicitly lock, and should instead use the other methods of this type that
19 // handle locking automatically.
21 // Since SyncState is able to safely consolidate multiple updates into a single
22 // atomic operation, many of its methods are at a higher level than those
23 // of the underlying types, and operate on the state as a whole rather than
24 // on individual sub-structures of the state.
26 // SyncState can only protect against races within its own methods. It cannot
27 // provide any guarantees about the order in which concurrent operations will
28 // be processed, so callers may still need to employ higher-level techniques
29 // for ensuring correct operation sequencing, such as building and walking
30 // a dependency graph.
31 type SyncState struct {
36 // Module returns a snapshot of the state of the module instance with the given
37 // address, or nil if no such module is tracked.
39 // The return value is a pointer to a copy of the module state, which the
40 // caller may then freely access and mutate. However, since the module state
41 // tends to be a large data structure with many child objects, where possible
42 // callers should prefer to use a more granular accessor to access a child
43 // module directly, and thus reduce the amount of copying required.
44 func (s *SyncState) Module(addr addrs.ModuleInstance) *Module {
46 ret := s.state.Module(addr).DeepCopy()
51 // RemoveModule removes the entire state for the given module, taking with
52 // it any resources associated with the module. This should generally be
53 // called only for modules whose resources have all been destroyed, but
54 // that is not enforced by this method.
55 func (s *SyncState) RemoveModule(addr addrs.ModuleInstance) {
59 s.state.RemoveModule(addr)
62 // OutputValue returns a snapshot of the state of the output value with the
63 // given address, or nil if no such output value is tracked.
65 // The return value is a pointer to a copy of the output value state, which the
66 // caller may then freely access and mutate.
67 func (s *SyncState) OutputValue(addr addrs.AbsOutputValue) *OutputValue {
69 ret := s.state.OutputValue(addr).DeepCopy()
74 // SetOutputValue writes a given output value into the state, overwriting
75 // any existing value of the same name.
77 // If the module containing the output is not yet tracked in state then it
78 // be added as a side-effect.
79 func (s *SyncState) SetOutputValue(addr addrs.AbsOutputValue, value cty.Value, sensitive bool) {
83 ms := s.state.EnsureModule(addr.Module)
84 ms.SetOutputValue(addr.OutputValue.Name, value, sensitive)
87 // RemoveOutputValue removes the stored value for the output value with the
90 // If this results in its containing module being empty, the module will be
91 // pruned from the state as a side-effect.
92 func (s *SyncState) RemoveOutputValue(addr addrs.AbsOutputValue) {
96 ms := s.state.Module(addr.Module)
100 ms.RemoveOutputValue(addr.OutputValue.Name)
101 s.maybePruneModule(addr.Module)
104 // LocalValue returns the current value associated with the given local value
106 func (s *SyncState) LocalValue(addr addrs.AbsLocalValue) cty.Value {
108 // cty.Value is immutable, so we don't need any extra copying here.
109 ret := s.state.LocalValue(addr)
114 // SetLocalValue writes a given output value into the state, overwriting
115 // any existing value of the same name.
117 // If the module containing the local value is not yet tracked in state then it
118 // will be added as a side-effect.
119 func (s *SyncState) SetLocalValue(addr addrs.AbsLocalValue, value cty.Value) {
121 defer s.lock.Unlock()
123 ms := s.state.EnsureModule(addr.Module)
124 ms.SetLocalValue(addr.LocalValue.Name, value)
127 // RemoveLocalValue removes the stored value for the local value with the
130 // If this results in its containing module being empty, the module will be
131 // pruned from the state as a side-effect.
132 func (s *SyncState) RemoveLocalValue(addr addrs.AbsLocalValue) {
134 defer s.lock.Unlock()
136 ms := s.state.Module(addr.Module)
140 ms.RemoveLocalValue(addr.LocalValue.Name)
141 s.maybePruneModule(addr.Module)
144 // Resource returns a snapshot of the state of the resource with the given
145 // address, or nil if no such resource is tracked.
147 // The return value is a pointer to a copy of the resource state, which the
148 // caller may then freely access and mutate.
149 func (s *SyncState) Resource(addr addrs.AbsResource) *Resource {
151 ret := s.state.Resource(addr).DeepCopy()
156 // ResourceInstance returns a snapshot of the state the resource instance with
157 // the given address, or nil if no such instance is tracked.
159 // The return value is a pointer to a copy of the instance state, which the
160 // caller may then freely access and mutate.
161 func (s *SyncState) ResourceInstance(addr addrs.AbsResourceInstance) *ResourceInstance {
163 ret := s.state.ResourceInstance(addr).DeepCopy()
168 // ResourceInstanceObject returns a snapshot of the current instance object
169 // of the given generation belonging to the instance with the given address,
170 // or nil if no such object is tracked..
172 // The return value is a pointer to a copy of the object, which the caller may
173 // then freely access and mutate.
174 func (s *SyncState) ResourceInstanceObject(addr addrs.AbsResourceInstance, gen Generation) *ResourceInstanceObjectSrc {
176 defer s.lock.RUnlock()
178 inst := s.state.ResourceInstance(addr)
182 return inst.GetGeneration(gen).DeepCopy()
185 // SetResourceMeta updates the resource-level metadata for the resource at
186 // the given address, creating the containing module state and resource state
187 // as a side-effect if not already present.
188 func (s *SyncState) SetResourceMeta(addr addrs.AbsResource, eachMode EachMode, provider addrs.AbsProviderConfig) {
190 defer s.lock.Unlock()
192 ms := s.state.EnsureModule(addr.Module)
193 ms.SetResourceMeta(addr.Resource, eachMode, provider)
196 // RemoveResource removes the entire state for the given resource, taking with
197 // it any instances associated with the resource. This should generally be
198 // called only for resource objects whose instances have all been destroyed,
199 // but that is not enforced by this method. (Use RemoveResourceIfEmpty instead
200 // to safely check first.)
201 func (s *SyncState) RemoveResource(addr addrs.AbsResource) {
203 defer s.lock.Unlock()
205 ms := s.state.EnsureModule(addr.Module)
206 ms.RemoveResource(addr.Resource)
207 s.maybePruneModule(addr.Module)
210 // RemoveResourceIfEmpty is similar to RemoveResource but first checks to
211 // make sure there are no instances or objects left in the resource.
213 // Returns true if the resource was removed, or false if remaining child
214 // objects prevented its removal. Returns true also if the resource was
215 // already absent, and thus no action needed to be taken.
216 func (s *SyncState) RemoveResourceIfEmpty(addr addrs.AbsResource) bool {
218 defer s.lock.Unlock()
220 ms := s.state.Module(addr.Module)
222 return true // nothing to do
224 rs := ms.Resource(addr.Resource)
226 return true // nothing to do
228 if len(rs.Instances) != 0 {
229 // We don't check here for the possibility of instances that exist
230 // but don't have any objects because it's the responsibility of the
231 // instance-mutation methods to prune those away automatically.
234 ms.RemoveResource(addr.Resource)
235 s.maybePruneModule(addr.Module)
239 // MaybeFixUpResourceInstanceAddressForCount deals with the situation where a
240 // resource has changed from having "count" set to not set, or vice-versa, and
241 // so we need to rename the zeroth instance key to no key at all, or vice-versa.
243 // Set countEnabled to true if the resource has count set in its new
244 // configuration, or false if it does not.
246 // The state is modified in-place if necessary, moving a resource instance
247 // between the two addresses. The return value is true if a change was made,
248 // and false otherwise.
249 func (s *SyncState) MaybeFixUpResourceInstanceAddressForCount(addr addrs.AbsResource, countEnabled bool) bool {
251 defer s.lock.Unlock()
253 ms := s.state.Module(addr.Module)
258 relAddr := addr.Resource
259 rs := ms.Resource(relAddr)
263 huntKey := addrs.NoKey
264 replaceKey := addrs.InstanceKey(addrs.IntKey(0))
266 huntKey, replaceKey = replaceKey, huntKey
269 is, exists := rs.Instances[huntKey]
274 if _, exists := rs.Instances[replaceKey]; exists {
275 // If the replacement key also exists then we'll do nothing and keep both.
279 // If we get here then we need to "rename" from hunt to replace
280 rs.Instances[replaceKey] = is
281 delete(rs.Instances, huntKey)
285 // SetResourceInstanceCurrent saves the given instance object as the current
286 // generation of the resource instance with the given address, simulataneously
287 // updating the recorded provider configuration address, dependencies, and
288 // resource EachMode.
290 // Any existing current instance object for the given resource is overwritten.
291 // Set obj to nil to remove the primary generation object altogether. If there
292 // are no deposed objects then the instance as a whole will be removed, which
293 // may in turn also remove the containing module if it becomes empty.
295 // The caller must ensure that the given ResourceInstanceObject is not
296 // concurrently mutated during this call, but may be freely used again once
297 // this function returns.
299 // The provider address and "each mode" are resource-wide settings and so they
300 // are updated for all other instances of the same resource as a side-effect of
303 // If the containing module for this resource or the resource itself are not
304 // already tracked in state then they will be added as a side-effect.
305 func (s *SyncState) SetResourceInstanceCurrent(addr addrs.AbsResourceInstance, obj *ResourceInstanceObjectSrc, provider addrs.AbsProviderConfig) {
307 defer s.lock.Unlock()
309 ms := s.state.EnsureModule(addr.Module)
310 ms.SetResourceInstanceCurrent(addr.Resource, obj.DeepCopy(), provider)
311 s.maybePruneModule(addr.Module)
314 // SetResourceInstanceDeposed saves the given instance object as a deposed
315 // generation of the resource instance with the given address and deposed key.
317 // Call this method only for pre-existing deposed objects that already have
318 // a known DeposedKey. For example, this method is useful if reloading objects
319 // that were persisted to a state file. To mark the current object as deposed,
320 // use DeposeResourceInstanceObject instead.
322 // The caller must ensure that the given ResourceInstanceObject is not
323 // concurrently mutated during this call, but may be freely used again once
324 // this function returns.
326 // The resource that contains the given instance must already exist in the
327 // state, or this method will panic. Use Resource to check first if its
328 // presence is not already guaranteed.
330 // Any existing current instance object for the given resource and deposed key
331 // is overwritten. Set obj to nil to remove the deposed object altogether. If
332 // the instance is left with no objects after this operation then it will
333 // be removed from its containing resource altogether.
335 // If the containing module for this resource or the resource itself are not
336 // already tracked in state then they will be added as a side-effect.
337 func (s *SyncState) SetResourceInstanceDeposed(addr addrs.AbsResourceInstance, key DeposedKey, obj *ResourceInstanceObjectSrc, provider addrs.AbsProviderConfig) {
339 defer s.lock.Unlock()
341 ms := s.state.EnsureModule(addr.Module)
342 ms.SetResourceInstanceDeposed(addr.Resource, key, obj.DeepCopy(), provider)
343 s.maybePruneModule(addr.Module)
346 // DeposeResourceInstanceObject moves the current instance object for the
347 // given resource instance address into the deposed set, leaving the instance
348 // without a current object.
350 // The return value is the newly-allocated deposed key, or NotDeposed if the
351 // given instance is already lacking a current object.
353 // If the containing module for this resource or the resource itself are not
354 // already tracked in state then there cannot be a current object for the
355 // given instance, and so NotDeposed will be returned without modifying the
357 func (s *SyncState) DeposeResourceInstanceObject(addr addrs.AbsResourceInstance) DeposedKey {
359 defer s.lock.Unlock()
361 ms := s.state.Module(addr.Module)
366 return ms.deposeResourceInstanceObject(addr.Resource, NotDeposed)
369 // DeposeResourceInstanceObjectForceKey is like DeposeResourceInstanceObject
370 // but uses a pre-allocated key. It's the caller's responsibility to ensure
371 // that there aren't any races to use a particular key; this method will panic
372 // if the given key is already in use.
373 func (s *SyncState) DeposeResourceInstanceObjectForceKey(addr addrs.AbsResourceInstance, forcedKey DeposedKey) {
375 defer s.lock.Unlock()
377 if forcedKey == NotDeposed {
378 // Usage error: should use DeposeResourceInstanceObject in this case
379 panic("DeposeResourceInstanceObjectForceKey called without forced key")
382 ms := s.state.Module(addr.Module)
384 return // Nothing to do, since there can't be any current object either.
387 ms.deposeResourceInstanceObject(addr.Resource, forcedKey)
390 // ForgetResourceInstanceAll removes the record of all objects associated with
391 // the specified resource instance, if present. If not present, this is a no-op.
392 func (s *SyncState) ForgetResourceInstanceAll(addr addrs.AbsResourceInstance) {
394 defer s.lock.Unlock()
396 ms := s.state.Module(addr.Module)
400 ms.ForgetResourceInstanceAll(addr.Resource)
401 s.maybePruneModule(addr.Module)
404 // ForgetResourceInstanceDeposed removes the record of the deposed object with
405 // the given address and key, if present. If not present, this is a no-op.
406 func (s *SyncState) ForgetResourceInstanceDeposed(addr addrs.AbsResourceInstance, key DeposedKey) {
408 defer s.lock.Unlock()
410 ms := s.state.Module(addr.Module)
414 ms.ForgetResourceInstanceDeposed(addr.Resource, key)
415 s.maybePruneModule(addr.Module)
418 // MaybeRestoreResourceInstanceDeposed will restore the deposed object with the
419 // given key on the specified resource as the current object for that instance
420 // if and only if that would not cause us to forget an existing current
421 // object for that instance.
423 // Returns true if the object was restored to current, or false if no change
425 func (s *SyncState) MaybeRestoreResourceInstanceDeposed(addr addrs.AbsResourceInstance, key DeposedKey) bool {
427 defer s.lock.Unlock()
429 if key == NotDeposed {
430 panic("MaybeRestoreResourceInstanceDeposed called without DeposedKey")
433 ms := s.state.Module(addr.Module)
435 // Nothing to do, since the specified deposed object cannot exist.
439 return ms.maybeRestoreResourceInstanceDeposed(addr.Resource, key)
442 // RemovePlannedResourceInstanceObjects removes from the state any resource
443 // instance objects that have the status ObjectPlanned, indiciating that they
444 // are just transient placeholders created during planning.
446 // Note that this does not restore any "ready" or "tainted" object that might
447 // have been present before the planned object was written. The only real use
448 // for this method is in preparing the state created during a refresh walk,
449 // where we run the planning step for certain instances just to create enough
450 // information to allow correct expression evaluation within provider and
451 // data resource blocks. Discarding planned instances in that case is okay
452 // because the refresh phase only creates planned objects to stand in for
453 // objects that don't exist yet, and thus the planned object must have been
454 // absent before by definition.
455 func (s *SyncState) RemovePlannedResourceInstanceObjects() {
456 // TODO: Merge together the refresh and plan phases into a single walk,
457 // so we can remove the need to create this "partial plan" during refresh
458 // that we then need to clean up before proceeding.
461 defer s.lock.Unlock()
463 for _, ms := range s.state.Modules {
464 moduleAddr := ms.Addr
466 for _, rs := range ms.Resources {
469 for ik, is := range rs.Instances {
470 instAddr := resAddr.Instance(ik)
472 if is.Current != nil && is.Current.Status == ObjectPlanned {
473 // Setting the current instance to nil removes it from the
474 // state altogether if there are not also deposed instances.
475 ms.SetResourceInstanceCurrent(instAddr, nil, rs.ProviderConfig)
478 for dk, obj := range is.Deposed {
479 // Deposed objects should never be "planned", but we'll
480 // do this anyway for the sake of completeness.
481 if obj.Status == ObjectPlanned {
482 ms.ForgetResourceInstanceDeposed(instAddr, dk)
488 // We may have deleted some objects, which means that we may have
489 // left a module empty, and so we must prune to preserve the invariant
490 // that only the root module is allowed to be empty.
491 s.maybePruneModule(moduleAddr)
495 // Lock acquires an explicit lock on the state, allowing direct read and write
496 // access to the returned state object. The caller must call Unlock once
497 // access is no longer needed, and then immediately discard the state pointer
500 // Most callers should not use this. Instead, use the concurrency-safe
501 // accessors and mutators provided directly on SyncState.
502 func (s *SyncState) Lock() *State {
507 // Unlock releases a lock previously acquired by Lock, at which point the
508 // caller must cease all use of the state pointer that was returned.
510 // Do not call this method except to end an explicit lock acquired by
511 // Lock. If a caller calls Unlock without first holding the lock, behavior
513 func (s *SyncState) Unlock() {
517 // maybePruneModule will remove a module from the state altogether if it is
518 // empty, unless it's the root module which must always be present.
520 // This helper method is not concurrency-safe on its own, so must only be
521 // called while the caller is already holding the lock for writing.
522 func (s *SyncState) maybePruneModule(addr addrs.ModuleInstance) {
524 // We never prune the root.
528 ms := s.state.Module(addr)
534 log.Printf("[TRACE] states.SyncState: pruning %s because it is empty", addr)
535 s.state.RemoveModule(addr)