empathy 0.0.1.RC0 → 0.0.1.RC2

data/lib/monitor.rb

@@ -0,0 +1,209 @@
+# See MRI Ruby's MonitorMixin
+# This file is derived from MRI Ruby 1.9.3 monitor.rb
+#
+# Copyright (C) 2001  Shugo Maeda <shugo@ruby-lang.org>
+#
+# The only changes are constant lookups, it dynamically uses thread constants
+# from the included class/extended object
+#
+# Note this relaces monitor.rb defined by ruby - so even if you don't include empathy
+# you may end up using this module.
+module MonitorMixin
+
+  # A condition variable associated with a monitor. Do not instantiate directly.
+  # @see MonitorMixin#new_cond
+  class ConditionVariable
+    #
+    # Releases the lock held in the associated monitor and waits; reacquires the lock on wakeup.
+    # @param [Numeric] timeout maximum time, in seconds, to wait for a signal
+    # @return [true]
+    def wait(timeout = nil)
+      @monitor.__send__(:mon_check_owner)
+      count = @monitor.__send__(:mon_exit_for_cond)
+      begin
+        @cond.wait(@monitor.instance_variable_get("@mon_mutex"), timeout)
+        return true
+      ensure
+        @monitor.__send__(:mon_enter_for_cond, count)
+      end
+    end
+
+    #
+    # Calls wait repeatedly while the given block yields a truthy value.
+    #
+    # @return [true]
+    def wait_while
+      while yield
+        wait
+      end
+    end
+
+    #
+    # Calls wait repeatedly until the given block yields a truthy value.
+    #
+    # @return [true]
+    def wait_until
+      until yield
+        wait
+      end
+    end
+
+    #
+    # Wakes up the first thread in line waiting for this lock.
+    #
+    def signal
+      @monitor.__send__(:mon_check_owner)
+      @cond.signal
+    end
+
+    #
+    # Wakes up all threads waiting for this lock.
+    #
+    def broadcast
+      @monitor.__send__(:mon_check_owner)
+      @cond.broadcast
+    end
+
+    private
+
+    def initialize(monitor)
+      @monitor = monitor
+      @cond = monitor.__send__(:mon_class_lookup,:ConditionVariable).new
+    end
+  end
+
+  # @private
+  def self.extend_object(obj)
+    super(obj)
+    obj.__send__(:mon_initialize)
+  end
+
+  #
+  # Attempts to enter exclusive section.
+  #
+  # @return [Boolean] whether entry was successful
+  def mon_try_enter
+    if @mon_owner != mon_class_lookup(:Thread).current
+      unless @mon_mutex.try_lock
+        return false
+      end
+      @mon_owner = mon_class_lookup(:Thread).current
+    end
+    @mon_count += 1
+    return true
+  end
+  # For backward compatibility
+  alias try_mon_enter mon_try_enter
+
+  #
+  # Enters exclusive section.
+  #
+  # @return [void]
+  def mon_enter
+    if @mon_owner != mon_class_lookup(:Thread).current
+      @mon_mutex.lock
+      @mon_owner = mon_class_lookup(:Thread).current
+    end
+    @mon_count += 1
+  end
+
+  #
+  # Leaves exclusive section.
+  #
+  # @return [void]
+  def mon_exit
+    mon_check_owner
+    @mon_count -=1
+    if @mon_count == 0
+      @mon_owner = nil
+      @mon_mutex.unlock
+    end
+  end
+
+  #
+  # Enters exclusive section and executes the block.  Leaves the exclusive
+  # section automatically when the block exits.
+  # @return [void]
+  def mon_synchronize
+    mon_enter
+    begin
+      yield
+    ensure
+      mon_exit
+    end
+  end
+  alias synchronize mon_synchronize
+
+  #
+  # @return [ConditionVariable]  a new condition variable associated with the receiver.
+  #
+  def new_cond
+    return ConditionVariable.new(self)
+  end
+
+  private
+
+  # Use <tt>extend MonitorMixin</tt> or <tt>include MonitorMixin</tt> instead
+  # of this constructor.  Have look at the examples above to understand how to
+  # use this module.
+  def initialize(*args)
+    super
+    mon_initialize
+  end
+
+  # Initializes the MonitorMixin after being included in a class or when an
+  # object has been extended with the MonitorMixin
+  def mon_initialize
+    @mon_owner = nil
+    @mon_count = 0
+
+    # Find the appropriate empathised module to use when resolving references to Thread, Mutex etc..
+    parts = self.class.name.split("::")[0..-2]
+    parents = parts.inject([Object]) { |result,name| result.unshift(result.first.const_get(name,false)) }
+    @mon_empathised_module = parents.detect { |p| p.instance_variable_get(:@empathised) } || Object
+
+    @mon_mutex = mon_class_lookup(:Mutex).new
+  end
+
+  def mon_check_owner
+    if @mon_owner != mon_class_lookup(:Thread).current
+      raise mon_class_lookup(:ThreadError), "current thread not owner"
+    end
+  end
+
+  def mon_enter_for_cond(count)
+    @mon_owner = mon_class_lookup(:Thread).current
+    @mon_count = count
+  end
+
+  def mon_exit_for_cond
+    count = @mon_count
+    @mon_owner = nil
+    @mon_count = 0
+    return count
+  end
+
+  # looks up namespace hierarchy for an empathised module
+  def mon_class_lookup(const)
+    @mon_empathised_module.const_get(const,false)
+  end
+end
+
+# Use the Monitor class when you want to have a lock object for blocks with
+# mutual exclusion.
+# @example
+#   require 'monitor'
+#
+#   lock = Monitor.new
+#   lock.synchronize do
+#     # exclusive access
+#   end
+#
+class Monitor
+  include MonitorMixin
+  alias try_enter try_mon_enter
+  alias enter mon_enter
+  alias exit mon_exit
+end
+
+

