synctest 0.0.1

data/lib/synctest/errors.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Synctest
+  class Error < StandardError
+  end
+
+  class NotInBubbleError < Error
+  end
+
+  class NestedBubbleError < Error
+  end
+
+  class ConcurrentWaitError < Error
+  end
+
+  class DeadlockError < Error
+  end
+
+  class StalledError < Error
+  end
+
+  class IsolationError < Error
+  end
+
+  class UnsupportedOperationError < Error
+  end
+end

data/lib/synctest/patches.rb

@@ -0,0 +1,608 @@
+# frozen_string_literal: true
+
+module Synctest
+  # Process-wide shims which dispatch to a thread-local bubble. Outside a
+  # bubble, every method immediately delegates to Ruby's original behavior.
+  module Patches
+    module KernelPatch
+      def sleep(duration = nil)
+        bubble = Synctest.current_bubble
+        return super unless bubble
+
+        bubble.sleep(duration)
+      end
+    end
+
+    module KernelSingletonPatch
+      def sleep(duration = nil)
+        bubble = Synctest.current_bubble
+        return super unless bubble
+
+        bubble.sleep(duration)
+      end
+    end
+
+    module TimeSingletonPatch
+      def now(**keywords)
+        bubble = Synctest.current_bubble
+        return super unless bubble
+        return super unless keywords.empty? || keywords.keys == [:in]
+
+        value = bubble.wall_time
+        zone = keywords[:in]
+        zone ? value.getlocal(zone) : value
+      end
+
+      def new(*arguments, **keywords)
+        bubble = Synctest.current_bubble
+        if bubble && arguments.empty? && (keywords.empty? || keywords.keys == [:in])
+          value = bubble.wall_time
+          zone = keywords[:in]
+          return zone ? value.getlocal(zone) : value
+        end
+
+        super
+      end
+    end
+
+    module ProcessSingletonPatch
+      def clock_gettime(clock_id, unit = :float_second)
+        bubble = Synctest.current_bubble
+        return super unless bubble
+
+        case clock_id
+        when Process::CLOCK_MONOTONIC
+          bubble.monotonic_time(unit)
+        when Process::CLOCK_REALTIME
+          bubble.realtime(unit)
+        else
+          super
+        end
+      end
+    end
+
+    module ThreadSingletonPatch
+      def new(*arguments, **keywords, &block)
+        bubble = Synctest.current_bubble
+        reserved = false
+        return super unless bubble && block
+
+        bubble.reserve_child
+        reserved = true
+        created = false
+        thread = super do |*block_arguments, **block_keywords|
+          Synctest.set_current_bubble(bubble)
+          bubble.attach_child(Thread.current)
+          Thread.current.report_on_exception = false
+          error = nil
+
+          begin
+            block.call(*block_arguments, **block_keywords)
+          rescue Exception => exception # rubocop:disable Lint/RescueException
+            error = exception
+            raise
+          ensure
+            bubble.child_finished(Thread.current, error)
+            Synctest.set_current_bubble(nil)
+          end
+        end
+        created = true
+        thread.instance_variable_set(Synctest::OBJECT_BUBBLE_IVAR, bubble)
+        bubble.await_child_attachment(thread)
+        thread
+      ensure
+        bubble&.cancel_child_reservation if reserved && !created
+      end
+
+      def start(*arguments, **keywords, &block)
+        return super unless Synctest.current_bubble
+
+        new(*arguments, **keywords, &block)
+      end
+
+      def fork(*arguments, **keywords, &block)
+        return super unless Synctest.current_bubble
+
+        new(*arguments, **keywords, &block)
+      end
+
+      def stop
+        bubble = Synctest.current_bubble
+        return super unless bubble
+
+        bubble.stop
+      end
+
+      def kill(thread)
+        return super unless thread.is_a?(Thread)
+
+        owner = thread.thread_variable_get(Synctest::THREAD_BUBBLE_KEY) || Synctest.bubble_for(thread)
+        return super unless owner
+
+        thread.kill
+      end
+    end
+
+    module ThreadPatch
+      def join(timeout = nil)
+        owner = Synctest.bubble_for(self)
+        bubble = owner ? Synctest.bubble_for_operation(self) : root_bubble_for_join
+        return super unless bubble
+
+        bubble.join(self, timeout)
+      end
+
+      def value
+        owner = Synctest.bubble_for(self)
+        bubble = owner ? Synctest.bubble_for_operation(self) : root_bubble_for_join
+        return super unless bubble
+        unless owner
+          if equal?(Thread.current)
+            Kernel.raise ThreadError, "Target thread must not be current thread"
+          end
+
+          Kernel.raise UnsupportedOperationError, "Thread#value cannot target the root of its own Synctest bubble"
+        end
+
+        bubble.join(self, nil)
+        Synctest::Raw::THREAD_VALUE.bind_call(self)
+      end
+
+      def wakeup
+        bubble = Synctest.bubble_for_thread_operation(self)
+        return super unless bubble
+        return self if bubble.wake_thread(self)
+
+        super
+      end
+
+      def run
+        bubble = Synctest.bubble_for_thread_operation(self)
+        return super unless bubble
+        return self if bubble.wake_thread(self)
+
+        super
+      end
+
+      def kill
+        if thread_variable_get(Synctest::THREAD_BUBBLE_KEY) || Synctest.bubble_for(self)
+          bubble = Synctest.bubble_for_thread_operation(self)
+          bubble.interrupt_thread(self)
+        end
+        super
+      end
+
+      def terminate
+        if thread_variable_get(Synctest::THREAD_BUBBLE_KEY) || Synctest.bubble_for(self)
+          bubble = Synctest.bubble_for_thread_operation(self)
+          bubble.interrupt_thread(self)
+        end
+        super
+      end
+
+      def exit
+        if thread_variable_get(Synctest::THREAD_BUBBLE_KEY) || Synctest.bubble_for(self)
+          bubble = Synctest.bubble_for_thread_operation(self)
+          bubble.interrupt_thread(self)
+        end
+        super
+      end
+
+      def raise(*arguments)
+        if thread_variable_get(Synctest::THREAD_BUBBLE_KEY) || Synctest.bubble_for(self)
+          bubble = Synctest.bubble_for_thread_operation(self)
+          bubble.interrupt_thread(self)
+        end
+        super
+      end
+
+      private
+
+      def root_bubble_for_join
+        current = Synctest.current_bubble
+        owner = thread_variable_get(Synctest::THREAD_BUBBLE_KEY)
+        return unless owner&.active?
+        return owner if owner.equal?(current)
+
+        Kernel.raise IsolationError, "Thread belongs to a different Synctest bubble" if current
+      end
+    end
+
+    module MutexPatch
+      def initialize(...)
+        super
+        Synctest.associate(self)
+      end
+
+      def lock
+        bubble = Synctest.bubble_for_operation(self)
+        return super unless bubble
+
+        bubble.mutex_lock(self)
+      end
+
+      def try_lock
+        bubble = Synctest.bubble_for_operation(self)
+        return super unless bubble
+
+        bubble.mutex_try_lock(self)
+      end
+
+      def unlock
+        bubble = Synctest.bubble_for_operation(self)
+        return super unless bubble
+
+        bubble.mutex_unlock(self)
+      end
+
+      def owned?
+        bubble = Synctest.bubble_for_operation(self)
+        return super unless bubble
+
+        bubble.mutex_owned?(self)
+      end
+
+      def synchronize
+        bubble = Synctest.bubble_for_operation(self)
+        return super unless bubble
+
+        locked = false
+        begin
+          bubble.mutex_lock(self)
+          locked = true
+          yield
+        ensure
+          bubble.mutex_unlock(self) if locked
+        end
+      end
+
+      def sleep(timeout = nil)
+        bubble = Synctest.bubble_for_operation(self)
+        return super unless bubble
+
+        bubble.mutex_sleep(self, timeout)
+      end
+    end
+
+    module ConditionVariablePatch
+      def initialize(...)
+        super
+        Synctest.associate(self)
+      end
+
+      def wait(mutex, timeout = nil)
+        bubble = Synctest.bubble_for_operation(self)
+        return super unless bubble
+        unless Synctest.bubble_for(mutex).equal?(bubble)
+          raise IsolationError, "a bubbled ConditionVariable requires a Mutex from the same bubble"
+        end
+
+        bubble.condition_wait(self, mutex, timeout)
+      end
+
+      def signal
+        bubble = Synctest.bubble_for_operation(self)
+        return super unless bubble
+
+        bubble.condition_signal(self, broadcast: false)
+      end
+
+      def broadcast
+        bubble = Synctest.bubble_for_operation(self)
+        return super unless bubble
+
+        bubble.condition_signal(self, broadcast: true)
+      end
+    end
+
+    module MonitorPatch
+      def initialize(...)
+        super
+        Synctest.associate(self)
+      end
+
+      def enter
+        bubble = Synctest.bubble_for_operation(self)
+        return super unless bubble
+
+        bubble.monitor_enter(self)
+        nil
+      end
+
+      def mon_enter
+        bubble = Synctest.bubble_for_operation(self)
+        return super unless bubble
+
+        bubble.monitor_enter(self)
+        nil
+      end
+
+      def try_enter
+        bubble = Synctest.bubble_for_operation(self)
+        return super unless bubble
+
+        bubble.monitor_try_enter(self)
+      end
+
+      def mon_try_enter
+        bubble = Synctest.bubble_for_operation(self)
+        return super unless bubble
+
+        bubble.monitor_try_enter(self)
+      end
+
+      def try_mon_enter
+        bubble = Synctest.bubble_for_operation(self)
+        return super unless bubble
+
+        bubble.monitor_try_enter(self)
+      end
+
+      def exit
+        bubble = Synctest.bubble_for_operation(self)
+        return super unless bubble
+
+        bubble.monitor_exit(self)
+        nil
+      end
+
+      def mon_exit
+        bubble = Synctest.bubble_for_operation(self)
+        return super unless bubble
+
+        bubble.monitor_exit(self)
+        nil
+      end
+
+      def mon_owned?
+        bubble = Synctest.bubble_for_operation(self)
+        return super unless bubble
+
+        bubble.monitor_owned?(self)
+      end
+
+      def synchronize
+        bubble = Synctest.bubble_for_operation(self)
+        return super unless bubble
+
+        entered = false
+        begin
+          bubble.monitor_enter(self)
+          entered = true
+          yield
+        ensure
+          bubble.monitor_exit(self) if entered
+        end
+      end
+
+      def mon_synchronize(&block)
+        bubble = Synctest.bubble_for_operation(self)
+        return super unless bubble
+
+        synchronize(&block)
+      end
+
+      def wait_for_cond(condition, timeout)
+        bubble = Synctest.bubble_for_operation(self)
+        return super unless bubble
+
+        bubble.monitor_wait(self, condition, timeout)
+      end
+    end
+
+    module QueuePatch
+      def initialize(...)
+        super
+        Synctest.associate(self)
+      end
+
+      def pop(non_block = false, timeout: nil)
+        bubble = Synctest.bubble_for_operation(self)
+        return super unless bubble
+
+        bubble.queue_pop(self, non_block, timeout)
+      end
+
+      def shift(non_block = false, timeout: nil)
+        bubble = Synctest.bubble_for_operation(self)
+        return super unless bubble
+
+        bubble.queue_pop(self, non_block, timeout)
+      end
+
+      def deq(non_block = false, timeout: nil)
+        bubble = Synctest.bubble_for_operation(self)
+        return super unless bubble
+
+        bubble.queue_pop(self, non_block, timeout)
+      end
+
+      def push(object)
+        bubble = Synctest.bubble_for_operation(self)
+        return super unless bubble
+
+        bubble.queue_push(self, object)
+      end
+
+      def enq(object)
+        bubble = Synctest.bubble_for_operation(self)
+        return super unless bubble
+
+        bubble.queue_push(self, object)
+      end
+
+      def <<(object)
+        bubble = Synctest.bubble_for_operation(self)
+        return super unless bubble
+
+        bubble.queue_push(self, object)
+      end
+
+      def close
+        bubble = Synctest.bubble_for_operation(self)
+        return super unless bubble
+
+        bubble.queue_close(self)
+      end
+
+      def clear
+        bubble = Synctest.bubble_for_operation(self)
+        return super unless bubble
+
+        bubble.queue_clear(self)
+      end
+
+      def num_waiting
+        bubble = Synctest.bubble_for_operation(self)
+        return super unless bubble
+
+        bubble.queue_num_waiting(self, super)
+      end
+    end
+
+    module SizedQueuePatch
+      def initialize(...)
+        super
+        Synctest.associate(self)
+      end
+
+      def pop(non_block = false, timeout: nil)
+        bubble = Synctest.bubble_for_operation(self)
+        return super unless bubble
+
+        bubble.queue_pop(self, non_block, timeout)
+      end
+
+      def shift(non_block = false, timeout: nil)
+        bubble = Synctest.bubble_for_operation(self)
+        return super unless bubble
+
+        bubble.queue_pop(self, non_block, timeout)
+      end
+
+      def deq(non_block = false, timeout: nil)
+        bubble = Synctest.bubble_for_operation(self)
+        return super unless bubble
+
+        bubble.queue_pop(self, non_block, timeout)
+      end
+
+      def push(object, non_block = false, timeout: nil)
+        bubble = Synctest.bubble_for_operation(self)
+        return super unless bubble
+
+        bubble.sized_queue_push(self, object, non_block, timeout)
+      end
+
+      def enq(object, non_block = false, timeout: nil)
+        bubble = Synctest.bubble_for_operation(self)
+        return super unless bubble
+
+        bubble.sized_queue_push(self, object, non_block, timeout)
+      end
+
+      def <<(object)
+        bubble = Synctest.bubble_for_operation(self)
+        return super unless bubble
+
+        bubble.sized_queue_push(self, object, false, nil)
+      end
+
+      def close
+        bubble = Synctest.bubble_for_operation(self)
+        return super unless bubble
+
+        bubble.queue_close(self)
+      end
+
+      def clear
+        bubble = Synctest.bubble_for_operation(self)
+        return super unless bubble
+
+        bubble.queue_clear(self)
+      end
+
+      def max=(maximum)
+        bubble = Synctest.bubble_for_operation(self)
+        if bubble
+          bubble.sized_queue_set_max(self, maximum)
+        else
+          super
+        end
+      end
+
+      def num_waiting
+        bubble = Synctest.bubble_for_operation(self)
+        return super unless bubble
+
+        bubble.queue_num_waiting(self, super)
+      end
+    end
+
+    module FiberSingletonPatch
+      def set_scheduler(scheduler)
+        if Synctest.current_bubble
+          raise UnsupportedOperationError, "Fiber schedulers are not supported inside a Synctest bubble"
+        end
+
+        super
+      end
+    end
+
+    module TimeoutPatch
+      def timeout(seconds, exception_class = nil, message = nil, &block)
+        bubble = Synctest.current_bubble
+        return super unless bubble
+        return block.call(seconds) if seconds.nil? || seconds.zero?
+
+        raise ArgumentError, "Timeout sec must be a non-negative number" if seconds.negative?
+
+        message ||= "execution expired"
+        if exception_class
+          Patches.run_timeout_timer(seconds, exception_class, message, &block)
+        else
+          Timeout::Error.handle_timeout(message) do |exception|
+            Patches.run_timeout_timer(seconds, exception, message, &block)
+          end
+        end
+      end
+    end
+
+    class << self
+      def install!
+        return if @installed
+
+        Kernel.prepend(KernelPatch)
+        Kernel.singleton_class.prepend(KernelSingletonPatch)
+        Time.singleton_class.prepend(TimeSingletonPatch)
+        Process.singleton_class.prepend(ProcessSingletonPatch)
+        Thread.singleton_class.prepend(ThreadSingletonPatch)
+        Thread.prepend(ThreadPatch)
+        Mutex.prepend(MutexPatch)
+        ConditionVariable.prepend(ConditionVariablePatch)
+        Monitor.prepend(MonitorPatch)
+        Queue.prepend(QueuePatch)
+        SizedQueue.prepend(SizedQueuePatch)
+        Fiber.singleton_class.prepend(FiberSingletonPatch)
+        Timeout.singleton_class.prepend(TimeoutPatch)
+        Timeout.prepend(TimeoutPatch)
+
+        @installed = true
+      end
+
+      def run_timeout_timer(seconds, exception, message)
+        target = Thread.current
+        timer = Thread.new do
+          sleep(seconds)
+          target.raise(exception, message)
+        end
+        yield(seconds)
+      ensure
+        if timer
+          timer.kill if timer.alive?
+          timer.join
+        end
+      end
+    end
+  end
+end

