thread_weaver 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: dd5d72da4e20257fc871fd0871efc9ebd7504cf9275bb9b176428c315c79a072
+  data.tar.gz: 6b4b129c96cc1e7f594c73c13a2147e576e404f80abd1c51d0615e84215912f1
+SHA512:
+  metadata.gz: 6b1659da15d1c1ae01f231c02926fce500d61ce2401507b18b262e5a3fc5ddecbc327d1f9866567378c40b0e92ca83606dae67f538899c9d9f38add06bbc6042
+  data.tar.gz: 07fc3d2be16a4e36b2b83fef5160c777b4b74ee891755087d722b00a294c5bcd1c072c07a9fe6357fb2e323f50d038386b53cbb1961c153a4a055ee78dc88d01

data/.github/workflows/main.yml

@@ -0,0 +1,19 @@
+name: Ruby
+
+on: [push,pull_request]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: 2.7.1
+    - name: Run the default task
+      run: |
+        gem install bundler -v 2.2.3
+        bundle install
+        bundle exec rake
+        bin/gem_smoke_test

data/.gitignore

@@ -0,0 +1,59 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+# Used by dotenv library to load environment variables.
+# .env
+
+# Ignore Byebug command history file.
+.byebug_history
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+*.bridgesupport
+build-iPhoneOS/
+build-iPhoneSimulator/
+
+## Specific to RubyMotion (use of CocoaPods):
+#
+# We recommend against adding the Pods directory to your .gitignore. However
+# you should judge for yourself, the pros and cons are mentioned at:
+# https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control
+#
+# vendor/Pods/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalization:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+Gemfile.lock
+.ruby-version
+.ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc
+
+# Used by RuboCop. Remote config files pulled in from inherit_from directive.
+# .rubocop-https?--*
+
+# rspec failure tracking
+.rspec_status

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.vscode/settings.json

@@ -0,0 +1,14 @@
+{
+    "cSpell.words": [
+        "bindir",
+        "nilable"
+    ],
+    "ruby.format": "standard",
+    "ruby.lint": {
+        "standard": {
+            "useBundler": true,
+          }
+    },
+    "ruby.useLanguageServer": true,
+    "ruby.useBundler": true
+}

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]

data/Gemfile

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in thread_weaver.gemspec
+gemspec
+
+gem "rake", "~> 13.0"
+
+gem "rspec", "~> 3.0"
+
+gem "standard"
+
+gem "sorbet", group: :development
+gem "sorbet-runtime"
+
+gem "byebug"

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Andrew Hamon
+
+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,37 @@
+# ThreadWeaver
+
+ThreadWeaver is a testing tool which can help uncover thread safety issues in code intended concurrently.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'thread_weaver'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install thread_weaver
+
+## Usage
+
+TODO: Write usage instructions here
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/thread_weaver.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "standard/rake"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :sorbet do
+  sh "bundle exec srb tc"
+end
+
+task default: %i[sorbet spec standard]

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "thread_weaver"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/gem_smoke_test

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+# See test/gem_smoke_test/README.md for more information as to the purpose of this file.
+
+cd test/gem_smoke_test
+bundle
+bundle exec ruby ./test.rb

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/examples/always_deadlocks.rb

@@ -0,0 +1,15 @@
+# This is a bit of a contrived example, but this class always deadlocks if the secondary is run
+# without eventually running the primary.
+class AlwaysDeadlocks
+  def initialize
+    @primary_has_run = false
+  end
+
+  def call(is_primary:)
+    if is_primary
+      @primary_has_run = true
+    else
+      Thread.pass until @primary_has_run
+    end
+  end
+end

data/examples/takes_a_while.rb

@@ -0,0 +1,7 @@
+# This is perfectly thread safe and "nonblocking", just kinda slow. It is used to simulate expensive
+# computations.
+class TakesAWhile
+  def call(duration_ms:)
+    sleep(duration_ms / 1000.0)
+  end
+end

