class Bundler::ConnectionPool::TimedStack - bundler: Ruby Standard Library Documentation

# class Bundler::ConnectionPool::TimedStack

Examples:

    ts = TimedStack.new(1) { MyConnection.new }

    # fetch a connection
    conn = ts.pop

    # return a connection
    ts.push conn

    conn = ts.pop
    ts.pop timeout: 5
    #=> raises Bundler::ConnectionPool::TimeoutError after 5 seconds

### Attributes

max[R]

### Public Class Methods

new(size = 0, &block) click to toggle source

Creates a new pool with `size` connections that are created from the given `block`.

    # File bundler/vendor/connection_pool/lib/connection_pool/timed_stack.rb, line 27
    def initialize(size = 0, &block)
      @create_block = block
      @created = 0
      @que = []
      @max = size
      @mutex = Thread::Mutex.new
      @resource = Thread::ConditionVariable.new
      @shutdown_block = nil
    end

### Public Instance Methods

<<(obj, options = {})
Alias for: push
empty?() click to toggle source

Returns `true` if there are no available connections.

    # File bundler/vendor/connection_pool/lib/connection_pool/timed_stack.rb, line 104
    def empty?
      (@created - @que.length) >= @max
    end

length() click to toggle source

The number of connections available on the stack.

    # File bundler/vendor/connection_pool/lib/connection_pool/timed_stack.rb, line 111
    def length
      @max - @created + @que.length
    end

pop(timeout = 0.5, options = {}) click to toggle source

Retrieves a connection from the stack. If a connection is available it is immediately returned. If no connection is available within the given timeout a `Bundler::ConnectionPool::TimeoutError` is raised.

`:timeout` is the only checked entry in `options` and is preferred over the `timeout` argument (which will be removed in a future release). Other options may be used by subclasses that extend `TimedStack`.

    # File bundler/vendor/connection_pool/lib/connection_pool/timed_stack.rb, line 63
    def pop(timeout = 0.5, options = {})
      options, timeout = timeout, 0.5 if Hash === timeout
      timeout = options.fetch :timeout, timeout

      deadline = current_time + timeout
      @mutex.synchronize do
        loop do
          raise Bundler::ConnectionPool::PoolShuttingDownError if @shutdown_block
          return fetch_connection(options) if connection_stored?(options)

          connection = try_create(options)
          return connection if connection

          to_wait = deadline - current_time
          raise Bundler::ConnectionPool::TimeoutError, "Waited #{timeout} sec, #{length}/#{@max} available" if to_wait <= 0
          @resource.wait(@mutex, to_wait)
        end
      end
    end

push(obj, options = {}) click to toggle source

Returns `obj` to the stack. `options` is ignored in `TimedStack` but may be used by subclasses that extend `TimedStack`.

    # File bundler/vendor/connection_pool/lib/connection_pool/timed_stack.rb, line 41
    def push(obj, options = {})
      @mutex.synchronize do
        if @shutdown_block
          @shutdown_block.call(obj)
        else
          store_connection obj, options
        end

        @resource.broadcast
      end
    end

Also aliased as: <<
shutdown(reload: false, &block) click to toggle source

Shuts down the `TimedStack` by passing each connection to `block` and then removing it from the pool. Attempting to checkout a connection after shutdown will raise `Bundler::ConnectionPool::PoolShuttingDownError` unless `:reload` is `true`.

    # File bundler/vendor/connection_pool/lib/connection_pool/timed_stack.rb, line 89
    def shutdown(reload: false, &block)
      raise ArgumentError, "shutdown must receive a block" unless block

      @mutex.synchronize do
        @shutdown_block = block
        @resource.broadcast

        shutdown_connections
        @shutdown_block = nil if reload
      end
    end

### Private Instance Methods

connection_stored?(options = nil) click to toggle source

This is an extension point for `TimedStack` and is called with a mutex.

This method must returns true if a connection is available on the stack.

    # File bundler/vendor/connection_pool/lib/connection_pool/timed_stack.rb, line 126
    def connection_stored?(options = nil)
      !@que.empty?
    end

current_time() click to toggle source

    # File bundler/vendor/connection_pool/lib/connection_pool/timed_stack.rb, line 117
    def current_time
      Process.clock_gettime(Process::CLOCK_MONOTONIC)
    end

fetch_connection(options = nil) click to toggle source

This is an extension point for `TimedStack` and is called with a mutex.

This method must return a connection from the stack.

    # File bundler/vendor/connection_pool/lib/connection_pool/timed_stack.rb, line 135
    def fetch_connection(options = nil)
      @que.pop
    end

shutdown_connections(options = nil) click to toggle source

This is an extension point for `TimedStack` and is called with a mutex.

This method must shut down all connections on the stack.

    # File bundler/vendor/connection_pool/lib/connection_pool/timed_stack.rb, line 144
    def shutdown_connections(options = nil)
      while connection_stored?(options)
        conn = fetch_connection(options)
        @shutdown_block.call(conn)
      end
      @created = 0
    end

store_connection(obj, options = nil) click to toggle source

This is an extension point for `TimedStack` and is called with a mutex.

This method must return `obj` to the stack.

    # File bundler/vendor/connection_pool/lib/connection_pool/timed_stack.rb, line 157
    def store_connection(obj, options = nil)
      @que.push obj
    end

try_create(options = nil) click to toggle source

This is an extension point for `TimedStack` and is called with a mutex.

This method must create a connection if and only if the total number of connections allowed has not been met.

    # File bundler/vendor/connection_pool/lib/connection_pool/timed_stack.rb, line 167
    def try_create(options = nil)
      unless @created == @max
        object = @create_block.call
        @created += 1
        object
      end
    end