climax 0.0.5 → 0.0.6

data/README.markdown

@@ -108,10 +108,12 @@ The above example is a simple application that adds an extra command line option
 `configure` method.  The `pre_main` method is simple and just writes a debug log statement.  As you
 can see logging has been setup at this point.  Then the `main` method is called.  Because the `main`
 method in this example always returns nil, this application will run forever until it is stopped
-externally (`Ctrl-C`, `kill -9`, or using the Control DRb).  Using `Ctrl-C` and `kill -9` will
-immediately halt execution of the application and `post_main` will never be called.  However if the
-Control DRb is used then the application will exit in an orderly fashion and the `post_main` method
-will be called.  Notice that for free you can fork this application, change the log level with the
+externally (`Ctrl-C`, `kill`, or using the Control DRb).  Using `Ctrl-C` and `kill -INT` (i.e.,
+sending an Interrupt signal) will cause the application to exit gracefully. The current iteration of
+`main` will finish and then `post_main` will be run.  You can send another Interrupt signal, for
+example by hitting `Ctrl-C` twice, to exit the application immediately.  Likewise if the Control DRb
+is used then the application will exit in an orderly fashion and the `post_main` method will be
+called.  Notice that for free you can fork this application, change the log level with the
 `--log-level` option, write the logs to a file using the `--log-file` option, and you can start a
 debugger at any time while this application is running using the Control DRb.  The Control DRb has a
 lot of power.  We'll talk about it more below.
@@ -159,12 +161,19 @@ good idea to keep each iteration of `main` as short as possible, although this i
 requirement.  In other words, if you wish to enter the remote debugger for a running process, the
 debugger will not begin until the current iteration of `main` has completed.
 
+This is exactly how graceful exiting is accomplished with climax.  When you send an Interrupt signal
+(via `Ctrl-C` or by sending a `kill -INT` to your application), climax intercepts this signal and
+places a `:exit` event onto the event queue.  If climax intercepts a second Interrupt signal it will
+halt execution immediately.
+
 This is excellent for stopping a long running process without interrupting its work.  By sending an
-:exit or :quit event, whether through the Control DRb or from your application itself, your
-application will be allowed to finish processing its current unit of work before exiting.
+:exit or :quit event, whether through the Control DRb, or by sending an Interrupt signal, or from
+your application itself, your application will be allowed to finish processing its current unit of
+work before exiting.
 
 For your convenience there is also a 'climax_has_event?' method that returns true only if there are
-events waiting on the event queue.
+events waiting on the event queue.  Your application can use this to determine if `main` should give
+up control temporarily to allow climax to handle events on the queue.
 
 Generating a New Application
 ============================
@@ -237,3 +246,104 @@ and then execute:
     climax control start_debugger
 
 When you are finished type `quit` to exit the debugger and resume your application.  
+
+Extending the Control DRb with Custom Functionality
+---------------------------------------------------
+
+Extending the Control DRb is a key aspect of climax.  For instance it is a common idiom for web
+applications to delegate difficult tasks to background jobs.  Let's take a common scenario and see
+how we might implement this scenario with climax.
+
+In this example there is a web application that allows users to upload images.  The image is stored
+in a temporary directory by the web application and then a request is sent to a background job
+asking it to process the image and store it in a more permanent location.  Let's say the web
+application simply wants to send the command `process_image` and pass as an argument the path of the
+image that was uploaded.
+
+Let's see how we can extend the Control DRb with a `process_image` method.  We'll also see a possible
+workflow for how the background job might tackle its work.
+
+    require 'climax'
+    require 'fileutils'
+    
+    module Climax
+      class ControlServer
+        def process_image (path)
+          app.climax_send_event(:process_image, path)
+        end
+      end
+    end
+    
+    class ImageProcessor
+      include Climax::Application
+    
+      def configure
+        options do
+          on 't', 'target-directory=', 'Destination directory to save processed images to.', :default => '/var/saved/images'
+        end
+      end
+    
+      def pre_main
+        FileUtils.mkdir_p(opts[:'target-directory'])
+        @processor_queue = []
+      end
+    
+      def main
+        if @processor_queue.empty?
+          sleep 0.5
+          return nil
+        end
+    
+        image_path = @processor_queue.pop
+        log.info "Processing image #{image_path}"
+        do_work(image_path)
+        return nil
+      end
+    
+      def process_image (path)
+        @processor_queue.push(path)
+      end
+    
+      def do_work(path)
+        # process image at path
+        # save to target directory
+      end
+    end
+
+Adding your own commands to the Control DRb couldn't be easier.  Simply extend the
+`Climax::ControlServer` class with your own methods that push events onto the climax event queue.
+When climax processes the event it will call a method in your application instance with the same
+name as the event.  In the example above we send a `:process_image` event with an argument.  When
+climax processes this event it will attempt to call a `process_image` method in the application
+instance, passing along any arguments.
+
+In this case we simply add the work to a simple queue and allow `main` to process the jobs from the
+queue.
+
+Notice that when you are extending `Climax::ControlServer` you have access to your application
+instance via the `app` method.  From here you can call any publicly available methods on your
+application instance.  *But be careful*.  The DRb is running in a separate thread.  This is why we
+simply send events!  It is always best to only send events from your custom ControlServer methods.
+Doing so allows you to never need worry about making your application thread-safe.  If you're a
+cowboy and decide to call various public methods on your app instance directly from your custom
+`ControlServer` methods you may end up with some strange results.  So unless you are familiar with
+thread-safe applications it is suggested that you only place events onto the queue from your custom
+`ControlServer` methods.
+
+Now the web application can simply connect to your application's DRb and call the `process_image`
+method, passing it an image path.
+
+Something interesting about this is that non-ruby applications can also easily tell our image
+processor to process images.
+
+For instance you can send commands to your application using the `climax` CLI interface:
+
+    climax control process_image /tmp/uploaded-images/tmp-d8ej2.jpg
+
+This means any application, even just simple shell scripts, can easily send commands to our
+background job.
+
+Of course it is best to give each of your climax applications a unique Control DRb port.  You can
+then specify which port to send commands to with the `-p` option to `climax control`:
+
+    climax control -p $IMAGE_PROCESSOR_PORT process_image /tmp/uploaded-images/tmp-d8ej2.jpg

data/lib/climax/application.rb

@@ -172,6 +172,8 @@ module Climax
             when :stop_control_drb then DRb.stop_service
             when :start_remote_debugger then binding.remote_pry rescue nil
             when :quit, :exit then return 0
+            else
+              self.send(event.type, *[event.payload])
             end
           end
         end while !event.nil?

data/lib/climax/control_drb.rb

@@ -2,20 +2,23 @@ require 'drb/drb'
 
 module Climax
   class ControlServer
+
     def initialize(app)
       @app = app
     end
 
+    attr_reader :app
+
     def log_level
-      @app.log_level
+      app.log_level
     end
 
     def log_level= (level)
-      @app.climax_send_event(:set_log_level, level)
+      app.climax_send_event(:set_log_level, level)
     end
 
     def start_debugger
-      @app.climax_send_event(:start_remote_debugger)
+      app.climax_send_event(:start_remote_debugger)
     end
   end
 

data/lib/climax/version.rb

@@ -1,3 +1,3 @@
 module Climax
-  VERSION = "0.0.5"
+  VERSION = "0.0.6"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: climax
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.0.6
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-02-25 00:00:00.000000000 Z
+date: 2013-02-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: pry