data/examples/thread_safe_nonblocking_run_at_most_once.rb

@@ -0,0 +1,23 @@
+# This is a non-blocking version of ThreadSafeRunAtMostOnce. It is still thread-safe, but instead of
+# blocking while waiting for the lock, it simply does nothing. If the lock can not be immediately
+# acquired, then another thread must have acquired it which means the block already has or will soon
+# be run.
+class ThreadSafeNonblockingRunAtMostOnce
+  def initialize(&blk)
+    @blk = blk
+    @ran = false
+    @mutex = Mutex.new
+  end
+
+  def call
+    lock_acquired = @mutex.try_lock
+    if lock_acquired
+      unless @ran
+        @ran = true
+        @blk.call
+      end
+    end
+  ensure
+    @mutex.unlock if lock_acquired
+  end
+end

data/examples/thread_safe_run_at_most_once.rb

@@ -0,0 +1,19 @@
+# This is a thread-safe version of ThreadUnsafeRunAtMostOnce. It wraps the call with a mutex which
+# guarantees that the critical section is only ever run in one thread at a time, thereby making this
+# safe to use and call from multiple threads.
+class ThreadSafeRunAtMostOnce
+  def initialize(&blk)
+    @blk = blk
+    @ran = false
+    @mutex = Mutex.new
+  end
+
+  def call
+    @mutex.synchronize do
+      unless @ran
+        @ran = true
+        @blk.call
+      end
+    end
+  end
+end

data/examples/thread_unsafe_run_at_most_once.rb

@@ -0,0 +1,17 @@
+# This is a naively written routine whose intended purpose is to run the provided block at most
+# once. In a single-threaded application this should work just fine, but if an instance of this
+# class is shared among several threads who all try to invoke call on it, it will eventually fail at
+# its intended purpose and execute the provided block more than once.
+class ThreadUnsafeRunAtMostOnce
+  def initialize(&blk)
+    @blk = blk
+    @ran = false
+  end
+
+  def call
+    unless @ran
+      @ran = true
+      @blk.call
+    end
+  end
+end

data/lib/thread_weaver.rb

@@ -0,0 +1,15 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+require "timeout"
+
+module ThreadWeaver
+  class Error < StandardError; end
+  # Your code goes here...
+end
+
+require_relative "thread_weaver/controllable_thread"
+require_relative "thread_weaver/iterative_race_detector"
+require_relative "thread_weaver/thread_instruction"
+require_relative "thread_weaver/version"

data/lib/thread_weaver/controllable_thread.rb

