momentarily 0.0.1 → 0.0.3

data/README.textile

@@ -0,0 +1,61 @@
+h1. Introducing Momentarily
+
+Momentarily was created to allow Rails developers to *speed up their applications for end users*.  Momentarily gives developers the ability to quickly and safely *move slow operations into a thread and out of the request chain* so user experience is not impacted by operations like sending emails, updating web services or database operations.
+
+Momentarily is a wrapper around EventMachine with Rails considerations baked in. EventMachine offers both an evented-model reactor designed for asychronous IO, and a thread-pool manager and processing queue for blocking IO. Momentarily provides the code to integrate EventMachine with Passenger, Thin, Rails Console or other environments, and then use the thread-pool manager in a Rails-safe manner.
+
+*Contributions are welcome!*
+
+To use Momentarily, first add it to your Gemfile:
+
+gem 'momentarily'
+
+You'll then need to start the reactor. Create a *config/initializers/momentarily.rb* file like this:
+
+Momentarily.start
+
+That's it! Once complete, *Momentarily.reactor_running?* should be true. 
+
+Momentarily provides the very useful "later" command. Calling .later will spawn a thread to complete the tasks you provide, allowing your Rails requests to complete and return to users. For example:
+
+def my_rails_action
+	# do something that has to be done inline
+	Momentarily.later( Proc.new{
+		# stuff you don't need done before you return ot the users, and might take awhile
+		# update databases using ActiveRecord
+		# send emails with ActionMailer
+		# other stuff
+	})
+	render
+end
+
+This will allow your request to complete without waiting for your activities to complete. Note that you are responsible for ensuring that your provided Proc is thread safe. 
+
+Momentarily.later does the following: 
+
+* Checks out (and returns) a connection from the ActiveRecord connection pool
+* Sends your request to EventMachine for scheduling
+* Catches and handles any general exceptions in the work thread for debugging
+* Automatically expires any work that fails to return within the default timeout. This is designed to avoid hung threads and eventual thread pool starvation. You can change the default of 60 seconds by setting *Momentarily.timeout* with a new value.
+
+For consistency, Momentarily also provide interfaces *EventMachine.next_tick* and *EventMachine.defer* as *Momentarily.next_tick* and *Momentarily.defer*. Use next_tick to schedule non-blocking IO operations, like AMQP calls or Pusher notifications. *Momentarily.defer* operates similarly to *Momentarily.later*, except *Momentarily.later* checks out an ActiveRecord connection, manages timeouts and handles exceptions for better safety in a Rails environment.  We use AMQP also, so our momentarily.rb initializer looks like this:
+
+require 'amqp'
+
+Momentarily.start
+
+Momentarily.next_tick( Proc.new { 
+	AMQP.channel ||= AMQP::Channel.new(AMQP.connect(:host=> Q_SERVER, :user=> Q_USER, :pass => Q_PASS, :vhost => Q_VHOST )) 
+	} )
+
+Momentarily bridges the gap between using non-blocking IO for asynch operations (like EventMachine) and industrial strength queueing (like RabbitMQ and AMQP) to offload work for later execution. Both have their places, but it's not always feasible to use only non-blocking IO, and it's often not worth the trouble to create messages and a consumer just to shave 500ms off a web request. Our goal is to make it simple to defer even small tasks and ensure a snappy end user experience.
+
+h2. Other notes:
+
+You can enable debug mode by setting *Momentarily.debug = true*. Momentarily will then put messages to the console about operation and halt if an unhandled exception occurs. 
+
+By default, EventMachine maintains a pool of 20 available threads. You may have to tune this to your processing environment.
+
+Similarly, ActiveRecord keeps a pool of connections available, and *the default is too low* - each thread explicitly claims (then releases) one of these connections while working. You can add "pool: 30" or similar to your database.yml file to increase it. Again, you'll have to tune this number to your processing environment.
+
+*On running Momentarily with Thin*. Momentarily detects the Thin object in the environment and skips startup of the EventMachine reactor in that case (preferring to wait for Thin to do it.) If for whatever reason you have Thin defined in your gemfile, but aren't using it as an active server, Momentarily will not start EM as intended (unless you are In the Rails console). To make sure your tests work, make sure your thin dependency is defined in the  production and/or development group in your Gemfile so it is not loaded when tests are run.

data/lib/momentarily.rb

@@ -1,47 +1,86 @@
-require "momentarily/version"
+$:.unshift(File.dirname(__FILE__)) unless
+  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+require "rubygems"
+require "momentarily/version.rb"
 require "eventmachine"
-require 'amqp'
+require 'timeout'
+
+# designed for rails
+require 'active_record'
+require 'active_support/core_ext/module'
 
 module Momentarily
