thread_order 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,15 @@
 ---
-SHA1:
-  metadata.gz: b2d68b153c8a232b3fdcb3efc2ec6799abf9e11a
-  data.tar.gz: 5f340011a9259a523b6fa3dca0494ad8f17887aa
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    ZmFjZjVkN2Y3Y2Y0M2UwMzNiODEwMzM5YWMwZjA2NjBkMzhkZGU2Zg==
+  data.tar.gz: !binary |-
+    ZThiYjJhMDE4YzFkMzZkNWM2YWIxNzMyOTExNDgyZjJlM2MzYmRjYw==
 SHA512:
-  metadata.gz: 6247a9d7f485371a1725e7098a2dde38b4376a822ecfcb6ea7a69c36d8a1abc7d60bded9f12c3c5297bd635c05e4c87c271bc73054f19724068e2f2a62ed979c
-  data.tar.gz: 988632f09cc15d15fa705e87a561d86b26c8f5f079df692c8d288865cd578674f1db67371e8363e08e66adc59ce778b6bdc3a91ea9e74a9cc7de2f126c828591
+  metadata.gz: !binary |-
+    NDhhN2IyYzA0Y2UyZmZkZWI5NDU1MDdmYWE0Y2E3ZDE3YTFkZjRlZjgwODIy
+    OTIxMjliZDc1NmZkMTU4NjA5OTYzYjliYmI1N2QxNjdhNGVjMTZlZDc5OGFj
+    N2UwY2U3ZjQ5ZDdlY2RkMWE4OThjYzNlMjU0MTEwZTc4MjM0NGQ=
+  data.tar.gz: !binary |-
+    MTI1ZDZkMGE1NGM0MzIzZTdiMGRjMDAyNjJhMTlmNWE4NWY5MWFjOTQyOTg5
+    NDJiMTI5YzJhNzE3MTIxNzYzNzRkOGEzMTcwNzQ4ZTBjMTM3YTZiZWVlODk3
+    YWRlMjM5YTg3YmY0ZTdmYTVlYjYxYWQ1ZmMwZmUwMDkwM2E0OTQ=

data/.gitignore

@@ -1,3 +1,4 @@
 *.gem
 Gemfile.lock
 tmp/
+.rbx

data/Readme.md

@@ -9,3 +9,54 @@ Its purpose is to enable reasoning about thread order.
 * Tested on 1.8.7 - 2.2, JRuby, Rbx
 * It has no external dependencies
 * It does not depend on the stdlib.
+
+Example
+-------
+
+```ruby
+# A somewhat contrived class we're going to test.
+class MyQueue
+  attr_reader :array
+
+  def initialize
+    @array, @mutex = [], Mutex.new
+  end
+
+  def enqueue
+    @mutex.synchronize { @array << yield }
+  end
+end
+
+
+
+require 'rspec/autorun'
+require 'thread_order'
+
+RSpec.describe MyQueue do
+  let(:queue) { described_class.new }
+  let(:order) { ThreadOrder.new }
+  after { order.apocalypse! } # ensure everything gets cleaned up (technically redundant for our one example, but it's a good practice)
+
+  it 'is threadsafe on enqueue' do
+    # will execute in a thread, can be invoked by name
+    order.declare :concurrent_enqueue do
+      queue.enqueue { :concurrent }
+    end
+
+    # this enqueue will block until the mutex puts the other one to sleep
+    queue.enqueue do
+      order.pass_to :concurrent_enqueue, resume_on: :sleep
+      :main
+    end
+
+    order.join_all # concurrent_enqueue may still be asleep
+    expect(queue.array).to eq [:main, :concurrent]
+  end
+end
+
+# >> MyQueue
+# >>   is threadsafe on enqueue
+# >>
+# >> Finished in 0.00131 seconds (files took 0.08687 seconds to load)
+# >> 1 example, 0 failures
+```

data/lib/thread_order.rb

