Class: DaemonController

Inherits:
Object
  • Object
show all
Defined in:
lib/daemon_controller.rb,
lib/daemon_controller/version.rb,
lib/daemon_controller/lock_file.rb

Overview

daemon_controller, library for robust daemon management Copyright © 2010-2014 Phusion

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Defined Under Namespace

Classes: AlreadyStarted, ConnectError, DaemonizationTimeout, Error, LockFile, StartError, StartTimeout, StopError, StopTimeout, TimeoutError

Constant Summary collapse

ALLOWED_CONNECT_EXCEPTIONS = 
[Errno::ECONNREFUSED, Errno::ENETUNREACH,
Errno::ETIMEDOUT, Errno::ECONNRESET, Errno::EINVAL,
Errno::EADDRNOTAVAIL]
SPAWNER_FILE = 
File.expand_path(File.join(File.dirname(__FILE__),
"daemon_controller", "spawn.rb"))
MAJOR = 
1
MINOR = 
2
TINY = 
0
VERSION_STRING = 
"#{MAJOR}.#{MINOR}.#{TINY}"

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options) ⇒ DaemonController

Create a new DaemonController object.

Mandatory options

:identifier

A human-readable, unique name for this daemon, e.g. “Sphinx search server”. This identifier will be used in some error messages. On some platforms, it will be used for concurrency control: on such platforms, no two DaemonController objects will operate on the same identifier on the same time.

:start_command

The command to start the daemon. This must be a a String, e.g. “mongrel_rails start -e production”, or a Proc which returns a String.

If the value is a Proc, and the before_start option is given too, then the start_command Proc is guaranteed to be called after the before_start Proc is called.

:ping_command

The ping command is used to check whether the daemon can be connected to. It is also used to ensure that #start only returns when the daemon can be connected to.

The value may be a command string. This command must exit with an exit code of 0 if the daemon can be successfully connected to, or exit with a non-0 exit code on failure.

The value may also be an Array which specifies the socket address of the daemon. It must be in one of the following forms:

  • :tcp, host_name, port
  • :unix, filename

The value may also be a Proc, which returns an expression that evaluates to true (indicating that the daemon can be connected to) or false (failure). If the Proc raises Errno::ECONNREFUSED, Errno::ENETUNREACH, Errno::ETIMEDOUT Errno::ECONNRESET, Errno::EINVAL or Errno::EADDRNOTAVAIL then that also means that the daemon cannot be connected to. NOTE: if the ping command returns an object which responds to #close, then that method will be called on it. This makes it possible to specify a ping command such as lambda { TCPSocket.new('localhost', 1234) }, without having to worry about closing it afterwards. Any exceptions raised by #close are ignored.

:pid_file

The PID file that the daemon will write to. Used to check whether the daemon is running.

:lock_file

The lock file to use for serializing concurrent daemon management operations. Defaults to “(filename of PID file).lock”.

:log_file

The log file that the daemon will write to. It will be consulted to see whether the daemon has printed any error messages during startup.

Optional options

:stop_command

A command to stop the daemon with, e.g. “/etc/rc.d/nginx stop”. If no stop command is given (i.e. nil), then DaemonController will stop the daemon by killing the PID written in the PID file.

The default value is nil.

:restart_command

A command to restart the daemon with, e.g. “/etc/rc.d/nginx restart”. If no restart command is given (i.e. nil), then DaemonController will restart the daemon by calling #stop and #start.

The default value is nil.

:before_start

This may be a Proc. It will be called just before running the start command. The before_start proc is not subject to the start timeout.

:start_timeout

The maximum amount of time, in seconds, that #start may take to start the daemon. Since #start also waits until the daemon can be connected to, that wait time is counted as well. If the daemon does not start in time, then #start will raise an exception.

The default value is 15.

:stop_timeout

The maximum amount of time, in seconds, that #stop may take to stop the daemon. Since #stop also waits until the daemon is no longer running, that wait time is counted as well. If the daemon does not stop in time, then #stop will raise an exception.

The default value is 15.

:log_file_activity_timeout

Once a daemon has gone into the background, it will become difficult to know for certain whether it is still initializing or whether it has failed and exited, until it has written its PID file. Suppose that it failed with an error after daemonizing but before it has written its PID file; not many system administrators want to wait 15 seconds (the default start timeout) to be notified of whether the daemon has terminated with an error.

An alternative way to check whether the daemon has terminated with an error, is by checking whether its log file has been recently updated. If, after the daemon has started, the log file hasn’t been updated for the amount of seconds given by the :log_file_activity_timeout option, then the daemon is assumed to have terminated with an error.

The default value is 7.

:daemonize_for_me

Normally daemon_controller will wait until the daemon has daemonized into the background, in order to capture any errors that it may print on stdout or stderr before daemonizing. However, if the daemon doesn’t support daemonization for some reason, then setting this option to true will cause daemon_controller to do the daemonization for the daemon.

The default is false.

:keep_ios

Upon spawning the daemon, daemon_controller will normally close all file descriptors except stdin, stdout and stderr. However if there are any file descriptors you want to keep open, specify the IO objects here. This must be an array of IO objects.

:env

This must be a Hash. The hash will contain the environment variables available to be made available to the daemon. Hash keys must be strings, not symbols.



185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
 
# File 'lib/daemon_controller.rb', line 185

