thread_order 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 9a2dabe6630ddb96b43c686369e6a50f85a1d55c
+  data.tar.gz: aa1928df61b660fec67fbd4d33eb3f8214c8aefb
+SHA512:
+  metadata.gz: b33ae8eafd3294c2f030f91e29268818eb5f1ec22f34a8e564b3731075033ba7c53dc6df07861932343e68858d3abf0d0e45a74bfdd2665e0cd6b9ebbdccbc81
+  data.tar.gz: a83df4acfce7b1d39bff123261b7ab12e0e8dc4cc35af6f973de76469873656f508360242427ea9c9f216b3d16fd4ae6056298e60d82709efc09c35bbf688c49

data/.gitignore

@@ -0,0 +1,2 @@
+*.gem
+Gemfile.lock

data/.travis.yml

@@ -0,0 +1,8 @@
+language: ruby
+script: bundle exec rspec
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - 2.1.2
+  - 2.2.0
+  - ruby-head

data/Gemfile

@@ -0,0 +1,2 @@
+source 'https://rubygems.org'
+gemspec

data/License.txt

@@ -0,0 +1,22 @@
+(The MIT License)
+
+Copyright (c) 2015 Josh Cheek
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Readme.md

@@ -0,0 +1,2 @@
+ThreadOrder
+===========

data/lib/thread_order.rb

@@ -0,0 +1,93 @@
+class ThreadOrder
+  def initialize
+    @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
+  end
+
+  def declare(name, &block)
+    @bodies[name] = block
+  end
+
+  def current
+    Thread.current[:thread_order_name]
+  end
+
+  def pass_to(name, options)
+    parent       = Thread.current
+    child        = nil
+    resume_event = extract_resume_event! options
+    resume_if    = lambda do |event|
+      return unless event == sync { resume_event }
+      parent.wakeup
+    end
+
+    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
+      end
+    end
+
+    sleep
+    child
+  end
+
+  def apocalypse!(thread_method=:kill)
+    enqueue do
+      @threads.each(&thread_method)
+      @queue.clear
+      @worker.kill
+    end
+    @worker.join
+  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 }
+    task.call
+  end
+
+  def extract_resume_event!(options)
+    resume_on = options.delete :resume_on
+    options.any? &&
+      raise(ArgumentError, "Unknown options: #{options.inspect}")
+    resume_on && ![:run, :exit, :sleep].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
+  end
+end

data/spec/thread_order_spec.rb

