bannister 0.0.1 → 0.0.2

data/Rakefile

@@ -3,6 +3,8 @@ CLEAN << ".yardoc"
 CLEAN << FileList["*.gem"]
 CLEAN << "doc"
 
+DOC_FILES=Dir['*.md']
+
 desc "Build the gem"
 task :gem do
   system "gem build bannister.gemspec"
@@ -10,5 +12,12 @@ end
 
 desc "Build the YARD docs"
 task :docs do
-  system "yardoc"
+  system "yardoc --files #{DOC_FILES.join(",")}"
+end
+
+task :doc => :docs
+
+desc "Build the YARD developer docs, including private methods"
+task :dev_docs do
+  system "yardoc --private --files #{DOC_FILES.join(",")}"
 end

data/lib/bannister/apache.rb

@@ -27,10 +27,13 @@ module Bannister
         catch :done do
           20.times do
             sleep(0.1)
+            # No need to trap error messages here, because `kill`
+            # gives us a meaningful error code
             next if system "kill -0 #{pid} 2> /dev/null"
             throw :done
           end
-          raise "Apache2 failed to stop!"
+          
+          raise "Apache2 (pid=#{pid}) failed to stop!"
         end
       end
     end
@@ -80,6 +83,10 @@ module Bannister
 
     private
 
+    # Read apache2's pid from {PidFilename}.
+    #
+    # @return [Integer] Apache's process id.
+    # @return nil if it's not there.
     def read_pid()
       if File.file?(PidFilename)
         return Integer(File.read(PidFilename).strip)

data/lib/bannister/recurse.rb

@@ -1,6 +1,6 @@
 module Bannister
 
-  # Use the Recurse class to launch other bannister apps from this one.
+  # Use the Recurse class to launch other apps with a runner script.
   class Recurse
 
     # @param [String] dir Directory to chdir to before running bannister
@@ -10,25 +10,37 @@ module Bannister
       @dir=dir
     end
 
-    
-    # Run "bannister stop" and exit.
+
+    # Run "runner stop" and exit.
     def stop
-      system "bannister stop"
+      system "./runner stop"
       exit(0)
     end
 
 
-    # If foreground is true, exec "bannister run" in @dir.  Otherwise set up
-    # traps for the right signals to a backgrounded "bannister start" process.
+    # Run the application's runner. If foreground is true, exec
+    # "runner run" in @dir.  Otherwise set up traps for the right
+    # signals to a backgrounded "runner start" process.
+    #
+    # @param [Boolean] foreground Pass true to run in the foreground, false
+    #   otherwise.
     def start(foreground=false)
       Dir.chdir(@dir) do
         if foreground
-          exec "bannister run"
+          # We're replacing the current process with the child, so we want
+          # std* to go to the console
+          exec "./runner run"
         else
           trap("TERM"){stop()}
           trap("HUP"){stop()}
 
-          system "bannister start &"
+          # This ignores stdout and stderr. Since the child process expects to
+          # running in the background anyway, we expect it to make its own
+          # arrangements.
+          #
+          # Yes, this is lazy, but there's not a lot more we can do at this
+          # point without a higher-level error-handling facility.
+          system "./runner start &"
 
           sleep()
         end

data/lib/bannister/version.rb

@@ -1,3 +1,3 @@
 module Bannister
-  VERSION="0.0.1"
+  VERSION="0.0.2"
 end

data/lib/bannister.rb

@@ -3,8 +3,17 @@ require 'fileutils'
 module Bannister
 
 
+  # List of scripts in script/startup sorted asciibetically. This is the order 
+  # they will be launched in, but there is no further dependency checking
+  # between the scripts.
   SCRIPTS = Dir['script/startup/*'].sort
+
+  # A list of pids of the started scripts. These will be sent TERM signals when
+  # bannister is stopped.
   LAUNCHED_PIDS = []
+
+  # The location of the pidfile for the master process. This will be 
+  # de-hard-coded in a future release.
   PID_FILENAME = "pids/bannister.pid"
 
 
@@ -42,7 +51,6 @@ module Bannister
     else # create it. The easiest way to do this is to write 
       # out a screenrc containing the relevant commands and
       # let screen launch them
-
       begin
         write_screenrc(screenrc_filename)
 
@@ -90,18 +98,37 @@ module Bannister
   end
 
 
+
   private
+  # Method to see whether a bannister process for the current application
+  # is running or not.
+  #
+  # @return [Boolean] true if PID_FILENAME exists, false otherwise.
   def running?
     return File.exists?(PID_FILENAME)
   end
 
 
