resque-forker 1.0.beta

data/CHANGELOG

@@ -0,0 +1,2 @@
+2010-07-30 v1.0
+	Extracted from Flowtown with permission

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+Copyright (c) 2010 Flowtown, Inc.
+
+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.rdoc

@@ -0,0 +1,163 @@
+= Resque::Forker
+
+Super awesome forking action for Resque workers.
+
+== Forking Workers
+
+If you're like us, you have a sizeable application with many models, libraries
+and dependencies that are shared between the front-facing UI and the back-end
+processing. And like us, you're Resque worker are loading the entire application
+each time the fire up.
+
+If you're running 8 workers that can be quite the CPU-churning delay loading
+them all up. Exactly the problem we're going to solve by starting the
+application once and then forking it. Forking all these workers takes
+milliseconds. Faster restart means faster deploy and less downtime. Yay!
+
+
+== Creating the script
+
+We're going to create a Ruby script that loads the applications, handles
+connections, and decides what kind of workload (how many workers on which
+queues) to process.
+
+Edit this to your needs and place it in script/workers:
+
+  #!/usr/bin/env ruby
+  require "resque/forker"
+
+  # Load the application.
+  Resque.setup do |forker|
+    require File.dirname(__FILE__) + "/../config/environment"
+    ActiveRecord::Base.connection.disconnect!
+    if Rails.env.production?
+      forker.logger = Rails.logger
+      forker.workload = ["*"] * 4        # 4 workers on all queues
+      forker.user "www-data", "www-data" # don't run as root
+    end
+  end
+  # Stuff to do after forking a worker.
+  Resque.after_fork do
+    ActiveRecord::Base.establish_connection
+  end
+  Resque.fork!
+
+You can now run workers from the command line:
+
+  $ ruby script/workers
+
+In development mode you will get one worker that outputs to the console. In
+production you get four workers that log messages to the Rails logger and run
+under the www-data account (never run as root).
+
+Worker processes can't share connections with each other, so we're closing the
+database connection from the master process and then establishing new connection
+for each individual worker. You'll have to do the same with other libraries that
+maintain open connections (MongoMapper, Vanity, etc)
+
+You tell Resque::Forker what workload to process using an array of queue lists.
+Each array element represents one worker, so 4 elements would start up four
+workers. The element's value tell the worker which queues to process. For
+example, if you want four workers processing the import queue, and two of these
+workers also processing the export queue:
+
+  forker.workload = ["import", "import,export"] * 2
+
+
+== Controlling the Workers
+
+You can use these signals to control individual workers, or send them to the
+master process, which will propagate them to all workers:
+
+  kill -QUIT -- Quit gracefully
+  kill -TERM -- Terminate immediately
+  kill -USR1 -- Stop any ongoing job
+  kill -USR2 -- Suspend worker
+  kill -CONT -- Resume suspended worker
+
+After deploying you want to stop all  workers, reload the master process (and
+the application and its configuration) and have all workers restarted. Simply
+send it the HUP signal. That easy.
+
+You probably want to suspend/resume (USR2/CONT signals) if you're doing any
+maintenance work that may disrupt the workers, like rake db:migrate. Of course
+you can stop/start the master process, but what would be the fun of that.
+
+Of course, you want the workers to start after reboot and each way to control
+them. Read on how to use Resque::Forker with Upstart.
+
+
+== Using Upstart and Capistrano
+
+If you're running a recent release of Ubuntu, you can get Upstart to manage your
+workers.
+
+Edit this to your needs and place it in /etc/init/workers:
+
+  start on runlevel [2345]
+  stop on runlevel [06]
+  chdir /var/www/myapp/current
+  env RAILS_ENV=production
+  exec script/workers
+  respawn
+
+After reading this, Upstart to make sure your workers are always up and running.
+It's awesome like that.
+
+To start, stop, check status and reload:
+
+  $ start workers
+  $ stop workers
+  $ status workers
+  $ reload workers
+
+You need to be root to start/stop the workers. However, if you change ownership
+of the workers (see fork.user above) you can reload them as that user. You can
+do something like this in your Capfile:
+
+  namespace :workers do
+    task :pause do
+      run "status workers | cut -d ' ' -f 4 | xargs kill -USR2"
+    end
+    task :resume do
+      run "status workers | cut -d ' ' -f 4 | xargs kill -CONT"
+    end
+    task :reload do
+      run "reload workers"
+    end
+  end
+  after "deploy:update_code", "workers:reload"
+
+Because of the way Upstart works, there is no need for PID file or running as
+daemon. Yay for sane process supervisors! When you reload workers,
+Resque::Forker reloads itself (and the application) while keeping the same PID.
+
+
+== Troubleshooting
+ 
+If you're using Bundler, you might need to run the script using: 
+
+  exec bundle exec script/workers
+
+If you're using RVM and Bundler, you might need to create a wrapper and use it:
+
+  exec run_bundle script/workers
+
+The point is, when the script starts it will expect both resque and
+resque-forker must be available for loading (that typically means GEMPATH).
+Depending on your setup, they may be loaded by Bundler, available in the RVM
+gemset, installed as system gems, etc.
+
+If you're hitting a wall, remember that any settings and aliases that you have
+in .bashrc (RVM, for example, or the path to bundle) are not sourced by Upstart,
+so commands that "just work" when you run from the console will fail.
+
+What you can do to troubleshoot this situation is run as root in a new shell
+that doesn't have your regular account settings:
+
+  $ env -i sudo /bin/bash --norc --noprofile
+
+
+== Credits
+
+Copyright (c) 2010 Flowtown, Inc.

data/Rakefile

@@ -0,0 +1,22 @@
+spec = Gem::Specification.load(File.expand_path("resque-forker.gemspec", File.dirname(__FILE__)))
+
+desc "Build the Gem"
+task :build do
+  sh "gem build #{spec.name}.gemspec"
+end
+
+desc "Install #{spec.name} locally"
+task :install=>:build do
+  sudo = "sudo" unless File.writable?( Gem::ConfigMap[:bindir])
+  sh "#{sudo} gem install #{spec.name}-#{spec.version}.gem"
+end
+
+desc "Push new release to gemcutter and git tag"
+task :push=>["build"] do
+  sh "git push"
+  puts "Tagging version #{spec.version} .."
+  sh "git tag v#{spec.version}"
+  sh "git push --tag"
+  puts "Building and pushing gem .."
+  sh "gem push #{spec.name}-#{spec.version}.gem"
+end

data/lib/resque/forker.rb

@@ -0,0 +1,232 @@
+require "logger"
+require "resque"
+
+module Resque
+  # Loading Rails, the application and all its dependencies takes significant time
+  # and eats up memory. We keep startup time manageable by loading the application
+  # once and forking the worker processes. When using REE, this will also keep
+  # memory usage low. Note that we can't reuse connections and file handles in
+  # child processes, so no saving on opening database connections, etc.
+  #
+  # To use this library, wrap your setup and teardown blocks: 
+  #   Resque.setup do |forker|
+  #     require File.dirname(__FILE__) + "/../config/environment"
+  #     ActiveRecord::Base.connection.disconnect!
+  #     forker.logger = Rails.logger
+  #     forker.user "nobody", "nobody"
+  #   end
+  #   Resque.after_fork do
+  #     ActiveRecord::Base.establish_connection
+  #   end
+  #
+  # Most libraries cannot share connections between child processes, you want to
+  # close these in the parent process (during setup) and reopen connections for
+  # each worker when it needs it to process a job (during after_work). This
+  # example shows how to do that for ActiveRecord, you will need to do the same
+  # for other libraries, e.g. MongoMapper, Vanity. 
+  #
+  # All the forking action is handled by a single call:
+  #   # Three workers, processing all queues
+  #   Resque.fork! ["*"] * 3
+  #
+  # The workload is specified as an array of lists of queues, that way you can
+  # decide how many workers to fork (length of the array) and give each worker
+  # different set of queues to work with. For example, to have four workers
+  # processing import queue, and only two of these also processing export queue:
+  #
+  #   Resque.fork! ["import,export", "import"] * 2
+  #
+  # Once the process is up and running, you control it by sending signals:
+  # - kill -QUIT -- Quit gracefully
+  # - kill -TERM -- Terminate immediately
+  # - kill -USR2 -- Suspend all workers (e.g when running rake db:migrate)
+  # - kill -CONT -- Resume suspended workers
+  # - kill -HUP -- Shutdown and restart
+  #
+  # The HUP signal will wait for all existing jobs to complete, run the teardown
+  # block, and reload the script with the same environment and arguments. It will
+  # reload the application, the libraries, and of course any configuration changes
+  # in this script (e.g. changes to the workload).
+  #
+  # The reloaded process keeps the same PID so you can use it with upstart:
+  #   reload workers
+  # The upstart script could look something like this:
+  #   start on runlevel [2345]
+  #   stop on runlevel [06]
+  #   chdir /var/app/current
+  #   env RAILS_ENV=production
+  #   exec script/workers
+  #   respawn
+  class Forker
+    def initialize(options = nil)
+      @options = options || {}
+      @logger = @options[:logger] || Logger.new($stderr)
+      @workload = ["*"]
+      @children = []
+      begin
+        require "system_timer"
+        @timeout = SystemTimer.method(:timeout_after)
+      rescue NameError, LoadError
+        require "timeout"
+        @timeout = method(:timeout)
+      end
+    end
+
+    # Workload is an array of queue sets, one entry per workers (so four entries
+    # if you want four workers). Each entry is comma-separated queue names.
+    attr_accessor :workload
+
+    # Defaults to stderr, but you may want to point this at Rails logger.
+    attr_accessor :logger
+
+    # Run and never return.
+    def run
+      @logger.info "** Running as #{Process.pid}"
+      setup_signals
+      if setup = Resque.setup
+        @logger.info "** Loading application ..."
+        setup.call self
+      end
+      reap_children
+      @logger.info "** Forking workers"
+      enable_gc_optimizations
+      # Serious forking action.
+      @workload.each do |queues|
+        @children << fork { run_worker queues }
+      end
+    rescue
+      @logger.error "** Failed to load application: #{$!.message}"
+      @logger.error $!.backtrace.join("\n")
+    ensure
+      # Sleep forever.
+      sleep 5 while true
+    end
+
+    # Change ownership of this process.
+    def user(user, group)
+      uid = Etc.getpwnam(user).uid
+      gid = Etc.getgrnam(group).gid
+      if Process.euid != uid || Process.egid != gid
+        Process.initgroups user, gid
+        Process::GID.change_privilege gid
+        Process::UID.change_privilege uid
+      end
+    end 
+
+  protected
+
+    # Setup signal handlers.
+    def setup_signals
+      # Stop gracefully
+      trap :QUIT do
+        stop
+        exit
+      end
+      # Pause/continue processing
+      trap(:USR1) { Process.kill :USR1, *@children }
+      trap(:USR2) { Process.kill :USR2, *@children }
+      trap(:CONT) { Process.kill :CONT, *@children }
+      # Reincarnate. Stop children, and reload binary (application and all)
+      # while keeping same PID.
+      trap :HUP do
+        @logger.info "** Reincarnating ..."
+        stop
+        exec $0, *ARGV
+      end
+      # Terminate quickly
+      trap(:TERM) { shutdown! }
+      trap(:INT) { shutdown! }
+    end
+
+    # Enables GC Optimizations if you're running REE.
+    # http://www.rubyenterpriseedition.com/faq.html#adapt_apps_for_cow
+    def enable_gc_optimizations
+      if GC.respond_to?(:copy_on_write_friendly=)
+        GC.copy_on_write_friendly = true
+      end
+    end
+
+    # Run and never return.
+    def run_worker(queues)
+      worker = Resque::Worker.new(*queues.split(","))
+      worker.verbose = $VERBOSE
+      worker.very_verbose = $DEBUG
+      worker.work(@options[:interval] || 5) # interval, will block
+    end
+
+    # Stop child processes and run any teardown action.
+    def stop(gracefully = true)
+      @logger.info "** Quitting ..."
+      @children.each do |pid|
+        begin
+          Process.kill gracefully ? :QUIT : :TERM, pid
+          sleep 0.1
+        rescue Errno::ESRCH
+        end
+      end
+      reap_children
+      if teardown = Resque.teardown
+        @timeout.call @options[:terminate] || 5 do
+          begin
+            teardown.call self
+          rescue Exception
+          end
+        end
+      end
+      @logger.info "** Good night"
+    end
+
+    # Eat up zombies.
+    def reap_children
+      loop do
+        wpid, status = Process.waitpid2(0, Process::WNOHANG)
+        wpid or break
+      end
+      @children.clear
+    rescue Errno::ECHILD
+    end
+
+    # When stop is not good enough.
+    def shutdown!
+      @logger.info "** Terminating"
+      stop false
+      exit!
+    end
+
+  end
+
+  
+  # Specify what needs to be done to setup the application. This is the place
+  # to load Rails or do anything expensive. For example:
+  #   Resque.setup do
+  #     require File.dirname(__FILE__) + "/../config/environment"
+  #     ActiveRecord.disconnect
+  #   end
+  def setup(&block)
+    block ? (@setup = block) : @setup
+  end
+
+  # Do this before exiting or before reloading.
+  def teardown(&block)
+    block ? (@teardown = block) : @teardown
+  end
+
+  # Forks workers to take care of the workload.
+  #
+  # The workload is an array of queue names, one entry for each worker. For
+  # example, if you want to run four workers processing all queues.
+  #   Resque.fork! ["*"] * 4
+  # If you want four workers, all of which will be processing imports, but
+  # only two processing exports:
+  #   Resque.fork! ["import", "import,export"] * 2
+  #
+  # Options are:
+  # - :logger -- Which Logger to use (default logger to stdout)
+  # - :interval -- Processing interval (default to 5 seconds)
+  # - :terminate -- Timeout running teardown block (default to 5 seconds)
+  def fork!(workload = nil, options = nil)
+    forker = Resque::Forker.new(options)
+    forker.workload = workload if workload
+    forker.run
+  end
+end

