empathy 0.0.1.RC0 → 0.0.1.RC2

data/lib/empathy/em/thread.rb

@@ -2,19 +2,35 @@ require "fiber"
 require "eventmachine"
 require 'empathy/em/mutex'
 require 'empathy/em/condition_variable'
+require 'empathy/em/queue'
 
 module Empathy
 
   module EM
 
+    @empathised = self
+    # Thread like errors are actually raw Fiber errors
+    ThreadError = ::FiberError
+
+    # Create alias constants in each of the supplied modules so that code within those modules
+    # will use modules from the Empathy::EM namespace instead of the native ruby ones
+    #
+    # Also monkey patches {Object} to provide EM safe Kernel methods
+    # @return [void]
     def self.empathise(*modules)
       modules.each do |m|
-        Empathy::map_classes(m,self,"Thread","Mutex","ConditionVariable","Queue","ThreadError" => FiberError)
+        Empathy::map_classes(m,self)
       end
     end
 
     module Kernel
-      # Like ::Kernel::sleep. Woken by an ::EM::Timer in +seconds+ if supplied
+
+      # Like ::Kernel.sleep
+      # @overload sleep()
+      #   Sleep forever
+      # @overload sleep(seconds)
+      #   @param [Numeric] seconds The number of seconds (including fractional seconds) to sleep
+      # @return [Fixnum] rounded number of seconds actually slept, which can be less than specified if woken early
       def self.sleep(seconds=:__empathy_sleep_forever)
 
         ::Kernel.raise TypeError, "seconds #{seconds} must be a number" unless seconds == :__empathy_sleep_forever or seconds.is_a? Numeric
@@ -27,30 +43,50 @@ module Empathy
         (Time.now - n).round()
       end
 
+      # Like ::Kernel.at_exit
+      #
+      # Queues block to run at shutdown of the reactor
+      # @return [void]
       def self.at_exit(&block)
         EventMachine.add_shutdown_hook(&block)
       end
+
     end
 
-    #Acts like a ::Thread using Fibers and EventMachine
+    # Acts like a ::Thread using Fibers and EventMachine
+    #
+    # {::Thread} methods not implemented by Empathy
+    #
+    #    *  .exclusive - not implemented
+    #    *  #critical - not implemented
+    #    *  #set_trace_func - not implemented
+    #    *  #safe_level - not implemented
+    #    *  #priority - not implemented
+
     class Thread
 
       @@em_threads = {}
 
-      # The underlying fiber.
+      # @return [Fiber] The underlying fiber.
       attr_reader :fiber
 
       # Like ::Thread::list. Return an array of all EM::Threads that are alive.
+      #
+      # @return [Array<Thread>]
       def self.list
         @@em_threads.values.select { |s| s.alive? }
       end
 
+      # Like ::Thread.main
+      #
+      # @return [Thread]
       def self.main
         @@main
       end
 
       # Like ::Thread::current. Get the currently running EM::Thread, eg to access thread local
       # variables
+      # @return [Thread] representing the current Fiber
       def self.current
         @@em_threads[Fiber.current] || ProxyThread.new(Fiber.current)
       end
@@ -68,12 +104,15 @@ module Empathy
 
 
       # Like ::Thread::stop. Sleep forever (until woken)
+      # @return [void]
       def self.stop
         Kernel.sleep()
       end
 
       # Like ::Thread::pass.
-      # The fiber is resumed on the next_tick of EM's event loop
+      # The fiber is paused and resumed on the next_tick of EM's event loop
+      #
+      # @return [nil]
       def self.pass
         em_thread = current
         ::EM.next_tick{ em_thread.__send__(:wake_resume) }
@@ -82,20 +121,27 @@ module Empathy
       end
 
       # Like ::Thread.exit
+      # @return [Thread]
       def self.exit
         current.exit
       end
 
+      # Like ::Thread.kill
+      # @return [Thread]
       def self.kill(thread)
         thread.exit
       end
 
+      # @private
       def self.new(*args,&block)
         instance = super(*args,&block)
-        ::Kernel.raise FiberError, "super not called for subclass of Thread" unless instance.instance_variable_defined?("@fiber")
+        ::Kernel.raise ThreadError, "super not called for subclass of Thread" unless instance.instance_variable_defined?("@fiber")
         instance
       end
 