-	
-	class MomentarilyEM
-		# this pattern is described here http://rdoc.info/github/ruby-amqp/amqp/master/file/docs/ConnectingToTheBroker.textile#In_Web_applications__Ruby_on_Rails__Sinatra__Merb__Rack_
-		# and here: http://railstips.org/blog/archives/2011/05/04/eventmachine-and-passenger/
-		def initialize()
-			self.start()
-		end
+	mattr_accessor :timeout, :debug
+	@@timeout = 60
+	@@debug = false
 
-		def self.start
-			if defined?(PhusionPassenger)
-			  PhusionPassenger.on_event(:starting_worker_process) do |forked|
-			  # for passenger, we need to avoid orphaned threads
-			    if forked && EM.reactor_running?
-			      EM.stop
-			    end
-			    Thread.new {
-			      EM.run do
-			         AMQP.channel ||= AMQP::Channel.new(AMQP.connect(:host=> Q_SERVER, :user=> Q_USER, :pass => Q_PASS, :vhost => Q_VHOST ))
-			      end
-			    }
-			    die_gracefully_on_signal
-			  end
-			else
-			  # faciliates debugging
-			  Thread.abort_on_exception = true
-			  # just spawn a thread and start it up
-			    Thread.new {
-			      EM.run do
-			         AMQP.channel ||= AMQP::Channel.new(AMQP.connect(:host=> Q_SERVER, :user=> Q_USER, :pass => Q_PASS, :vhost => Q_VHOST ))
-			      end
-			    } unless defined?(Thin)
-			    # Thin is built on EventMachine, doesn't need this thread
+	def Momentarily.start
+		# faciliates debugging
+		Thread.abort_on_exception = @@debug
+		if defined?(PhusionPassenger)
+			puts "Momentarily: Passenger thread init." if @@debug
+			PhusionPassenger.on_event(:starting_worker_process) do |forked|
+				# for passenger, we need to avoid orphaned threads
+				if forked && EM.reactor_running?
+					EM.stop
+				end
+				Thread.new {
+					EM.run
+				}
+				die_gracefully_on_signal
 			end
+		# if Thin is defined, but in console mode, Thin probably isn't running
+		elsif (!EM.reactor_running? && defined?(Thin).nil?) || !defined?(Rails::Console).nil?
+			# spawn a thread and start it up
+			puts "Momentarily: Standard thread init." if @@debug
+			Thread.new {
+				EM.run
+			}
+		else
+			# Thin is built on EventMachine, doesn't need another thread
+			puts "Momentarily: Reactor already running or detected Thin." if @@debug
 		end
 
-		def self.die_gracefully_on_signal
-			Signal.trap("INT")  { EM.stop }
-			Signal.trap("TERM") { EM.stop }
+	end
+
+	def Momentarily.die_gracefully_on_signal
+		Signal.trap("INT")  { EM.stop }
+		Signal.trap("TERM") { EM.stop }
+	end
+	
+	def Momentarily.later(work = nil, callback = nil, &block)
+		EM.defer( self.railsify(( work || block )), self.railsify(callback) )
+	end
+
+	def Momentarily.next_tick(work = nil, &block)
+		EM.next_tick( ( work || block ) ) 
+	end
+
+	def Momentarily.defer(work = nil, callback = nil, &block)
+		EM.defer( ( work || block ), callback)
+	end
+
+	def Momentarily.reactor_running?
+		EM.reactor_running?
+	end
+
+private 
+	def Momentarily.railsify(work)
+	    unless work.nil?
+			Proc.new {
+				# checks out connection for use in this thread
+				ActiveRecord::Base.connection_pool.with_connection do
+					begin
+						# make sure it doesn't hang
+						Timeout::timeout(@@timeout) { work.call() unless work.nil? }
+					rescue => e
+						puts "Momentarily: Thread failed with: " + e.to_s if @@debug
+					rescue TimeoutError => e
+						puts "Momentarily: Thread timeout." if @@debug
+					end
+				end }
 		end
-	end # MomentarilyEM
+	end
 
 end # Momentarily

data/lib/momentarily/version.rb

@@ -1,3 +1,3 @@
 module Momentarily
-  VERSION = "0.0.1"
+  VERSION = "0.0.3"
 end

data/test/test_momentarily.rb