@@ -1,73 +1,102 @@
 require 'thread_order/mutex'
 
 class ThreadOrder
+  Error        = Class.new RuntimeError
+  CannotResume = Class.new Error
+
+  # Note that this must tbe initialized in a threadsafe environment
+  # Otherwise, syncing may occur before the mutex is set
   def initialize
+    @mutex   = Mutex.new
     @bodies  = {}
     @threads = []
-    @queue   = [] # we may not have thread stdlib required, so may not have Queue class
-    @mutex   = Mutex.new
-    @worker  = Thread.new { loop { work } }
-    @worker.abort_on_exception = true
+    @queue   = [] # Queue is in stdlib, but half the purpose of this lib is to avoid such deps, so using an array in a Mutex
+    @worker  = Thread.new do
+      Thread.current.abort_on_exception = true
+      Thread.current[:thread_order_name] = :internal_worker
+      loop { break if :shutdown == work() }
+    end
   end
 
   def declare(name, &block)
-    @bodies[name] = block
+    sync { @bodies[name] = block }
   end
 
   def current
     Thread.current[:thread_order_name]
   end
 
-  def pass_to(name, options)
-    parent       = Thread.current
+  def pass_to(name, options={})
     child        = nil
-    resume_event = extract_resume_event! options
-    resume_if    = lambda do |event|
-      return unless event == sync { resume_event }
-      parent.wakeup
-    end
-
+    parent       = Thread.current
+    resume_event = extract_resume_event!(options)
     enqueue do
-      child = Thread.new do
-        enqueue { @threads << child }
-        sync { resume_event } == :sleep &&
-          enqueue { watch_for_sleep(child) { resume_if.call :sleep } }
-        begin
-          enqueue { resume_if.call :run }
-          Thread.current[:thread_order_name] = name
-          @bodies.fetch(name).call
-        rescue Exception => error
-          enqueue { parent.raise error }
-          raise
-        ensure
-          enqueue { resume_if.call :exit }
-        end
+      sync do
+        @threads << Thread.new {
+          child = Thread.current
+          child[:thread_order_name] = name
+          body = sync { @bodies.fetch(name) }
+          wait_until { parent.stop? }
+          :run == resume_event && parent.wakeup
+          wake_on_sleep = lambda do
+            child.status == 'sleep' ? parent.wakeup :
+            child.status == nil     ? :noop         :
+            child.status == false   ? parent.raise(CannotResume.new "#{name} exited instead of sleeping") :
+                                      enqueue(&wake_on_sleep)
+          end
+          :sleep == resume_event && enqueue(&wake_on_sleep)
+          begin
+            body.call parent
+          rescue Exception => e
+            enqueue { parent.raise e }
+            raise
+          ensure
+            :exit == resume_event && enqueue { parent.wakeup }
+          end
+        }
       end
     end
-
     sleep
     child
   end
 
+  def join_all
+    sync { @threads }.each { |th| th.join }
+  end
+
   def apocalypse!(thread_method=:kill)
     enqueue do
       @threads.each(&thread_method)
       @queue.clear
-      @worker.kill
+      :shutdown
     end
     @worker.join
   end
 
+  def enqueue(&block)
+    sync { @queue << block if @worker.alive? }
+  end
+
+  def wait_until(&condition)
+    return if condition.call
+    thread = Thread.current
+    wake_when_true = lambda do
+      if thread.stop? && condition.call
+        thread.wakeup
+      else
+        enqueue(&wake_when_true)
+      end
+    end
+    enqueue(&wake_when_true)
+    sleep
+  end
+
   private
 
   def sync(&block)
     @mutex.synchronize(&block)
   end
 
-  def enqueue(&block)
-    sync { @queue << block }
-  end
-
   def work
     task = sync { @queue.shift }
     task ||= lambda { Thread.pass }
@@ -78,18 +107,8 @@ class ThreadOrder
     resume_on = options.delete :resume_on
     options.any? &&
       raise(ArgumentError, "Unknown options: #{options.inspect}")
