Class DaemonController
In: lib/daemon_controller/lock_file.rb
lib/daemon_controller/version.rb
lib/daemon_controller.rb
Parent: Object

Main daemon controller object. See the README for an introduction and tutorial.

Methods

connect   new   pid   running?   start   stop  

Classes and Modules

Class DaemonController::AlreadyStarted
Class DaemonController::ConnectError
Class DaemonController::DaemonizationTimeout
Class DaemonController::Error
Class DaemonController::LockFile
Class DaemonController::StartError
Class DaemonController::StartTimeout
Class DaemonController::StopError
Class DaemonController::StopTimeout
Class DaemonController::TimeoutError

Constants

MAJOR = 0
MINOR = 2
TINY = 5
VERSION_STRING = "#{MAJOR}.#{MINOR}.#{TINY}"
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"))

Public Class methods

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.

Public Instance methods

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.

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.

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.

Start the daemon and wait until it can be pinged.

Raises:

Stop the daemon and wait until it has exited.

Raises:

[Validate]