data/resque-forker.gemspec

@@ -0,0 +1,19 @@
+Gem::Specification.new do |spec|
+  spec.name           = "resque-forker"
+  spec.version        = "1.0.beta"
+  spec.author         = "Assaf Arkin"
+  spec.email          = "assaf@labnotes.org"
+  spec.homepage       = "http://github.com/assaf/resque-forker"
+  spec.summary        = "Super awesome forking action for Resque workers"
+  spec.post_install_message = ""
+
+  spec.files          = Dir["{lib,script}/**/*", "CHANGELOG", "MIT-LICENSE", "README.rdoc", "Rakefile", "resque-forker.gemspec"]
+
+  spec.has_rdoc         = true
+  spec.extra_rdoc_files = "README.rdoc", "CHANGELOG"
+  spec.rdoc_options     = "--title", "Resque Forker  #{spec.version}", "--main", "README.rdoc",
+                          "--webcvs", "http://github.com/assaf/#{spec.name}"
+
+  spec.required_ruby_version = '>= 1.8.7'
+  spec.add_dependency "resque"
+end

data/script/workers

@@ -0,0 +1,18 @@
+#!/usr/bin/env ruby
+require "resque/forker"
+
+# Load the application.
+Resque.setup do |forker|
+  require File.dirname(__FILE__) + "/../config/environment"
+  ActiveRecord::Base.connection.disconnect!
+  if Rails.env.production?
+    forker.logger = Rails.logger
+    forker.workload = ["*"] * 4        # 4 workers on all queues
+    forker.user "www-data", "www-data" # don't run as root
+  end
+end
+# Stuff to do after forking a worker.
+Resque.after_fork do
+  ActiveRecord::Base.establish_connection
+end
+Resque.fork!

