Class: CMDx::Chain

Inherits:
Object
  • Object
show all
Includes:
Enumerable
Defined in:
lib/cmdx/chain.rb

Overview

Ordered collection of Results produced by a top-level task and any nested tasks it triggers. A Chain is stored per-fiber so concurrent workflows (see Pipeline parallel strategy) each get their own. The root Runtime clears the chain on teardown.

Constant Summary collapse

STORAGE_KEY =

Fiber-local storage key used by current/current=/clear.

:cmdx_chain

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(xid = nil) ⇒ Chain

Returns a new instance of Chain.

Parameters:

  • xid (String, nil) (defaults to: nil) —

    external correlation id (e.g. Rails ‘request_id`) shared across every Result in this chain. Resolved once by Runtime from Configuration#xid when the root chain is created.



42
43
44
45
46
47
 
# File 'lib/cmdx/chain.rb', line 42

def initialize(xid = nil)
  @xid     = xid
  @id      = SecureRandom.uuid_v7
  @mutex   = Mutex.new
  @results = []
end

Instance Attribute Details

#id ⇒ Object (readonly)

Returns the value of attribute id.



37
38
39
 
# File 'lib/cmdx/chain.rb', line 37

def id
  @id
end

#results ⇒ Object (readonly)

Returns the value of attribute results.



37
38
39
 
# File 'lib/cmdx/chain.rb', line 37

def results
  @results
end

#xid ⇒ Object (readonly)

Returns the value of attribute xid.



37
38
39
 
# File 'lib/cmdx/chain.rb', line 37

def xid
  @xid
end

Class Method Details

.clear ⇒ nil

Clears the fiber-local chain reference.

Returns:

  • (nil) 


31
32
33
 
# File 'lib/cmdx/chain.rb', line 31

def clear
  Fiber[STORAGE_KEY] = nil
end

.current ⇒ Chain?

Returns the chain active on the current fiber, or nil outside execution.

Returns:

  • (Chain, nil) —

    the chain active on the current fiber, or nil outside execution



18
19
20
 
# File 'lib/cmdx/chain.rb', line 18

def current
  Fiber[STORAGE_KEY]
end

.current=(chain) ⇒ Chain?

Installs ‘chain` as the active chain on the current fiber.

Parameters:

Returns:



25
26
27
 
# File 'lib/cmdx/chain.rb', line 25

def current=(chain)
  Fiber[STORAGE_KEY] = chain
end

Instance Method Details

#each {|Result| ... } ⇒ Enumerator, Chain

Yields:

  • (Result) —

    each result in insertion order

Returns:



106
107
108
 
# File 'lib/cmdx/chain.rb', line 106

def each(&)
  @results.each(&)
end

#empty? ⇒ Boolean

Returns:

  • (Boolean) 


95
96
97
 
# File 'lib/cmdx/chain.rb', line 95

def empty?
  @results.empty?
end

#freeze ⇒ Chain

Freezes the chain and its results. Called by Runtime teardown.

Returns:



113
114
115
116
 
# File 'lib/cmdx/chain.rb', line 113

def freeze
  @mutex.synchronize { @results.freeze }
  super
end

#index(result) ⇒ Integer?

Returns zero-based position of ‘result`, or nil when absent.

Parameters:

Returns:

  • (Integer, nil) —

    zero-based position of ‘result`, or nil when absent



70
71
72
 
# File 'lib/cmdx/chain.rb', line 70

def index(result)
  @results.index(result)
end

#last ⇒ Result?

Returns the most recently appended result.

Returns:

  • (Result, nil) —

    the most recently appended result



75
76
77
 
# File 'lib/cmdx/chain.rb', line 75

def last
  @results.last
end

#push(result) ⇒ Chain Also known as: <<

Appends ‘result` to the chain. Thread-safe to support parallel pipelines.

Parameters:

Returns:

  • (Chain) —

    self for chaining



53
54
55
56
 
# File 'lib/cmdx/chain.rb', line 53

def push(result)
  @mutex.synchronize { @results << result }
  self
end

#root ⇒ Result?

Returns the root result, or nil when absent.

Returns:

  • (Result, nil) —

    the root result, or nil when absent



80
81
82
 
# File 'lib/cmdx/chain.rb', line 80

def root
  @results.find(&:root?)
end

#size ⇒ Integer

Returns:

  • (Integer) 


100
101
102
 
# File 'lib/cmdx/chain.rb', line 100

def size
  @results.size
end

#state ⇒ String?

Returns the state of the root result, or nil when absent.

Returns:

  • (String, nil) —

    the state of the root result, or nil when absent



85
86
87
 
# File 'lib/cmdx/chain.rb', line 85

def state
  root&.state
end

#status ⇒ String?

Returns the status of the root result, or nil when absent.

Returns:

  • (String, nil) —

    the status of the root result, or nil when absent



90
91
92
 
# File 'lib/cmdx/chain.rb', line 90

def status
  root&.status
end

#unshift(result) ⇒ Chain

Prepends ‘result` to the chain. Thread-safe to support parallel pipelines.

Parameters:

Returns:

  • (Chain) —

    self for chaining



63
64
65
66
 
# File 'lib/cmdx/chain.rb', line 63

def unshift(result)
  @mutex.synchronize { @results.unshift(result) }
  self
end