daemon_controller 2.0.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c9dce68cae7ce8da028c91815950481313672404aeaa48a0b97e817263dbb5ff
-  data.tar.gz: 921a96fe368c826fa881e2beecab2a298620249b4a76bf1934849a22ea5bb61c
+  metadata.gz: bd4f2d08b82c7340e6b00c8a97e63f66a6677fbc28e9b705ecb6c53d75701e00
+  data.tar.gz: 11bc6d68d7837db49c123b5e2b08fc932bf60c1b0c29742e7e891e66d8f4f82a
 SHA512:
-  metadata.gz: 27a36b21d30836e901637ea07f538872fa306f9ce9bfacd6175b0b4858ac45ba825999d798e9e7740371148f47e93d212df9f16a326835385613730e69389c65
-  data.tar.gz: 23acb3cee9eef3f771f42e8deb06c750ba8bb4aa04d58bfa6b24837a15ff928edbe97c56b4f2018aed142e600f5f26733afc7e01bc1b1941f127d5e9d068142e
+  metadata.gz: c29f7ea6b92d607774bef4f42dba2e03215f85078079fb3febd404cf87efff8f0536e03ba870234c72925f7404142dba2bf73217d7586175328d6611ba72e3d8
+  data.tar.gz: 1b5d67e7165fb4c2ba1c667c774e089a5a5029e57ba47dd1f91cbcd17e2dcdef7136947b0d115d71b7db9c154013043f9da01428d55659898eee198bd1ca3d3a

data/README.md

