rails-four-queueing 0.1.0

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2012 YOURNAME
+
+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,97 @@
+# Rails::Four::Queueing
+
+[![Build Status](https://secure.travis-ci.org/phlipper/rails-four-queueing.png)](https://next.travis-ci.org/phlipper/rails-four-queueing)
+
+## Description
+
+It's the Queue from Rails 4, backported to Rails 3.2+ for your Queueing pleasure.
+
+
+## Requirements
+
+This gem requires Rails 3.2+ and has been tested on the following versions:
+
+* 3.2.8
+
+This gem has been tested against the following Ruby versions:
+
+* 1.9.2
+* 1.9.3
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "rails-four-queueing"
+```
+
+And then execute:
+
+```
+$ bundle
+```
+
+Or install it yourself as:
+
+```
+$ gem install rails-four-queueing
+```
+
+
+## Usage
+
+It's the [Rails 4 Queue](https://github.com/rails/rails/blob/master/activesupport/lib/active_support/queueing.rb):
+
+```
+Rails.queue is the application's queue. You can push a job onto
+the queue by:
+
+  Rails.queue.push job
+
+A job is an object that responds to +run+. Queue consumers will
+pop jobs off of the queue and invoke the queue's +run+ method.
+
+Note that depending on your queue implementation, jobs may not
+be executed in the same process as they were created in, and
+are never executed in the same thread as they were created in.
+
+If necessary, a queue implementation may need to serialize your
+job for distribution to another process. The documentation of
+your queue will specify the requirements for that serialization
+```
+
+
+## Contributing
+
+1. [Fork it](https://github.com/phlipper/rails-four-queueing/fork_select)
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. [Create a Pull Request](hhttps://github.com/phlipper/rails-four-queueing/pull/new)
+
+
+## Contributors
+
+Many thanks go to the following who have contributed to making this gem even better:
+
+* **[@rails](https://github.com/rails)**
+  * for making this all possible in the first place
+* **[@elskwid](https://github.com/elskwid)**
+  * for providing the inspiration, and the persperation, to see this through to the bitter end
+* **[@phlipper](https://github.com/phlipper)**
+  * for providing the inspiration, and the persperation, to see this through to the bitter end
+
+
+## License
+
+**rails-four-queueing**
+
+* Freely distributable and licensed under the [MIT license](http://phlipper.mit-license.org/2012/license.html).
+* Copyright (c) 2012 Phil Cohen (github@phlippers.net) [![endorse](http://api.coderwall.com/phlipper/endorsecount.png)](http://coderwall.com/phlipper)
+* http://phlippers.net/
+
+**rails**
+
+* Ruby on Rails is released under the [MIT License](http://www.opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,38 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Rails::Four::Queueing'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+
+
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+
+task :default => :test

data/lib/rails-four-queueing.rb

@@ -0,0 +1,8 @@
+require "rails/four/queueing/engine"
+
+module Rails
+  module Four
+    module Queueing
+    end
+  end
+end

data/lib/rails/four/application.rb

@@ -0,0 +1,17 @@
+module Rails
+  module Four
+    module Application
+      extend ActiveSupport::Concern
+
+      included do
+        attr_accessor :queue_consumer
+        attr_writer :queue
+      end
+
+      def queue #:nodoc:
+        @queue ||= config.queue || Rails::Four::Queueing::Queue.new
+      end
+
+    end
+  end
+end

data/lib/rails/four/configuration.rb

@@ -0,0 +1,12 @@
+module Rails
+  module Four
+    module Configuration
+      extend ActiveSupport::Concern
+
+      included do
+        attr_accessor :queue, :queue_consumer
+      end
+
+    end
+  end
+end

data/lib/rails/four/queueing.rb

@@ -0,0 +1,106 @@
+# Original File: RAILS_ROOT/activesupport/lib/active_support/queueing.rb
+require "delegate"
+require "thread"
+
+module Rails::Four::Queueing
+  # A Queue that simply inherits from STDLIB's Queue. When this
+  # queue is used, Rails automatically starts a job runner in a
+  # background thread.
+  class Queue < ::Queue
+    attr_writer :consumer
+
+    def initialize(consumer_options = {})
+      super()
+      @consumer_options = consumer_options
+    end
+
+    def consumer
+      @consumer ||= ThreadedQueueConsumer.new(self, @consumer_options)
+    end
+
+    # Drain the queue, running all jobs in a different thread. This method
+    # may not be available on production queues.
+    def drain
+      # run the jobs in a separate thread so assumptions of synchronous
+      # jobs are caught in test mode.
+      consumer.drain
+    end
+  end
+
+  class SynchronousQueue < Queue
+    def push(job)
+      super.tap { drain }
+    end
+    alias <<  push
+    alias enq push
+  end
+
+  # In test mode, the Rails queue is backed by an Array so that assertions
+  # can be made about its contents. The test queue provides a +jobs+
+  # method to make assertions about the queue's contents and a +drain+
+  # method to drain the queue and run the jobs.
+  #
+  # Jobs are run in a separate thread to catch mistakes where code
+  # assumes that the job is run in the same thread.
+  class TestQueue < Queue
+    # Get a list of the jobs off this queue. This method may not be
+    # available on production queues.
+    def jobs
+      @que.dup
+    end
+
+    # Marshal and unmarshal job before pushing it onto the queue.  This will
+    # raise an exception on any attempts in tests to push jobs that can't (or
+    # shouldn't) be marshalled.
+    def push(job)
+      super Marshal.load(Marshal.dump(job))
+    end
+  end
+
+  # The threaded consumer will run jobs in a background thread in
+  # development mode or in a VM where running jobs on a thread in
+  # production mode makes sense.
+  #
+  # When the process exits, the consumer pushes a nil onto the
+  # queue and joins the thread, which will ensure that all jobs
+  # are executed before the process finally dies.
+  class ThreadedQueueConsumer
+    attr_accessor :logger
+
+    def initialize(queue, options = {})
+      @queue = queue
+      @logger = options[:logger]
+      @fallback_logger = Logger.new($stderr)
+    end
+
+    def start
+      @thread = Thread.new { consume }
+      self
+    end
+
+    def shutdown
+      @queue.push nil
+      @thread.join
+    end
+
+    def drain
+      @queue.pop.run until @queue.empty?
+    end
+
+    def consume
+      while job = @queue.pop
+        run job
+      end
+    end
+
+    def run(job)
+      job.run
+    rescue Exception => exception
+      handle_exception job, exception
+    end
+
+    def handle_exception(job, exception)
+      (logger || @fallback_logger).error "Job Error: #{job.inspect}\n#{exception.message}\n#{exception.backtrace.join("\n")}"
+    end
+  end
+end

data/lib/rails/four/queueing/engine.rb

@@ -0,0 +1,50 @@
+require "rails"
+require "rails/four/configuration"
+require "rails/four/application"
+
+module Rails
+  module Four
+    module Queueing
+
+      # Public: Initialize Rails 4 Queue
+      class Engine < ::Rails::Engine
+
+        # mixin the queue and queue_consumer to Configuration
+        Rails::Application::Configuration.send :include,
+          Rails::Four::Configuration
+
+        # mixin the queue and queue_consumer to Application with default Queue
+        Rails::Application.send :include, Rails::Four::Application
+
+        # provide a `queue` accessor from the top-level module
+        def Rails.queue
+          application.queue
+        end
+
+        # initialize the configuration instance queue if needed
+        config.after_initialize do |app|
+          unless app.config.instance_variable_get(:"@queue")
+            app.config.instance_variable_set(
+              :"@queue", Rails::Four::Queueing::SynchronousQueue.new
+            )
+          end
+        end
+
+        # initialize the queue_consumer
+        # copied from: railties/lib/rails/application/finisher.rb
+        initializer :activate_queue_consumer, after: "finisher_hook" do |app|
+          if app.config.queue.class == Rails::Four::Queueing::Queue
+            app.queue_consumer = app.config.queue_consumer ||
+                                 app.config.queue.consumer
+            if app.queue_consumer.respond_to?(:logger=)
+              app.queue_consumer.logger ||= Rails.logger
+            end
+            app.queue_consumer.start
+            at_exit { app.queue_consumer.shutdown }
+          end
+        end
+
+      end
+    end
+  end
+end

data/lib/rails/four/queueing/version.rb

@@ -0,0 +1,7 @@
+module Rails
+  module Four
+    module Queueing
+      VERSION = "0.1.0"
+    end
+  end
+end

data/lib/tasks/rails-four-queueing_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :rails-four-queueing do
+#   # Task goes here
+# end

data/test/ci/before_script.sh

@@ -0,0 +1,4 @@
+# clone Rails 3.2 one directory up from our library
+git clone git://github.com/rails/rails.git ../rails
+cd ../rails
+git checkout v3.2.8

data/test/rails-four-queueing_test.rb

@@ -0,0 +1,7 @@
+require File.expand_path("../../lib/rails-four-queueing", __FILE__)
+
+class Rails::Four::QueueingTest < ActiveSupport::TestCase
+  test "module definition" do
+    assert_kind_of Module, Rails::Four::Queueing
+  end
+end

data/test/rails/four/queueing/synchronous_queue_test.rb

@@ -0,0 +1,28 @@
+# Original File: RAILS_ROOT/activesupport/test/queueing/synchronous_queue_test.rb
+require "support/active_support_abstract_unit"
+require "rails/four/queueing"
+
+class SynchronousQueueTest < ActiveSupport::TestCase
+  class Job
+    attr_reader :ran
+    def run; @ran = true end
+  end
+
+  class ExceptionRaisingJob
+    def run; raise end
+  end
+
+  def setup
+    @queue = Rails::Four::Queueing::SynchronousQueue.new
+  end
+
+  def test_runs_jobs_immediately
+    job = Job.new
+    @queue.push job
+    assert job.ran
+
+    assert_raises RuntimeError do
+      @queue.push ExceptionRaisingJob.new
+    end
+  end
+end

data/test/rails/four/queueing/test_queue_test.rb

@@ -0,0 +1,147 @@
+# Original File: RAILS_ROOT/activesupport/test/queueing/test_queue_test.rb
+require "support/active_support_abstract_unit"
+require "rails/four/queueing"
+
+class TestQueueTest < ActiveSupport::TestCase
+  def setup
+    @queue = Rails::Four::Queueing::TestQueue.new
+  end
+
+  class ExceptionRaisingJob
+    def run
+      raise
+    end
+  end
+
+  def test_drain_raises_exceptions_from_running_jobs
+    @queue.push ExceptionRaisingJob.new
+    assert_raises(RuntimeError) { @queue.drain }
+  end
+
+  def test_jobs
+    @queue.push 1
+    @queue.push 2
+    assert_equal [1,2], @queue.jobs
+  end
+
+  class EquivalentJob
+    def initialize
+      @initial_id = self.object_id
+    end
+
+    def run
+    end
+
+    def ==(other)
+      other.same_initial_id?(@initial_id)
+    end
+
+    def same_initial_id?(other_id)
+      other_id == @initial_id
+    end
+  end
+
+  def test_contents
+    job = EquivalentJob.new
+    assert @queue.empty?
+    @queue.push job
+    refute @queue.empty?
+    assert_equal job, @queue.pop
+  end
+
+  class ProcessingJob
+    def self.clear_processed
+      @processed = []
+    end
+
+    def self.processed
+      @processed
+    end
+
+    def initialize(object)
+      @object = object
+    end
+
+    def run
+      self.class.processed << @object
+    end
+  end
+
+  def test_order
+    ProcessingJob.clear_processed
+    job1 = ProcessingJob.new(1)
+    job2 = ProcessingJob.new(2)
+
+    @queue.push job1
+    @queue.push job2
+    @queue.drain
+
+    assert_equal [1,2], ProcessingJob.processed
+  end
+
+  class ThreadTrackingJob
+    attr_reader :thread_id
+
+    def run
+      @thread_id = Thread.current.object_id
+    end
+
+    def ran?
+      @thread_id
+    end
+  end
+
+  def test_drain
+    @queue.push ThreadTrackingJob.new
+    job = @queue.jobs.last
+    @queue.drain
+
+    assert @queue.empty?
+    assert job.ran?, "The job runs synchronously when the queue is drained"
+    assert_equal job.thread_id, Thread.current.object_id
+  end
+
+  class IdentifiableJob
+    def initialize(id)
+      @id = id
+    end
+
+    def ==(other)
+      other.same_id?(@id)
+    end
+
+    def same_id?(other_id)
+      other_id == @id
+    end
+
+    def run
+    end
+  end
+
+  def test_queue_can_be_observed
+    jobs = (1..10).map do |id|
+      IdentifiableJob.new(id)
+    end
+
+    jobs.each do |job|
+      @queue.push job
+    end
+
+    assert_equal jobs, @queue.jobs
+  end
+
+  def test_adding_an_unmarshallable_job
+    anonymous_class_instance = Struct.new(:run).new
+
+    assert_raises TypeError do
+      @queue.push anonymous_class_instance
+    end
+  end
+
+  def test_attempting_to_add_a_reference_to_itself
+    job = {reference: @queue}
+    assert_raises TypeError do
+      @queue.push job
+    end
+  end
+end