class 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 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 or Errno::ECONNRESET, Errno::EINVAL and 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 the return value. 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.

: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.

: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.

# File lib/daemon_controller.rb, line 167
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]
        @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(@identifier, @pid_file)
end

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.

# File lib/daemon_controller.rb, line 222
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

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.

# File lib/daemon_controller.rb, line 291
def pid
        @lock_file.shared_lock do
                return read_pid_file
        end
end

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.

# File lib/daemon_controller.rb, line 303
def running?
        @lock_file.shared_lock do
                return daemon_is_running?
        end
end

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.

# File lib/daemon_controller.rb, line 196
def start
        @lock_file.exclusive_lock do
                start_without_locking
        end
end

Stop the daemon and wait until it has exited.

Raises:

• StopError - the stop command failed.

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

# File lib/daemon_controller.rb, line 268
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