Class: Legion::Extensions::Llm::Inventory::CallableHandle

Inherits:
Object
  • Object
show all
Includes:
Logging::Helper
Defined in:
lib/legion/extensions/llm/inventory/callable_handle.rb

Overview

Owns the acquire/retire lifecycle for one provider callable. The handle's object identity is stable while its state moves ACTIVE -> RETIRING -> DISPOSED under a private Mutex. Retiring an old handle cannot disconnect a distinct new callable because a new claim must supply a distinct callable object. See section 11.4.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(handle_id:, callable:) ⇒ CallableHandle

Returns a new instance of CallableHandle.

Raises:



50
51
52
53
54
55
56
57
58
59
60
 
# File 'lib/legion/extensions/llm/inventory/callable_handle.rb', line 50

def initialize(handle_id:, callable:)
  raise Errors::ValidationError, 'handle_id must be a non-empty String' unless nonempty_string?(handle_id)
  raise Errors::ValidationError, 'callable must not be nil' if callable.nil?

  @handle_id = handle_id.dup.freeze
  @callable = callable
  @state = :active
  @reference_count = 0
  @disposed_with_error = false
  @mutex = Mutex.new
end

Instance Attribute Details

#handle_id ⇒ Object (readonly)

Returns the value of attribute handle_id.



48
49
50
 
# File 'lib/legion/extensions/llm/inventory/callable_handle.rb', line 48

def handle_id
  @handle_id
end

Instance Method Details

#acquire ⇒ Object 



70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
 
# File 'lib/legion/extensions/llm/inventory/callable_handle.rb', line 70

def acquire
  @mutex.synchronize do
    case @state
    when :retiring
      raise Errors::StaleCallableError, "callable handle #{@handle_id} is retiring"
    when :disposed
      raise Errors::CallableDisposedError, "callable handle #{@handle_id} is disposed"
    end

    @reference_count += 1
    DispatchLease.new(
      lease_id: "lease:v1:#{SecureRandom.uuid}", callable_handle: self, callable: @callable
    )
  end
end

#reference_count ⇒ Object 



66
67
68
 
# File 'lib/legion/extensions/llm/inventory/callable_handle.rb', line 66

def reference_count
  @mutex.synchronize { @reference_count }
end

#retire ⇒ Object 



86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/legion/extensions/llm/inventory/callable_handle.rb', line 86

def retire
  @mutex.synchronize do
    case @state
    when :disposed
      return @disposed_with_error ? :disposed_with_error : :disposed
    when :retiring
      return :retiring
    end

    @state = :retiring
    return :retiring if @reference_count.positive?

    dispose_locked
  end
end

#state ⇒ Object 



62
63
64
 
# File 'lib/legion/extensions/llm/inventory/callable_handle.rb', line 62

def state
  @mutex.synchronize { @state }
end