raad 0.4.0 → 0.4.1

data/CHANGELOG.md

@@ -7,6 +7,13 @@
 - wrong exit code bug
 - comments & cosmetics
 
-# 0.4, 09-05-2011
+# 0.4.0, 09-13-2011
 - using SignalTrampoline for safe signal handling
-- JRuby support
+- JRuby support
+- specs and validations for all supported rubies
+- tested on MRI 1.8.7 & 1.9.2, REE 1.8.7, JRuby 1.6.4 under OSX 10.6.8 and Linux Ubuntu 10.04
+
+# 0.4.1, 09-22-2011
+- allow arbitrary environment name
+- added Raad.stopped?
+- avoid calling stop multiple times, https://github.com/praized/raad/issues/3

data/README.md

@@ -2,56 +2,116 @@
 
 Raad - Ruby as a daemon lightweight service wrapper.
 
-Raad is a non-intrusive, lightweight, simple Ruby daemon wrapper. Basically A simple class which implements
-the start and stop methods, can be used seamlessly as a daemon or a normal console app.
+Raad is a non-intrusive, lightweight, simple Ruby daemon wrapper. Basically any class which implements
+the `start` and `stop` methods, can be used seamlessly as a daemon or a normal console app.
 
-Raad provides daemon control using the start/stop commands. Your code can optionnally use the Raad
-logging module. 
+Raad **deamonizing** will work the same way for both MRI Ruby and **JRuby**, without
+modification in your code.
+
+Raad provides basic daemon control using the start/stop commands. Your code can also use the Raad
+logging module and benefit easy log file output while daemonized.
 
 ## Installation
 
 ### Gem
-gem install raad
+
+``` sh
+$ gem install raad
+```
 
 ### Bundler
 #### Latest from github
+
+``` sh
 gem "raad", :git => "git://github.com/praized/raad.git", :branch => "master"
+```
 
 #### Released gem
+
+``` bash
 gem "raad", "~> 0.4.0"
+```
 
 ## Example
-Create a class with a start and a stop method. Just by requiring 'raad', your class will be 
-wrapped by Raad and daemonizable.
-
-    require 'raad'
-
-    class SimpleDaemon
-      def start
-        @stopped = false
-        while !@stopped
-          Raad::Logger.info("simple_daemon running")
-          sleep(1)
-        end
-      end
-
-      def stop
-        @stopped = true
-        Raad::Logger.info("simple_daemon stopped")
-      end
+Create a class with a `start` and a `stop` method. Just by requiring 'raad', your class will be 
+wrapped by Raad and become **daemonizable**.
+
+``` ruby
+require 'rubygems'
+require 'raad'
+
+class SimpleDaemon
+  def start
+    while !Raad.stopped?
+      Raad::Logger.info("simple_daemon running")
+      sleep(1)
     end
+  end
+
+  def stop
+    Raad::Logger.info("simple_daemon stopped")
+  end
+end
+```
+ - run it in console mode, `^C` will stop it, calling the stop method
+
+``` sh
+$ ruby simple_daemon.rb start
+```
+ - run it daemonized, by default `./simple_daemon.log` and `./simple_daemon.pid` will be created
 
-    run it in console mode, ^C will stop it, calling the stop method
-    $ ruby simple_daemon.rb start
+``` sh
+$ ruby simple_daemon.rb -d start
+```
 
-    run it daemonized, by default ./simple_daemon.log and ./simple_daemon.pid will be created
-    $ ruby simple_daemon.rb -d start
+ - stop daemon, removing `./simple_daemon.pid`
 
-    stop daemon, removing ./simple_daemon.pid
-    $ ruby simple_daemon.rb stop 
+``` sh
+$ ruby simple_daemon.rb stop
+```
 
 ## Documentation
 
