synctest 0.0.1

data/lib/synctest.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "monitor"
+require "timeout"
+
+require_relative "synctest/version"
+require_relative "synctest/errors"
+require_relative "synctest/raw"
+require_relative "synctest/bubble"
+require_relative "synctest/patches"
+
+# Deterministic tests for concurrent Ruby code.
+module Synctest
+  THREAD_BUBBLE_KEY = :__synctest_bubble__
+  OBJECT_BUBBLE_IVAR = :@__synctest_bubble__
+  DEFAULT_START_TIME = Time.utc(2000, 1, 1).freeze
+  DEFAULT_TIMEOUT = 5.0
+
+  class << self
+    # Runs +block+ in an isolated concurrency bubble.
+    #
+    # Threads and synchronization primitives created by the block belong to
+    # the bubble. Time is virtual and advances only when every bubble thread is
+    # durably blocked.
+    def run(start_at: DEFAULT_START_TIME, timeout: DEFAULT_TIMEOUT, &block)
+      raise ArgumentError, "Synctest.run requires a block" unless block
+      raise NestedBubbleError, "cannot start a Synctest bubble from inside another bubble" if current_bubble
+
+      if Fiber.respond_to?(:scheduler) && Fiber.scheduler
+        raise UnsupportedOperationError, "Fiber schedulers are not supported inside a Synctest bubble"
+      end
+
+      bubble = Bubble.new(start_at: start_at, timeout: timeout)
+      bubble.run(&block)
+    end
+
+    # Waits until all other threads in the current bubble have either exited
+    # or become durably blocked. Unlike sleeping, waiting never advances time.
+    def wait
+      bubble = current_bubble
+      raise NotInBubbleError, "Synctest.wait must be called from inside Synctest.run" unless bubble
+
+      bubble.wait
+    end
+
+    # Returns whether the calling thread currently belongs to a bubble.
+    def active?
+      !current_bubble.nil?
+    end
+
+    # :nodoc:
+    def current_bubble
+      Thread.current.thread_variable_get(THREAD_BUBBLE_KEY)
+    end
+
+    # :nodoc:
+    def bubble_for(object)
+      object.instance_variable_get(OBJECT_BUBBLE_IVAR)
+    end
+
+    # :nodoc:
+    def associate(object)
+      bubble = current_bubble
+      return object unless bubble
+
+      owner = bubble_for(object)
+      if owner && !owner.equal?(bubble)
+        raise IsolationError, "object already belongs to a different Synctest bubble"
+      end
+
+      object.instance_variable_set(OBJECT_BUBBLE_IVAR, bubble)
+      object
+    end
+
+    # Returns the object's bubble when access is valid, nil for an ordinary
+    # object, and raises when a bubbled object is accessed from elsewhere.
+    # :nodoc:
+    def bubble_for_operation(object)
+      owner = bubble_for(object)
+      return nil unless owner
+
+      current = current_bubble
+      unless owner.equal?(current) && owner.active?
+        raise IsolationError, "#{object.class} belongs to a different or finished Synctest bubble"
+      end
+
+      owner
+    end
+
+    # Root threads predate their bubbles and are intentionally not permanently
+    # associated with them, so thread operations also inspect live thread-local
+    # membership.
+    # :nodoc:
+    def bubble_for_thread_operation(thread)
+      owner = thread.thread_variable_get(THREAD_BUBBLE_KEY) || bubble_for(thread)
+      return nil unless owner
+
+      current = current_bubble
+      unless owner.equal?(current) && owner.active?
+        raise IsolationError, "Thread belongs to a different or finished Synctest bubble"
+      end
+
+      owner
+    end
+
+    # :nodoc:
+    def set_current_bubble(bubble)
+      Thread.current.thread_variable_set(THREAD_BUBBLE_KEY, bubble)
+    end
+  end
+
+  Patches.install!
+end

metadata

@@ -0,0 +1,135 @@
+--- !ruby/object:Gem::Specification
+name: synctest
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Alexander Baygeldin
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: nats-pure
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.5.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.5.0
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.15'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.15'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !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'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: Runs concurrent Ruby tests in isolated bubbles with tracked threads,
+  synchronization primitives, quiescence, and virtual time.
+email:
+- a.baygeldin@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/synctest.rb
+- lib/synctest/bubble.rb
+- lib/synctest/errors.rb
+- lib/synctest/patches.rb
+- lib/synctest/raw.rb
+- lib/synctest/version.rb
+homepage: https://github.com/baygeldin/synctest-rb
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/baygeldin/synctest-rb
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.4.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Deterministic concurrency testing with virtual time for Ruby.
+test_files: []