+  # Generate the screen command for the passed script filename. Since this
+  # will only ever be called when running in the foreground, we append -X
+  # to the command. A title for the screen window is also generated based
+  # on the current directory name and the script filename.
+  #
+  # @param [String] script the filename of a script to run.
+  # @return [String] the screen command to run the script.
   def command_for_script(script)
     title = File.basename(FileUtils.pwd)+':'+File.basename(script)
     return "screen -t '#{title}' #{script} -X"
   end
 
 
+  # Generate a screen config file and save it to the passed screenrc_filename.
+  # Screen is set up to allow restarting of dead processes with the 'r' key,
+  # and to give each script a meaningful title in the status line.
+  #
+  # @param [String] screenrc_filename the filename to save the
+  #   generated config file to.
+  # @return [NilClass] nil.
   def write_screenrc(screenrc_filename)
     File.open(screenrc_filename, "wb") do |f|
       f.write <<-SCREENRC
@@ -113,10 +140,18 @@ SCREENRC
         f.puts( command_for_script(script) )
       end
     end
+
+    return nil
   end
 
 
 
+  # Daemonize the bannister process and yield. Used when running in
+  # the background. This is a slightly different daemonize method to
+  # the usual, in that we need to be sure that the script filenames in
+  # SCRIPT don't lose their relative location, so we chdir to '/'
+  # *after* kicking them off. It's each individual script's
+  # responsibility to daemonise properly.
   def daemonize()
     exit!(0) if fork
     Process::setsid
@@ -132,25 +167,43 @@ SCREENRC
     # and if any of them rely on relative paths, they won't get
     # broken
     Dir::chdir("/")
+
+    return nil
   end
 
 
+  # Set up our environment and launch everything in the background.
   def do_start()
     set_name()
     drop_pid()
     launch_all()
   end
 
+  # Set the process name to something meaningful. In this case,
+  # "something meaningful" means "bannister:" + the name of the
+  # directory we're in. This makes it easy to see which bannister pids
+  # are responsible for which applications.
+  #
+  # @return [NilClass] nil.
   def set_name
     $0 = "bannister:"+File.basename(FileUtils.pwd)
+
+    return nil
   end
 
+  # Record the current pid somewhere it can be found later
   def drop_pid
     system "mkdir -p #{File.dirname PID_FILENAME}"
     File.open(PID_FILENAME, "w"){|f| f.write $$.to_s}
+
+    return nil
   end
 
 
+  # Read the pid from where drop_pid left it, or nil if it's not there.
+  #
+  # @return [Fixnum] pid as integer if it exists
+  # @return [NilClass] nil otherwise.
   def read_pid
     if File.exists?(PID_FILENAME)
       return Integer(File.read(PID_FILENAME).strip)
@@ -160,31 +213,51 @@ SCREENRC
   end
 
 
+  # Clear the pid that drop_pid left behind.
+  #
+  # @return [NilClass] nil.
   def remove_pid
     FileUtils.rm_f(PID_FILENAME)
+
+    return nil
   end
 
 
+  # Fork and exec each of SCRIPTS.
+  #
+  # @return [NilClass] nil.
   def launch_all()
     SCRIPTS.each do |script|
       LAUNCHED_PIDS << fork do
         exec script
       end
     end
+
+    return nil
   end
 
 
+  # Call Process.waitpid on each process launched by launch_all.
+  #
+  # @return [NilClass] nil.
   def wait_for_all()
     LAUNCHED_PIDS.each do |pid|
       Process.waitpid(pid)
     end
+
+    return nil
   end
 
 
+  # Send the TERM signal to each process launched by launch_all.
+  #
+  # @return [NilClass] nil.
   def kill_all()
     LAUNCHED_PIDS.each do |pid|
       system "kill -15 #{pid}"
     end
+
+    return nil
   end
 
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: bannister
 version: !ruby/object:Gem::Version 
-  hash: 29
+  hash: 27
   prerelease: false
   segments: 
   - 0
   - 0
-  - 1
-  version: 0.0.1
+  - 2
+  version: 0.0.2
 platform: ruby
 authors: 
 - Alex Young
@@ -15,10 +15,23 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-09-22 00:00:00 +01:00
+date: 2010-10-13 00:00:00 +01:00
 default_executable: 
-dependencies: []
-
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: bluecloth
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id001
 description: |
   An application launcher which maintains a tree of processes to keep background
   processes tied to the launcher.
@@ -33,9 +46,9 @@ extra_rdoc_files: []
 
 files: 
 - bin/bannister
-- lib/bannister/apache.rb
-- lib/bannister/recurse.rb
 - lib/bannister/version.rb
+- lib/bannister/recurse.rb
+- lib/bannister/apache.rb
 - lib/bannister.rb
 - README.md
 - Rakefile