workforce 0.1.0

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,23 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+## PROJECT::SPECIFIC
+log
+pid

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Rodrigo Kochenburger
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,26 @@
+Summary
+=======
+
+Workforce is an attempt to create a framework to develop background processes and controlling the execution of these processes in a distributed environment.
+
+Project Description
+===================
+
+Coming soon.
+
+Contributing
+============
+
+Note on Patches/Pull Requests
+-----------------------------
+ 
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a future version unintentionally.
+* Commit, do not mess with Rakefile, version, or history.
+* Send me a pull request. Bonus points for topic branches.
+
+Copyright & Licensing
+=====================
+
+Copyright (c) 2010 Rodrigo Kochenburger. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,45 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name        = "workforce"
+    gem.summary     = "Framework and a distributed runtime manager to creating and running background processes"
+    gem.description = "Workforce is an attempt to create a framework to develop background processes and controlling the execution of these processes in a distributed environment"
+    gem.email       = "divoxx@gmail.com"
+    gem.homepage    = "http://github.com/divoxx/workforce"
+    gem.authors     = ["Rodrigo Kochenburger"]
+    gem.add_development_dependency "rspec", ">= 1.2.9"
+    gem.add_development_dependency "yard", ">= 0.5.5"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :spec => :check_dependencies
+
+task :default => :spec
+
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new
+rescue LoadError
+  task :yardoc do
+    abort "YARD is not available. In order to run yardoc, you must: sudo gem install yard"
+  end
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/bin/workforce

@@ -0,0 +1,43 @@
+#!/usr/bin/env ruby
+require "ostruct"
+require "optparse"
+require "workforce"
+
+config = Workforce::Config.instance
+files_to_require = []
+
+optparser = OptionParser.new do |opts|
+  opts.banner = "Usage: #{$0} [options] path/to/worker.rb #{Workforce::Controller::ACTIONS.join("|")}"
+
+  opts.separator ""
+  opts.separator "Options:"
+
+  opts.on("-c", "--config [CONFIG_PATH]", "Uses configurations in config_file") do |config_path|
+    config.load_file(config_path)
+  end
+  
+  opts.on("--pid-dir PID_DIR", "Store pids on directory PID_DIR", "Default: #{config.pid_dir}") do |pid_dir|
+    config.pid_dir = pid_dir
+  end
+  
+  opts.on("--log-dir LOG_DIR", "Store logs on directory LOG_DIR", "Default: #{config.log_dir}") do |log_dir|
+    config.log_dir = log_dir
+  end
+  
+  opts.on("--require FILE", "Require FILE before executing action") do |file_path|
+    files_to_require << file_path
+  end
+end
+
+optparser.parse!
+worker_path, action = ARGV
+
+unless worker_path && action
+  puts optparser
+  exit(1)
+end
+
+files_to_require.each { |path| require(path) }
+require worker_path
+worker_class = File.basename(worker_path, ".rb").camelcase
+Workforce::Controller.instance.dispatch(worker_class, action)

data/config_sample.rb

@@ -0,0 +1,4 @@
+base_path = File.dirname(__FILE__)
+
+pid_dir "#{base_path}/pid"
+log_dir "#{base_path}/log"

data/lib/core_ext.rb

@@ -0,0 +1,9 @@
+class String
+  def underscore
+    self.sub(/\A([A-Z])/){ $1.downcase }.gsub(/([a-z])([A-Z])/){ "#{$1}_#{$2.downcase}" }
+  end
+  
+  def camelcase
+    self.sub(/\A([a-z])/){ $1.upcase }.gsub(/([a-z])_([a-z])/){ "#{$1}#{$2.upcase}"}
+  end
+end

data/lib/workforce/configuration.rb

@@ -0,0 +1,39 @@
+require "singleton"
+
+module Workforce
+  class Config
+    include Singleton
+    
+    def self.config_attr(attr_name)
+      define_method(attr_name) do |*args|
+        raise ArgumentError, "wrong number of arguments (#{args.size} for 1)" if args.size > 1
+        
+        if instance_variable_get("@#{attr_name}").nil? || args[0]
+          instance_variable_set("@#{attr_name}", args[0] || yield)
+        end
+        
+        instance_variable_get("@#{attr_name}")
+      end
+    end
+    
+    def self.get(attr_name)
+      self.instance.send(attr_name)
+    end
+    
+    def initialize
+      yield self if block_given?
+    end
+    
+    def load_file(file_path)
+      instance_eval(File.read(file_path))
+    end
+
+    config_attr :pid_dir do
+      "./pid"
+    end
+
+    config_attr :log_dir do
+      "./log"
+    end
+  end
+end

data/lib/workforce/controller.rb