@@ -0,0 +1,90 @@
+require 'test/unit'
+require './lib/momentarily.rb'
+
+ActiveRecord::Base.establish_connection(YAML::load(File.read(File.dirname(__FILE__) + '/../config/database.yml')))
+
+class TestMomentarily < Test::Unit::TestCase
+	def setup
+	    if !ActiveRecord::Base.connection.table_exists?('momentarily_test')
+			puts "Creating test table..."
+			AddEntitiesTable.create
+		end
+		Momentarily.debug = false
+		if !Momentarily.reactor_running?
+			Momentarily.start
+		end
+	end
+
+	def test_instantiation
+		assert(EM.reactor_running?)
+	end
+
+	def test_later
+		a = 1
+		Momentarily.later( Proc.new { a = 2 } )
+		sleep(0.5)
+		assert(a == 2)
+
+		Momentarily.later( Proc.new { asdfputs "I am a bad proc" } )
+		assert(EM.reactor_running?)
+
+		a = 1
+		Momentarily.timeout = 1
+		Momentarily.later( Proc.new { 
+			sleep(2)
+			a = 2	 } )
+		sleep(3)
+		assert(a == 1)
+
+	end
+
+	def test_later_blocks
+		a = 1
+		Momentarily.later { a = 2 }
+		sleep(0.5)
+		assert(a == 2)
+
+		Momentarily.later { asdfputs "I am a bad proc" } 
+		assert(EM.reactor_running?)
+
+		a = 1
+		Momentarily.timeout = 1
+		Momentarily.later { 
+			sleep(2)
+			a = 2	 } 
+		sleep(3)
+		assert(a == 1)
+
+	end
+
+	def test_next_tick
+		a = 1
+		Momentarily.next_tick( Proc.new { a = 2 })
+		sleep(0.5)
+		assert(a == 2)
+		Momentarily.next_tick { a = 3 }
+		sleep(0.5)
+		assert(a == 3)
+	end
+
+	def simulate_thin()
+		require 'thin'
+		Thread.new { EM.run }
+	end
+end
+
+  class AddEntitiesTable < ActiveRecord::Migration
+		# up and down functions call broken code in Rail3 migrations gem, called it 'create'
+
+    def self.create
+      create_table "momentarily_test", :force => true do |t|
+				t.string   "key",        :limit => 512, :null => false
+				t.string     "value"
+				t.datetime "created_at"
+				t.datetime "updated_at"
+      end
+
+      add_index "momentarily_test", ["key"], :name => "key"
+    end
+
+  end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: momentarily
 version: !ruby/object:Gem::Version 
-  hash: 29
+  hash: 25
   prerelease: 
   segments: 
   - 0
   - 0
-  - 1
-  version: 0.0.1
+  - 3
+  version: 0.0.3
 platform: ruby
 authors: 
 - Joshua Siler
@@ -15,9 +15,64 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2012-01-15 00:00:00 Z
-dependencies: []
-
+date: 2012-01-16 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: thin
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: eventmachine
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: activerecord
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: activesupport
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id004
 description: A rails gem that allows you to briefly defer execution of tasks and return from requests faster.
 email: 
 - joshua.siler@gmail.com
@@ -28,12 +83,10 @@ extensions: []
 extra_rdoc_files: []
 
 files: 
-- .gitignore
-- Gemfile
-- Rakefile
 - lib/momentarily.rb
 - lib/momentarily/version.rb
-- momentarily.gemspec
+- README.textile
+- test/test_momentarily.rb
 homepage: ""
 licenses: []
 
@@ -67,5 +120,5 @@ rubygems_version: 1.8.10
 signing_key: 
 specification_version: 3
 summary: A rails gem that allows you to briefly defer execution of tasks and return from requests faster.
-test_files: []
-
+test_files: 
+- test/test_momentarily.rb

data/.gitignore

@@ -1,4 +0,0 @@
-*.gem
-.bundle
-Gemfile.lock
-pkg/*

data/Gemfile

@@ -1,4 +0,0 @@
-source "http://rubygems.org"
-
-# Specify your gem's dependencies in momentarily.gemspec
-gemspec

data/Rakefile

@@ -1 +0,0 @@
-require "bundler/gem_tasks"

data/momentarily.gemspec

@@ -1,24 +0,0 @@
-# -*- encoding: utf-8 -*-
-$:.push File.expand_path("../lib", __FILE__)
-require "momentarily/version"
-
-Gem::Specification.new do |s|
-  s.name        = "momentarily"
-  s.version     = Momentarily::VERSION
-  s.authors     = ["Joshua Siler"]
-  s.email       = ["joshua.siler@gmail.com"]
-  s.homepage    = ""
-  s.summary     = %q{A rails gem that allows you to briefly defer execution of tasks and return from requests faster.}
-  s.description = %q{A rails gem that allows you to briefly defer execution of tasks and return from requests faster.}
-
-  s.rubyforge_project = "momentarily"
-
-  s.files         = `git ls-files`.split("\n")
-  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
-  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
-  s.require_paths = ["lib"]
-
-  # specify any dependencies here; for example:
-  # s.add_development_dependency "rspec"
-  # s.add_runtime_dependency "rest-client"
-end