djinn 0.0.5 → 0.0.6

data/README.rdoc

@@ -1,10 +1,10 @@
-= djinn
+= Djinn
 
-Djinn is a very basic helper for building simple daemons
+Djinn is a very basic helper for building simple daemons.
 
 == Non-Rails Example
 
-#!/usr/bin/env ruby
+  #!/usr/bin/env ruby
 
   require 'rubygems'
   require 'djinn'
@@ -41,9 +41,32 @@ this is the general idea:
   sleep(10)
   djinn.stop
   
+Assuming you didn't sleep there your script would end and the daemon would
+detach and run in the background until it dies or gets killed. You can wrap
+argument parsing around that if you want, or do it in any other way. By default 
+the daemon will look for a config YAML file in same directory as you executed it
+from, named the same as the Djinn class, so in this case _basic.yml_. It will by
+default create the pid and log files in the same way. You can change this by 
+putting it in the config file or supplying an options hash:
+
+  options = {
+    'pid_file_path' => 'path/to/pid/file',
+    'log_file_path' => 'path/to/log/file'
+  }
+  
+  djinn.start(options)
+  
+These options will also be passed to your *perform* method, so you can include
+anything you need in the hash as well, or in the YAML file for that matter.
+  
+It might seem ugly, but the solution is minimal, and so remains flexible I think. 
+The rails daemon helpers are an implementation on top of this illustrating how it 
+can be tailored to include some option parsing and so forth, and so do a little 
+more for you.
+  
 == Rails Example
 
-There's a nice example in the example directory if you check the code out, but
+There's a simple example in the example directory if you check the code out, but
 here's the gist of it.
 
 Assumes a scenario where you have a Book model that keeps a count of how many
@@ -51,12 +74,12 @@ times a book has been read.
 
 Create a file in RAILS_ROOT/lib or somewhere similar:
 
-  BOOK_WORKER_INTERVAL = 5
+  require 'djinn/rails'
 
   class BookDjinn
-
-    require 'djinn/rails'
-
+  
+    BOOK_WORKER_INTERVAL = 5
+  
     include Djinn::Rails
 
     def perform config
@@ -80,16 +103,16 @@ Create a file in RAILS_ROOT/lib or somewhere similar:
 Right, now you need to start it somehow. The easiest way is to create a file 
 in RAILS_ROOT/scripts and pop this in it:
 
- #!/usr/bin/env ruby
- require 'rubygems'
- require File.join(File.dirname(__FILE__), '../lib/book_djinn')
- BookDjinn.go ARGV
+  #!/usr/bin/env ruby
+  require 'rubygems'
+  require File.join(File.dirname(__FILE__), '../lib/book_djinn')
+  BookDjinn.go ARGV
  
 Righto, now start it from RAILS_ROOT:
 
   ruby script/book_djinn
   
-Okay, but that defaults to "run", which starts it in the foreground and also 
+Okay, but that defaults to _run_, which starts it in the foreground and also 
 uses the rails development environment by default. Try this:
 
   ruby script/book_djinn --help
@@ -107,7 +130,7 @@ and monitor it with god or a similar process monitor.
   
 == TODO
 
-  Lots. Keep 'em peeled.
+Lots. Keep 'em peeled.
 
 == Copyright
 

data/Rakefile

@@ -13,9 +13,14 @@ begin
     gem.add_development_dependency "shoulda", ">= 2.11.1"
     gem.files.exclude 'example/**/*'
     gem.test_files.exclude 'example/**/*'
+    gem.has_rdoc = true
+    gem.rubyforge_project = 'djinn'
     # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
   end
   Jeweler::GemcutterTasks.new
+  Jeweler::RubyforgeTasks.new do |rubyforge|
+    rubyforge.doc_task = "rdoc"
+  end
 rescue LoadError
   puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
 end

data/VERSION

@@ -1 +1 @@
-0.0.5
+0.0.6

data/djinn.gemspec

@@ -5,7 +5,7 @@
 
 Gem::Specification.new do |s|
   s.name = %q{djinn}
-  s.version = "0.0.5"
+  s.version = "0.0.6"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Craig Paterson"]
@@ -37,6 +37,7 @@ Gem::Specification.new do |s|
   s.homepage = %q{http://github.com/craigp/djinn}
   s.rdoc_options = ["--charset=UTF-8"]
   s.require_paths = ["lib"]
+  s.rubyforge_project = %q{djinn}
   s.rubygems_version = %q{1.3.7}
   s.summary = %q{Helper for creating simple custom daemons}
   s.test_files = [

data/lib/djinn.rb

@@ -1,5 +1,7 @@
 require 'djinn/base'
 
+# This is a base implementation which handles looking for config
+# files and sets up the default locations for pid and log files
 module Djinn
 
   include Djinn::Base

data/lib/djinn/base.rb

@@ -5,6 +5,7 @@ require 'pid_file'
 require 'logging'
 
 module Djinn
+  # The base class from which all Djinn spring forth
   module Base
     
     include Djinn::Tonic
@@ -12,8 +13,9 @@ module Djinn
     
     attr_reader :config
     
+    # Base implementation does nothing worthwhile, you should override this 
+    # in your own implementation 
     def perform config={}
-      # base implementation does nothing worthwhile
       trap('TERM') { handle_exit }
       trap('INT')  { handle_exit }
       while true
@@ -22,11 +24,13 @@ module Djinn
       end 
     end
 
+    # Override this with useful exit code if you need to, but remember to
+    # call *super* or call *exit* yourself, or your Djinn will be immortal 
     def handle_exit
-      # override this with useful exit code if you need it
       exit(0)
     end
 
+    # Starts the Djinn in the background
     def start config={}
       @config = (config.empty?) ? load_config : config.empty?
       log "Starting #{name} in the background.."
@@ -38,6 +42,8 @@ module Djinn
       end
     end
 
+    # Starts the Djinn in the foreground, which is often useful for
+    # testing or other noble pursuits
     def run config={}
       @config = (config.empty?) ? load_config : config.empty?
       log "Starting #{name} in the foreground.."
@@ -46,13 +52,17 @@ module Djinn
       perform(config)
     end
 
-    def restart
+    # Convenience method, really just calls *stop* and then *start* for you :P
+    def restart config={}
       stop
-      start
+      start(config)
     end
 
-    def stop
-      pidfile = get_pidfile(load_config)
+    # Stops the Djinn, unless you change the location of the pid file, in 
+    # which case its all about you and the *kill* command
+    def stop config={}
+      @config = (config.empty?) ? load_config : config.empty?
+      pidfile = get_pidfile(@config)
       log 'No such process' and exit unless pidfile.pid
       begin
         log "Sending TERM signal to process #{pidfile.pid}"
@@ -66,12 +76,15 @@ module Djinn
     
     protected
     
+      # The name used to identify the Djinn, for pid and log file
+      # naming, as well as finding default config files
       def name
         underscore(self.class.name)
       end
     
     private
     
+      # Shamelessly stolen from the Rails source
       def underscore(camel_cased_word)
         camel_cased_word.to_s.gsub(/::/, '/').
           gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: djinn
 version: !ruby/object:Gem::Version 
-  hash: 21
+  hash: 19
   prerelease: false
   segments: 
   - 0
   - 0
-  - 5
-  version: 0.0.5
+  - 6
+  version: 0.0.6
 platform: ruby
 authors: 
 - Craig Paterson
@@ -89,7 +89,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: "0"
 requirements: []
 
-rubyforge_project: 
+rubyforge_project: djinn
 rubygems_version: 1.3.7
 signing_key: 
 specification_version: 3