empathy 0.0.1.RC0

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Grant Gardner
+
+MIT License
+
+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,135 @@
+= empathy
+
+Empathy
+
+http://rubygems.org/gems/empathy
+
+Make EventMachine behave like standard Ruby
+
+== Empathic Threads
+
+Empathy::EM module uses Fibers to provide Thread, Queue, Mutex, ConditionVariable and MonitorMixin classes that behave like the native ruby ones.
+
+  require 'eventmachine'
+  require 'empathy'
+
+  # start eventmachine and a main EM::Thread
+  Empathy.run do
+    thread = Empathy::EM::Thread.new do
+      my_thread = Empathy::EM::Thread.current
+
+      #local storage
+      Empathy::EM::Thread.current[:my_key] = "some value"
+
+      #pass control elsewhere
+      Empathy::EM::Thread.pass
+
+      Empathy::EM::Kernel.sleep(1)
+
+      1 + 2
+    end
+
+    thread.join
+    thread.value # => 3
+  end
+
+Almost all Thread behaviour is provided except that one thread will never see another as "running". Where ruby's thread API raises ThreadError, Empathy::EM will raise FiberError.
+
+== Empathic code outside of the EventMachine reactor
+
+If your code may run inside or outside the reactor the Empathy module itself provides a set of submodules that delegate to either the native ruby class when called outside of the reactor, or to the Empathy:EM class when called inside the reactor.
+
+  require 'eventmachine'
+  require 'empathy'
+  Empathy::Thread.current.inspect # => "Thread<...>"
+
+  # normal Kernel.sleep
+  Empathy::Thread.sleep(1)
+
+  Empathy.event_machine? # => false
+
+  Empathy.run do
+
+    Empathy.event_machine? # => true
+
+    Empathy::Thread.new do
+
+      Empathy::Thread.current.inspect #=> "Empathy::EM::Thread<...>"
+
+      Empathy::Kernel.sleep(1)
+
+      begin
+           #...do something with threads...
+      rescue Empathy::ThreadError
+           # ...
+      end
+    end
+  end
+
+Note that since Empathy::Thread and friends are modules, you cannot subclass them
+
+== Empathise with all ruby code
+
+Seamlessly Replace Ruby's native classes with the Empathy:EM ones (redefines constants), plus monkey patching of
+ Object#sleep and Object#at_exit
+
+  require 'empathy/thread'
+  # do not run any code that uses threads outside of the reactor after the above require
+
+  Empathy.run do
+    t = Thread.new { 1 + 2 }
+
+    t.inspect # => "Empathy::EM::Thread<.....>"
+
+    # this will be a Fiber+EM sleep, not Kernel.sleep
+    sleep(4)
+
+    t.join
+  end
+
+Caveat: Take care with code that subclasses Thread. This can work as long as the classes are defined after
+ 'empathy/thread' is required.
+
+Q: But doesn't eventmachine need to use normal threads?
+A: Indeed, 'empathy/thread' also defines constants in the EventMachine namespace that refer to the original Ruby classes
+
+== Empathise a library module
+
+  module MyLibary
+     def create_thread
+        Thread.new { Thread.current.inspect }
+     end
+  end
+
+  # If library will only be used inside the reactor
+  Empathy::EM::empathise(MyLibrary)
+
+  # If library is used both inside and outside the reactor
+  Empathy.empathise((MyLibrary)
+
+In both cases constants are defined in the MyLibrary namespace so that Thread, Queue etc, refer to either Empathy modules
+or Empathy:EM classes. Note that any call to empathise will have the side-effect of monkey patching Object to provide EM
+safe #sleep and #at_exit.
+
+Caveat: MyLibrary must not subclass Thread etc...
+
+== Empathy::EM::IO - Implement Ruby's Socket API over EventMachine
+
+Work in progress - see experimental socket-io branch 
+
+== Contributing to empathy
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
+* Fork the project
+* Start a feature/bugfix branch
+* Commit and push until you are happy with your contribution
+* Make sure to add specs, preferably based on ruby-spec
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+== Copyright
+
+Copyright (c) 2011 Christopher J. Bottaro. (Original fiber+EM concept in "strand" library)
+Copyright (c) 2012,2013 Grant Gardner.
+
+See LICENSE.txt for further details.
+

data/Rakefile

@@ -0,0 +1,33 @@
+require "bundler/gem_tasks"
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+require 'rdoc/task'
+require 'rake/clean'
+
+RSpec::Core::RakeTask.new(:spec)
+
+RDoc::Task.new do |rdoc|
+    rdoc.main = "README.rdoc"
+    rdoc.rdoc_files.include("README.rdoc", "CHANGELOG","lib/**/*.rb")
+    rdoc.title = "Empathy"
+end
+
+# Create the test task.
+desc 'Run mspec'
+task :mspec do
+  sh "mspec -B empathy.mspec -r 'mspec/empathy' -f spec"
+end
+
+# Run specs against ruby
+desc "Run tests on native ruby"
+task :mspec_ruby do
+  sh "mspec -B empathy.mspec"
+end
+
+desc "Run tests"
+task :test => [ :spec, :mspec ]
+
+task :default => [ :test, :build ]
+CLOBBER.include [ "pkg/" ]
+

data/TESTING.rdoc

@@ -0,0 +1,11 @@
+= Empathy Testing
+
+== Empathy::EM
+
+Classes in Empathy::EM module are tested  using the fully empathic method - replacing Ruby's ::Thread constant with one that points to Empathy::EM::Thread etc, and then running against the subset of rubyspec to do with threads. The rubyspecs are not changed at all. Some tests are skipped (see *.mspec)
+
+This also tests Empathy.run and the class replacement approach (including subclassing)
+
+== Empathy module - reactor aware
+
+We just test that the delegation works as expected, with explicit specs run under rspec

data/empathy.gemspec

@@ -0,0 +1,23 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'empathy/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "empathy"
+  gem.version       = Empathy::VERSION
+  gem.authors       = ["Grant Gardner","Christopher J. Bottaro"]
+  gem.email         = ["grant@lastweekend.com.au"]
+  gem.description   = %q{Empathic Eventmachine}
+  gem.summary       = %q{Make EventMachine behave like ruby}
+  gem.homepage      = "http://rubygems.org/gems/empathy"
+  gem.files         = `git ls-files`.split($/)
+  gem.test_files    = `git ls-files -- {spec,rubyspec}/*`.split($/)
+  gem.require_paths = ["lib"]
+  gem.licenses      = %q{MIT}
+
+  gem.add_development_dependency 'mspec', '>= 1.5.18'
+  gem.add_development_dependency 'rspec'
+  gem.add_development_dependency 'rr'
+  gem.add_development_dependency 'eventmachine', '~> 1.0.0'
+end

data/empathy.mspec

@@ -0,0 +1,34 @@
+# encoding: UTF-8
+
+require 'mspec/runner/formatters'
+
+class MSpecScript
+  # An ordered list of the directories containing specs to run
+  set :files, ['rubyspec']
+
+  # The default implementation to run the specs.
+  set :target, 'ruby'
+
+  irrelevant_class_methods = [
+    "Thread.fork","Thread.allocate","Thread.abort_on_exception","Thread.exclusive"
+  ]
+
+  irrelevant_instance_methods = [
+    "Thread#abort_on_exception"
+  ]
+
+  # and some intentionally not compliant
+  non_compliant = [
+    "running","interrupt Kernel#sleep","thread group","Mutex#lock raises a ThreadError when used recursively",
+  ]
+
+  # Exclude IO specs not relevant to IO::Like
+  set :excludes, irrelevant_class_methods + irrelevant_instance_methods + non_compliant
+
+  # These are options that are passed to the ruby interpreter running the tests
+  #  to test io like "-r io/like" must be passed on the command line to mspec
+  set :requires, [
+    "-I", File.expand_path("../lib", __FILE__),
+    "-I", File.expand_path("../mspec/lib", __FILE__),
+  ]
+end

data/lib/empathy.rb

@@ -0,0 +1,162 @@
+require 'empathy/version'
+require 'thread'
+require 'fiber'
+
+# This module provides a shim between using standard ruby Threads
+# and the thread-like behaviour for Fibers provided by classes in
+# the Empathy::EM module
+#
+#   # For the Empathy::EM classes to be available
+#   # you must first load EventMachine
+#   'require eventmachine'
+#
+#   'require empathy'
+#
+#   t = Empathy::Thread.new() do
+#       begin
+#       # "t" is a standard ::Thread
+#       ...something...
+#   end
+#
+#   EventMachine.run do
+#      t = Empathy::Thread.new() do
+#           # "t" is a ::Empathy::EM::Thread
+#           # which wraps a ::Fiber
+#      end
+#   end
+#
+#   # Outside of event machine
+#   t = Empathy::Thread.new() do
+#       # "t" is a raw ::Thread
+#   end
+#
+# Code using Empathy that may be used in both Fiber or Thread contexts
+# should take care to rescue *Empathy::Errors which is shorthand for
+# *[FiberError,ThreadError]
+#
+#   def maybe_em_method
+#      # some code
+#   rescue *Empathy::Errors
+#
+#   end
+#
+# {::Thread} methods not implemented by Empathy
+#   * #exclusive - not implemented
+#   * #critical - not implemented
+#   * #set_trace_func - not implemented
+#   * #safe_level - not implemented
+#   * #priority - not implemented
+module Empathy
+
+  class ThreadError < StandardError
+    def self.===(other)
+      super || ::FiberError === other || ::ThreadError === other
+    end
+  end
+
+  # Start EventMachine and run reactor block within a surrounding Empathy::EM::Thread (Fiber).
+  # The reactor loop is terminated when the supplied block finishes
+  def self.run
+    reload()
+    exception = nil
+    value = nil
+    EventMachine.run do
+      EM::Thread.new do
+        begin
+          value = yield
+        rescue Exception => ex
+          exception = ex
+        ensure
+          EventMachine.stop
+        end
+      end
+    end
+    raise exception if exception
+    value
+  end
+
+  def self.empathise(*modules)
+    modules.each do |m|
+      map_classes(m, self, "Thread","Queue","Mutex","ConditionVariable", "ThreadError")
+    end
+  end
+
+  #@api private
+  def self.map_classes(into,from,*class_names)
+    # Make Object reactor aware
+    require 'empathy/object'
+    class_names.each do |cname|
+      case cname
+      when Hash
+        cname.each { |cn,replace_class| replace_class_constant(into,cn,replace_class) }
+      else
+        replace_class_constant(into,cname,from.const_get(cname))
+      end
+    end
+  end
+
+  def self.replace_class_constant(into,cname,replace_class)
+    if into != Object && into.const_defined?(cname,false)
+       existing_const = into.const_get(cname)
+       if !existing_const.is_a?(Module) || existing_const.name.start_with?(into.name)
+         warn "mmpathy: Skipping replacement of #{into.name}::#{cname}"
+         return nil
+       end
+    end
+
+    warn "empathy: Defined fake class constant #{into}::#{cname} => #{replace_class.name}"
+    into.const_set(cname,replace_class)
+  end
+
+  # Test whether we have real fibers or a thread based fiber implmentation
+  t = Thread.current
+  ft = nil
+  Fiber.new { ft = Thread.current }.resume
+
+  ROOT_FIBER = Fiber.current
+  REAL_FIBERS = ( t == ft )
+
+  # Specifically try to enable use of Eventmachine if it is now available
+  def self.reload()
+    @loaded ||= false
+    if !@loaded && defined?(EventMachine)
+      require 'empathy/em/thread.rb'
+      require 'empathy/em/queue.rb'
+      @loaded = true
+    end
+    return @loaded
+  end
+
+  # If EM already required then enable it, otherwise defer until first use
+  reload()
+
+  # Are we running in the EventMachine reactor thread
+  #
+  # For JRuby or other interpreters where fibers are implemented with threads
+  # this will return true if the reactor is running and the code is called from
+  # *any* fiber other than the root fiber
+  def self.event_machine?
+    @loaded ||= false
+    @loaded && EventMachine.reactor_running? &&
+      ( EventMachine.reactor_thread? || (!REAL_FIBERS && ROOT_FIBER != Fiber.current))
+  end
+
+  private
+  def self.create_delegate_module(cname,*methods)
+    mod = Module.new
+    self.const_set(cname,mod)
+    methods.each do |m|
+      mod.define_singleton_method(m) do |*args,&block|
+        parent = Empathy.event_machine? ? Empathy::EM : Object
+        delegate = parent.const_get(cname)
+        delegate.send(m,*args,&block)
+      end
+    end
+  end
+
+  create_delegate_module('Kernel',:sleep,:at_exit)
+  create_delegate_module('Thread',:new, :list, :current, :stop, :pass, :main)
+  create_delegate_module('Queue',:new)
+  create_delegate_module('ConditionVariable',:new)
+  create_delegate_module('Mutex',:new)
+end