Module: Capistrano::Configuration::Connections

### Home Classes Methods

### In Files

- lib/capistrano/configuration/connections.rb

### Methods

- #connect!
- #connection_factory
- #establish_connections_to
- #execute_on_servers
- #failed!
- #filter_servers
- #has_failed?
- #sessions
- #teardown_connections_to

### Files

- help.txt

### Class/Module Index

Quicksearch

- Capistrano
- Capistrano::CLI
- Capistrano::CLI::Execute
- Capistrano::CLI::Execute::ClassMethods
- Capistrano::CLI::Help
- Capistrano::CLI::Options
- Capistrano::CLI::Options::ClassMethods
- Capistrano::CLI::UI
- Capistrano::CLI::UI::ClassMethods
- Capistrano::Callback
- Capistrano::Command
- Capistrano::Command::Tree
- Capistrano::Command::Tree::Branch
- Capistrano::Command::Tree::ConditionBranch
- Capistrano::Command::Tree::ConditionBranch::Evaluator
- Capistrano::Command::Tree::ElseBranch
- Capistrano::Configuration
- Capistrano::Configuration::Actions
- Capistrano::Configuration::Actions::FileTransfer
- Capistrano::Configuration::Actions::Inspect
- Capistrano::Configuration::Actions::Invocation
- Capistrano::Configuration::Actions::Invocation::ClassMethods
- Capistrano::Configuration::AliasTask
- Capistrano::Configuration::Callbacks
- Capistrano::Configuration::Connections
- Capistrano::Configuration::Execution
- Capistrano::Configuration::Loading
- Capistrano::Configuration::Loading::ClassMethods
- Capistrano::Configuration::LogFormatters
- Capistrano::Configuration::Namespaces
- Capistrano::Configuration::Namespaces::Namespace
- Capistrano::Configuration::Roles
- Capistrano::Configuration::Servers
- Capistrano::Configuration::Variables
- Capistrano::Deploy
- Capistrano::Deploy::Dependencies
- Capistrano::Deploy::LocalDependency
- Capistrano::Deploy::RemoteDependency
- Capistrano::Deploy::SCM
- Capistrano::Deploy::SCM::Accurev
- Capistrano::Deploy::SCM::Accurev::InternalRevision
- Capistrano::Deploy::SCM::Base
- Capistrano::Deploy::SCM::Base::LocalProxy
- Capistrano::Deploy::SCM::Bzr
- Capistrano::Deploy::SCM::Cvs
- Capistrano::Deploy::SCM::Darcs
- Capistrano::Deploy::SCM::Git
- Capistrano::Deploy::SCM::Mercurial
- Capistrano::Deploy::SCM::None
- Capistrano::Deploy::SCM::Perforce
- Capistrano::Deploy::SCM::Subversion
- Capistrano::Deploy::Strategy
- Capistrano::Deploy::Strategy::Base
- Capistrano::Deploy::Strategy::Checkout
- Capistrano::Deploy::Strategy::Copy
- Capistrano::Deploy::Strategy::Export
- Capistrano::Deploy::Strategy::Remote
- Capistrano::Deploy::Strategy::RemoteCache
- Capistrano::Deploy::Strategy::UnsharedRemoteCache
- Capistrano::ProcCallback
- Capistrano::Processable
- Capistrano::Processable::SessionAssociation
- Capistrano::RemoteError
- Capistrano::Role
- Capistrano::Role::DynamicServerList
- Capistrano::SSH
- Capistrano::ServerDefinition
- Capistrano::Shell
- Capistrano::TaskCallback
- Capistrano::TaskDefinition
- Capistrano::Transfer
- Capistrano::Transfer::SFTPTransferWrapper
- Capistrano::Version
- Kernel
- Object
- String

No matching classes.

# Capistrano::Configuration::Connections

### Public Instance Methods

connect!(options={}) click to toggle source

Used to force connections to be made to the current task's servers. Connections are normally made lazily in Capistrano--you can use this to force them open before performing some operation that might be time-sensitive.

    # File lib/capistrano/configuration/connections.rb, line 100
    def connect!(options={})
      execute_on_servers(options) { }
    end

connection_factory() click to toggle source

Returns the object responsible for establishing new SSH connections. The factory will respond to connect_to, which can be used to establish connections to servers defined via ServerDefinition objects.

    # File lib/capistrano/configuration/connections.rb, line 107
    def connection_factory
      @connection_factory ||= begin
        if exists?(:gateway) && !fetch(:gateway).nil? && !fetch(:gateway).empty?
          logger.debug "establishing connection to gateway `#{fetch(:gateway).inspect}'"
          GatewayConnectionFactory.new(fetch(:gateway), self)
        else
          DefaultConnectionFactory.new(self)
        end
      end
    end

