Module: Semian

Extended by:
Semian, Instrumentable
Included in:
Semian
Defined in:
lib/semian.rb,
lib/semian/adapter.rb,
lib/semian/version.rb,
lib/semian/platform.rb,
lib/semian/resource.rb,
lib/semian/simple_state.rb,
lib/semian/instrumentable.rb,
lib/semian/simple_integer.rb,
lib/semian/circuit_breaker.rb,
lib/semian/protected_resource.rb,
lib/semian/unprotected_resource.rb,
lib/semian/simple_sliding_window.rb,
lib/semian/net_http.rb,
lib/semian/mysql2.rb,
lib/semian/redis.rb

Overview

Overview

Semian is a library that can be used to control access to external services.

It’s desirable to control access to external services so that in the case that one is slow or not responding, the performance of an entire system is not compromised.

Semian uses the concept of a “resource” as an identifier that controls access to some external service. So for example, “mysql” or “redis” would be considered resources. If a system is sharded, like a database, you would typically create a resource for every shard.

Resources are visible across an IPC namespace. This means that you can register a resource in one process and access it from another. This is useful in application servers like Unicorn that are multi-process. A resource is persistent. It will continue to exist even after the application exits, and will only be destroyed by manually removing it with the ipcrm command, calling Resource.destroy, or rebooting the machine.

Each resource has a configurable number of tickets. Tickets are what controls access to the external service. If a client does not have a ticket, it cannot access a service. If there are no tickets available, the client will block for a configurable amount of time until a ticket is available. If there are no tickets available after the timeout period has elapsed, the client will be unable to access the service and an error will be raised.

Resources also integrate a circuit breaker in order to fail faster and to let the resource the time to recover. If ‘error_threshold` errors happen in the span of `error_timeout` then the circuit will be opened and every attempt to acquire the resource will immediately fail.

Once in open state, after ‘error_timeout` is elapsed, the ciruit will transition in the half-open state. In that state a single error will fully re-open the circuit, and the circuit will transition back to the closed state only after the resource is acquired `success_threshold` consecutive times.

A resource is registered by using the Semian.register method.

Examples

Registering a resource
Semian.register(:mysql_shard0, tickets: 10, timeout: 0.5, error_threshold: 3, error_timeout: 10, success_threshold: 2)

This registers a new resource called :mysql_shard0 that has 10 tickets and a default timeout of 500 milliseconds.

After 3 failures in the span of 10 seconds the circuit will be open. After an additional 10 seconds it will transition to half-open. And finally after 2 successulf acquisitions of the resource it will transition back to the closed state.

Using a resource
Semian[:mysql_shard0].acquire do
  # Perform a MySQL query here
end

This acquires a ticket for the :mysql_shard0 resource. If we use the example above, the ticket count would be lowered to 9 when block is executed, then raised to 10 when the block completes.

Overriding the default timeout
Semian[:mysql_shard0].acquire(timeout: 1) do
  # Perform a MySQL query here
end

This is the same as the previous example, but overrides the timeout from the default value of 500 milliseconds to 1 second.

Defined Under Namespace

Modules: Adapter, AdapterError, Instrumentable, Mysql2, NetHTTP, Redis, Simple, ThreadSafe Classes: CircuitBreaker, InternalError, ProtectedResource, Resource, SyscallError, TimeoutError, UnprotectedResource

Constant Summary collapse

BaseError = 
Class.new(StandardError)
OpenCircuitError = 
Class.new(BaseError)
MAX_TICKETS =

Maximum number of tickets available on this system.

INT2FIX(system_max_semaphore_count)
VERSION = 
'0.7.9'

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Instrumentable

notify, subscribe, unsubscribe

Instance Attribute Details

#logger ⇒ Object

Returns the value of attribute logger.



114
115
116
 
# File 'lib/semian.rb', line 114

def logger
  @logger
end

Instance Method Details

#[](name) ⇒ Object

Retrieves a resource by name.



176
177
178
 
# File 'lib/semian.rb', line 176

def [](name)
  resources[name]
end

#consumers ⇒ Object

Retrieves a hash of all registered resource consumers.



223
224
225
 
# File 'lib/semian.rb', line 223

def consumers
  @consumers ||= {}
end

#destroy(name) ⇒ Object 



180
181
182
183
184
 
# File 'lib/semian.rb', line 180

def destroy(name)
  if resource = resources.delete(name)
    resource.destroy
  end
end

#disabled? ⇒ Boolean

Returns:

  • (Boolean) 


13
14
15
 
# File 'lib/semian/platform.rb', line 13

def disabled?
  ENV['SEMIAN_SEMAPHORES_DISABLED'] || ENV['SEMIAN_DISABLED']
end

#issue_disabled_semaphores_warning ⇒ Object 