+### Introduction
+
+By requiring 'raad' in your class, it will automagically be wrapped by the Raad bootstrap code.
+When running your class file with the `start` parameter, Raad will call your class `start` method.
+
+The `start` method **should not return** unless your service has completed its work or has been
+instructed to stop.
+
+There are two ways to know when your service has been instructed to stop:
+
+ * the `stop` method of your class will be called if it is defined
+ * `Raad.stopped?` will return true
+
+There are basically 3 ways to run execute your service:
+
+ * start it in foreground console mode, useful for debugging, `^C` to execute the stop sequence
+
+``` sh
+$ ruby your_service.rb start
+```
+
+ * start it as a detached, backgrounded daemon:
+
+``` sh
+$ ruby your_service.rb -d start
+```
+
+ * stop the daemonized service by signaling it to execute the stop sequence
+
+``` sh
+$ ruby your_service.rb stop
+```
+
+In **console mode** Raad logging for level `:info` and up and stdout, ie `puts`, will be displayed by default.
+
+In **daemon mode**, Raad logging for level `:info` and up will be output in `your_service.log` log file and the
+`your_service.pid`pid file will be created.
+
+To toggle output of all logging levels simply use the verbose `-v` parameter.
+
 ### Supported rubies and environments
 Raad has been tested on MRI 1.8.7, MRI 1.9.2, REE 1.8.7, JRuby 1.6.4 under OSX 10.6.8 and Linux Ubuntu 10.04
 
@@ -87,28 +147,38 @@ tbd.
 tbd.
 
 ### Testing
-There are specs and a validation suite which ca be run in the current ruby environment:
+There are specs and a validation suite which ca be run in your **current** ruby environment:
 
-- rake spec
-- rake validation
+``` sh
+$ rake spec
+```
+``` sh
+$ rake validation
+```
 
-Also, specs and validations can be run in all currently tested Ruby environement. For this [RVM][rvm] is required and the following rubies must be installed: 
+Also, specs and validations can be run in **all currently tested Ruby environement**. For this [RVM][rvm] is required and the following rubies must be installed: 
 
 - ruby-1.8.7
 - ree-1.8.7
 - ruby-1.9.2
 - jruby-1.6.4
 
-In each of these rubies, the gemset @raad containing log4r (~> 1.1.9), rake (~> 0.9.2) and rspec (~> 2.6.0) must be created.
+In each of these rubies, the gemset @raad containing `log4r ~> 1.1.9`, `rake ~> 0.9.2` and `rspec ~> 2.6.0` must be created.
 
 This RVM environment can be created/updated using:
 
-- rake rvm_setup
+``` sh
+$ rake rvm_setup
+```
 
 To launch the tests for all rubies use:
 
-- rake specs
-- rake validations
+``` sh
+$ rake specs
+```
+``` sh
+$ rake validations
+```
 
 ## TODO
 - better doc

data/lib/raad/{service.rb → bootstrap.rb}

@@ -1,18 +1,16 @@
 module Raad
 
-  # The main execution class for Raad. This will execute in the at_exit
-  # handler to run the server.
-  class Service
+  # The bootstrap class for Raad. This will execute in the at_exit
+  # handler to run the service.
+  class Bootstrap
 
-    # Set of caller regex's to be skippe when looking for our API file
     CALLERS_TO_IGNORE = [ # :nodoc:
-      /\/raad(\/(service))?\.rb$/, # all raad code
-      /rubygems\/custom_require\.rb$/,    # rubygems require hacks
-      /bundler(\/runtime)?\.rb/,          # bundler require hacks
-      /<internal:/                        # internal in ruby >= 1.9.2
+      /\/raad(\/(bootstrap))?\.rb$/,    # all raad code
+      /rubygems\/custom_require\.rb$/,  # rubygems require hacks
+      /bundler(\/runtime)?\.rb/,        # bundler require hacks
+      /<internal:/                      # internal in ruby >= 1.9.2
     ]
 
-    # @todo add rubinius (and hopefully other VM impls) ignore patterns ...
     CALLERS_TO_IGNORE.concat(RUBY_IGNORE_CALLERS) if defined?(RUBY_IGNORE_CALLERS)
 
     # Like Kernel#caller but excluding certain magic entries and without
@@ -21,7 +19,7 @@ module Raad
       caller_locations.map { |file, line| file }
     end
 
-    # Like caller_files, but containing Arrays rather than strings with the
+    # like caller_files, but containing Arrays rather than strings with the
     # first element being the file, and the second being the line.
     def self.caller_locations
       caller(1).
@@ -29,7 +27,7 @@ module Raad
         reject { |file, line| CALLERS_TO_IGNORE.any? { |pattern| file =~ pattern } }
     end
 
-    # Find the service_file that was used to execute the service
+    # find the service_file that was used to execute the service
     #
     # @return [String] The service file
     def self.service_file
@@ -38,20 +36,20 @@ module Raad
       c
     end
 
-    # Execute the service
+    # execute the service
     #
     # @return [Nil]
     def self.run!
       file = File.basename(service_file, '.rb')
       service = Object.module_eval(camel_case(file)).new
 