+      # Like ::Thread.start
+      #
+      # @return [Thread]
       def self.start(*args,&block)
         ::Kernel.raise ArgumentError, "no block" unless block_given?
         c = if self != Thread
@@ -106,22 +152,20 @@ module Empathy
               end
             else
               self
-            end 
+            end
         c.new(*args,&block)
       end
 
-      # Create and run 
+      # Like ::Thread#initialize
       def initialize(*args,&block)
 
-        ::Kernel.raise FiberError, "no block" unless block_given?
+        ::Kernel.raise ThreadError, "no block" unless block_given?
         initialize_fiber(*args,&block)
       end
 
       # Like ::Thread#join.
-      #   s1 = Empathy.new{ Empathy.sleep(1) }
-      #   s2 = Empathy.new{ Empathy.sleep(1) }
-      #   s1.join
-      #   s2.join
+      # @param [Numeric] limit seconds to wait for thread to expire
+      # @return [nil,Thread] nil if timeout expires, otherwise this Thread
       def join(limit = nil)
         @mutex.synchronize { @join_cond.wait(@mutex,limit) } if alive?
         ::Kernel.raise @exception if @exception
@@ -136,16 +180,22 @@ module Empathy
       end
 
       # Like ::Thread#alive? or Fiber#alive?
+      # @return [true,false]
       def alive?
         fiber.alive?
       end
 
-      # Like ::Thread#stop? Always true unless our fiber is the current fiber
+      # Like ::Thread#stop?
+      # @return [false] if called on the current fiber
+      # @return [true] otherwise
       def stop?
         Fiber.current != fiber
       end
 
       # Like ::Thread#status
+      # @return [String]
+      # @return [false]
+      # @return [nil]
       def status
         case @status
         when :run
@@ -165,13 +215,13 @@ module Empathy
       end
 
       # Like ::Thread#value.  Implicitly calls #join.
-      #   em_thread = Empathy.new{ 1+2 }
-      #   em_thread.value # => 3
       def value
         join and @value
       end
 
       # Like ::Thread#exit. Signals thread to wakeup and die
+      #
+      # @return [nil, Thread]
       def exit
         case @status
         when :sleep
@@ -185,13 +235,25 @@ module Empathy
       alias :terminate :exit
 
       # Like ::Thread#wakeup Wakes a sleeping Thread
+      # @return [Thread]
       def wakeup
-        ::Kernel.raise FiberError, "dead em_thread" unless status
-        wake_resume() 
+        ::Kernel.raise ThreadError, "dead em_thread" unless status
+        wake_resume()
         self
       end
 
       # Like ::Thread#raise, raise an exception on a sleeping Thread
+      # @overload raise()
+      #   @raise RuntimeError
+      # @overload raise(string)
+      #   @param [String] string
+      #   @raise RuntimeError
+      # @overload raise(exception,string=nil,array=caller())
+      #   @param [Class,String,Object) exception
+      #   @param [String] string exception message
+      #   @param [Array<String>] array caller information
+      #   @raise Exception
+      # @return [void]
       def raise(*args)
         args << RuntimeError if args.empty?
         if fiber == Fiber.current
@@ -207,45 +269,43 @@ module Empathy
 
 
       # Access to "fiber local" variables, akin to "thread local" variables.
-      #   Empathy.new do
-      #     ...
-      #     Empathy.current[:connection].send(data)
-      #     ...
-      #   end
+      # @param [Symbol] name
+      # @return [Object,nil]
       def [](name)
         ::Kernel.raise TypeError, "name #{name} must convert to_sym" unless name and name.respond_to?(:to_sym)
         @locals[name.to_sym]
       end
 
       # Access to "fiber local" variables, akin to "thread local" variables.
-      #   Empathy.new do
-      #     ...
-      #     Empathy.current[:connection] = SomeConnectionClass.new(host, port)
-      #     ...
-      #   end
       def []=(name, value)
         ::Kernel.raise TypeError, "name #{name} must convert to_sym" unless name and name.respond_to?(:to_sym)
         @locals[name.to_sym] = value
       end
 
       # Like ::Thread#key? Is there a "fiber local" variable defined called +name+