-    resume_on && ![:run, :exit, :sleep].include?(resume_on) and
+    resume_on && ![:run, :exit, :sleep, nil].include?(resume_on) and
       raise(ArgumentError, "Unknown status: #{resume_on.inspect}")
-    resume_on
-  end
-
-  def watch_for_sleep(thread, &cb)
-    if thread.status == false || thread.status == nil
-      # noop, dead threads dream no dreams
-    elsif thread.status == 'sleep'
-      cb.call
-    else
-      enqueue { watch_for_sleep(thread, &cb) }
-    end
+    resume_on || :none
   end
 end

data/lib/thread_order/mutex.rb

@@ -1,21 +1,21 @@
-# On > 1.9, this is in core.
-# On 1.8.7, it's in the stdlib.
-# We don't want to load the stdlib, b/c this is a test tool, and can affect the test environment,
-# causing tests to pass where they should fail.
-#
-# So we're transcribing it here, from.
-# It is based on this implementation: https://github.com/ruby/ruby/blob/v1_8_7_374/lib/thread.rb#L56
-# If it's not already defined. Some methods we don't need are deleted.
-# Anything I don't understand is left in.
 class ThreadOrder
   Mutex = if defined? ::Mutex
+    # On 1.9 and up, this is in core, so we just use the real one
     ::Mutex
   else
+
+    # On 1.8.7, it's in the stdlib.
+    # We don't want to load the stdlib, b/c this is a test tool, and can affect the test environment,
+    # causing tests to pass where they should fail.
+    #
+    # So we're transcribing/modifying it from https://github.com/ruby/ruby/blob/v1_8_7_374/lib/thread.rb#L56
+    # Some methods we don't need are deleted.
+    # Anything I don't understand (there's quite a bit, actually) is left in.
     Class.new do
       def initialize
         @waiting = []
         @locked = false;
-        @waiting.taint		# enable tainted comunication
+        @waiting.taint
         self.taint
       end
 

data/lib/thread_order/version.rb

@@ -1,3 +1,3 @@
 class ThreadOrder
-  VERSION = '1.0.0'
+  VERSION = '1.1.0'
 end

data/spec/run

@@ -34,25 +34,25 @@ get_gem "rspec-core"         "https://rubygems.org/downloads/rspec-core-3.2.1.ge
 get_gem "rspec-support"      "https://rubygems.org/downloads/rspec-support-3.2.2.gem" &&
 get_gem "rspec-expectations" "https://rubygems.org/downloads/rspec-expectations-3.2.0.gem" &&
 get_gem "rspec-mocks"        "https://rubygems.org/downloads/rspec-mocks-3.2.1.gem" &&
-get_gem "diff-lcs"           "https://rubygems.org/downloads/diff-lcs-1.2.5.gem"
+get_gem "diff-lcs"           "https://rubygems.org/downloads/diff-lcs-1.2.5.gem" || exit 1
 
 
 # run specs
-cd $project_root
+cd "$project_root"
 
 export PATH="$project_root/tmp/rspec-core/exe:$PATH"
 
-opts=""
-opts=" -I $project_root/tmp/diff-lcs/lib $opts"
-opts=" -I $project_root/tmp/rspec/lib $opts"
-opts=" -I $project_root/tmp/rspec-core/lib $opts"
-opts=" -I $project_root/tmp/rspec-expectations/lib $opts"
-opts=" -I $project_root/tmp/rspec-mocks/lib $opts"
-opts=" -I $project_root/tmp/rspec-support/lib $opts"
+opts=()
+opts+=(-I "$project_root/tmp/diff-lcs/lib")
+opts+=(-I "$project_root/tmp/rspec/lib")
+opts+=(-I "$project_root/tmp/rspec-core/lib")
+opts+=(-I "$project_root/tmp/rspec-expectations/lib")
+opts+=(-I "$project_root/tmp/rspec-mocks/lib")
+opts+=(-I "$project_root/tmp/rspec-support/lib")
 
 if `ruby -e "exit RUBY_VERSION != '1.8.7'"`
 then
