synctest 0.0.1

data/lib/synctest/bubble.rb

@@ -0,0 +1,1225 @@
+# frozen_string_literal: true
+
+module Synctest
+  # Coordinates the threads, clock, and synchronization objects in one run.
+  class Bubble
+    NANOSECONDS = 1_000_000_000
+    TIMEOUT = Object.new.freeze
+    CLOSED = Object.new.freeze
+    THREAD_ABORT = Class.new(Exception) # standard:disable Lint/InheritException
+    private_constant :THREAD_ABORT
+
+    ThreadState = Struct.new(:status, :blocker)
+    Blocker = Struct.new(
+      :thread,
+      :kind,
+      :resource,
+      :deadline_ns,
+      :description,
+      :ready,
+      :result,
+      :error
+    )
+
+    attr_reader :start_at
+
+    def initialize(start_at:, timeout:)
+      unless start_at.is_a?(Time)
+        raise ArgumentError, "start_at must be a Time"
+      end
+      if timeout && (!timeout.is_a?(Numeric) || timeout <= 0)
+        raise ArgumentError, "timeout must be a positive number or nil"
+      end
+
+      @start_at = start_at.dup.freeze
+      @timeout = timeout&.to_f
+      @now_ns = 0
+
+      @lock = Mutex.new
+      @condition = ConditionVariable.new
+      @states = {}.compare_by_identity
+      @children = {}.compare_by_identity
+      @resource_waiters = {}.compare_by_identity
+      @mutex_owners = {}.compare_by_identity
+      @monitor_owners = {}.compare_by_identity
+      @grants = {}.compare_by_identity
+      @queue_grants = {}.compare_by_identity
+
+      @pending_children = 0
+      @root = nil
+      @root_active = false
+      @active_waiter = nil
+      @background_errors = {}.compare_by_identity
+      @observed_error_threads = {}.compare_by_identity
+      @fatal = nil
+      @aborting = false
+      @active = false
+      @progress_sequence = 0
+    end
+
+    def active?
+      @active
+    end
+
+    def run
+      @root = Thread.current
+      @active = true
+      with_lock do
+        @root_active = true
+        @states[@root] = state(:running)
+      end
+      Synctest.set_current_bubble(self)
+
+      result = nil
+      error = nil
+
+      begin
+        result = yield
+      rescue Exception => exception # rubocop:disable Lint/RescueException
+        error = exception
+      ensure
+        root_returned
+
+        begin
+          error ? abort_and_join : finish
+        rescue Exception => finish_error # rubocop:disable Lint/RescueException
+          error = finish_error if error.nil? || finish_error.is_a?(StalledError)
+        ensure
+          @active = false
+          Synctest.set_current_bubble(nil)
+          release_references
+        end
+      end
+
+      raise error if error
+
+      result
+    end
+
+    def wall_time
+      nanoseconds = with_lock { @now_ns }
+      @start_at + Rational(nanoseconds, NANOSECONDS)
+    end
+
+    def monotonic_time(unit = :float_second)
+      nanoseconds = with_lock { @now_ns }
+      convert_nanoseconds(nanoseconds, unit)
+    end
+
+    def realtime(unit = :float_second)
+      nanoseconds = (@start_at.to_r * NANOSECONDS).to_i + with_lock { @now_ns }
+      convert_nanoseconds(nanoseconds, unit)
+    end
+
+    def sleep(duration = nil)
+      start_ns = with_lock { @now_ns }
+      deadline = duration.nil? ? nil : start_ns + duration_to_nanoseconds(duration)
+      blocker = register_blocker(
+        kind: :sleep,
+        resource: Thread.current,
+        deadline_ns: deadline,
+        description: duration.nil? ? "sleep forever" : "sleep until #{format_deadline(deadline)}"
+      )
+      await(blocker)
+      Rational(with_lock { @now_ns } - start_ns, NANOSECONDS).round
+    end
+
+    def stop
+      blocker = register_blocker(
+        kind: :stop,
+        resource: Thread.current,
+        description: "Thread.stop"
+      )
+      await(blocker)
+      nil
+    end
+
+    def wake_thread(thread)
+      with_lock do
+        blocker = @states[thread]&.blocker
+        return false unless blocker && %i[sleep stop mutex_sleep].include?(blocker.kind)
+
+        wake_blocker_locked(blocker, result: true)
+        reconcile_locked
+        true
+      end
+    end
+
+    def interrupt_thread(thread)
+      with_lock do
+        current = @states[thread]
+        if current && %i[blocked waiting].include?(current.status)
+          @states[thread] = state(:runnable, current.blocker)
+          signal_locked
+        end
+      end
+    end
+
+    def wait
+      thread = Thread.current
+      blocker = with_lock do
+        if @active_waiter
+          raise ConcurrentWaitError, "only one Synctest.wait may be active in a bubble"
+        end
+
+        @active_waiter = thread
+        register_blocker_locked(
+          thread: thread,
+          kind: :wait,
+          description: "Synctest.wait",
+          status: :waiting
+        )
+      end
+
+      await(blocker)
+      raise_background_error
+      nil
+    ensure
+      with_lock { @active_waiter = nil if @active_waiter.equal?(thread) } if thread
+    end
+
+    # Thread lifecycle -----------------------------------------------------
+
+    def reserve_child
+      with_lock do
+        raise Error, "cannot create a thread in a finished Synctest bubble" unless @active && !@aborting
+
+        @pending_children += 1
+        signal_locked
+      end
+    end
+
+    def cancel_child_reservation
+      with_lock do
+        @pending_children -= 1
+        signal_locked
+        reconcile_locked
+      end
+    end
+
+    def attach_child(thread)
+      thread.instance_variable_set(Synctest::OBJECT_BUBBLE_IVAR, self)
+      with_lock do
+        @pending_children -= 1
+        @children[thread] = true
+        @states[thread] = state(:running)
+        signal_locked
+        reconcile_locked
+      end
+    end
+
+    # Thread.new returns before the new thread is guaranteed to have executed
+    # any Ruby code. Do not hand the Thread object to user code until its
+    # reservation has become a real member, or an immediate Thread#kill could
+    # strand a pending reservation forever.
+    def await_child_attachment(thread)
+      with_lock do
+        until @states.key?(thread)
+          unless thread.alive?
+            @pending_children -= 1
+            raise Error, "child thread exited before joining its Synctest bubble"
+          end
+
+          Raw::CONDITION_WAIT.bind_call(@condition, @lock, 0.01)
+        end
+      end
+    end
+
+    def child_finished(thread, error)
+      with_lock do
+        @background_errors[thread] = error if error && !@aborting
+        current = @states[thread]
+        @states[thread] = state(:exited)
+        remove_blocker_locked(current.blocker) if current&.blocker
+        release_owned_resources_locked(thread)
+        wake_resource_locked(thread, kinds: [:join], result: thread, all: true)
+        signal_locked
+        reconcile_locked unless @fatal
+      end
+    end
+
+    def join(thread, timeout)
+      raise ThreadError, "Target thread must not be current thread" if thread.equal?(Thread.current)
+
+      deadline = timeout.nil? ? nil : with_lock { @now_ns } + timeout_to_nanoseconds(timeout)
+      blocker = with_lock do
+        unless thread_finished_locked?(thread)
+          register_blocker_locked(
+            thread: Thread.current,
+            kind: :join,
+            resource: thread,
+            deadline_ns: deadline,
+            description: "join #{thread_label(thread)}"
+          )
+        end
+      end
+
+      result = blocker && await(blocker)
+      return nil if result.equal?(TIMEOUT)
+
+      raise_join_error(thread)
+      thread
+    end
+
+    # Mutex ---------------------------------------------------------------
+
+    def mutex_lock(mutex)
+      thread = Thread.current
+      with_lock do
+        loop do
+          owner = @mutex_owners[mutex]
+          raise ThreadError, "deadlock; recursive locking" if owner.equal?(thread)
+
+          granted = @grants[mutex]
+          if (!granted || granted.equal?(thread)) && Raw::MUTEX_TRY_LOCK.bind_call(mutex)
+            @grants.delete(mutex)
+            @mutex_owners[mutex] = thread
+            return mutex
+          end
+
+          blocker = register_blocker_locked(
+            thread: thread,
+            kind: :mutex_lock,
+            resource: mutex,
+            description: "Mutex#lock"
+          )
+          await_locked(blocker)
+        end
+      end
+    end
+
+    def mutex_try_lock(mutex)
+      thread = Thread.current
+      with_lock do
+        return false if @mutex_owners[mutex].equal?(thread)
+
+        granted = @grants[mutex]
+        return false if granted && !granted.equal?(thread)
+        return false unless Raw::MUTEX_TRY_LOCK.bind_call(mutex)
+
+        @grants.delete(mutex)
+        @mutex_owners[mutex] = thread
+        true
+      end
+    end
+
+    def mutex_unlock(mutex)
+      with_lock do
+        release_mutex_locked(mutex, Thread.current)
+        reconcile_locked
+      end
+      mutex
+    end
+
+    def mutex_owned?(mutex)
+      with_lock { @mutex_owners[mutex].equal?(Thread.current) }
+    end
+
+    def mutex_sleep(mutex, timeout)
+      released = false
+      start_ns = with_lock do
+        release_mutex_locked(mutex, Thread.current)
+        released = true
+        @now_ns
+      end
+
+      deadline = timeout.nil? ? nil : start_ns + duration_to_nanoseconds(timeout)
+      blocker = register_blocker(
+        kind: :mutex_sleep,
+        resource: Thread.current,
+        deadline_ns: deadline,
+        description: timeout.nil? ? "Mutex#sleep" : "Mutex#sleep until #{format_deadline(deadline)}"
+      )
+      await(blocker)
+      nil
+    ensure
+      mutex_lock(mutex) if released && !aborting?
+    end
+
+    # ConditionVariable ---------------------------------------------------
+
+    def condition_wait(condition, mutex, timeout)
+      blocker = nil
+      released = false
+
+      with_lock do
+        release_mutex_locked(mutex, Thread.current)
+        released = true
+        deadline = timeout.nil? ? nil : @now_ns + duration_to_nanoseconds(timeout)
+        blocker = register_blocker_locked(
+          thread: Thread.current,
+          kind: :condition,
+          resource: condition,
+          deadline_ns: deadline,
+          description: timeout.nil? ? "ConditionVariable#wait" : "ConditionVariable#wait until #{format_deadline(deadline)}"
+        )
+      end
+
+      result = await(blocker)
+      result.equal?(TIMEOUT) ? nil : 0
+    ensure
+      mutex_lock(mutex) if released && !aborting?
+    end
+
+    def condition_signal(condition, broadcast:)
+      with_lock do
+        wake_resource_locked(
+          condition,
+          kinds: [:condition],
+          result: true,
+          all: broadcast
+        )
+        reconcile_locked
+      end
+      condition
+    end
+
+    # Monitor -------------------------------------------------------------
+
+    def monitor_enter(monitor)
+      thread = Thread.current
+      with_lock do
+        loop do
+          owner, depth = @monitor_owners[monitor]
+          if owner.equal?(thread)
+            Raw::MONITOR_ENTER.bind_call(monitor)
+            @monitor_owners[monitor] = [thread, depth + 1]
+            return monitor
+          end
+
+          granted = @grants[monitor]
+          if (!granted || granted.equal?(thread)) && Raw::MONITOR_TRY_ENTER.bind_call(monitor)
+            @grants.delete(monitor)
+            @monitor_owners[monitor] = [thread, 1]
+            return monitor
+          end
+
+          blocker = register_blocker_locked(
+            thread: thread,
+            kind: :monitor_lock,
+            resource: monitor,
+            description: "Monitor#enter"
+          )
+          await_locked(blocker)
+        end
+      end
+    end
+
+    def monitor_try_enter(monitor)
+      thread = Thread.current
+      with_lock do
+        owner, depth = @monitor_owners[monitor]
+        if owner.equal?(thread)
+          Raw::MONITOR_ENTER.bind_call(monitor)
+          @monitor_owners[monitor] = [thread, depth + 1]
+          return true
+        end
+
+        granted = @grants[monitor]
+        return false if granted && !granted.equal?(thread)
+        return false unless Raw::MONITOR_TRY_ENTER.bind_call(monitor)
+
+        @grants.delete(monitor)
+        @monitor_owners[monitor] = [thread, 1]
+        true
+      end
+    end
+
+    def monitor_exit(monitor)
+      with_lock do
+        release_monitor_locked(monitor, Thread.current)
+        reconcile_locked
+      end
+      monitor
+    end
+
+    def monitor_owned?(monitor)
+      with_lock { @monitor_owners[monitor]&.first.equal?(Thread.current) }
+    end
+
+    def monitor_wait(monitor, condition, timeout)
+      depth = nil
+      blocker = nil
+
+      with_lock do
+        owner, depth = @monitor_owners[monitor]
+        raise ThreadError, "current thread not owner" unless owner.equal?(Thread.current)
+
+        depth.times { Raw::MONITOR_EXIT.bind_call(monitor) }
+        @monitor_owners.delete(monitor)
+        grant_next_locked(monitor, :monitor_lock)
+
+        deadline = timeout.nil? ? nil : @now_ns + duration_to_nanoseconds(timeout)
+        blocker = register_blocker_locked(
+          thread: Thread.current,
+          kind: :condition,
+          resource: condition,
+          deadline_ns: deadline,
+          description: timeout.nil? ? "Monitor condition wait" : "Monitor condition wait until #{format_deadline(deadline)}"
+        )
+      end
+
+      result = await(blocker)
+      !result.equal?(TIMEOUT)
+    ensure
+      depth&.times { monitor_enter(monitor) } unless aborting?
+    end
+
+    # Queue ---------------------------------------------------------------
+
+    def queue_pop(queue, non_block, timeout)
+      if non_block && !timeout.nil?
+        raise ArgumentError, "can't set a timeout if non_block is enabled"
+      end
+
+      with_lock do
+        loop do
+          grant = queue_grants_for_locked(queue)
+          begin
+            item = raw_queue_pop(queue, true)
+            if grant&.thread&.equal?(Thread.current)
+              consume_queue_grant_locked(queue, grant) if grant
+            elsif grant && raw_queue_length(queue).zero?
+              @queue_grants.delete(queue)
+              settle_queue_waiters_locked(queue)
+            end
+            fill_sized_queue_locked(queue) if queue.is_a?(SizedQueue)
+            reconcile_locked
+            return item
+          rescue ThreadError
+            consume_queue_grant_locked(queue, grant) if grant&.thread&.equal?(Thread.current)
+            return nil if Raw::QUEUE_CLOSED.bind_call(queue)
+            raise if non_block
+          end
+
+          deadline = timeout.nil? ? nil : @now_ns + timeout_to_nanoseconds(timeout)
+          blocker = register_blocker_locked(
+            thread: Thread.current,
+            kind: :queue_pop,
+            resource: queue,
+            deadline_ns: deadline,
+            description: timeout.nil? ? "Queue#pop" : "Queue#pop until #{format_deadline(deadline)}"
+          )
+          result = await_locked(blocker)
+          return nil if result.equal?(TIMEOUT) || result.equal?(CLOSED)
+        end
+      end
+    end
+
+    def queue_push(queue, item)
+      with_lock do
+        raise ClosedQueueError, "queue closed" if Raw::QUEUE_CLOSED.bind_call(queue)
+
+        Raw::QUEUE_PUSH.bind_call(queue, item)
+        grant_queued_item_locked(queue)
+        reconcile_locked
+      end
+      queue
+    end
+
+    def sized_queue_push(queue, item, non_block, timeout)
+      if non_block && !timeout.nil?
+        raise ArgumentError, "can't set a timeout if non_block is enabled"
+      end
+
+      blocker = with_lock do
+        raise ClosedQueueError, "queue closed" if Raw::QUEUE_CLOSED.bind_call(queue)
+
+        begin
+          Raw::SIZED_QUEUE_PUSH.bind_call(queue, item, true)
+          grant_queued_item_locked(queue)
+          reconcile_locked
+          return queue
+        rescue ThreadError
+          raise if non_block
+        end
+
+        deadline = timeout.nil? ? nil : @now_ns + timeout_to_nanoseconds(timeout)
+        register_blocker_locked(
+          thread: Thread.current,
+          kind: :queue_push,
+          resource: queue,
+          deadline_ns: deadline,
+          description: timeout.nil? ? "SizedQueue#push" : "SizedQueue#push until #{format_deadline(deadline)}",
+          result: item
+        )
+      end
+
+      result = await(blocker)
+      result.equal?(TIMEOUT) ? nil : queue
+    end
+
+    def queue_close(queue)
+      with_lock do
+        raw_queue_close(queue)
+        waiters_for_locked(queue).dup.each do |waiter|
+          case waiter.kind
+          when :queue_pop
+            settle_queue_waiters_locked(queue)
+          when :queue_push
+            wake_blocker_locked(waiter, error: ClosedQueueError.new("queue closed"))
+          end
+        end
+        reconcile_locked
+      end
+      queue
+    end
+
+    def queue_clear(queue)
+      with_lock do
+        raw_queue_clear(queue)
+        @queue_grants.delete(queue)
+        fill_sized_queue_locked(queue) if queue.is_a?(SizedQueue)
+        settle_queue_waiters_locked(queue)
+        reconcile_locked
+      end
+      queue
+    end
+
+    def sized_queue_set_max(queue, maximum)
+      with_lock do
+        result = Raw::SIZED_QUEUE_SET_MAX.bind_call(queue, maximum)
+        fill_sized_queue_locked(queue)
+        reconcile_locked
+        result
+      end
+    end
+
+    def queue_num_waiting(queue, native_count)
+      with_lock do
+        native_count + waiters_for_locked(queue).count { |waiter| !waiter.ready }
+      end
+    end
+
+    # Diagnostics and utilities ------------------------------------------
+
+    def duration_to_nanoseconds(duration)
+      interval_to_nanoseconds(duration, negative_as_zero: false)
+    end
+
+    def timeout_to_nanoseconds(timeout)
+      interval_to_nanoseconds(timeout, negative_as_zero: true)
+    end
+
+    def diagnostics
+      with_lock { diagnostics_locked }
+    end
+
+    private
+
+    def state(status, blocker = nil)
+      ThreadState.new(status:, blocker:)
+    end
+
+    def blocker(thread:, kind:, description:, resource: nil, deadline_ns: nil, ready: false, result: nil, error: nil)
+      Blocker.new(
+        thread:,
+        kind:,
+        resource:,
+        deadline_ns:,
+        description:,
+        ready:,
+        result:,
+        error:
+      )
+    end
+
+    def with_lock
+      Raw::MUTEX_LOCK.bind_call(@lock)
+      yield
+    ensure
+      Raw::MUTEX_UNLOCK.bind_call(@lock) if Raw::MUTEX_OWNED.bind_call(@lock)
+    end
+
+    def register_blocker(kind:, description:, resource: nil, deadline_ns: nil, result: nil)
+      with_lock do
+        register_blocker_locked(
+          thread: Thread.current,
+          kind:,
+          resource:,
+          deadline_ns:,
+          description:,
+          result:
+        )
+      end
+    end
+
+    def register_blocker_locked(thread:, kind:, description:, status: :blocked, resource: nil, deadline_ns: nil, result: nil)
+      item = blocker(
+        thread:,
+        kind:,
+        resource:,
+        deadline_ns:,
+        description:,
+        result:
+      )
+      @states[thread] = state(status, item)
+      waiters_for_locked(resource) << item if resource
+      signal_locked
+      if @fatal
+        wake_blocker_locked(item, error: @fatal)
+      elsif deadline_ns && deadline_ns <= @now_ns
+        wake_blocker_locked(item, result: TIMEOUT)
+      else
+        reconcile_locked
+      end
+      item
+    end
+
+    def await(item)
+      with_lock { await_locked(item) }
+    end
+
+    def await_locked(item)
+      real_deadline = @timeout && real_monotonic + @timeout
+      observed_progress = @progress_sequence
+      failed = true
+
+      begin
+        until item.ready
+          if real_deadline
+            remaining = real_deadline - real_monotonic
+            if remaining <= 0
+              fail_locked(StalledError.new(stalled_message_locked(item)))
+              next
+            end
+            Raw::CONDITION_WAIT.bind_call(@condition, @lock, remaining)
+          else
+            Raw::CONDITION_WAIT.bind_call(@condition, @lock)
+          end
+          current = @states[item.thread]
+          if !item.ready && current&.status == :runnable
+            @states[item.thread] = state(:blocked, item)
+            signal_locked
+          end
+          if real_deadline && @progress_sequence != observed_progress
+            real_deadline = real_monotonic + @timeout
+            observed_progress = @progress_sequence
+          end
+          reconcile_locked unless @fatal
+        end
+
+        raise item.error if item.error
+
+        failed = false
+        item.result
+      ensure
+        remove_blocker_locked(
+          item,
+          abandon_grant: failed || !item.ready || item.error
+        )
+        current = @states[item.thread]
+        @states[item.thread] = state(:running) if current && current.status != :exited
+        @active_waiter = nil if item.kind == :wait && @active_waiter.equal?(item.thread)
+        signal_locked
+      end
+    end
+
+    def reconcile_locked
+      return if @aborting || @fatal
+
+      if @active_waiter
+        waiter = @states[@active_waiter]&.blocker
+        if waiter && wait_quiescent_locked?(@active_waiter)
+          wake_blocker_locked(waiter, result: true)
+          return
+        end
+      end
+
+      return unless all_threads_durable_locked?
+
+      deadline = next_deadline_locked
+      if @root_active && deadline
+        @now_ns = deadline if deadline > @now_ns
+        due = blockers_locked.select { |item| item.deadline_ns && item.deadline_ns <= @now_ns }
+        due.each { |item| wake_blocker_locked(item, result: TIMEOUT) }
+        signal_locked
+      elsif active_thread_count_locked.positive?
+        error = unobserved_background_error_locked || DeadlockError.new(deadlock_message_locked)
+        fail_locked(error)
+      end
+    end
+
+    def wait_quiescent_locked?(waiter_thread)
+      return false unless @pending_children.zero?
+
+      @states.all? do |thread, thread_state|
+        thread.equal?(waiter_thread) ||
+          thread_state.status == :exited ||
+          thread_state.status == :blocked
+      end
+    end
+
+    def all_threads_durable_locked?
+      return false unless @pending_children.zero?
+      return false if active_thread_count_locked.zero?
+
+      @states.values.all? { |thread_state| %i[blocked waiting exited].include?(thread_state.status) }
+    end
+
+    def active_thread_count_locked
+      @states.values.count { |thread_state| thread_state.status != :exited } + @pending_children
+    end
+
+    def blockers_locked
+      @states.values.filter_map(&:blocker).reject(&:ready)
+    end
+
+    def next_deadline_locked
+      blockers_locked.filter_map(&:deadline_ns).min
+    end
+
+    def wake_blocker_locked(item, result: nil, error: nil)
+      return if item.ready
+
+      item.ready = true
+      item.result = result
+      item.error = error
+      current = @states[item.thread]
+      @states[item.thread] = state(:runnable, item) if current && current.status != :exited
+      signal_locked
+    end
+
+    def remove_blocker_locked(item, abandon_grant: true)
+      return unless item
+
+      if item.resource
+        waiters = @resource_waiters[item.resource]
+        waiters&.delete(item)
+        @resource_waiters.delete(item.resource) if waiters && waiters.empty?
+      end
+
+      if abandon_grant &&
+          @grants[item.resource].equal?(item.thread) &&
+          %i[mutex_lock monitor_lock].include?(item.kind)
+        @grants.delete(item.resource)
+        grant_next_locked(item.resource, item.kind)
+      end
+
+      abandon_queue_grant_locked(item) if abandon_grant && item.kind == :queue_pop
+    end
+
+    def waiters_for_locked(resource)
+      @resource_waiters[resource] ||= []
+    end
+
+    def first_waiter_locked(resource, *kinds)
+      @resource_waiters[resource]&.find { |item| !item.ready && kinds.include?(item.kind) }
+    end
+
+    def wake_resource_locked(resource, kinds:, result: nil, error: nil, all: false)
+      selected = Array(@resource_waiters[resource]).select { |item| !item.ready && kinds.include?(item.kind) }
+      selected = selected.first(1) unless all
+      selected.each { |item| wake_blocker_locked(item, result:, error:) }
+      selected
+    end
+
+    def grant_next_locked(resource, kind)
+      waiter = first_waiter_locked(resource, kind)
+      return unless waiter
+
+      @grants[resource] = waiter.thread
+      wake_blocker_locked(waiter, result: true)
+    end
+
+    def release_mutex_locked(mutex, thread)
+      unless @mutex_owners[mutex].equal?(thread)
+        raise ThreadError, "Attempt to unlock a mutex which is not locked by current thread"
+      end
+
+      Raw::MUTEX_UNLOCK.bind_call(mutex)
+      @mutex_owners.delete(mutex)
+      grant_next_locked(mutex, :mutex_lock)
+    end
+
+    def release_monitor_locked(monitor, thread)
+      owner, depth = @monitor_owners[monitor]
+      raise ThreadError, "current thread not owner" unless owner.equal?(thread)
+
+      Raw::MONITOR_EXIT.bind_call(monitor)
+      if depth == 1
+        @monitor_owners.delete(monitor)
+        grant_next_locked(monitor, :monitor_lock)
+      else
+        @monitor_owners[monitor] = [thread, depth - 1]
+      end
+    end
+
+    def fill_sized_queue_locked(queue)
+      loop do
+        waiter = first_waiter_locked(queue, :queue_push)
+        break unless waiter
+        break if Raw::QUEUE_CLOSED.bind_call(queue)
+
+        begin
+          Raw::SIZED_QUEUE_PUSH.bind_call(queue, waiter.result, true)
+          wake_blocker_locked(waiter, result: true)
+          grant_queued_item_locked(queue)
+        rescue ThreadError
+          break
+        end
+      end
+    end
+
+    def queue_grants_for_locked(queue)
+      @queue_grants[queue]
+    end
+
+    def grant_queued_item_locked(queue)
+      return if @queue_grants.key?(queue)
+      return unless raw_queue_length(queue).positive?
+
+      waiter = first_waiter_locked(queue, :queue_pop)
+      return unless waiter
+
+      @queue_grants[queue] = waiter
+      wake_blocker_locked(waiter, result: true)
+    end
+
+    def consume_queue_grant_locked(queue, grant)
+      return unless grant && @queue_grants[queue].equal?(grant)
+
+      @queue_grants.delete(queue)
+      settle_queue_waiters_locked(queue)
+    end
+
+    def abandon_queue_grant_locked(item)
+      queue = item.resource
+      return unless @queue_grants[queue].equal?(item)
+
+      @queue_grants.delete(queue)
+      settle_queue_waiters_locked(queue)
+    end
+
+    def settle_queue_waiters_locked(queue)
+      if raw_queue_length(queue).positive?
+        grant_queued_item_locked(queue)
+      elsif Raw::QUEUE_CLOSED.bind_call(queue)
+        wake_resource_locked(queue, kinds: [:queue_pop], result: CLOSED, all: true)
+      end
+    end
+
+    def raw_queue_pop(queue, non_block)
+      method = queue.is_a?(SizedQueue) ? Raw::SIZED_QUEUE_POP : Raw::QUEUE_POP
+      method.bind_call(queue, non_block)
+    end
+
+    def raw_queue_close(queue)
+      method = queue.is_a?(SizedQueue) ? Raw::SIZED_QUEUE_CLOSE : Raw::QUEUE_CLOSE
+      method.bind_call(queue)
+    end
+
+    def raw_queue_clear(queue)
+      method = queue.is_a?(SizedQueue) ? Raw::SIZED_QUEUE_CLEAR : Raw::QUEUE_CLEAR
+      method.bind_call(queue)
+    end
+
+    def raw_queue_length(queue)
+      method = queue.is_a?(SizedQueue) ? Raw::SIZED_QUEUE_LENGTH : Raw::QUEUE_LENGTH
+      method.bind_call(queue)
+    end
+
+    def release_owned_resources_locked(thread)
+      @queue_grants.keys.each do |queue|
+        item = @queue_grants[queue]
+        abandon_queue_grant_locked(item) if item.thread.equal?(thread)
+      end
+
+      @grants.keys.each do |resource|
+        next unless @grants[resource].equal?(thread)
+
+        kind = resource.is_a?(Monitor) ? :monitor_lock : :mutex_lock
+        @grants.delete(resource)
+        grant_next_locked(resource, kind)
+      end
+
+      @mutex_owners.keys.each do |mutex|
+        next unless @mutex_owners[mutex].equal?(thread)
+
+        begin
+          Raw::MUTEX_UNLOCK.bind_call(mutex)
+        rescue ThreadError
+          # The VM already released it while unwinding.
+        end
+        @mutex_owners.delete(mutex)
+        grant_next_locked(mutex, :mutex_lock)
+      end
+
+      @monitor_owners.keys.each do |monitor|
+        owner, depth = @monitor_owners[monitor]
+        next unless owner.equal?(thread)
+
+        depth.times do
+          Raw::MONITOR_EXIT.bind_call(monitor)
+        rescue ThreadError
+          break
+        end
+        @monitor_owners.delete(monitor)
+        grant_next_locked(monitor, :monitor_lock)
+      end
+    end
+
+    def thread_finished_locked?(thread)
+      @states[thread]&.status == :exited || !thread.alive?
+    end
+
+    def root_returned
+      with_lock do
+        @root_active = false
+        @states[@root] = state(:exited)
+        wake_resource_locked(@root, kinds: [:join], result: @root, all: true)
+        signal_locked
+      end
+    end
+
+    def finish
+      real_deadline = @timeout && real_monotonic + @timeout
+      observed_progress = with_lock { @progress_sequence }
+
+      loop do
+        done = with_lock do
+          reconcile_locked unless @fatal
+          break true if @pending_children.zero? && children_finished_locked?
+          break true if @fatal
+
+          if real_deadline
+            remaining = real_deadline - real_monotonic
+            if remaining <= 0
+              fail_locked(StalledError.new(stalled_finish_message_locked))
+              break true
+            end
+            Raw::CONDITION_WAIT.bind_call(@condition, @lock, remaining)
+          else
+            Raw::CONDITION_WAIT.bind_call(@condition, @lock)
+          end
+          if real_deadline && @progress_sequence != observed_progress
+            real_deadline = real_monotonic + @timeout
+            observed_progress = @progress_sequence
+          end
+          false
+        end
+        break if done
+      end
+
+      error = with_lock { @fatal || unobserved_background_error_locked }
+      abort_and_join if error
+      join_finished_children
+      raise error if error
+    end
+
+    def children_finished_locked?
+      @children.keys.all? { |thread| @states[thread]&.status == :exited }
+    end
+
+    def abort_and_join
+      children = with_lock do
+        @aborting = true
+        blockers_locked.each do |item|
+          wake_blocker_locked(item, error: @fatal || Error.new("Synctest bubble aborted"))
+        end
+        signal_locked
+        @children.keys
+      end
+
+      children.each do |thread|
+        next unless thread.alive?
+
+        Raw::THREAD_KILL.bind_call(thread)
+      rescue ThreadError
+        nil
+      end
+
+      join_until(children, [@timeout || 0.5, 0.5].min)
+      survivors = children.select(&:alive?)
+      survivors.each do |thread|
+        Raw::THREAD_RAISE.bind_call(thread, THREAD_ABORT, "Synctest bubble aborted")
+      rescue ThreadError
+        nil
+      end
+      join_until(survivors, 0.5)
+
+      survivors.select!(&:alive?)
+      return if survivors.empty?
+
+      labels = survivors.map { |thread| thread_label(thread) }.join(", ")
+      raise StalledError, "Synctest could not terminate bubble threads after abort: #{labels}"
+    ensure
+      @active = false
+    end
+
+    def join_until(threads, timeout)
+      deadline = real_monotonic + timeout
+      threads.each do |thread|
+        next unless thread.alive?
+
+        remaining = deadline - real_monotonic
+        break unless remaining.positive?
+
+        Raw::THREAD_JOIN.bind_call(thread, remaining)
+      rescue Exception # rubocop:disable Lint/RescueException
+        nil
+      end
+    end
+
+    def join_finished_children
+      @children.each_key do |thread|
+        Raw::THREAD_JOIN.bind_call(thread)
+      rescue
+        # A child exception is reported through @background_errors.
+      end
+    end
+
+    def fail_locked(error)
+      @fatal ||= error
+      blockers_locked.each { |item| wake_blocker_locked(item, error: @fatal) }
+      signal_locked
+    end
+
+    def raise_background_error
+      error = with_lock do
+        source, background_error = unobserved_background_error_pair_locked
+        if @fatal && (!source || !@fatal.equal?(background_error))
+          @fatal
+        elsif source
+          observe_thread_error_locked(source)
+        end
+      end
+      raise error if error
+    end
+
+    def raise_join_error(thread)
+      error = with_lock { observe_thread_error_locked(thread) }
+      raise error if error
+    end
+
+    def observe_thread_error_locked(thread)
+      error = @background_errors[thread]
+      return unless error
+
+      @observed_error_threads[thread] = true
+      if @fatal.equal?(error)
+        _source, @fatal = unobserved_background_error_pair_locked
+      end
+      error
+    end
+
+    def unobserved_background_error_locked
+      unobserved_background_error_pair_locked&.last
+    end
+
+    def unobserved_background_error_pair_locked
+      @background_errors.find { |thread, _error| !@observed_error_threads.key?(thread) }
+    end
+
+    def interval_to_nanoseconds(value, negative_as_zero:)
+      unless value.is_a?(Numeric) && !value.is_a?(Complex)
+        raise TypeError, "can't convert #{value.class} into time interval"
+      end
+
+      number = value.to_f
+      unless number.finite?
+        label = number.nan? ? "NaN" : "Inf"
+        raise RangeError, "#{label} out of Time range"
+      end
+      if number.negative?
+        return 0 if negative_as_zero
+
+        raise ArgumentError, "time interval must not be negative"
+      end
+
+      rational = value.is_a?(Float) ? value.to_s.to_r : value.to_r
+      (rational * NANOSECONDS).ceil
+    rescue NoMethodError
+      raise TypeError, "can't convert #{value.class} into time interval"
+    end
+
+    def release_references
+      with_lock do
+        return if @children.each_key.any?(&:alive?)
+
+        @states.clear
+        @children.clear
+        @resource_waiters.clear
+        @mutex_owners.clear
+        @monitor_owners.clear
+        @grants.clear
+        @queue_grants.clear
+        @background_errors.clear
+        @observed_error_threads.clear
+        @root = nil
+        @active_waiter = nil
+      end
+    end
+
+    def aborting?
+      with_lock { @aborting }
+    end
+
+    def real_monotonic
+      Raw::CLOCK_GETTIME.call(Process::CLOCK_MONOTONIC)
+    end
+
+    def convert_nanoseconds(nanoseconds, unit)
+      case unit
+      when :nanosecond
+        nanoseconds
+      when :microsecond
+        nanoseconds / 1_000
+      when :millisecond
+        nanoseconds / 1_000_000
+      when :second
+        nanoseconds / NANOSECONDS
+      when :float_microsecond
+        nanoseconds.fdiv(1_000)
+      when :float_millisecond
+        nanoseconds.fdiv(1_000_000)
+      when :float_second
+        nanoseconds.fdiv(NANOSECONDS)
+      else
+        raise ArgumentError, "unexpected unit: #{unit}"
+      end
+    end
+
+    def format_deadline(nanoseconds)
+      "#{nanoseconds.fdiv(NANOSECONDS)}s"
+    end
+
+    def deadlock_message_locked
+      "Synctest bubble deadlocked: every active thread is durably blocked and no timer can fire\n" \
+        "#{diagnostics_locked}"
+    end
+
+    def stalled_message_locked(item)
+      "Synctest bubble stalled while #{item.description}; a thread may be blocked on unsupported I/O or native code\n" \
+        "#{diagnostics_locked}"
+    end
+
+    def stalled_finish_message_locked
+      "Synctest bubble stalled while waiting for child threads to exit; a thread may be blocked on unsupported I/O or native code\n" \
+        "#{diagnostics_locked}"
+    end
+
+    def diagnostics_locked
+      lines = ["virtual time: #{format_deadline(@now_ns)}"]
+      lines << "pending child threads: #{@pending_children}" if @pending_children.positive?
+      @states.each do |thread, thread_state|
+        next if thread_state.status == :exited
+
+        detail = thread_state.blocker&.description || thread_state.status
+        lines << "- #{thread_label(thread)}: #{thread_state.status} (#{detail})"
+        Array(thread.backtrace).first(5).each { |line| lines << "    #{line}" }
+      end
+      lines.join("\n")
+    end
+
+    def thread_label(thread)
+      name = thread.name
+      name ? "#{name} (0x#{thread.object_id.to_s(16)})" : "thread 0x#{thread.object_id.to_s(16)}"
+    end
+
+    def signal_locked
+      @progress_sequence += 1
+      Raw::CONDITION_BROADCAST.bind_call(@condition)
+    end
+  end
+end