+      # @param [Symbol] name
+      # @return [true,false]
       def key?(name)
         ::Kernel.raise TypeError, "name #{name} must convert to_sym" unless name and name.respond_to?(:to_sym)
         @locals.has_key?(name.to_sym)
       end
 
       # Like ::Thread#keys The set of "em_thread local" variable keys
+      # @return [Array<Symbol>]
       def keys()
         @locals.keys
       end
 
-      def inspect #:nodoc:
+      # Like ::Thread#inspect
+      # @return [String]
+      def inspect
         "#<Empathy::EM::Thread:0x%s %s %s" % [object_id, @fiber == Fiber.current ? "run" : "yielded", status || "dead" ]
       end
 
       # Do something when the fiber completes.
+      # @return [void]
       def ensure_hook(key,&block)
-        if block_given? then 
+        if block_given? then
           @ensure_hooks[key] = block
         else
           @ensure_hooks.delete(key)
@@ -286,7 +346,7 @@ module Empathy
       private
 
       def initialize_fiber(*args,&block)
-        ::Kernel.raise FiberError, "already initialized" if @fiber
+        ::Kernel.raise ThreadError, "already initialized" if @fiber
         # Create our fiber.
         fiber = Fiber.new{ fiber_body(*args,&block) }
 

data/lib/empathy/object.rb

@@ -1,16 +1,16 @@
 
-warn "empathy/object: Monkey patching Object#sleep and Object@at_exit for EM::reactor awareness"
+warn "empathy/object: Monkey patching Object#sleep and Object#at_exit for EventMachine reactor awareness"
 
 # Monkey patch object to make EM safe
 class Object
 
-  # use EM safe sleep if we are in the reactor
+  # use {Empathy::EM::Kernel.sleep} if we are in the reactor, Kernel.sleep otherwise
   def sleep(*args)
     kernel = Empathy.event_machine? ? Empathy::EM::Kernel : Kernel
     kernel.sleep(*args)
   end
 
-  # run exit blocks created in the reactor as reactor shutdown hooks
+  # use {Empathy::EM::Kernel.at_exit} if we are in the reactor, Kernel.sleep otherwise
   def at_exit(&block)
     kernel = Empathy.event_machine? ? Empathy::EM::Kernel : Kernel
     kernel.at_exit(&block)

data/lib/empathy/version.rb

@@ -1,3 +1,3 @@
 module Empathy
-  VERSION = "0.0.1.RC0"
+  VERSION = "0.0.1.RC2"
 end

data/lib/empathy/with_all_of_ruby.rb

@@ -0,0 +1,8 @@
+require 'eventmachine'
+require 'empathy'
+require 'empathy/object'
+
+module Empathy
+ map_classes(::EventMachine,::Object)
+ map_classes(::Object,Empathy::EM)
+end

data/lib/empathy.rb

@@ -1,61 +1,62 @@
 require 'empathy/version'
 require 'thread'
+require 'monitor'
 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
+# the {Empathy::EM} namespace.
 #
-#   # For the Empathy::EM classes to be available
-#   # you must first load EventMachine
-#   'require eventmachine'
+#     # For the Empathy::EM classes to be available
+#     # you must first load EventMachine
+#     'require eventmachine'
 #
-#   'require empathy'
+#     'require empathy'
 #
-#   t = Empathy::Thread.new() do
-#       begin
-#       # "t" is a standard ::Thread
-#       ...something...
-#   end
+#     t = Empathy::Thread.new() do
+#         # "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
+#     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
+#     # 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]
+#     #Code using Empathy that may be used in both Fiber or Thread contexts
+#     #should take care to rescue Empathy::ThreadError
 #
-#   def maybe_em_method
-#      # some code
-#   rescue *Empathy::Errors
+#     def maybe_em_method
+#        # ...
+#     rescue Empathy::ThreadError
+#        # ... will rescue either ::FiberError or ::ThreadError
+#     end
 #
-#   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
 
+  @empathised = self
+  @empathic_classes = []
+
+  #This is never thrown but can be used to rescue both ThreadError and FiberError
   class ThreadError < StandardError
+    RUBY_ThreadError = ::ThreadError
     def self.===(other)
-      super || ::FiberError === other || ::ThreadError === other
+      super || ::FiberError === other || RUBY_ThreadError === other
     end
   end
 
+  @empathic_classes << 'ThreadError'
+
   # Start EventMachine and run reactor block within a surrounding Empathy::EM::Thread (Fiber).
   # The reactor loop is terminated when the supplied block finishes
+  # @return the value of the block
   def self.run
     reload()
     exception = nil
@@ -75,17 +76,21 @@ module Empathy
     value
   end
 
+  # Create alias constants in each of the supplied modules so that code witin those modules
+  # will use modules from the Empathy namespace instaad of the native ruby ones
+  #
+  # Also monkey patches {Object} to provide EM safe Kernel methods
+  # @param [Array<Module>] modules
+  # @return [void]
   def self.empathise(*modules)
-    modules.each do |m|
-      map_classes(m, self, "Thread","Queue","Mutex","ConditionVariable", "ThreadError")
-    end
+    modules.each { |m| map_classes(m, self) }
   end
 
-  #@api private
-  def self.map_classes(into,from,*class_names)
+  # @private
+  def self.map_classes(into,from)
     # Make Object reactor aware
     require 'empathy/object'
-    class_names.each do |cname|
+    @empathic_classes.each do |cname|
       case cname
       when Hash
         cname.each { |cn,replace_class| replace_class_constant(into,cn,replace_class) }
@@ -93,8 +98,10 @@ module Empathy
         replace_class_constant(into,cname,from.const_get(cname))
       end
     end
+    into.instance_variable_set(:@empathised,from)
   end
 
+private
   def self.replace_class_constant(into,cname,replace_class)
     if into != Object && into.const_defined?(cname,false)
        existing_const = into.const_get(cname)
@@ -107,7 +114,7 @@ module Empathy
     warn "empathy: Defined fake class constant #{into}::#{cname} => #{replace_class.name}"
     into.const_set(cname,replace_class)
   end
-
+public
   # Test whether we have real fibers or a thread based fiber implmentation
   t = Thread.current
   ft = nil
@@ -121,7 +128,7 @@ module Empathy
     @loaded ||= false
     if !@loaded && defined?(EventMachine)
       require 'empathy/em/thread.rb'
-      require 'empathy/em/queue.rb'
+      require 'empathy/em/monitor.rb'
       @loaded = true
     end
     return @loaded
@@ -142,16 +149,44 @@ module Empathy
   end
 
   private
+
+  # Create a module under the Empathy namespace that delegates class methods (potentially including #new)
+  # to either the top level class, or to its equivalent under the {Empathy::EM} namespace
+  # based on being in/out of the reactor
+  #
+  # Library authors can use this to define an eventmachine aware replacement class for their own purposes
+  # @example
+  #
+  #   class MyBinding
+  #     #...code that does not use event machine
+  #   end
+  #
+  #   module Empathy
+  #     module EM
+  #       class MyBinding
+  #         # ... code that uses event machine ...
+  #       end
+  #     end
+  #
+  #     create_delegate_module('MyBinding',:new, :my_class_method)
+  #   end
+  #
+  # @visibility public
+  # @param [String] cname name of the top level class or module to delegate, there must
+  #    also be a class with the same name in the Empathy::EM namespace
+  # @param [Array<Sumbol>] methods names of class/module methods to delegate
   def self.create_delegate_module(cname,*methods)
     mod = Module.new
+    native_mod = Object.const_get(cname)
+    em_mod = Empathy::EM.const_get(cname)
     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 = Empathy.event_machine? ? em_mod : native_mod
         delegate.send(m,*args,&block)
       end
     end
+    @empathic_classes << cname unless cname == 'Kernel'
   end
 
   create_delegate_module('Kernel',:sleep,:at_exit)
@@ -159,4 +194,5 @@ module Empathy
   create_delegate_module('Queue',:new)
   create_delegate_module('ConditionVariable',:new)
   create_delegate_module('Mutex',:new)
+  create_delegate_module('Monitor',:new)
 end