establish_connections_to(servers) click to toggle source

Ensures that there are active sessions for each server in the list.

    # File lib/capistrano/configuration/connections.rb, line 119
    def establish_connections_to(servers)
      failed_servers = []

      # force the connection factory to be instantiated synchronously,
      # otherwise we wind up with multiple gateway instances, because
      # each connection is done in parallel.
      connection_factory

      threads = Array(servers).map { |server| establish_connection_to(server, failed_servers) }
      threads.each { |t| t.join }

      if failed_servers.any?
        errors = failed_servers.map { |h| "#{h[:server]} (#{h[:error].class}: #{h[:error].message})" }
        error = ConnectionError.new("connection failed for: #{errors.join(', ')}")
        error.hosts = failed_servers.map { |h| h[:server] }
        raise error
      end
    end

execute_on_servers(options={}) click to toggle source

Determines the set of servers within the current task's scope and establishes connections to them, and then yields that list of servers.

    # File lib/capistrano/configuration/connections.rb, line 182
    def execute_on_servers(options={})
      raise ArgumentError, "expected a block" unless block_given?

      task, servers = filter_servers(options)
      return if servers.empty?
      logger.trace "servers: #{servers.map { |s| s.host }.inspect}"

      max_hosts = (options[:max_hosts] || (task && task.max_hosts) || servers.size).to_i
      is_subset = max_hosts < servers.size

      # establish connections to those servers in groups of max_hosts, as necessary
      servers.each_slice(max_hosts) do |servers_slice|
        begin
          establish_connections_to(servers_slice)
        rescue ConnectionError => error
          raise error unless task && task.continue_on_error?
          error.hosts.each do |h|
            servers_slice.delete(h)
            failed!(h)
          end
        end

        begin
          yield servers_slice
        rescue RemoteError => error
          raise error unless task && task.continue_on_error?
          error.hosts.each { |h| failed!(h) }
        end

        # if dealing with a subset (e.g., :max_hosts is less than the
        # number of servers available) teardown the subset of connections
        # that were just made, so that we can make room for the next subset.
        teardown_connections_to(servers_slice) if is_subset
      end
    end

failed!(server) click to toggle source

Indicate that the given server could not be connected to.

    # File lib/capistrano/configuration/connections.rb, line 86
    def failed!(server)
      Thread.current[:failed_sessions] << server
    end

filter_servers(options={}) click to toggle source

Determines the set of servers within the current task's scope

    # File lib/capistrano/configuration/connections.rb, line 151
    def filter_servers(options={})
      if task = current_task
        servers = find_servers_for_task(task, options)

        if servers.empty?
          if ENV['HOSTFILTER'] || task.options.merge(options)[:on_no_matching_servers] == :continue
            logger.info "skipping `#{task.fully_qualified_name}' because no servers matched"
          else
            unless dry_run
              raise Capistrano::NoMatchingServersError, "`#{task.fully_qualified_name}' is only run for servers matching #{task.options.inspect}, but no servers matched"
            end
          end
        end

        if task.continue_on_error?
          servers.delete_if { |s| has_failed?(s) }
        end
      else
        servers = find_servers(options)
        if servers.empty? && !dry_run
          raise Capistrano::NoMatchingServersError, "no servers found to match #{options.inspect}" if options[:on_no_matching_servers] != :continue
        end
      end

      servers = [servers.first] if options[:once]
      [task, servers.compact]
    end

has_failed?(server) click to toggle source

Query whether previous connection attempts to the given server have failed.

    # File lib/capistrano/configuration/connections.rb, line 92
    def has_failed?(server)
      Thread.current[:failed_sessions].include?(server)
    end

sessions() click to toggle source

A hash of the SSH sessions that are currently open and available. Because sessions are constructed lazily, this will only contain connections to those servers that have been the targets of one or more executed tasks. Stored on a per-thread basis to improve thread-safety.

    # File lib/capistrano/configuration/connections.rb, line 75
    def sessions
      Thread.current[:sessions] ||= {}
    end

teardown_connections_to(servers) click to toggle source

Destroys sessions for each server in the list.

    # File lib/capistrano/configuration/connections.rb, line 139
    def teardown_connections_to(servers)
      servers.each do |server|
        begin
          session = sessions.delete(server)
          session.close if session
        rescue IOError, Net::SSH::Disconnect
          # the TCP connection is already dead
        end
      end
    end

[Validate]

Generated with the Darkfish Rdoc Generator 2.