-      runner = Raad::Runner.new(ARGV, service)
+      runner = Runner.new(ARGV, service)
       runner.run
     end
 
     private
 
-    # Convert a string to camel case
+    # convert a string to camel case
     #
     # @param str [String] The string to convert
     # @return [String] The camel cased string
@@ -63,8 +61,10 @@ module Raad
   end
 
   at_exit do
-    if $!.nil? && $0 == Raad::Service.service_file
-      Service.run!
+    unless defined?($RAAD_NOT_RUN)
+      if $!.nil? && $0 == Raad::Bootstrap.service_file
+        Raad::Bootstrap.run!
+      end
     end
   end
 end

data/lib/raad/env.rb

@@ -1,8 +1,11 @@
 require 'rbconfig'
+require 'thread'
 
 module Raad
   
   @env = :development
+  @stopped = false
+  @stop_lock = Mutex.new
 
   # retrieves the current environment
   #
@@ -13,13 +16,14 @@ module Raad
 
   # sets the current environment
   #
-  # @param [String or Symbol] env the environment [development|production|stage|test]
+  # @param [String or Symbol] env the environment
   def env=(env)
     case(env.to_s)
     when 'dev', 'development' then @env = :development
     when 'prod', 'production' then @env = :production
     when 'stage', 'staging' then @env = :stage
     when 'test' then @env = :test
+    else @env = env.to_sym
     end
   end
 
@@ -55,7 +59,7 @@ module Raad
   #
   # @return [Boolean] true if runnig inside jruby
   def jruby?
-    defined?(RUBY_ENGINE) && RUBY_ENGINE == 'jruby'
+    !!(defined?(RUBY_ENGINE) && RUBY_ENGINE == 'jruby')
   end
 
   # absolute path of current interpreter
@@ -65,6 +69,20 @@ module Raad
     File.join(Config::CONFIG["bindir"], Config::CONFIG["RUBY_INSTALL_NAME"] + Config::CONFIG["EXEEXT"])
   end
 
-  module_function :env, :env=, :production?, :development?, :stage?, :test?, :jruby?, :ruby_path
+  # a request to stop the service has been received (or the #start method has returned and, if defined, the service #stop method has been called by Raad.
+  #
+  # @return [Boolean] true is the service has been stopped
+  def stopped?
+    @stop_lock.synchronize{@stopped}
+  end
+
+  # used internally to set the stopped flag
+  #
+  # @param [Boolean] state true to set the stopped flag
+  def stopped=(state)
+    @stop_lock.synchronize{@stopped = !!state}
+  end
+
+  module_function :env, :env=, :production?, :development?, :stage?, :test?, :jruby?, :ruby_path, :stopped?, :stopped=
 
 end

data/lib/raad/runner.rb

@@ -1,4 +1,6 @@
 require 'optparse'
+require 'timeout'
+require 'thread'
 
 module Raad
   class Runner
@@ -29,6 +31,7 @@ module Raad
       @logger_options = nil
       @pid_file = nil
 
+      @stop_lock = Mutex.new
       @stop_signaled = false
     end
 
@@ -58,8 +61,8 @@ module Raad
       if options[:command] == 'stop'
         puts(">> Raad service wrapper v#{VERSION} stopping")
         # first send the TERM signal which will invoke the daemon wait_or_will method which will timeout after @stop_timeout
-        # if still not stopped afer @stop_timeout + 2, KILL -9 will be sent.
-        success = send_signal('TERM', @stop_timeout + 2) 
+        # if still not stopped afer @stop_timeout + 2 seconds, KILL -9 will be sent.
+        success = send_signal('TERM', @stop_timeout + (2 * SECOND)) 
         exit(success)
       end
 
@@ -92,25 +95,29 @@ module Raad
       end
 
       # do not trap :QUIT because its not supported in jruby
-      [:INT, :TERM].each do |sig|
-        SignalTrampoline.trap(sig) {@stop_signaled = true; stop_service}
-      end
+      [:INT, :TERM].each{|sig| SignalTrampoline.trap(sig) {stop_service}}
 
       # launch the service thread and call start. we expect start not to return
       # unless it is done or has been stopped.
       service_thread = Thread.new do
         Thread.current.abort_on_exception = true
         service.start
-        stop_service unless @stop_signaled # don't stop twice if already called from the signal handler
+        stop_service 
       end
 
