Class Index [+]

Quicksearch

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
100:       def connect!(options={})
101:         execute_on_servers(options) { }
102:       end
connection_factory() click to toggle source

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

     # File lib/capistrano/configuration/connections.rb, line 107
107:       def connection_factory
108:         @connection_factory ||= begin
109:           if exists?(:gateway)
110:             logger.debug "establishing connection to gateway `#{fetch(:gateway).inspect}'"
111:             GatewayConnectionFactory.new(fetch(:gateway), self)
112:           else
113:             DefaultConnectionFactory.new(self)
114:           end
115:         end
116:       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
119:       def establish_connections_to(servers)
120:         failed_servers = []
121: 
122:         # force the connection factory to be instantiated synchronously,
123:         # otherwise we wind up with multiple gateway instances, because
124:         # each connection is done in parallel.
125:         connection_factory
126: 
127:         threads = Array(servers).map { |server| establish_connection_to(server, failed_servers) }
128:         threads.each { |t| t.join }
129: 
130:         if failed_servers.any?
131:           errors = failed_servers.map { |h| "#{h[:server]} (#{h[:error].class}: #{h[:error].message})" }
132:           error = ConnectionError.new("connection failed for: #{errors.join(', ')}")
133:           error.hosts = failed_servers.map { |h| h[:server] }
134:           raise error
135:         end
136:       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 152
152:       def execute_on_servers(options={})
153:         raise ArgumentError, "expected a block" unless block_given?
154: 
155:         if task = current_task
156:           servers = find_servers_for_task(task, options)
157: 
158:           if servers.empty?
159:             if ENV['HOSTFILTER'] || task.options.merge(options)[:on_no_matching_servers] == :continue
160:               logger.info "skipping `#{task.fully_qualified_name}' because no servers matched"
161:               return
162:             else
163:               raise Capistrano::NoMatchingServersError, "`#{task.fully_qualified_name}' is only run for servers matching #{task.options.inspect}, but no servers matched"
164:             end
165:           end
166: 
167:           if task.continue_on_error?
168:             servers.delete_if { |s| has_failed?(s) }
169:             return if servers.empty?
170:           end
171:         else
172:           servers = find_servers(options)
173:           if servers.empty?
174:             raise Capistrano::NoMatchingServersError, "no servers found to match #{options.inspect}" if options[:on_no_matching_servers] != :continue
175:             return
176:           end
177:         end
178: 
179:         servers = [servers.first] if options[:once]
180:         logger.trace "servers: #{servers.map { |s| s.host }.inspect}"
181: 
182:         max_hosts = (options[:max_hosts] || (task && task.max_hosts) || servers.size).to_i
183:         is_subset = max_hosts < servers.size
184: 
185:         # establish connections to those servers in groups of max_hosts, as necessary
186:         servers.each_slice(max_hosts) do |servers_slice|
187:           begin
188:             establish_connections_to(servers_slice)
189:           rescue ConnectionError => error
190:             raise error unless task && task.continue_on_error?
191:             error.hosts.each do |h|
192:               servers_slice.delete(h)
193:               failed!(h)
194:             end
195:           end
196: 
197:           begin
198:             yield servers_slice
199:           rescue RemoteError => error
200:             raise error unless task && task.continue_on_error?
201:             error.hosts.each { |h| failed!(h) }
202:           end
203: 
204:           # if dealing with a subset (e.g., :max_hosts is less than the
205:           # number of servers available) teardown the subset of connections
206:           # that were just made, so that we can make room for the next subset.
207:           teardown_connections_to(servers_slice) if is_subset
208:         end
209:       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
86:       def failed!(server)
87:         Thread.current[:failed_sessions] << server
88:       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
92:       def has_failed?(server)
93:         Thread.current[:failed_sessions].include?(server)
94:       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
75:       def sessions
76:         Thread.current[:sessions] ||= {}
77:       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
139:       def teardown_connections_to(servers)
140:         servers.each do |server|
141:           begin
142:             sessions.delete(server).close
143:           rescue IOError
144:             # the TCP connection is already dead
145:           end
146:         end
147:       end

Private Instance Methods

establish_connection_to(server, failures=nil) click to toggle source

We establish the connection by creating a thread in a new method—this prevents problems with the thread’s scope seeing the wrong ‘server’ variable if the thread just happens to take too long to start up.

     # File lib/capistrano/configuration/connections.rb, line 216
216:         def establish_connection_to(server, failures=nil)
217:           current_thread = Thread.current
218:           Thread.new { safely_establish_connection_to(server, current_thread, failures) }
219:         end
safely_establish_connection_to(server, thread, failures=nil) click to toggle source
     # File lib/capistrano/configuration/connections.rb, line 221
221:         def safely_establish_connection_to(server, thread, failures=nil)
222:           thread[:sessions] ||= {}
223:           thread[:sessions][server] ||= connection_factory.connect_to(server)
224:         rescue Exception => err
225:           raise unless failures
226:           failures << { :server => server, :error => err }
227:         end

Disabled; run with --debug to generate this.

[Validate]

Generated with the Darkfish Rdoc Generator 1.1.6.