@@ -31,12 +31,6 @@ It provides the following functionality:
 gem install daemon_controller
 ```
 
-## Resources
-
-*   [Website](https://github.com/FooBarWidget/daemon_controller)
-*   [RDoc](http://rdoc.info/projects/FooBarWidget/daemon_controller)
-*   [Git repository](git://github.com/FooBarWidget/daemon_controller.git)
-
 
 What is it for?
 ===============
@@ -87,13 +81,15 @@ daemon varies. We've observed that waiting a fixed amount of time is by far the
 most common way. For example, UltraSphinx's daemon starting code looks like
 this:
 
-    system "searchd --config '#{Ultrasphinx::CONF_PATH}'"
-    sleep(4) # give daemon a chance to write the pid file
-    if ultrasphinx_daemon_running?
-       say "started successfully"
-    else
-       say "failed to start"
-    end
+```ruby
+system "searchd --config '#{Ultrasphinx::CONF_PATH}'"
+sleep(4) # give daemon a chance to write the pid file
+if ultrasphinx_daemon_running?
+  say "started successfully"
+else
+  say "failed to start"
+end
+```
 
 This is in no way a slam against UltraSphinx. However, if the daemon starts in
 200 miliseconds, then the user who issued the start command will be waiting for
@@ -291,7 +287,7 @@ without having to start the daemons manually.
 Tutorial #1: controlling Apache
 ===============================
 
-Suppose that you're a [Phusion Passenger](http://www.modrails.com/) developer,
+Suppose that you're a [Phusion Passenger](https://www.phusionpasseenger.com/) developer,
 and you need to write tests for the Apache module. In particular, you want to
 test whether the different Phusion Passenger configuration directives are
 working as expected. Obviously, to test the Apache module, the Apache web
@@ -306,29 +302,30 @@ server must be running. For every test, you will want the unit test suite to:
 
 That can be done with the following code:
 
-    require 'daemon_controller'
-
-    File.open("apache.conf", "w") do |f|
-       f.write("PidFile apache.pid\n")
-       f.write("LogFile apache.log\n")
-       f.write("Listen 1234\n")
-       f.write(... other relevant configuration options ...)
-    end
-
-    controller = DaemonController.new(
-       :identifier    => 'Apache web server',
-       :start_command => 'apachectl -f apache.conf -k start',
-       :ping_command  => [:tcp, 'localhost', 1234],
-       :pid_file      => 'apache.pid',
-       :log_file      => 'apache.log',
-       :start_timeout => 25
-    )
-    controller.start
-
-    .... apache is now started ....
-    .... some test code here ....
-
-    controller.stop
+```ruby
+require "daemon_controller"
+
+File.open("apache.conf", "w") do |f|
+  f.write("PidFile apache.pid\n")
+  f.write("LogFile apache.log\n")
+  f.write("Listen 1234\n")
+  f.write(... other relevant configuration options ...)
+end
+
+controller = DaemonController.new(
+  identifier: "Apache web server",
+  start_command: "apachectl -f apache.conf -k start",
+  ping_command: [:tcp, "localhost", 1234],
+  pid_file: "apache.pid",
+  log_file: "apache.log"
+)
+controller.start
+
+# .... apache is now started ....
+# .... some test code here ....
+
+controller.stop
+```
 
 The `File.open` line is obvious: it writes the relevant Apache configuration
 file.
@@ -336,8 +333,8 @@ file.
 The next line is for creating a new DaemonController object. We pass a
 human-readable identifier for this daemon ("Apache web server") to the
 constructor. This is used for generating friendlier error messages.
-We also tell it how Apache is supposed to be started (`:start_command`), how to
-check whether it can be connected to (`:ping_command`), and where its PID file
+We also tell it how Apache is supposed to be started (`start_command:`), how to
+check whether it can be connected to (`ping_command:`), and where its PID file
 and log file is. If Apache failed with an error during startup, then it will be
 reported. If Apache failed with an error after it has gone into the background,
 then that will be reported too: the given log file is monitored for new error
@@ -345,7 +342,8 @@ messages.
 Finally, a timeout of 25 seconds is given. If Apache doesn't start within 25
 seconds, then an exception will be raised.
 
-The ping command is just a `Proc` which returns true or false. If the Proc
+The ping command specifies which socket to connect to in order to check whether
+the daemon is ready. It can also be a `Proc` which returns true or false. If the Proc
 raises `Errno::ECONNREFUSED`, then that's also interpreted by DaemonController
 as meaning that the daemon isn't responding yet.
 
@@ -392,41 +390,43 @@ isn't running.
 
 This can be achieved with the following code:
 
-    require 'daemon_controller'
-
-    class SearchServer
-       SEARCH_SERVER_PORT = 1234
-
-       def initialize
-          @controller = DaemonController.new(
-             :identifier => 'Sphinx search server',
-             :start_command => "searchd -c config/sphinx.conf",
-             :before_start => method(:before_start),
-             :ping_command => [:tcp, 'localhost', SEARCH_SERVER_PORT],
-             :pid_file => 'tmp/pids/sphinx.pid',
-             :log_file => 'log/sphinx.log')
-       end
-
-       def query(search_terms)
-          socket = @controller.connect do
-             TCPSocket.new('localhost', SEARCH_SERVER_PORT)
-          end
-          send_query(socket, search_terms)
-          return retrieve_results(socket)
-       end
-
-    private
-       def before_start
-          generate_configuration_file
-          if !index_exists?
-             generate_index
-          end
-       end
-
-       ...
+```ruby
+require "daemon_controller"
+
+class SearchServer
+  SEARCH_SERVER_PORT = 1234
+
+  def initialize
+    @controller = DaemonController.new(
+      identifier: "Sphinx search server",
+      start_command: "searchd -c config/sphinx.conf",
+      before_start: method(:before_start),
+      ping_command: [:tcp, "localhost", SEARCH_SERVER_PORT],
+      pid_file: "tmp/pids/sphinx.pid",
+      log_file: "log/sphinx.log")
+  end
+
+  def query(search_terms)
+    socket = @controller.connect do
+      TCPSocket.new("localhost", SEARCH_SERVER_PORT)
     end
+    send_query(socket, search_terms)
+    retrieve_results(socket)
+  end
+
+private
+  def before_start
+    generate_configuration_file
+    if !index_exists?
+      generate_index
+    end
+  end
+
+  # ...
+end
+```
 
-Notice the `:before_start` option. We pass a block of code which is to be run,
+Notice the `before_start:` option. We pass a block of code which is to be run,
 just before the daemon is started. This block, along with starting the daemon,
 is completely serialized. That is, if you're inside the block, then it's
 guaranteed that no other process is running this block at the same time as well.
@@ -498,5 +498,7 @@ synchronization. This has a few implications:
 API documentation
 =================
 
-Detailed API documentation is available in the form of inline comments in
-`lib/daemon_controller.rb`.
+Detailed API documentation is available here:
+- [Configuration options](doc/OPTIONS.md)
+- [Stop flow](doc/STOP_FLOW.md)
+- Inline comments in `lib/daemon_controller.rb`.

data/lib/daemon_controller/version.rb

@@ -22,7 +22,7 @@
 # THE SOFTWARE.
 
 class DaemonController
-  MAJOR = 2
+  MAJOR = 3
   MINOR = 0
   TINY = 0
   VERSION_STRING = "#{MAJOR}.#{MINOR}.#{TINY}"