@@ -0,0 +1,107 @@
+require "singleton"
+require "workforce/manager"
+
+module Workforce
+  class Controller
+    ACTIONS = %w(run start stop restart status schedule dispose)
+    include Singleton
+    
+    def dispatch(worker_klass, action)
+      unless ACTIONS.include?(action.to_s)
+        puts "Invalid action #{action}"
+        exit(1)
+      end
+      
+      send(action, worker_klass)
+    end
+    
+    def run(worker_klass)
+      if running?(worker_klass)
+        puts "#{worker_klass}'s manager already running"
+        exit(1)
+      end
+      
+      manager = Workforce::Manager.new(get_klass(worker_klass))
+      store_pid(worker_klass, Process.pid)
+      manager.run
+      remove_pid_file(worker_klass)
+    end
+    
+    def start(worker_klass)
+      if running?(worker_klass)
+        puts "#{worker_klass}'s manager already running"
+        exit(1)
+      end
+      
+      manager = Workforce::Manager.new(get_klass(worker_klass))
+      store_pid(worker_klass, manager.launch)
+    end
+      
+    def stop(worker_klass)
+      Process.kill(:QUIT, running_pid(worker_klass))
+      remove_pid_file(worker_klass)
+    end
+    
+    def restart(worker_klass)
+      stop(worker_klass) if running?(worker_klass)
+      start(worker_klass)
+    end
+    
+    def status(worker_klass)
+      if running?(worker_klass)
+        puts "Running (#{running_pid(worker_klass)})"
+      else
+        puts "Not running"
+      end
+    end
+    
+    def schedule(worker_klass)
+      unless running?(worker_klass)
+        puts "#{worker_klass}'s manager not running yet"
+        exit(1)
+      end
+      
+      Process.kill(:USR1, running_pid(worker_klass))
+    end
+    
+    def dispose(worker_klass)
+      unless running?(worker_klass)
+        puts "#{worker_klass}'s manager not running yet"
+        exit(1)
+      end
+      
+      Process.kill(:USR2, running_pid(worker_klass))
+    end
+    
+  protected
+    def get_klass(klass)
+      return klass unless klass.is_a?(String) || klass.is_a?(Symbol)
+      
+      klass.to_s.split(/::/).inject(Object) do |namespace, const_name|  
+        namespace.const_get(const_name)
+      end
+    end
+    
+    def pid_file(worker_klass)
+      "#{Workforce::Config.get(:pid_dir)}/#{worker_klass.to_s.underscore}.pid"
+    end
+  
+    def running?(worker_klass)
+      File.exist?(pid_file(worker_klass))
+    end
+    
+    def running_pid(worker_klass)
+      Integer(File.read(pid_file(worker_klass)))
+    end
+    
+    def store_pid(worker_klass, pid)
+      File.open(pid_file(worker_klass), "w") do |fp| 
+        fp.write(pid)
+      end
+    end
+    
+    def remove_pid_file(worker_klass)
+      File.unlink(pid_file(worker_klass))
+    end
+  end
+end

data/lib/workforce/manager.rb