data/mspec/lib/mspec/empathy.rb

@@ -1,4 +1,4 @@
-require 'empathy/thread'
+require 'empathy/with_all_of_ruby'
 require 'mspec'
 require 'mspec/guards/empathy'
 module MSpec

data/rubyspec/monitor_spec.rb

@@ -0,0 +1,162 @@
+require "monitor"
+require File.expand_path('../spec_helper', __FILE__)
+
+describe "Monitor" do
+    before(:each) do
+        @monitor = Monitor.new
+    end
+
+    it "controls entry and exit" do
+        ary = []
+        queue = Queue.new
+        th = Thread.start {
+            queue.pop
+            @monitor.enter
+            for i in 6 .. 10
+                ary.push(i)
+                Thread.pass
+            end
+            @monitor.exit
+        }
+        @monitor.enter
+        queue.enq(nil)
+        for i in 1 .. 5
+            ary.push(i)
+            Thread.pass
+        end
+        @monitor.exit
+        th.join
+        ary.should == (1..10).to_a
+    end
+
+    it "synchronises on itself" do
+        ary = []
+        queue = Queue.new
+        th = Thread.start {
+            queue.pop
+            @monitor.synchronize do
+                for i in 6 .. 10
+                    ary.push(i)
+                    Thread.pass
+                end
+            end
+        }
+        @monitor.synchronize do
+            queue.enq(nil)
+            for i in 1 .. 5
+                ary.push(i)
+                Thread.pass
+            end
+        end
+        th.join
+        ary.should == (1..10).to_a
+    end
+
+    it "recovers from thread killed in synchronize" do
+        ary = []
+        queue = Queue.new
+        t1 = Thread.start {
+            queue.pop
+            @monitor.synchronize {
+                ary << :t1
+            }
+        }
+        t2 = Thread.start {
+            queue.pop
+            @monitor.synchronize {
+                ary << :t2
+            }
+        }
+        @monitor.synchronize do
+            queue.enq(nil)
+            queue.enq(nil)
+            ary.empty?.should be_true
+            t1.kill
+            t2.kill
+            ary << :main
+        end
+        ary.should == [ :main ]
+    end
+
+    it "performs try_enter appropriately" do
+        queue1 = Queue.new
+        queue2 = Queue.new
+        th = Thread.start {
+            queue1.deq
+            @monitor.enter
+            queue2.enq(nil)
+            queue1.deq
+            @monitor.exit
+            queue2.enq(nil)
+        }
+        @monitor.try_enter.should be_true
+        @monitor.exit
+        queue1.enq(nil)
+        queue2.deq
+        @monitor.try_enter.should be_false
+        queue1.enq(nil)
+        queue2.deq
+        @monitor.try_enter.should be_true
+    end
+
+    describe "MonitorMixin::ConditionVariable" do
+        it "waits and signals" do
+            cond = @monitor.new_cond
+
+            a = "foo"
+            queue1 = Queue.new
+            Thread.start do
+                queue1.deq
+                @monitor.synchronize do
+                    a = "bar"
+                    cond.signal
+                end
+            end
+            @monitor.synchronize do
+                queue1.enq(nil)
+                a.should == "foo"
+                result1 = cond.wait
+                result1.should == true
+                a.should == "bar"
+            end
+        end
+
+        it "timesout on wait" do
+            cond = @monitor.new_cond
+            b = "foo"
+            queue2 = Queue.new
+            Thread.start do
+                queue2.deq
+                @monitor.synchronize do
+                    b = "bar"
+                    cond.signal
+                end
+            end
+            @monitor.synchronize do
+                queue2.enq(nil)
+                b.should == "foo"
+                cond.wait(0.1).should == true
+                b.should == "bar"
+            end
+
+            c = "foo"
+            queue3 = Queue.new
+            Thread.start do
+                queue3.deq
+                @monitor.synchronize do
+                    c = "bar"
+                    cond.signal
+                end
+            end
+            @monitor.synchronize do
+                c.should == "foo"
+                cond.wait(0.1).should be_true
+                c.should == "foo"
+                queue3.enq(nil)
+                cond.wait.should be_true
+                c.should == "bar"
+            end
+
+        end
+    end
+end

