Class: BreakerMachines::Circuit::Native

Inherits:
Object
  • Object
show all
Defined in:
lib/breaker_machines/circuit/native.rb

Overview

Native circuit breaker implementation using Rust FFI

This provides a high-performance circuit breaker with state machine logic implemented in Rust. It’s fully compatible with the Ruby circuit API but significantly faster for high-throughput scenarios.

Examples:

Basic usage

circuit = BreakerMachines::Circuit::Native.new('api_calls',
  failure_threshold: 5,
  failure_window_secs: 60.0
)

circuit.call { api.fetch_data }

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(name, options = {}) ⇒ Native

Create a new native circuit breaker

Parameters:

  • name (String) —

    Circuit name

  • options (Hash) (defaults to: {}) —

    Configuration options

Options Hash (options):

  • :failure_threshold (Integer) —

    Number of failures to open circuit (default: 5)

  • :failure_window_secs (Float) —

    Time window for counting failures (default: 60.0)

  • :half_open_timeout_secs (Float) —

    Timeout before attempting reset (default: 30.0)

  • :success_threshold (Integer) —

    Successes needed to close from half-open (default: 2)

  • :auto_register (Boolean) —

    Register with global registry (default: true)



34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
 
# File 'lib/breaker_machines/circuit/native.rb', line 34

def initialize(name, options = {})
  unless BreakerMachines.native_available?
    raise BreakerMachines::ConfigurationError,
          'Native extension not available. Install with native support or use Circuit::Ruby'
  end

  @name = name
  @config = default_config.merge(options)

  # Create the native circuit breaker
  @native_circuit = BreakerMachinesNative::Circuit.new(
    name,
    {
      failure_threshold: @config[:failure_threshold],
      failure_window_secs: @config[:failure_window_secs],
      half_open_timeout_secs: @config[:half_open_timeout_secs],
      success_threshold: @config[:success_threshold]
    }
  )

  # Register with global registry unless disabled
  BreakerMachines::Registry.instance.register(self) unless @config[:auto_register] == false
end

Instance Attribute Details

#config ⇒ Hash (readonly)

Returns Circuit configuration.

Returns:

  • (Hash) —

    Circuit configuration



23
24
25
 
# File 'lib/breaker_machines/circuit/native.rb', line 23

def config
  @config
end

#name ⇒ String (readonly)

Returns Circuit name.

Returns:

  • (String) —

    Circuit name



20
21
22
 
# File 'lib/breaker_machines/circuit/native.rb', line 20

def name
  @name
end

Instance Method Details

#call { ... } ⇒ Object

Execute a block with circuit breaker protection

Yields:

  • Block to execute

Returns:

  • Result of the block

Raises:



63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
 
# File 'lib/breaker_machines/circuit/native.rb', line 63

def call
  raise CircuitOpenError, "Circuit '#{@name}' is open" if open?

  start_time = BreakerMachines.monotonic_time
  begin
    result = yield
    duration = BreakerMachines.monotonic_time - start_time
    @native_circuit.record_success(duration)
    result
  rescue StandardError => _e
    duration = BreakerMachines.monotonic_time - start_time
    @native_circuit.record_failure(duration)
    raise
  end
end

#closed? ⇒ Boolean

Check if circuit is closed

Returns:

  • (Boolean) 


87
88
89
 
# File 'lib/breaker_machines/circuit/native.rb', line 87

def closed?
  @native_circuit.is_closed
end

#open? ⇒ Boolean

Check if circuit is open

Returns:

  • (Boolean) 


81
82
83
 
# File 'lib/breaker_machines/circuit/native.rb', line 81

def open?
  @native_circuit.is_open
end

#reset! ⇒ Object

Reset the circuit (clear all events)



98
99
100
 
# File 'lib/breaker_machines/circuit/native.rb', line 98

def reset!
  @native_circuit.reset
end

#state ⇒ String

Get current state name

Returns:

  • (String) —

    ‘open’ or ‘closed’



93
94
95
 
# File 'lib/breaker_machines/circuit/native.rb', line 93

def state
  @native_circuit.state_name
end

#status ⇒ Hash

Get circuit status for inspection

Returns:

  • (Hash) —

    Status information



104
105
106
107
108
109
110
111
112
 
# File 'lib/breaker_machines/circuit/native.rb', line 104

def status
  {
    name: @name,
    state: state,
    open: open?,
    closed: closed?,
    config: @config
  }
end