92
93
94
95
96
97
98
99
100
 
# File 'lib/semian.rb', line 92

def issue_disabled_semaphores_warning
  return if defined?(@warning_issued)
  @warning_issued = true
  if !sysv_semaphores_supported?
    logger.info("Semian sysv semaphores are not supported on #{RUBY_PLATFORM} - all operations will no-op")
  elsif disabled?
    logger.info("Semian semaphores are disabled, is this what you really want? - all operations will no-op")
  end
end

#register(name, **options) ⇒ Object

Registers a resource.

name: Name of the resource - this can be either a string or symbol. (required)

circuit_breaker: The boolean if you want a circuit breaker acquired for your resource. Default true.

bulkhead: The boolean if you want a bulkhead to be acquired for your resource. Default true.

tickets: Number of tickets. If this value is 0, the ticket count will not be set, but the resource must have been previously registered otherwise an error will be raised. Mutually exclusive with the ‘quota’ argument.

quota: Calculate tickets as a ratio of the number of registered workers. Must be greater than 0, less than or equal to 1. There will always be at least 1 ticket, as it is calculated as (workers * quota).ceil Mutually exclusive with the ‘ticket’ argument. but the resource must have been previously registered otherwise an error will be raised. (bulkhead)

permissions: Octal permissions of the resource. Default 0660. (bulkhead)

timeout: Default timeout in seconds. Default 0. (bulkhead)

error_threshold: The number of errors that will trigger the circuit opening. (circuit breaker required)

error_timeout: The duration in seconds since the last error after which the error count is reset to 0. (circuit breaker required)

success_threshold: The number of consecutive success after which an half-open circuit will be fully closed. (circuit breaker required)

exceptions: An array of exception classes that should be accounted as resource errors. Default []. (circuit breaker)

Returns the registered resource.



152
153
154
155
156
157
158
159
160
161
 
# File 'lib/semian.rb', line 152

def register(name, **options)
  circuit_breaker = create_circuit_breaker(name, **options)
  bulkhead = create_bulkhead(name, **options)

  if circuit_breaker.nil? && bulkhead.nil?
    raise ArgumentError, 'Both bulkhead and circuitbreaker cannot be disabled.'
  end

  resources[name] = ProtectedResource.new(name, bulkhead, circuit_breaker)
end

#reset! ⇒ Object 



227
228
229
230
 
# File 'lib/semian.rb', line 227

def reset!
  @consumers = {}
  @resources = {}
end

#resources ⇒ Object

Retrieves a hash of all registered resources.



218
219
220
 
# File 'lib/semian.rb', line 218

def resources
  @resources ||= {}
end

#retrieve_or_register(name, **args) ⇒ Object 



163
164
165
166
167
168
169
170
171
172
173
 
# File 'lib/semian.rb', line 163

def retrieve_or_register(name, **args)
  # If consumer who retrieved / registered by a Semian::Adapter, keep track
  # of who the consumer was so that we can clear the resource reference if needed.
  if consumer = args.delete(:consumer)
    if consumer.class.include?(Semian::Adapter)
      consumers[name] ||= []
      consumers[name] << WeakRef.new(consumer)
    end
  end
  self[name] || register(name, **args)
end

#semaphores_enabled? ⇒ Boolean

Returns:

  • (Boolean) 


9
10
11
 
# File 'lib/semian/platform.rb', line 9

def semaphores_enabled?
  !disabled? && sysv_semaphores_supported?
end

#sysv_semaphores_supported? ⇒ Boolean

Determines if Semian supported on the current platform.

Returns:

  • (Boolean) 


5
6
7
 
# File 'lib/semian/platform.rb', line 5

def sysv_semaphores_supported?
  /linux/.match(RUBY_PLATFORM)
end

#unregister(name) ⇒ Object

Unregister will not destroy the semian resource, but it will remove it from the hash of registered resources, and decrease the number of registered workers. Semian.destroy removes the underlying resource, but Semian.unregister will remove all references, while preserving the underlying semian resource (and sysV semaphore). Also clears any semian_resources in use by any semian adapters if the weak reference is still alive.



194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
 
# File 'lib/semian.rb', line 194

def unregister(name)
  if resource = resources.delete(name)
    resource.bulkhead.unregister_worker if resource.bulkhead
    consumers_for_resource = consumers.delete(name) || []
    consumers_for_resource.each do |consumer|
      begin
        if consumer.weakref_alive?
          consumer.clear_semian_resource
        end
      rescue WeakRef::RefError
        next
      end
    end
  end
end

#unregister_all_resources ⇒ Object

Unregisters all resources



211
212
213
214
215
 
# File 'lib/semian.rb', line 211

def unregister_all_resources
  resources.keys.each do |resource|
    unregister(resource)
  end
end