data/lib/synctest/raw.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Synctest
+  # Original methods captured before process-wide instrumentation is installed.
+  # Bubble internals must use these methods to avoid observing themselves.
+  module Raw
+    MUTEX_LOCK = Mutex.instance_method(:lock)
+    MUTEX_TRY_LOCK = Mutex.instance_method(:try_lock)
+    MUTEX_UNLOCK = Mutex.instance_method(:unlock)
+    MUTEX_LOCKED = Mutex.instance_method(:locked?)
+    MUTEX_OWNED = Mutex.instance_method(:owned?)
+
+    CONDITION_WAIT = ConditionVariable.instance_method(:wait)
+    CONDITION_SIGNAL = ConditionVariable.instance_method(:signal)
+    CONDITION_BROADCAST = ConditionVariable.instance_method(:broadcast)
+
+    MONITOR_ENTER = Monitor.instance_method(:enter)
+    MONITOR_TRY_ENTER = Monitor.instance_method(:try_enter)
+    MONITOR_EXIT = Monitor.instance_method(:exit)
+    MONITOR_OWNED = Monitor.instance_method(:mon_owned?)
+
+    QUEUE_POP = Queue.instance_method(:pop)
+    QUEUE_PUSH = Queue.instance_method(:push)
+    QUEUE_CLOSE = Queue.instance_method(:close)
+    QUEUE_CLOSED = Queue.instance_method(:closed?)
+    QUEUE_CLEAR = Queue.instance_method(:clear)
+    QUEUE_LENGTH = Queue.instance_method(:length)
+
+    SIZED_QUEUE_PUSH = SizedQueue.instance_method(:push)
+    SIZED_QUEUE_POP = SizedQueue.instance_method(:pop)
+    SIZED_QUEUE_CLOSE = SizedQueue.instance_method(:close)
+    SIZED_QUEUE_CLEAR = SizedQueue.instance_method(:clear)
+    SIZED_QUEUE_LENGTH = SizedQueue.instance_method(:length)
+    SIZED_QUEUE_MAX = SizedQueue.instance_method(:max)
+    SIZED_QUEUE_SET_MAX = SizedQueue.instance_method(:max=)
+
+    THREAD_JOIN = Thread.instance_method(:join)
+    THREAD_VALUE = Thread.instance_method(:value)
+    THREAD_KILL = Thread.instance_method(:kill)
+    THREAD_RAISE = Thread.instance_method(:raise)
+    THREAD_WAKEUP = Thread.instance_method(:wakeup)
+    THREAD_RUN = Thread.instance_method(:run)
+
+    CLOCK_GETTIME = Process.method(:clock_gettime)
+  end
+end

data/lib/synctest/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Synctest
+  VERSION = "0.0.1"
+end