data/spec/empathy_spec.rb

@@ -69,6 +69,11 @@ describe Empathy do
       Empathy::Kernel.singleton_methods.should include(:sleep)
     end
 
+    it "delegates Monitor" do
+      m = Empathy::Monitor.new()
+      m.should be_kind_of(monitor_class)
+    end
+
     it "rescues errors" do
       lambda do
         begin
@@ -90,9 +95,9 @@ describe Empathy do
     let (:condition_variable_class) { Empathy::EM::ConditionVariable }
     let (:mutex_class) { Empathy::EM::Mutex }
     let (:error_class) { ::FiberError }
+    let (:monitor_class) { Empathy::EM::Monitor }
 
     it "delegates to Empathy::EM classes" do
-      Empathy.run do
         Empathy.event_machine?.should be_true
         t = Empathy::EmTest.new
         t.should be_kind_of(Empathy::EM::EmTest)
@@ -100,7 +105,6 @@ describe Empathy do
         Empathy::EmTest.test_class_method.should == :em_test_class_method
         Empathy::EmTest.test_class_method(:em_hello).should == :em_hello
         Empathy::EmTest.test_class_method() { :em_with_block }.should == :em_with_block
-      end
     end
 
     include_examples "empathy_delegation"
@@ -112,6 +116,7 @@ describe Empathy do
     let (:condition_variable_class) { ::ConditionVariable }
     let (:mutex_class) { ::Mutex }
     let (:error_class) { ::ThreadError }
+    let (:monitor_class) { ::Monitor }
 
     it "delegate to ruby top level classes" do
       EventMachine.reactor_running?.should be_false

data/spec/library_spec.rb

@@ -1,79 +1,126 @@
 require 'spec_helper'
 
-module TestReactorLibrary
-  def self.test_thread_error
-    raise ::FiberError, "oops"
-  rescue ThreadError
-    :rescued
-  end
-end
+module EmpathyEMLibrary
 
-Empathy::EM.empathise(TestReactorLibrary)
+  module SubModule
+    def self.thread_class
+      Thread
+    end
+  end
+  class TestClass
+    include MonitorMixin
 
-module TestLibrary
-  def self.test_thread_error
-    begin
-      raise ::FiberError, "fiber error"
-    rescue ThreadError
+    def self.thread_class
+      Thread
     end
 
-    begin
-      raise ::ThreadError, "thread error"
-    rescue ThreadError
+    def thread_class
+      Thread
     end
-    :ok
+
   end
 end
 
-Empathy.empathise(TestLibrary)
+Empathy::EM.empathise(EmpathyEMLibrary)
+
+module EmpathyLibrary
+  module SubModule
+    def self.thread_class
+      Thread
+    end
+  end
+  class TestClass
+    include MonitorMixin
+
+    def self.thread_class
+      Thread
+    end
+
+    def thread_class
+      Thread
+    end
 
-shared_examples_for "Empathy.empathise" do
-  it "rescues thread and fiber exceptions" do
-    TestLibrary.test_thread_error.should == :ok
   end
+
 end
 
-describe "Empathy.empathise" do
+Empathy.empathise(EmpathyLibrary)
 
-  it "defines constants in Library namespace" do
-    TestLibrary::Thread.should == Empathy::Thread
-    TestLibrary::Queue.should == Empathy::Queue
-    TestLibrary::ConditionVariable.should == Empathy::ConditionVariable
-    TestLibrary::Mutex.should == Empathy::Mutex
-    TestLibrary::ThreadError.should == Empathy::ThreadError
+module NonEmpathisedLibrary
+  module SubModule
+    def self.thread_class
+      Thread
+    end
   end
+  class TestClass
+    include MonitorMixin
 
-  context "in reactor" do
-    around :each do |example|
-      Empathy.run { example.run }
+    def self.thread_class
+      Thread
     end
 
-    include_examples "Empathy.empathise"
-  end
+    def thread_class
+      Thread
+    end
 
-  context "outside reactor" do
-    include_examples "Empathy.empathise"
   end
+end
+
+shared_examples_for "an empathised library" do
 
+  it "has constant references in its namespace pointing to modules in empathy namespace" do
+    library_module.const_get('Thread',false).should == empathy_module.const_get('Thread',false)
+    library_module.const_get('Queue',false).should == empathy_module.const_get('Queue',false)
+    library_module.const_get('Mutex',false).should == empathy_module.const_get('Mutex',false)
+    library_module.const_get('ConditionVariable',false).should == empathy_module.const_get('ConditionVariable',false)
+    library_module.const_get('Monitor',false).should == empathy_module.const_get('Monitor',false)
+    library_module.const_get('ThreadError',false).should == empathy_module.const_get('ThreadError',false)
+  end
 end
 
-describe "Empathy::EM.empathise" do
+shared_examples_for "a possibly empathised library" do
 
-  it "defines constants in Library namespace" do
-    TestReactorLibrary::Thread.should == Empathy::EM::Thread
-    TestReactorLibrary::Queue.should == Empathy::EM::Queue
-    TestReactorLibrary::ConditionVariable.should == Empathy::EM::ConditionVariable
-    TestReactorLibrary::Mutex.should == Empathy::EM::Mutex
-    TestReactorLibrary::ThreadError.should == FiberError
+  it "resolves constant references from submodules in its namepsace to modules in empathy namepsace" do
+    submodule = library_module.const_get('SubModule',false)
+    submodule.thread_class.should == empathy_module.const_get('Thread',false)
   end
 
-  context "in reactor" do
-    around :each do |example|
-      Empathy.run { example.run }
-    end
+  it "resolves constant references from classes within its namespace to modules in empathy namespace" do
+    library_class = library_module.const_get('TestClass',false)
+    library_class.thread_class.should == empathy_module.const_get('Thread',false)
+    obj = library_module.const_get('TestClass',false).new()
+    obj.thread_class.should == empathy_module.const_get('Thread',false)
+  end
 
-    it "rescues fiber errors" do
-      TestReactorLibrary.test_thread_error.should == :rescued
+  context "MonitorMixin" do
+    it "uses empathised classes" do
+      monitor = library_module.const_get("TestClass",false).new
+      monitor.__send__(:mon_class_lookup,'Thread').should == empathy_module.const_get('Thread',false)
     end
   end
 end
+
+describe Empathy do
+
+  let(:empathy_module) { described_class }
+  let(:library_module) { EmpathyLibrary }
+
+  include_examples "an empathised library"
+  include_examples "a possibly empathised library"
+end
+
+describe Empathy::EM do
+
+  let(:empathy_module) { described_class }
+  let(:library_module) { EmpathyEMLibrary }
+
+  include_examples "an empathised library"
+  include_examples "a possibly empathised library"
+end
+
+describe Object do
+  let(:empathy_module) { described_class }
+  let(:library_module) { NonEmpathisedLibrary }
+
+  include_examples "a possibly empathised library"
+end

data/yard/extensions.rb

@@ -0,0 +1,24 @@
+class ModuleDelegationHandler< YARD::Handlers::Ruby::Base
+  handles method_call(:create_delegate_module)
+  namespace_only
+
+  def process
+    module_name = statement.parameters.first.jump(:tstring_content,:ident,:symbol).source
+    object = YARD::CodeObjects::ModuleObject.new(namespace,module_name)
+    register(object)
+
+    object.docstring.replace("Delegates to {Empathy::EM::#{module_name}} when in the EM reactor, otherwise plain old ::#{module_name}")
+    object.dynamic = true
+
+    statement.parameters[1..-1].each do |parameter|
+      next unless parameter
+      method_name = parameter.jump(:symbol_literal).source[1..-1]
+      method = YARD::CodeObjects::MethodObject.new(object, method_name, :module)
+      register(method)
+      method.docstring.replace("Delegates to {Empathy::EM::#{module_name}.#{method_name}} when in the EM reactor, otherwise to plain old ::#{module_name}.#{method_name}")
+      method.dynamic=true
+      method.visibility=:public
+    end
+  end
+
+end