strand 0.1.0 → 0.2.0.rc0

data/.gitignore

@@ -0,0 +1,3 @@
+Gemfile.lock
+html
+pkg/

data/CHANGELOG

@@ -0,0 +1,13 @@
+== 0.2.0
+New features
+* Strand now implements many more ::Thread methods and equivalents for ::Queue and ::Mutex
+* Strand is now a module that behaves like a class. Strand.new will return a ::Thread or a Strand::EM::Thread
+  depending on whether it is running within the EventMachine reactor or not
+     
+Changes
+* EventMachine is now an optional dependency (because it can work without EM)
+* Strand.yield and Strand.resume can now take arguments (like Fiber)
+* Final call to Strand.resume will return strand's value (or exception)
+* Normalize access to strand local variables (converts everything to symbols interally)
+
+== 0.1.0 - Initial version

data/Gemfile

@@ -1,16 +1,4 @@
-source "http://rubygems.org"
-# Add dependencies required to use your gem here.
-# Example:
-#   gem "activesupport", ">= 2.3.5"
+source 'https://rubygems.org'
 
-# Add dependencies to develop your gem here.
-# Include everything needed to run rake, tests, features, etc.
-group :development do
-  gem "bundler", "~> 1.0.0"
-  gem "em-spec"
-  gem "eventmachine", "~> 0.12.0"
-  gem "jeweler", "~> 1.6.4"
-  gem "rcov", ">= 0"
-  gem "rr"
-  gem "rspec"
-end
+# Specify your gem's dependencies in strand.gemspec
+gemspec

data/LICENSE.txt

@@ -1,4 +1,5 @@
 Copyright (c) 2011 Christopher J. Bottaro
+Copyright (c) 2012 Grant Gardner
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.rdoc

@@ -1,12 +1,12 @@
 = strand
 
-Strand is a class that wraps Fibers and gives them Thread-like behavior by using EventMachine.
+Strand is a module that provides Thread-like behavior for Fibers in EventMachine.
 
-Strand::ConditionVariable provides functionality for Fibers similar to Ruby's built in ConditionVariable for Threads.
+http://rubygems.org/gems/strand
 
 == Like Threads
 
-Strand has an interface similar to Thread.
+Strand has an interface identical to Thread wherever possible. The specs for Strand are based on the ruby-spec for Thread
 
   thread = Thread.new{ 1+2 }
   thread.join
@@ -18,15 +18,7 @@ Strand has an interface similar to Thread.
 
 == Fiber/EventMachine aware sleep
 
-Calling sleep usually results in EventMachine's reactor being blocked, but Strand defines an EM+Fiber safe sleep.
-
-Consider mimicking the following threaded code:
-
-  t1 = Thread.new{ sleep(1) }
-  t2 = Thread.new{ sleep(1) }
-  t1.join
-  t2.join
-  # Roughly 1 second will have passed.
+Calling ruby's Kernel.sleep will block the EventMachine reactor, but Strand defines an EM+Fiber safe sleep.
 
 Assuming that EventMachine is running:
 
@@ -34,8 +26,11 @@ Assuming that EventMachine is running:
   s2 = Strand.new{ Strand.sleep(1) }
   s1.join
   s2.join
+
   # Roughly 1 second will have passed.
 
+When run outside of the EventMachine reactor, Strand delegates to ruby's native ::Thread so the above code would still work as expected.
+
 == Thread local, Fiber local and Strand local variables
 
 Thread local storage is the same as Fiber local storage in Ruby.
@@ -152,10 +147,6 @@ The output is:
   3
   3
 