-  opts="--disable-gems $opts"
+  opts+=(--disable-gems)
 fi
 
-ruby $opts -S rspec
+ruby "${opts[@]}" -S rspec --colour --fail-fast --format documentation

data/spec/thread_order_spec.rb

@@ -45,35 +45,75 @@ RSpec.describe ThreadOrder do
       order.declare(:t) { Thread.exit }
       order.pass_to :t, :resume_on => :exit
     end
+
+    it 'passes the parent to the thread' do
+      parent = nil
+      order.declare(:t) { |p| parent = p }
+      order.pass_to :t, :resume_on => :exit
+      expect(parent).to eq Thread.current
+    end
+
+    it 'sleeps until woken if it does not provide a :resume_on key' do
+      order.declare(:t) { |parent|
+        order.enqueue {
+          expect(parent.status).to eq 'sleep'
+          parent.wakeup
+        }
+      }
+      order.pass_to :t
+    end
+
+    it 'blows up if it is waiting on another thread to sleep and that thread exits instead' do
+      expect {
+        order.declare(:t1) { :exits_instead_of_sleeping }
+        order.pass_to :t1, :resume_on => :sleep
+      }.to raise_error ThreadOrder::CannotResume, /t1 exited/
+    end
+  end
+
+  describe 'error types' do
+    it 'has a toplevel lib error: ThreadOrder::Error which is a RuntimeError' do
+      expect(ThreadOrder::Error.superclass).to eq RuntimeError
+    end
+
+    specify 'all behavioural errors it raises inherit from ThreadOrder::Error' do
+      expect(ThreadOrder::CannotResume.superclass).to eq ThreadOrder::Error
+    end
   end
 
   describe 'errors in children' do
     specify 'are raised in the child' do
-      child = nil
-      order.declare(:err) { child = Thread.current; raise 'the roof' }
-      order.pass_to :err, :resume_on => :exit rescue nil
-      child.join                              rescue nil
-      expect(child.status).to eq nil
+      order.declare(:err) { sleep }
+      child = order.pass_to :err, :resume_on => :sleep
+      begin
+        child.raise RuntimeError.new('the roof')
+        sleep
+      rescue RuntimeError => e
+        expect(e.message).to eq 'the roof'
+      else
+        raise 'expected an error'
+      end
     end
 
     specify 'are raised in the parent' do
-      order.declare(:err) { raise Exception, 'to the rules' }
       expect {
-        order.pass_to :err, :resume_on => :run
-        loop { :noop }
+        order.declare(:err) { raise Exception, "to the rules" }
+        order.pass_to :err, :resume_on => :exit
+        sleep
       }.to raise_error Exception, 'to the rules'
     end
 
     specify 'even if the parent is asleep' do
+      order.declare(:err) { sleep }
       parent = Thread.current
-      order.declare(:err) {
-        :noop until parent.status == 'sleep'
-        raise 'the roof'
-      }
+      child  = order.pass_to :err, :resume_on => :sleep
       expect {
-        order.pass_to :err, :resume_on => :run
+        order.enqueue {
+          expect(parent.status).to eq 'sleep'
+          child.raise Exception.new 'to the rules'
+        }
         sleep
-      }.to raise_error RuntimeError, 'the roof'
+      }.to raise_error Exception, 'to the rules'
     end
   end
 
@@ -127,4 +167,87 @@ RSpec.describe ThreadOrder do
         to raise_error(ArgumentError, /bad_key/)
     end
   end