+      result = wait_or_kill(service_thread)
+      # if not daemonized start a sentinel thread, if still alive after 2 seconds, do arakiri
+      Thread.new{sleep(2 * SECOND);  Process.kill(:KILL, Process.pid)} unless options[:daemonize]
       # use exit and not exit! to make sure the at_exit hooks are called, like the pid cleanup, etc.
-      exit(wait_or_kill(service_thread))
+      exit(result)
     end
 
     def stop_service
+      return if @stop_lock.synchronize{s = @stop_signaled; @stop_signaled = true; s}
+      
       Logger.info("stopping #{@service_name} service")
       service.stop if service.respond_to?(:stop)
+      Raad.stopped = true
     end
 
     # try to do a timeout join periodically on the given thread. if the join succeed then the stop
@@ -122,7 +129,7 @@ module Raad
     def wait_or_kill(thread)
       while thread.join(SECOND).nil?
         # the join has timed out, thread is still buzzy.
-        if @stop_signaled
+        if @stop_lock.synchronize{@stop_signaled}
           # but if stop has been signalled, start "the final countdown" ♫
           try = 0; join = nil
           while (try += 1) <= @stop_timeout && join.nil? do

data/lib/raad/unix_daemon.rb

@@ -78,28 +78,22 @@ module Daemonizable
       false
     end
   rescue Timeout::Error
-    force_kill_and_remove_pid_file
+    force_kill_and_remove_pid_file(pid)
   rescue Interrupt
-    force_kill_and_remove_pid_file
+    force_kill_and_remove_pid_file(pid)
   rescue Errno::ESRCH # No such process
     puts(">> can't stop process, no such process #{pid}")
     remove_pid_file
     false
   end
   
-  def force_kill_and_remove_pid_file
-    success = if (pid = read_pid_file)
-      puts(">> sending KILL signal to process #{pid}")
-      Process.kill("KILL", pid)
-      true
-    else
-      puts(">> can't stop process, no pid found in #{@pid_file}")
-      false
-    end
+  def force_kill_and_remove_pid_file(pid)
+    puts(">> sending KILL signal to process #{pid}")
+    Process.kill("KILL", pid)
     remove_pid_file
-    success
+    true
   rescue Errno::ESRCH # No such process
-    puts(">> can't stop process, no such process #{pid}")
+    puts(">> can't send KILL, no such process #{pid}")
     remove_pid_file
     false
   end

data/lib/raad/version.rb

@@ -1,3 +1,3 @@
 module Raad
-  VERSION = "0.4.0"
+  VERSION = "0.4.1"
 end unless defined?(Raad::VERSION)

data/lib/raad.rb

@@ -5,4 +5,4 @@ require 'raad/configuration'
 require 'raad/unix_daemon'
 require 'raad/signal_trampoline'
 require 'raad/runner'
-require 'raad/service'
+require 'raad/bootstrap'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: raad
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-09-13 00:00:00.000000000Z
+date: 2011-09-23 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rubyforge
-  requirement: &2152610040 !ruby/object:Gem::Requirement
+  requirement: &2165092620 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2152610040
+  version_requirements: *2165092620
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &2152609480 !ruby/object:Gem::Requirement
+  requirement: &2165092060 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -32,10 +32,10 @@ dependencies:
         version: 2.6.0
   type: :development
   prerelease: false
-  version_requirements: *2152609480
+  version_requirements: *2165092060
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &2152608960 !ruby/object:Gem::Requirement
+  requirement: &2165091540 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -43,10 +43,10 @@ dependencies:
         version: 0.9.2
   type: :development
   prerelease: false
-  version_requirements: *2152608960
+  version_requirements: *2165091540
 - !ruby/object:Gem::Dependency
   name: log4r
-  requirement: &2152608480 !ruby/object:Gem::Requirement
+  requirement: &2165091060 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -54,7 +54,7 @@ dependencies:
         version: 1.1.9
   type: :runtime
   prerelease: false
-  version_requirements: *2152608480
+  version_requirements: *2165091060
 description: Ruby as a Daemon lightweight service wrapper
 email:
 - colin.surprenant@gmail.com
@@ -62,11 +62,11 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- lib/raad/bootstrap.rb
 - lib/raad/configuration.rb
 - lib/raad/env.rb
 - lib/raad/logger.rb
 - lib/raad/runner.rb
-- lib/raad/service.rb
 - lib/raad/signal_trampoline.rb
 - lib/raad/spoon.rb
 - lib/raad/unix_daemon.rb