@@ -0,0 +1,156 @@
+module Workforce
+  # A manager is responisble for managing instance of workers of a certain class.
+  # It allows to dinamically schedule a new worker or dispose an existing one by trapping signals.
+  #
+  # A worker is any class that defines the method _run_.
+  #
+  # For example:
+  #
+  #   class ContinuousRun
+  #     def initialize
+  #       Signal.trap(:QUIT) { @shutdown = true }
+  #     end
+  #
+  #     def run
+  #       loop do
+  #         puts "Running worker #{Process.pid}"
+  #         sleep 1
+  #         Process.exit if @shutdown
+  #       end
+  #     end
+  #   end
+  #   
+  #   manager = Workforce::Manager.new(ContinuousRun)
+  #   manager.run
+  #
+  # Now the current process will be managing instances of the ContinuousRun task:
+  #  - If you send a SIGUSR1 to it, it will schedule a new instance of ContinuousRun to run.
+  #  - If you send a SIGUSR2 to it, it will dispose one of the running instance of it.
+  #  - If you send a SIGQUIT or SIGINT to it, it will stop all the instances and then exit.
+  #
+  # When a instance is disposed, a SIGQUIT is send to the worker process, so if you might want to
+  # trap the signal and perform a graceful shutdown on the worker.
+  class Manager
+    include Services
+    
+    # Creates a new Manager instance to the given worker class.
+    def initialize(worker)
+      @worker             = worker
+      @pids               = []
+      @old_signals        = {}
+      @pipe_in, @pipe_out = IO.pipe
+    end
+    
+    # Run the manager main loop, which controls the running instances.
+    def run
+      log_errors do
+        logger.info "Starting manager for #{@worker}"
+
+        @running = true
+        $0 = "Workforce: #{@worker.name} master"
+
+        trap_signal(:INT, :shutdown)
+        trap_signal(:QUIT, :shutdown)
+        trap_signal(:USR1, :schedule)
+        trap_signal(:USR2, :dispose)
+
+        trap_signal(:CLD) do
+          pid = Process.wait
+          logger.info "Removing process (#{pid}) from worker pool"
+          @pids.delete(pid)
+        end
+
+        # Block process until something is written to @pipe_out
+        IO.select([@pipe_in], nil, nil, nil)
+        logger.info "Shutting down manager"
+      end
+    ensure
+      @pipe_in.close
+      @pipe_out.close
+    end
+    
+    # Launch a manager as a daemon. Creates a new fork running the manager and returns the
+    # manager pid to the parent process (the one who called this method).
+    def launch
+      logger.info "Launching a new manager for #{@worker.name}"
+      child_id = fork and return child_id
+      Process.setsid
+      Dir.chdir '/'
+      File.umask 0000
+      STDIN.reopen '/dev/null'
+      STDOUT.reopen '/dev/null', 'a'
+      STDERR.reopen STDOUT
+      run
+    end
+
+    # Sends a SIGQUIT to all worker processes and signals the main loop that it is safe to exit.
+    def shutdown
+      log_errors do
+        ensure_running!
+      
+        logger.info "Shutting down child processes"
+        @pids.each do |pid|
+          Process.kill(:QUIT, pid)
+        end
+      
+        @pipe_out.write(1)
+      end
+    end
+
+    # schedule a new worker instance.
+    # This will fork the master process and start running the worker as a child process.
+    def schedule
+      log_errors do
+        ensure_running!
+        logger.info "Scheduling new worker"
+      
+        if pid = fork
+          logger.info "New worker scheduled: #{pid}"
+          @pids << pid
+        else
+          $0 = "Workforce: #{@worker.name} worker"
+          restore_signals
+          @worker.new.run
+          logger.info "Worker finished processing: #{Process.pid}"
+          Process.exit
+        end
+      end
+    end
+    
+    # Sends a SIGQUIT to one of the workers.
+    def dispose
+      log_errors do
+        ensure_running!
+        logger.info "Disposing one of the workers"
+      
+        Process.kill(:QUIT, @pids.shift) unless @pids.empty?
+      end
+    end
+    
+  protected
+    def ensure_running!
+      raise RuntimeError, "manager is not running" unless @running
+    end
+    
+    def log_errors
+      yield
+    rescue => e
+      logger.error("#{e.message}\n#{e.backtrace.join("\n")}")
+      raise(e)
+    end
+    
+    def trap_signal(signal, method = nil, &block)
+      current_pid = Process.pid
+      
+      @old_signals[signal] = Signal.trap(signal) do
+        if Process.pid == current_pid
+          method ? send(method) : block.call
+        end
+      end
+    end
+    
+    def restore_signals
+      @old_signals.each { |sig, cmd| Signal.trap(sig, cmd) }
+    end
+  end
+end

data/lib/workforce.rb

@@ -0,0 +1,13 @@
+module Workforce
+  module Services
+    def logger
+      @logger ||= Logger.new("#{Config.get(:log_dir)}/#{@worker.name.underscore}.log")
+    end
+  end
+end
+
+require "logger"
+require "core_ext"
+require "workforce/configuration"
+require "workforce/manager"
+require "workforce/controller"

data/sleep_daemon.rb

@@ -0,0 +1,5 @@
+class SleepDaemon
+  def run
+    loop { sleep 1 }
+  end
+end

data/spec/spec.opts

@@ -0,0 +1 @@
+--color

data/spec/spec_helper.rb

@@ -0,0 +1,9 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'workforce'
+require 'spec'
+require 'spec/autorun'
+
+Spec::Runner.configure do |config|
+  
+end

metadata

@@ -0,0 +1,105 @@
+--- !ruby/object:Gem::Specification 
+name: workforce
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Rodrigo Kochenburger
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-05-31 00:00:00 -03:00
+default_executable: workforce
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 2
+        - 9
+        version: 1.2.9
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: yard
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        - 5
+        - 5
+        version: 0.5.5
+  type: :development
+  version_requirements: *id002
+description: Workforce is an attempt to create a framework to develop background processes and controlling the execution of these processes in a distributed environment
+email: divoxx@gmail.com
+executables: 
+- workforce
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.md
+files: 
+- .document
+- .gitignore
+- LICENSE
+- README.md
+- Rakefile
+- VERSION
+- bin/workforce
+- config_sample.rb
+- lib/core_ext.rb
+- lib/workforce.rb
+- lib/workforce/configuration.rb
+- lib/workforce/controller.rb
+- lib/workforce/manager.rb
+- sleep_daemon.rb
+- spec/spec.opts
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://github.com/divoxx/workforce
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: Framework and a distributed runtime manager to creating and running background processes
+test_files: 
+- spec/spec_helper.rb