+
+  describe 'join_all' do
+    it 'joins with all the child threads' do
+      parent   = Thread.current
+      children = []
+
+      order.declare(:t1) do
+        order.pass_to :t2, :resume_on => :run
+        children << Thread.current
+      end
+
+      order.declare(:t2) do
+        children << Thread.current
+      end
+
+      order.pass_to :t1, :resume_on => :run
+      order.join_all
+      statuses = children.map { |th| th.status }
+      expect(statuses).to eq [false, false] # none are alive
+    end
+  end
+
+  describe 'synchronization' do
+    it 'allows any thread to enqueue work' do
+      seen = []
+
+      order.declare :enqueueing do |parent|
+        order.enqueue do
+          order.enqueue { seen << 2 }
+          order.enqueue { seen << 3 }
+          order.enqueue { parent.wakeup }
+          seen << 1
+        end
+      end
+
+      order.pass_to :enqueueing
+      expect(seen).to eq [1, 2, 3]
+    end
+
+    it 'allows a thread to put itself to sleep until some condition is met' do
+      i = 0
+      increment = lambda do
+        i += 1
+        order.enqueue(&increment)
+      end
+      increment.call
+      order.wait_until { i > 20_000 } # 100k is too slow on 1.8.7, but 10k is too fast on 2.2.0
+      expect(i).to be > 20_000
+    end
+  end
+
+  describe 'apocalypse!' do
+    it 'kills threads that are still alive' do
+      order.declare(:t) { sleep }
+      child = order.pass_to :t, :resume_on => :sleep
+      expect(child).to receive(:kill).and_call_original
+      expect(child).to_not receive(:join)
+      order.apocalypse!
+    end
+
+    it 'can be overridden to call a different method than kill' do
+      # for some reason, the mock calling original join doesn't work
+      order.declare(:t) { sleep }
+      child = order.pass_to :t, :resume_on => :run
+      expect(child).to_not receive(:kill)
+      joiner = Thread.new { order.apocalypse! :join }
+      Thread.pass until child.status == 'sleep' # can't use wait_until b/c that occurs within the worker, which is apocalypsizing
+      child.wakeup
+      joiner.join
+    end
+
+    it 'can call apocalypse! any number of times without harm' do
+      order.declare(:t) { sleep }
+      order.pass_to :t, :resume_on => :sleep
+      100.times { order.apocalypse! }
+    end
+
+    it 'does not enqueue events after the apocalypse' do
+      order.apocalypse!
+      thread = Thread.current
+      order.enqueue { thread.raise "Should not happen" }
+    end
+  end
 end

data/thread_order.gemspec

@@ -1,11 +1,11 @@
-require_relative 'lib/thread_order/version'
+require File.expand_path('../lib/thread_order/version', __FILE__)
 
 Gem::Specification.new do |s|
   s.name        = 'thread_order'
   s.version     = ThreadOrder::VERSION
   s.licenses    = ['MIT']
   s.summary     = "Test helper for ordering threaded code"
-  s.description = "Test helper for ordering threaded code (does not depend on gems or stdlib, tested on 1.8.7 - 2.2)."
+  s.description = "Test helper for ordering threaded code (does not depend on gems or stdlib, tested on 1.8.7 - 2.2, rbx, jruby)."
   s.authors     = ["Josh Cheek"]
   s.email       = 'josh.cheek@gmail.com'
   s.files       = `git ls-files`.split("\n")

metadata

@@ -1,38 +1,38 @@
 --- !ruby/object:Gem::Specification
 name: thread_order
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Josh Cheek
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-03-08 00:00:00.000000000 Z
+date: 2015-03-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '3.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '3.0'
 description: Test helper for ordering threaded code (does not depend on gems or stdlib,
-  tested on 1.8.7 - 2.2).
+  tested on 1.8.7 - 2.2, rbx, jruby).
 email: josh.cheek@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".gitignore"
-- ".travis.yml"
+- .gitignore
+- .travis.yml
 - Gemfile
 - License.txt
 - Readme.md
@@ -52,17 +52,17 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.5
+rubygems_version: 2.4.1
 signing_key: 
 specification_version: 4
 summary: Test helper for ordering threaded code