def initialize(options)
	[:identifier, :start_command, :ping_command, :pid_file, :log_file].each do |option|
		if !options.has_key?(option)
			raise ArgumentError, "The ':#{option}' option is mandatory."
		end
	end
	@identifier = options[:identifier]
	@start_command = options[:start_command]
	@stop_command = options[:stop_command]
	@ping_command = options[:ping_command]
	@restart_command = options[:restart_command]
	@ping_interval = options[:ping_interval] || 0.1
	@pid_file = options[:pid_file]
	@log_file = options[:log_file]
	@before_start = options[:before_start]
	@start_timeout = options[:start_timeout] || 15
	@stop_timeout = options[:stop_timeout] || 15
	@log_file_activity_timeout = options[:log_file_activity_timeout] || 7
	@daemonize_for_me = options[:daemonize_for_me]
	@keep_ios = options[:keep_ios] || []
	@lock_file = determine_lock_file(options, @identifier, @pid_file)
	@env = options[:env] || {}
end

Class Method Details

.can_ping_unix_sockets? ⇒ Boolean

Checks whether ping Unix domain sockets is supported. Currently this is supported on all Ruby implementations, except JRuby.

Returns:

  • (Boolean) 


342
343
344
 
# File 'lib/daemon_controller.rb', line 342

def self.can_ping_unix_sockets?
	return RUBY_PLATFORM != "java"
end

Instance Method Details

#connect ⇒ Object

Connect to the daemon by running the given block, which contains the connection logic. If the daemon isn’t already running, then it will be started.

The block must return nil or raise Errno::ECONNREFUSED, Errno::ENETUNREACH, Errno::ETIMEDOUT, Errno::ECONNRESET, Errno::EINVAL and Errno::EADDRNOTAVAIL to indicate that the daemon cannot be connected to. It must return non-nil if the daemon can be connected to. Upon successful connection, the return value of the block will be returned by #connect.

Note that the block may be called multiple times.

Raises:

  • StartError - an attempt to start the daemon was made, but the start command failed with an error.

  • StartTimeout - an attempt to start the daemon was made, but the daemon did not start in time, or it failed after it has gone into the background.

  • ConnectError - the daemon wasn’t already running, but we couldn’t connect to the daemon even after starting it.



242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
 
# File 'lib/daemon_controller.rb', line 242

def connect
	connection = nil
	@lock_file.shared_lock do
		begin
			connection = yield
		rescue *ALLOWED_CONNECT_EXCEPTIONS
			connection = nil
		end
	end
	if connection.nil?
		@lock_file.exclusive_lock do
			if !daemon_is_running?
				start_without_locking
			end
			connect_exception = nil
			begin
				connection = yield
			rescue *ALLOWED_CONNECT_EXCEPTIONS => e
				connection = nil
				connect_exception = e
			end
			if connection.nil?
				# Daemon is running but we couldn't connect to it. Possible
				# reasons:
				# - The daemon froze.
				# - Bizarre security restrictions.
				# - There's a bug in the yielded code.
				if connect_exception
					raise ConnectError, "Cannot connect to the daemon: #{connect_exception} (#{connect_exception.class})"
				else
					raise ConnectError, "Cannot connect to the daemon"
				end
			else
				return connection
			end
		end
	else
		return connection
	end
end

#pid ⇒ Object

Returns the daemon’s PID, as reported by its PID file. Returns the PID as an integer, or nil there is no valid PID in the PID file.

This method doesn’t check whether the daemon’s actually running. Use #running? if you want to check whether it’s actually running.

Raises SystemCallError or IOError if something went wrong during reading of the PID file.



322
323
324
325
326
 
# File 'lib/daemon_controller.rb', line 322

def pid
	@lock_file.shared_lock do
		return read_pid_file
	end
end

#restart ⇒ Object

Restarts the daemon. Uses the restart_command if provided, otherwise calls #stop and #start.



305
306
307
308
309
310
311
312
 
# File 'lib/daemon_controller.rb', line 305

def restart
	if @restart_command
		run_command(@restart_command)
	else
		stop
		start
	end
end

#running? ⇒ Boolean

Checks whether the daemon is still running. This is done by reading the PID file and then checking whether there is a process with that PID.

Raises SystemCallError or IOError if something went wrong during reading of the PID file.

Returns:

  • (Boolean) 


334
335
336
337
338
 
# File 'lib/daemon_controller.rb', line 334

def running?
	@lock_file.shared_lock do
		return daemon_is_running?
	end
end

#start ⇒ Object

Start the daemon and wait until it can be pinged.

Raises:

  • AlreadyStarted - the daemon is already running.

  • StartError - the start command failed.

  • StartTimeout - the daemon did not start in time. This could also mean that the daemon failed after it has gone into the background.



216
217
218
219
220
 
# File 'lib/daemon_controller.rb', line 216

def start
	@lock_file.exclusive_lock do
		start_without_locking
	end
end

#stop ⇒ Object

Stop the daemon and wait until it has exited.

Raises:

  • StopError - the stop command failed.

  • StopTimeout - the daemon didn’t stop in time.



288
289
290
291
292
293
294
295
296
297
298
299
300
301
 
# File 'lib/daemon_controller.rb', line 288

def stop
	@lock_file.exclusive_lock do
		begin
			Timeout.timeout(@stop_timeout, Timeout::Error) do
				kill_daemon
				wait_until do
					!daemon_is_running?
				end
			end
		rescue Timeout::Error
			raise StopTimeout, "Daemon '#{@identifier}' did not exit in time"
		end
	end
end