@@ -0,0 +1,126 @@
+require 'thread_order'
+
+RSpec.describe ThreadOrder do
+  let(:order) { described_class.new }
+  after { order.apocalypse! }
+
+  it 'allows thread behaviour to be declared and run by name' do
+    seen = []
+    order.declare(:third)  { seen << :third }
+    order.declare(:first)  { seen << :first;  order.pass_to :second, :resume_on => :exit }
+    order.declare(:second) { seen << :second; order.pass_to :third,  :resume_on => :exit }
+    expect(seen).to eq []
+    order.pass_to :first, :resume_on => :exit
+    expect(seen).to eq [:first, :second, :third]
+  end
+
+  it 'sleeps the thread which passed' do
+    main_thread = Thread.current
+    order.declare(:thread) { :noop until main_thread.status == 'sleep' }
+    order.pass_to :thread, :resume_on => :exit # passes if it doesn't lock up
+  end
+
+  context 'resume events' do
+    def self.test_status(name, statuses, *args, &threadmaker)
+      it "can resume the thread when the called thread enters #{name}", *args do
+        thread   = instance_eval(&threadmaker)
+        statuses = Array statuses
+        expect(statuses).to include thread.status
+      end
+    end
+
+    test_status ':run', 'run' do
+      order.declare(:t) { loop { 1 } }
+      order.pass_to :t, :resume_on => :run
+    end
+
+    test_status ':sleep', 'sleep' do
+      order.declare(:t) { sleep }
+      order.pass_to :t, :resume_on => :sleep
+    end
+
+    # can't reproduce 'dead', but apparently JRuby 1.7.19 returned
+    # this on CI https://travis-ci.org/rspec/rspec-core/jobs/51933739
+    test_status ':exit', [false, 'aborting', 'dead'] do
+      order.declare(:t) { Thread.exit }
+      order.pass_to :t, :resume_on => :exit
+    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
+    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 }
+      }.to raise_error Exception, 'to the rules'
+    end
+
+    specify 'even if the parent is asleep' do
+      parent = Thread.current
+      order.declare(:err) {
+        :noop until parent.status == 'sleep'
+        raise 'the roof'
+      }
+      expect {
+        order.pass_to :err, :resume_on => :run
+        sleep
+      }.to raise_error RuntimeError, 'the roof'
+    end
+  end
+
+  it 'knows which thread is running' do
+    thread_names = []
+    order.declare(:a) {
+      thread_names << order.current
+      order.pass_to :b, :resume_on => :exit
+      thread_names << order.current
+    }
+    order.declare(:b) {
+      thread_names << order.current
+    }
+    order.pass_to :a, :resume_on => :exit
+    expect(thread_names.map(&:to_s).sort).to eq ['a', 'a', 'b']
+  end
+
+  it 'returns nil when asked for the current thread by one it did not define' do
+    thread_names = []
+    order.declare(:a) {
+      thread_names << order.current
+      Thread.new { thread_names << order.current }.join
+    }
+    expect(order.current).to eq nil
+    order.pass_to :a, :resume_on => :exit
+    expect(thread_names).to eq [:a, nil]
+  end
+
+  xit 'is implemented without depending on the stdlib' do
+    loaded_filenames = $LOADED_FEATURES.map { |filepath| File.basename filepath }
+    pending 'fucking fails :('
+    expect(loaded_filenames).to_not include 'monitor.rb'
+    expect(loaded_filenames).to_not include 'thread.rb'
+    expect(loaded_filenames).to_not include 'thread.bundle'
+  end
+
+  describe 'incorrect interface usage' do
+    it 'raises ArgumentError when told to resume on an unknown status' do
+      order.declare(:t) { }
+      expect { order.pass_to :t, :resume_on => :bad_status }.
+        to raise_error(ArgumentError, /bad_status/)
+    end
+
+    it 'raises an ArgumentError when you give it unknown keys (ie you spelled resume_on wrong)' do
+      order.declare(:t) { }
+      expect { order.pass_to :t, :bad_key => :t }.
+        to raise_error(ArgumentError, /bad_key/)
+    end
+  end
+end

data/thread_order.gemspec

@@ -0,0 +1,13 @@
+Gem::Specification.new do |s|
+  s.name        = 'thread_order'
+  s.version     = '0.1.0'
+  s.licenses    = ['MIT']
+  s.summary     = "Test helper for ordering threaded code (does not depend on stdlib)"
+  s.description = "Test helper for ordering threaded code (does not depend on stdlib)."
+  s.authors     = ["Josh Cheek"]
+  s.email       = 'josh.cheek@gmail.com'
+  s.files       = `git ls-files`.split("\n")
+  s.test_files  = `git ls-files -- spec/*`.split("\n")
+  s.homepage    = 'https://github.com/JoshCheek/thread_order'
+  s.add_development_dependency 'rspec', '~> 3.0'
+end

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification
+name: thread_order
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Josh Cheek
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-02-28 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 stdlib).
+email: josh.cheek@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".travis.yml"
+- Gemfile
+- License.txt
+- Readme.md
+- lib/thread_order.rb
+- spec/thread_order_spec.rb
+- thread_order.gemspec
+homepage: https://github.com/JoshCheek/thread_order
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+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.1
+signing_key: 
+specification_version: 4
+summary: Test helper for ordering threaded code (does not depend on stdlib)
+test_files:
+- spec/thread_order_spec.rb
+has_rdoc: