Class: CMDx::Chain

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Defined in:
lib/cmdx/chain.rb

Overview

Manages a collection of task execution results in a thread and fiber safe manner. Chains provide a way to track related task executions and their outcomes within the same execution context.

Constant Summary collapse

CONCURRENCY_KEY =

Rbs:

  • CONCURRENCY_KEY: Symbol

:cmdx_chain

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(dry_run: false) ⇒ Chain

Creates a new chain with a unique identifier and empty results collection.

Rbs:

  • () -> void



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

def initialize(dry_run: false)
  @mutex = Mutex.new
  @id = Identifier.generate
  @results = []
  @dry_run = !!dry_run
end

Instance Attribute Details

#id ⇒ String (readonly)

Returns the unique identifier for this chain.

Examples:

chain.id # => "abc123xyz"

Returns:

  • (String) —

    The chain identifier

Rbs:

  • @id: String



22
23
24
 
# File 'lib/cmdx/chain.rb', line 22

def id
  @id
end

#results ⇒ Array<Result> (readonly)

Returns the collection of execution results in this chain.

Examples:

chain.results # => [#<Result>, #<Result>]

Returns:

  • (Array<Result>) —

    Array of task results

Rbs:



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

def results
  @results
end

Class Method Details

.build(result, dry_run: false) ⇒ Chain

Builds or extends the current chain by adding a result. Creates a new chain if none exists, otherwise appends to the current one.

Examples:

result = task.execute
chain = Chain.build(result)
puts "Chain size: #{chain.size}"

Parameters:

  • result (Result) —

    The task execution result to add

Returns:

  • (Chain) —

    The current chain (newly created or existing)

Raises:

  • (TypeError) —

    If result is not a CMDx::Result instance

Rbs:

  • (Result result) -> Chain



107
108
109
110
111
112
113
 
# File 'lib/cmdx/chain.rb', line 107

def build(result, dry_run: false)
  raise TypeError, "must be a CMDx::Result" unless result.is_a?(Result)

  self.current ||= new(dry_run:)
  current.push(result)
  current
end

.clear ⇒ nil

Clears the current chain for the current execution context.

Examples:

Chain.clear

Returns:

  • (nil) —

    Always returns nil

Rbs:

  • () -> nil



88
89
90
 
# File 'lib/cmdx/chain.rb', line 88

def clear
  thread_or_fiber[CONCURRENCY_KEY] = nil
end

.current ⇒ Chain?

Retrieves the current chain for the current execution context.

Examples:

chain = Chain.current
if chain
  puts "Current chain: #{chain.id}"
end

Returns:

  • (Chain, nil) —

    The current chain or nil if none exists

Rbs:

  • () -> Chain?



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

def current
  thread_or_fiber[CONCURRENCY_KEY]
end

.current=(chain) ⇒ Chain

Sets the current chain for the current execution context.

Examples:

Chain.current = my_chain

Parameters:

  • chain (Chain) —

    The chain to set as current

Returns:

  • (Chain) —

    The set chain

Rbs:

  • (Chain chain) -> Chain



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

def current=(chain)
  thread_or_fiber[CONCURRENCY_KEY] = chain
end

Instance Method Details

#dry_run? ⇒ Boolean

Returns whether the chain is running in dry-run mode.

Examples:

chain.dry_run? # => true

Returns:

  • (Boolean) —

    Whether the chain is running in dry-run mode

Rbs:

  • () -> bool



164
165
166
 
# File 'lib/cmdx/chain.rb', line 164

def dry_run?
  !!@dry_run
end

#freeze ⇒ Chain

Freezes the chain and its internal results to prevent modifications.

Examples:

chain.freeze
chain.results << result # => raises FrozenError

Returns:

  • (Chain) —

    the frozen chain

Rbs:

  • () -> self



177
178
179
180
 
# File 'lib/cmdx/chain.rb', line 177

def freeze
  results.freeze
  super
end

#index(result) ⇒ Integer?

Thread-safe lookup of a result’s position in the chain.

Parameters:

  • result (Result) —

    The result to find

Returns:

  • (Integer, nil) —

    The zero-based index or nil if not found

Rbs:

  • (Result result) -> Integer?



152
153
154
 
# File 'lib/cmdx/chain.rb', line 152

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

#push(result) ⇒ Array<Result>

Thread-safe append of a result to the chain. Caches the result’s index to avoid repeated O(n) lookups.

Parameters:

  • result (Result) —

    The result to append

Returns:

  • (Array<Result>) —

    The updated results array

Rbs:

  • (Result result) -> Array



138
139
140
141
142
143
 
# File 'lib/cmdx/chain.rb', line 138

def push(result)
  @mutex.synchronize do
    result.instance_variable_set(:@chain_index, @results.size)
    @results << result
  end
end

#to_h ⇒ Hash

Converts the chain to a hash representation.

Examples:

chain_hash = chain.to_h
puts chain_hash[:id]
puts chain_hash[:results].size

Parameters:

  • return (Hash) —

    a customizable set of options

Returns:

  • (Hash) —

    Hash containing chain id and serialized results

Rbs:

  • () -> Hash[Symbol, untyped]



195
196
197
198
199
200
201
 
# File 'lib/cmdx/chain.rb', line 195

def to_h
  {
    id:,
    dry_run: dry_run?,
    results: results.map(&:to_h)
  }
end

#to_s ⇒ String

Converts the chain to a string representation.

Examples:

puts chain.to_s

Returns:

  • (String) —

    Formatted string representation of the chain

Rbs:

  • () -> String



211
212
213
 
# File 'lib/cmdx/chain.rb', line 211

def to_s
  Utils::Format.to_str(to_h)
end