@@ -0,0 +1,177 @@
+# typed: strict
+
+module ThreadWeaver
+  class ThreadCompletedEarlyError < Error; end
+
+  class ControllableThread < Thread
+    extend T::Sig
+
+    sig { returns(String) }
+    attr_reader :last_trace_point_summary
+
+    sig do
+      params(context: T.untyped, name: String, blk: T.proc.params(arg0: T.untyped).void).void
+    end
+    def initialize(context, name:, &blk)
+      @waiting = T.let(false, T::Boolean)
+      @execution_counter = T.let(-1, Integer)
+      @last_trace_point_summary = T.let("<no traces detected>", String)
+      @line_counts_by_class = T.let({}, T::Hash[Module, Integer])
+      @current_instruction = T.let(PauseAtThreadStart.new, ThreadInstruction)
+
+      self.name = name
+      self.report_on_exception = false
+
+      super do
+        tracer = TracePoint.new(:line, :call, :return, :b_call, :b_return, :thread_begin, :thread_end, :c_call, :c_return) { |tp|
+          current_thread = Thread.current
+          if current_thread == self
+            current_thread.handle_trace_point(tp)
+          end
+        }
+        handle_thread_start
+        tracer.enable
+        blk.call(context)
+        handle_thread_end
+      ensure
+        tracer&.disable
+      end
+
+      wait_until_next_instruction_complete
+    end
+
+    sig { void }
+    def wait_until_next_instruction_complete
+      assert_self_is_not_current_thread
+
+      do_nothing while alive? && !@waiting
+    end
+
+    sig { void }
+    def release
+      assert_self_is_not_current_thread
+
+      @waiting = false
+    end
+
+    sig { void }
+    def next
+      assert_self_is_not_current_thread
+
+      case @current_instruction
+      when PauseWhenLineCount, PauseAtSourceLine
+        set_next_instruction(
+          @current_instruction.next
+        )
+      else
+        raise "Next is only supported when paused on a #{PauseWhenLineCount.name} or a #{PauseAtSourceLine} instruction "
+      end
+    end
+
+    sig { params(instruction: ThreadInstruction).void }
+    def set_next_instruction(instruction)
+      assert_self_is_not_current_thread
+      @current_instruction = instruction
+      release
+    end
+
+    sig { params(instruction: ThreadInstruction).void }
+    def set_and_wait_for_next_instruction(instruction)
+      set_next_instruction(instruction)
+      wait_until_next_instruction_complete
+    end
+
+    sig { params(tp: TracePoint).void }
+    def handle_trace_point(tp)
+      event = T.let(tp.event, Symbol)
+      klass = T.let(tp.defined_class, T.nilable(Module))
+      path = T.let(tp.path, T.nilable(String))
+      line = T.let(tp.lineno, T.nilable(Integer))
+      method_name = T.let(tp.method_id, T.nilable(Symbol))
+
+      @last_trace_point_summary = "#{event} #{klass}##{method_name} #{path}#L#{line}"
+
+      if klass
+        current_count = @line_counts_by_class.fetch(klass, 0)
+        @line_counts_by_class[klass] = (current_count + 1)
+      end
+
+      case @current_instruction
+      when PauseAtThreadStart
+        if event == :thread_begin
+          wait_until_released
+        end
+      when ContinueToThreadEnd
+        # do nothing
+      when PauseWhenLineCount
+        current_count = @current_instruction.target_classes.map { |klass| @line_counts_by_class.fetch(klass, 0) }.sum
+        required_count = @current_instruction.count
+        if required_count == current_count
+          wait_until_released
+        end
+      when PauseAtMethodCall
+        if @current_instruction.klass == klass && @current_instruction.method_name == method_name
+          wait_until_released
+        end
+      when PauseAtMethodReturn
+        if @current_instruction.klass == klass && @current_instruction.method_name == method_name
+          wait_until_released
+        end
+      when PauseAtSourceLine
+        if path&.end_with?(@current_instruction.path_suffix) && @current_instruction.line == line
+          wait_until_released
+        end
+      else
+        T.absurd(@current_instruction)
+      end
+    end
+
+    sig { override.returns(ControllableThread) }
+    def join
+      while alive?
+        release
+        do_nothing
+      end
+      super()
+    end
+
+    private
+
+    sig { void }
+    def handle_thread_start
+      assert_self_is_current_thread
+      if @current_instruction.is_a?(PauseAtThreadStart)
+        wait_until_released
+      end
+    end
+
+    sig { void }
+    def handle_thread_end
+      assert_self_is_current_thread
+      unless @current_instruction.is_a?(ContinueToThreadEnd)
+        raise ThreadCompletedEarlyError.new("Thread #{name} completed while attempting to match instruction #{@current_instruction}")
+      end
+    end
+
+    sig { void }
+    def wait_until_released
+      @waiting = true
+      do_nothing while @waiting
+    end
+
+    sig { void }
+    def do_nothing
+      Thread.pass
+    end
+
+    sig { void }
+    def assert_self_is_current_thread
+      raise "illegal call from thread other than self" unless Thread.current == self
+    end
+
+    sig { void }
+    def assert_self_is_not_current_thread
+      raise "illegal call from self" unless Thread.current != self
+    end
+  end
+end