-== RDoc
-
-{\http://doc.stochasticbytes.com/strand/index.html}[http://doc.stochasticbytes.com/strand/index.html]
-
 == Contributing to strand
  
 * Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
@@ -163,11 +154,13 @@ The output is:
 * Fork the project
 * Start a feature/bugfix branch
 * Commit and push until you are happy with your contribution
-* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* 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. See LICENSE.txt for
-further details.
+Copyright (c) 2011 Christopher J. Bottaro.
+Copyright (c) 2012 Grant Gardner.
+
+See LICENSE.txt for further details.
 

data/Rakefile

@@ -1,64 +1,17 @@
-# encoding: utf-8
-
-require 'rubygems'
-require 'bundler'
-begin
-  Bundler.setup(:default, :development)
-rescue Bundler::BundlerError => e
-  $stderr.puts e.message
-  $stderr.puts "Run `bundle install` to install missing gems"
-  exit e.status_code
-end
-require 'rake'
-
-require 'jeweler'
-Jeweler::Tasks.new do |gem|
-  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
-  gem.name = "strand"
-  gem.homepage = "http://github.com/cjbottaro/strand"
-  gem.license = "MIT"
-  gem.summary = %Q{Make fibers behave like threads using EventMachine.}
-  gem.description = %Q{Get thread-like behavior from fibers using EventMachine.}
-  gem.email = "cjbottaro@alumni.cs.utexas.edu"
-  gem.authors = ["Christopher J. Bottaro"]
-  # dependencies defined in Gemfile
-end
-Jeweler::RubygemsDotOrgTasks.new
-
-require 'rake/testtask'
-Rake::TestTask.new(:test) do |test|
-  test.libs << 'lib' << 'test'
-  test.pattern = 'test/**/test_*.rb'
-  test.verbose = true
-end
-
-require 'rcov/rcovtask'
-Rcov::RcovTask.new do |test|
-  test.libs << 'test'
-  test.pattern = 'test/**/test_*.rb'
-  test.verbose = true
-  test.rcov_opts << '--exclude "gems/*"'
-end
+require "bundler/gem_tasks"
 
 require 'rspec/core'
 require 'rspec/core/rake_task'
-RSpec::Core::RakeTask.new(:spec) do |spec|
-  spec.pattern = FileList['spec/**/*_spec.rb']
-end
+require 'rdoc/task'
+require 'rake/clean'
 
-RSpec::Core::RakeTask.new(:rcov) do |spec|
-  spec.pattern = 'spec/**/*_spec.rb'
-  spec.rcov = true
-end
+RSpec::Core::RakeTask.new(:spec)
 
-task :default => :test
+RDoc::Task.new do |rdoc|
+    rdoc.main = "README.rdoc"
+    rdoc.rdoc_files.include("README.rdoc", "CHANGELOG","lib/**/*.rb")
+    rdoc.title = "Strand"
+end
 
-require 'rake/rdoctask'
-Rake::RDocTask.new do |rdoc|
-  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+CLOBBER.include [ "pkg/" ]
 
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = "strand #{version}"
-  rdoc.rdoc_files.include('README*')
-  rdoc.rdoc_files.include('lib/**/*.rb')
-end

data/lib/strand.rb

@@ -1,132 +1,157 @@
-require "fiber"
-require "eventmachine"
-require "strand/condition_variable"
-
-class Strand
-
-  @@strands = {}
-
-  # The strand's underlying fiber.
-  attr_reader :fiber
-
-  # Return an array of all Strands that are alive.
-  def self.list
-    @@strands.values
-  end
-
-  # Get the currently running strand.  Primarily used to access "strand local" variables.
-  def self.current
-    @@strands[Fiber.current]
-  end
-
-  # EM/fiber safe sleep.
-  def self.sleep(seconds)
-    fiber = Fiber.current
-    EM::Timer.new(seconds){ fiber.resume }
-    Fiber.yield
-  end
-
-  # Alias for Fiber.yield.
-  def self.yield
-    Fiber.yield
-  end
-
-  # Yield the strand, but have EM resume it on the next tick.
-  def self.pass
-    fiber = Fiber.current
-    EM.next_tick{ fiber.resume }
-    Fiber.yield
-  end
-
-  # Create and run a strand.
-  def initialize(&block)
-
-    # Initialize our "fiber local" storage.
-    @locals = {}
-
-    # Condition variable for joining.
-    @join_cond = ConditionVariable.new
-
-    # Create our fiber.
-    @fiber = Fiber.new{ fiber_body(&block) }
-
-    # Add us to the list of living strands.
-    @@strands[@fiber] = self
-
-    # Finally start the strand.
-    resume
-  end
-
-  # Like Thread#join.
-  #   s1 = Strand.new{ Strand.sleep(1) }
-  #   s2 = Strand.new{ Strand.sleep(1) }
-  #   s1.join
-  #   s2.join
-  def join
-    @join_cond.wait if alive?
-    raise @exception if @exception
-    true
-  end
-
-  # Like Fiber#resume.
-  def resume
-    @fiber.resume
-  end
-
-  # Like Thread#alive? or Fiber#alive?
-  def alive?
-    @fiber.alive?
-  end
-
-  # Like Thread#value.  Implicitly calls #join.
-  #   strand = Strand.new{ 1+2 }
-  #   strand.value # => 3
-  def value
-    join and @value
-  end
-
-  # Access to "strand local" variables, akin to "thread local" variables.
-  #   Strand.new do
-  #     ...
-  #     Strand.current[:connection].send(data)
-  #     ...
-  #   end
-  def [](name)
-    @locals[name]
-  end
-
-  # Access to "strand local" variables, akin to "thread local" variables.
-  #   Strand.new do
-  #     ...
-  #     Strand.current[:connection] = SomeConnectionClass.new(host, port)
-  #     ...
-  #   end
-  def []=(name, value)
-    @locals[name] = value
-  end
-
-  def inspect #:nodoc:
-    "#<Strand:0x%s %s" % [object_id, @fiber == Fiber.current ? "run" : "yielded"]
-  end
-
-protected
-  
-  def fiber_body(&block) #:nodoc:
-    # Run the strand's block and capture the return value.
-    begin
-      @value = block.call
-    rescue StandardError => e
-      @exception = e
+require 'strand/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 Strand::EM module
+# 
+#   # For the Strand::EM classes to be available
+#   # you must first load EventMachine
+#   'require eventmachine'
+#
+#   'require strand'
+#
+#   t = Strand.new() do
+#       # "t" is a standard ::Thread
+#       ...something...
+#   end
+#
+#   EventMachine.run do
+#      t = Strand.new() do
+#           # "t" is a ::Strand::EM::Thread
+#           # which wraps a ::Fiber
+#      end
+#   end
+#
+#   # Outside of event machine 
+#   t = Strand.new() do
+#       # "t" is a raw ::Thread
+#   end
+#
+# Code using Strand that may be used in both Fiber or Thread contexts
+# should take care to rescue both {FiberError} and {ThreadError} in any
+# exception handling code
+#
+# {::Thread} methods not implemented by Strand
+#   * .main - although there is a root fiber it is not really equivalent to {::Thread.main}
+#   * .start - not implemented
+#   * #exclusive - not implemented  
+#   * #critical - not implemented
+#   * #set_trace_func - not implemented
+#   * #safe_level - not implemented
+#   * #priority - not implemented
+module Strand
+
+    # 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()
+        @em_class_map = if defined?(EventMachine) then enable_eventmachine() else nil end
     end
 
-    # Mark the strand as finished running.
-    @finished = true
+    # Private
+    def self.enable_eventmachine
+        return false unless defined?(EventMachine)
+
+        require 'strand/em/thread.rb'
+        require 'strand/em/queue.rb'
+
+        # Classes if eventmachine has been previously loaded
+        {
+            ::Thread => Strand::EM::Thread,
+            ::Kernel => Strand::EM::Thread,
+            ::Mutex  => Strand::EM::Mutex,
+            ::ConditionVariable => Strand::EM::ConditionVariable,
+            ::Queue => Strand::EM::Queue
+        }
+    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?
+        @em_class_map = enable_eventmachine() if @em_class_map.nil?
+
+        @em_class_map && EventMachine.reactor_running? &&
+                ( EventMachine.reactor_thread? || (!REAL_FIBERS && ROOT_FIBER != Fiber.current))
+    end
+
+    def self.delegate_class(class_key)
+        if self.event_machine? then @em_class_map[class_key] else class_key end
+    end
+
+    # ::Thread::list or EM::Thread::list
+    def self.list
+        delegate_class(::Thread).list()
+    end
+
+    # ::Thread::current or EM::Thread::current
+    def self.current
+        delegate_class(::Thread).current()
+    end
+
+    # ::Kernel::sleep or EM::Thread::sleep
+    # Note that passing nil will sleep forever (where Kernel.sleep raises TypeError)
+    def self.sleep(*args)
+        # Kernel.sleep treats nil as an error, but we use it to indicate sleeping forever
+        args.shift if args.length == 1 and args.first.nil?    
+        delegate_class(::Kernel).sleep(*args)
+    end
+
+    # ::Thread::stop or EM::Thread::stop
+    def self.stop()
+        delegate_class(::Thread).stop() 
+    end
+
+    # ::Thread::pass or EM::Thread::pass
+    def self.pass()
+        delegate_class(::Thread).pass()
+    end
+
+    #TODO Is there some equivalence between the root Fiber and Thread.main?
+    
+    # Convenience to call Fiber.yield. Note the warning on EM::Thread::yield
+    def self.yield(*args)
+        Fiber.yield(*args)
+    end
+
+    # Behave like a class returning
+    # an instance of ::Thread, or ::Strand::EM::Thread based on
+    # whether the caller is within the EventMachine reactor 
+    def self.new(*args,&block)
+        delegate_class(::Thread).new(*args,&block)
+    end
 
-    # Delete from the list of running stands.
-    @@strands.delete(@fiber)
+    module Mutex
+        # Return a new ::Mutex or EM::Mutex
+        def self.new(*args,&block)
+            Strand.delegate_class(::Mutex).new(*args,&block)
+        end
+    end
 
-    # Resume anyone who called join on us.
-    @join_cond.signal
-  end
+    module ConditionVariable
+        # Return a new ::ConditionVariable or EM::ConditionVariable
+        def self.new(*args,&block)
+            Strand.delegate_class(::ConditionVariable).new(*args,&block)
+        end
+    end
 
+    module Queue
+        # Return a new ::Queue or EM::Queue
+        def self.new(*args,&block)
+            Strand.delegate_class(::Queue).new(*args,&block)
+        end
+    end
 end