empathy 0.0.1.RC0 → 0.0.1.RC2

data/.yardopts

@@ -0,0 +1,5 @@
+-e ./yard/extensions.rb --markup=markdown --no-private -
+LICENSE.txt
+CHANGES.md
+TESTING.md
+

data/CHANGES.md

@@ -0,0 +1,8 @@
+Empathy Changelog
+=====================
+
+
+0.0.1
+
+  * Port from strand - with intention to make empathy encompass more than threads
+

data/README.md

@@ -0,0 +1,144 @@
+Empathy
+=======================
+
+http://rubygems.org/gems/empathy
+
+Make EventMachine behave like standard Ruby
+
+Empathic Threads
+------------------------
+
+{Empathy::EM} 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 (which is also available as {Empathy::EM::ThreadError})
+
+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<...>"
+
+    Empathy::Kernel.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 top level constants), plus monkey patching of
+{Object#sleep} and {Object#at_exit}
+
+    require 'empathy/with_all_of_ruby'
+    # 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)
+
+ See {Empathy::EM.empathise} and {Empathy.empathise}.
+
+ 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
+
+Copyright
+-----------------
+
+Copyright (c) 2011 Christopher J. Bottaro. (Original fiber+EM concept in "strand" library)
+
+Copyright (c) 2012,2013 Grant Gardner.
+
+See {file:LICENSE.txt} for further details.
+

data/Rakefile

@@ -2,16 +2,12 @@ require "bundler/gem_tasks"
 
 require 'rspec/core'
 require 'rspec/core/rake_task'
-require 'rdoc/task'
+require 'yard'
 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
+YARD::Rake::YardocTask.new
 
 # Create the test task.
 desc 'Run mspec'
@@ -29,5 +25,6 @@ desc "Run tests"
 task :test => [ :spec, :mspec ]
 
 task :default => [ :test, :build ]
-CLOBBER.include [ "pkg/" ]
+
+CLOBBER.include [ "pkg/","doc/" ]
 

data/TESTING.md

@@ -0,0 +1,27 @@
+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 but some tests are skipped (see empathy.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 - see spec/empathy_spec.rb
+
+
+Empathising libaries
+-------------------------------
+
+We prove that code can reference various classes as normal, and have them actually use the ones injected by {Empathy.empathise} or {Empathy::EM.empathise}. Aside from some magic for the MonitorMixin this is really just standard ruby behaviour.
+
+MonitorMixin
+-------------------------------
+
+There are no rubyspecs for this module, so I have converted ruby 1.9's unit tests into a simple rubyspec - see rubyspec/monitor_spec.rb
+
+
+

data/empathy.gemspec

@@ -16,8 +16,12 @@ Gem::Specification.new do |gem|
   gem.require_paths = ["lib"]
   gem.licenses      = %q{MIT}
 
+  # Empathy can be used without eventmachine
+  gem.add_development_dependency 'eventmachine', '~> 1.0.0'
+
   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'
+  gem.add_development_dependency 'yard'
+  gem.add_development_dependency 'redcarpet'
 end

data/lib/empathy/em/condition_variable.rb

@@ -11,7 +11,8 @@ module Empathy
       # Using a mutex for condition variables is meant to protect
       # against race conditions when the signal occurs between testing whether
       # a wait is needed and waiting. This situation will never occur with
-      # fibers, but the semantic is retained
+      # fibers, but the semantic is retained for compatibility with ::ConditionVariable
+      # @return [ConditionVariable] self
       def wait(mutex=nil,timeout = nil)
 
         if timeout.nil? && (mutex.nil? || Numeric === mutex)
@@ -20,31 +21,37 @@ module Empathy
         end
 
         # Get the fiber (Empathy::EM::Thread) that called us.
-        empathy = Thread.current
+        thread = Thread.current
         # Add the fiber to the list of waiters.
-        @waiters << empathy
+        @waiters << thread
         begin
           sleeper = mutex ? mutex : Kernel
           if timeout then sleeper.sleep(timeout) else sleeper.sleep() end
         ensure
-          # Remove from list of waiters.
-          @waiters.delete(empathy)
+          # Remove from list of waiters. Note this doesn't run if the thread is killed
+          @waiters.delete(thread)
         end
         self
       end
 
+      # Like ::ConditionVariable#signal
+      # @return [ConditionVariable] self
       def signal
-        # If there are no waiters, do nothing.
-        return self if @waiters.empty?
 
-        # Find a waiter to wake up.
-        waiter = @waiters.shift
+        # Find a waiter to wake up
+        until @waiters.empty?
+           waiter = @waiters.shift
+           if waiter.alive?
+             ::EM.next_tick{ waiter.wakeup if waiter.alive? }
+             break;
+           end
+        end
 
-        # Resume it on next tick.
-        ::EM.next_tick{ waiter.wakeup }
         self
       end
 
+      # Like ::ConditionVariable#broadcast
+      # @return [ConditionVariable] self
       def broadcast
         all_waiting = @waiters.dup
         @waiters.clear

data/lib/empathy/em/monitor.rb

@@ -0,0 +1,8 @@
+
+# like ::Monitor
+class Empathy::EM::Monitor
+  include MonitorMixin
+  alias try_enter try_mon_enter
+  alias enter mon_enter
+  alias exit mon_exit
+end

data/lib/empathy/em/mutex.rb

@@ -1,11 +1,15 @@
 module Empathy
   module EM
+
+    # An Empathy equivalent to ::Mutex
     class Mutex
 
       def initialize()
         @waiters = []
       end
 
+      # Like ::Mutex#lock, except allows reentrant locks
+      # @return [Mutex] self
       def lock()
         em_thread = Thread.current
         @waiters << em_thread
@@ -16,16 +20,24 @@ module Empathy
         self
       end
 
+      # Like ::Mutex#unlock
+      # @return [Mutex] self
+      # @raise [FiberError] if not owner of the mutex
       def unlock()
         em_thread = Thread.current
         raise FiberError, "not owner" unless @waiters.first == em_thread
         release()
+        self
       end
 
+      # Like ::Mutex#locked?
+      # @return [true,false]
       def locked?
         !@waiters.empty? && @waiters.first.alive?
       end
 
+      # Like ::Mutex#try_lock
+      # @return [true,false]
       def try_lock
         if locked?
           false
@@ -35,6 +47,8 @@ module Empathy
         end
       end
 
+      # Like ::Mutex#synchronize
+      # @return the result of the block
       def synchronize(&block)
         lock
         yield
@@ -42,6 +56,9 @@ module Empathy
         unlock
       end
 
+      # Like ::Mutex#sleep
+      # @param [Numeric] timeout
+      # @return [Fixnum]
       def sleep(timeout=nil)
         unlock
         begin

data/lib/empathy/em/queue.rb

@@ -1,26 +1,7 @@
 module Empathy
   module EM
+
     # A Empathy equivalent to ::Queue from thread.rb
-    #     queue = Empathy::Queue.new
-    #
-    #     producer = Empathy::Thread.new do
-    #          5.times do |i|
-    #              Empathy::Kernel.sleep rand(i) # simulate expense
-    #              queue << i
-    #              puts "#{i} produced"
-    #          end
-    #      end
-    #
-    #      consumer = Empathy.new do
-    #          5.times do |i|
-    #              value = queue.pop
-    #              Empathy::Kernel.sleep rand(i/2) # simulate expense
-    #              puts "consumed #{value}"
-    #          end
-    #      end
-    #
-    #      consumer.join
-    #
     class Queue
 
       # Creates a new queue
@@ -31,7 +12,8 @@ module Empathy
         @waiting = 0
       end
 
-      # Pushes +obj+ to the queue
+      # @param [Object] obj
+      # @return [void]
       def push(obj)
         @q << obj
         @mutex.synchronize { @cv.signal }
@@ -40,12 +22,8 @@ module Empathy
       alias :enq :push
 
       # Retrieves data from the queue.
-      #
-      #
-      # If the queue is empty, the calling fiber is suspended until data is
-      # pushed onto the queue, unless +non_block+ is true in which case a
-      # +FiberError+ is raised
-      #
+      # @param [Boolean] non_block
+      # @raise FiberError if non_block is true and the queue is empty
       def pop(non_block=false)
         raise FiberError, "queue empty" if non_block && empty?
         if empty?
@@ -59,23 +37,25 @@ module Empathy
       alias :shift :pop
       alias :deq :pop
 
-      # Returns the length of the queue
+      # @return [Fixnum] the length of the queue
       def length
         @q.length
       end
       alias :size :length
 
-      # Returns +true+ if the queue is empty
+      # @return [true] if the queue is empty
+      # @return [false] otherwise
       def empty?
         @q.empty?
       end
 
       # Removes all objects from the queue
+      # @return [void]
       def clear
         @q.clear
       end
 
-      # Returns the number of fibers waiting on the queue
+      # @return [Fixnum] the number of fibers waiting on the queue
       def num_waiting
         @waiting
       end