Class: Faulty::Storage::Interface

Inherits:
Object
  • Object
show all
Defined in:
lib/faulty/storage/interface.rb

Overview

The interface required for a storage backend implementation

This is for documentation only and is not loaded

Instance Method Summary collapse

Instance Method Details

#close(circuit) ⇒ Boolean

Set the circuit state to closed

If multiple parallel processes close the circuit simultaneously, close may be called more than once. If so, this method should return true only once, when the circuit transitions from open to closed.

If the backend does not support locking or atomic operations, then it may always return true, but that could result in duplicate close notifications.

Returns:

  • (Boolean) —

    True if the circuit transitioned from open to closed

Raises:

  • (NotImplementedError) 


74
75
76
 
# File 'lib/faulty/storage/interface.rb', line 74

def close(circuit)
  raise NotImplementedError
end

#entry(circuit, time, success) ⇒ Array<Array>

Add a circuit run entry to storage

The backend may choose to store this in whatever manner it chooses as long as it can implement the other read methods.

Parameters:

  • circuit (Circuit) —

    The circuit that ran

  • time (Integer) —

    The unix timestamp for the run

  • success (Boolean) —

    True if the run succeeded

Returns:

  • (Array<Array>) —

    An array of the new history tuples after adding the new entry, see #history

Raises:

  • (NotImplementedError) 


19
20
21
 
# File 'lib/faulty/storage/interface.rb', line 19

def entry(circuit, time, success)
  raise NotImplementedError
end

#fault_tolerant? ⇒ Boolean

Can this storage backend raise an error?

If the storage backend returns false from this method, it will be wrapped in a FaultTolerantProxy, otherwise it will be used as-is.

Returns:

  • (Boolean) —

    True if this cache backend is fault tolerant

Raises:

  • (NotImplementedError) 


157
158
159
 
# File 'lib/faulty/storage/interface.rb', line 157

def fault_tolerant?
  raise NotImplementedError
end

#history(circuit) ⇒ Array<Array>

Get the entry history of a circuit

No concurrency gurantees are provided for getting status. It's possible that status may represent a circuit in the middle of modification.

A storage backend may choose not to implement this method and instead return an empty array.

Each item in the history array is an array of two items (a tuple) of [run_time, succeeded], where run_time is a unix timestamp, and succeeded is a boolean, true if the run succeeded.

Parameters:

  • circuit (Circuit) —

    The circuit to get history for

Returns:

  • (Array<Array>) —

    An array of history tuples

Raises:

  • (NotImplementedError) 


137
138
139
 
# File 'lib/faulty/storage/interface.rb', line 137

def history(circuit)
  raise NotImplementedError
end

#list ⇒ Array<String>

Get a list of all circuit names

If the storage backend does not support listing circuits, this may return an empty array.

Returns:

  • (Array<String>)

Raises:

  • (NotImplementedError) 


147
148
149
 
# File 'lib/faulty/storage/interface.rb', line 147

def list
  raise NotImplementedError
end

#lock(circuit, state) ⇒ void

This method returns an undefined value.

Lock the circuit in a given state

No concurrency gurantees are provided for locking

Parameters:

  • circuit (Circuit) —

    The circuit to lock

  • state (:open, :closed) —

    The state to lock the circuit in

Raises:

  • (NotImplementedError) 


85
86
87
 
# File 'lib/faulty/storage/interface.rb', line 85

def lock(circuit, state)
  raise NotImplementedError
end

#open(circuit, opened_at) ⇒ Boolean

Set the circuit state to open

If multiple parallel processes open the circuit simultaneously, open may be called more than once. If so, this method should return true only once, when the circuit transitions from closed to open.

If the backend does not support locking or atomic operations, then it may always return true, but that could result in duplicate open notifications.

If returning true, this method also updates opened_at to the current time.

Parameters:

  • circuit (Circuit) —

    The circuit to open

  • opened_at (Integer) —

    The timestmp the circuit was opened at

Returns:

  • (Boolean) —

    True if the circuit transitioned from closed to open

Raises:

  • (NotImplementedError) 


39
40
41
 
# File 'lib/faulty/storage/interface.rb', line 39

def open(circuit, opened_at)
  raise NotImplementedError
end

#reopen(circuit, opened_at, previous_opened_at) ⇒ Boolean

Reset the opened_at time for a half_open circuit

If multiple parallel processes open the circuit simultaneously, reopen may be called more than once. If so, this method should return true only once, when the circuit updates the opened_at value. It can use the value from previous_opened_at to do a compare-and-set operation.

If the backend does not support locking or atomic operations, then it may always return true, but that could result in duplicate reopen notifications.

Parameters:

  • circuit (Circuit) —

    The circuit to reopen

  • opened_at (Integer) —

    The timestmp the circuit was opened at

  • previous_opened_at (Integer) —

    The last known value of opened_at. Can be used to comare-and-set.

Returns:

  • (Boolean) —

    True if the opened_at time was updated

Raises:

  • (NotImplementedError) 


59
60
61
 
# File 'lib/faulty/storage/interface.rb', line 59

def reopen(circuit, opened_at, previous_opened_at)
  raise NotImplementedError
end

#reset(circuit) ⇒ void

This method returns an undefined value.

Reset the circuit to a fresh state

Clears all circuit status including entries, state, locks, opened_at, and any other values that would affect Status.

No concurrency gurantees are provided for resetting

Parameters:

  • circuit (Circuit) —

    The circuit to unlock

Raises:

  • (NotImplementedError) 


108
109
110
 
# File 'lib/faulty/storage/interface.rb', line 108

def reset(circuit)
  raise NotImplementedError
end

#status(circuit) ⇒ Status

Get the status object for a circuit

No concurrency gurantees are provided for getting status. It's possible that status may represent a circuit in the middle of modification.

Parameters:

  • circuit (Circuit) —

    The circuit to get status for

Returns:

  • (Status) —

    The current status

Raises:

  • (NotImplementedError) 


119
120
121
 
# File 'lib/faulty/storage/interface.rb', line 119

def status(circuit)
  raise NotImplementedError
end

#unlock(circuit) ⇒ void

This method returns an undefined value.

Unlock the circuit from any state

No concurrency gurantees are provided for locking

Parameters:

  • circuit (Circuit) —

    The circuit to unlock

Raises:

  • (NotImplementedError) 


95
96
97
 
# File 'lib/faulty/storage/interface.rb', line 95

def unlock(circuit)
  raise NotImplementedError
end