metadata

@@ -0,0 +1,96 @@
+--- !ruby/object:Gem::Specification 
+name: resque-forker
+version: !ruby/object:Gem::Version 
+  hash: 31098137
+  prerelease: true
+  segments: 
+  - 1
+  - 0
+  - beta
+  version: 1.0.beta
+platform: ruby
+authors: 
+- Assaf Arkin
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-07-30 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: resque
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id001
+description: 
+email: assaf@labnotes.org
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+- CHANGELOG
+files: 
+- lib/resque/forker.rb
+- script/workers
+- CHANGELOG
+- MIT-LICENSE
+- README.rdoc
+- Rakefile
+- resque-forker.gemspec
+has_rdoc: true
+homepage: http://github.com/assaf/resque-forker
+licenses: []
+
+post_install_message: ""
+rdoc_options: 
+- --title
+- Resque Forker  1.0.beta
+- --main
+- README.rdoc
+- --webcvs
+- http://github.com/assaf/resque-forker
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 57
+      segments: 
+      - 1
+      - 8
+      - 7
+      version: 1.8.7
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">"
+    - !ruby/object:Gem::Version 
+      hash: 25
+      segments: 
+      - 1
+      - 3
+      - 1
+      version: 1.3.1
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Super awesome forking action for Resque workers
+test_files: []
+