wgpu 1.2.0 → 1.2.2

data/lib/wgpu/core/device.rb

@@ -1,29 +1,75 @@
 # frozen_string_literal: true
 
+require "monitor"
+
 module WGPU
   class Device
     attr_reader :handle, :queue, :adapter
 
     LIMIT_FIELDS = Native::Limits.members.freeze
 
+    # Requests a logical device and waits for the native callback.
+    #
+    # @param adapter [Adapter] adapter that will create the device
+    # @param label [String, nil] optional debugging label
+    # @param required_features [Array<Symbol, Integer>] features the device must enable
+    # @param required_limits [Hash, nil] minimum required limits
+    # @param timeout [Numeric, nil] maximum wait time in seconds
+    # @return [Device] requested device
+    # @raise [DeviceError] if device creation fails
+    # @raise [TimeoutError] if the request exceeds +timeout+
+    # @raise [ArgumentError] if +timeout+ is used without an instance-backed adapter
     def self.request(adapter, label: nil, required_features: [], required_limits: nil, timeout: nil)
+      timeout = AsyncWaiter.normalize_timeout(timeout)
+      if timeout && !adapter.instance
+        raise ArgumentError,
+          "Device.request timeout requires an instance-backed adapter; " \
+          "pass instance: to Adapter.from_handle"
+      end
+
       device_ptr = FFI::MemoryPointer.new(:pointer)
-      status_holder = { done: false, value: nil, message: nil }
+      status_holder = {
+        done: false,
+        value: nil,
+        message: nil,
+        abandoned: false,
+        cleanup_claimed: false,
+        mutex: Mutex.new
+      }
       device_callback_state = {
         mutex: Mutex.new,
         uncaptured_error: nil,
         device_lost: nil
       }
 
+      callback_token = nil
       callback = FFI::Function.new(
         :void, [:uint32, :pointer, Native::StringView.by_value, :pointer, :pointer]
       ) do |status, device, message, _userdata1, _userdata2|
-        status_holder[:value] = Native::RequestDeviceStatus[status]
-        if message[:data] && !message[:data].null? && message[:length] > 0
-          status_holder[:message] = message[:data].read_string(message[:length])
+        cleanup_abandoned = false
+        begin
+          status_holder[:mutex].synchronize do
+            status_holder[:value] = Native::RequestDeviceStatus[status]
+            if message[:data] && !message[:data].null? && message[:length] > 0
+              status_holder[:message] = message[:data].read_string(message[:length])
+            end
+            device_ptr.write_pointer(device)
+            status_holder[:done] = true
+            if status_holder[:abandoned] && !status_holder[:cleanup_claimed]
+              status_holder[:cleanup_claimed] = true
+              cleanup_abandoned = true
+            end
+          end
+          if cleanup_abandoned
+            if status_holder[:value] == :success && device && !device.null?
+              release_abandoned_device(device, device_callback_state)
+            else
+              release_device_callback_keepalive(device_callback_state)
+            end
+          end
+        ensure
+          CallbackKeepalive.release(adapter, callback_token)
         end
-        device_ptr.write_pointer(device)
-        status_holder[:done] = true
       end
 
       queue_desc = Native::QueueDescriptor.new
@@ -81,35 +127,90 @@ module WGPU
       callback_info[:userdata1] = nil
       callback_info[:userdata2] = nil
 
+      device_lost_token = CallbackKeepalive.retain(adapter, device_lost_callback)
+      uncaptured_error_token = CallbackKeepalive.retain(adapter, uncaptured_error_callback)
+      configure_device_callback_keepalive(
+        device_callback_state,
+        owner: adapter,
+        tokens: [device_lost_token, uncaptured_error_token]
+      )
       callback_token = CallbackKeepalive.retain(adapter, callback)
+      future =
+        begin
+          Native.wgpuAdapterRequestDevice(NativeResource.checked_handle(adapter, expected_class: Adapter), desc, callback_info)
+        rescue StandardError
+          CallbackKeepalive.release(adapter, callback_token)
+          release_device_callback_keepalive(device_callback_state)
+          raise
+        end
+
       begin
-        future = Native.wgpuAdapterRequestDevice(adapter.handle, desc, callback_info)
         AsyncWaiter.wait(
           status_holder: status_holder,
           instance: adapter.instance,
           future: future,
           timeout: timeout
         )
-      ensure
-        CallbackKeepalive.release(adapter, callback_token)
+      rescue StandardError
+        abandoned_device = nil
+        cleanup_abandoned = status_holder[:mutex].synchronize do
+          status_holder[:abandoned] = true
+          next false unless status_holder[:done] && !status_holder[:cleanup_claimed]
+
+          status_holder[:cleanup_claimed] = true
+          abandoned_device = device_ptr.read_pointer
+          true
+        end
+        if cleanup_abandoned
+          if status_holder[:value] == :success && abandoned_device && !abandoned_device.null?
+            release_abandoned_device(abandoned_device, device_callback_state)
+          else
+            release_device_callback_keepalive(device_callback_state)
+          end
+        end
+        raise
       end
 
       handle = device_ptr.read_pointer
       if handle.null? || status_holder[:value] != :success
+        release_device_callback_keepalive(device_callback_state)
         msg = status_holder[:message] || "Unknown error"
         raise DeviceError, "Failed to request device: #{msg}"
       end
 
-      device = new(handle, adapter: adapter, label: label, callback_state: device_callback_state)
-      device.send(:retain_device_callback, device_lost_callback)
-      device.send(:retain_device_callback, uncaptured_error_callback)
-      device
+      begin
+        callback_lifetime = DeviceCallbackLifetime.new do
+          release_device_callback_keepalive(device_callback_state)
+        end
+        device_callback_state[:mutex].synchronize do
+          device_callback_state[:callback_lifetime] = callback_lifetime
+        end
+        device = new(
+          handle,
+          adapter: adapter,
+          label: label,
+          callback_state: device_callback_state,
+          callback_lifetime: callback_lifetime
+        )
+        device.send(:adopt_device_callback_keepalive)
+        device
+      rescue StandardError
+        device&.release
+        release_device_callback_keepalive(device_callback_state)
+        raise
+      end
     end
 
-    def initialize(handle, adapter: nil, label: nil, callback_state: nil)
+    # Wraps a native device and obtains its default queue.
+    # @param handle [FFI::Pointer] native device handle
+    # @param adapter [Adapter, nil] adapter that created the device
+    # @param label [String, nil] optional debug label
+    # @param callback_lifetime [DeviceCallbackLifetime, nil] shared native callback lifetime
+    def initialize(handle, adapter: nil, label: nil, callback_state: nil, callback_lifetime: nil)
       @handle = handle
       @adapter = adapter
       @label = label
+      @device_callback_lifetime = callback_lifetime
       @device_callback_state = callback_state || {
         mutex: Mutex.new,
         uncaptured_error: nil,
@@ -119,14 +220,20 @@ module WGPU
       @queue = Queue.new(Native.wgpuDeviceGetQueue(@handle), device: self)
     end
 
+    # Returns information about the adapter that created this device.
+    # @return [Hash, nil]
     def adapter_info
       @adapter&.info
     end
 
+    # Creates a GPU buffer.
+    # @return [Buffer]
     def create_buffer(label: nil, size:, usage:, mapped_at_creation: false)
       Buffer.new(self, label: label, size: size, usage: usage, mapped_at_creation: mapped_at_creation)
     end
 
+    # Creates a shader module from WGSL or SPIR-V source.
+    # @return [ShaderModule]
     def create_shader_module(label: nil, code: nil, spirv: nil, compilation_hints: [], validate: false)
       ShaderModule.new(
         self,
@@ -138,32 +245,46 @@ module WGPU
       )
     end
 
+    # Creates a command encoder.
+    # @return [CommandEncoder]
     def create_command_encoder(label: nil)
       CommandEncoder.new(self, label: label)
     end
 
+    # Creates a bind group layout.
+    # @return [BindGroupLayout]
     def create_bind_group_layout(label: nil, entries:)
       BindGroupLayout.new(self, label: label, entries: entries)
     end
 
+    # Creates a bind group.
+    # @return [BindGroup]
     def create_bind_group(label: nil, layout:, entries:)
       BindGroup.new(self, label: label, layout: layout, entries: entries)
     end
 
+    # Creates a pipeline layout.
+    # @return [PipelineLayout]
     def create_pipeline_layout(label: nil, bind_group_layouts:)
       PipelineLayout.new(self, label: label, bind_group_layouts: bind_group_layouts)
     end
 
+    # Creates a compute pipeline.
+    # @return [ComputePipeline]
     def create_compute_pipeline(label: nil, layout:, compute:)
       ComputePipeline.new(self, label: label, layout: layout, compute: compute)
     end
 
+    # Creates a compute pipeline on a background task.
+    # @return [AsyncTask] task yielding a {ComputePipeline}
     def create_compute_pipeline_async(label: nil, layout:, compute:)
       AsyncTask.new do
         create_compute_pipeline(label: label, layout: layout, compute: compute)
       end
     end
 
+    # Creates a render pipeline.
+    # @return [RenderPipeline]
     def create_render_pipeline(label: nil, layout:, vertex:, primitive: {}, depth_stencil: nil, multisample: {}, fragment: nil)
       RenderPipeline.new(self,
         label: label,
@@ -176,6 +297,8 @@ module WGPU
       )
     end
 
+    # Creates a render pipeline on a background task.
+    # @return [AsyncTask] task yielding a {RenderPipeline}
     def create_render_pipeline_async(label: nil, layout:, vertex:, primitive: {}, depth_stencil: nil, multisample: {}, fragment: nil)
       AsyncTask.new do
         create_render_pipeline(
@@ -190,6 +313,8 @@ module WGPU
       end
     end
 
+    # Creates a texture.
+    # @return [Texture]
     def create_texture(label: nil, size:, format:, usage:, dimension: :d2, mip_level_count: 1, sample_count: 1, view_formats: [])
       Texture.new(self,
         label: label,
@@ -203,6 +328,8 @@ module WGPU
       )
     end
 
+    # Creates a texture sampler.
+    # @return [Sampler]
     def create_sampler(label: nil, address_mode_u: :clamp_to_edge, address_mode_v: :clamp_to_edge, address_mode_w: :clamp_to_edge, mag_filter: :nearest, min_filter: :nearest, mipmap_filter: :nearest, lod_min_clamp: 0.0, lod_max_clamp: 32.0, compare: nil, max_anisotropy: 1)
       Sampler.new(self,
         label: label,
@@ -219,6 +346,11 @@ module WGPU
       )
     end
 
+    # Creates a mapped buffer initialized from typed Ruby data.
+    # @param data [Array, String, FFI::Pointer] source data
+    # @param usage [Symbol, Array<Symbol>, Integer] buffer usage flags
+    # @param type [Symbol] source element type
+    # @return [Buffer]
     def create_buffer_with_data(label: nil, data:, usage:, type: :f32)
       data_ptr, byte_size = DataTypes.to_pointer(data, type:)
       DataTypes.validate_alignment!(byte_size, 4, name: "buffer data size")
@@ -233,10 +365,14 @@ module WGPU
       buffer
     end
 
+    # Creates a GPU query set.
+    # @return [QuerySet]
     def create_query_set(label: nil, type:, count:)
       QuerySet.new(self, label: label, type: type, count: count)
     end
 
+    # Creates an encoder for reusable render commands.
+    # @return [RenderBundleEncoder]
     def create_render_bundle_encoder(color_formats:, depth_stencil_format: nil, sample_count: 1,
                                      depth_read_only: false, stencil_read_only: false, label: nil)
       RenderBundleEncoder.new(self,
@@ -249,6 +385,8 @@ module WGPU
       )
     end
 
+    # Lists optional features enabled on the device.
+    # @return [Array<Symbol>]
     def features
       supported = Native::SupportedFeatures.new
       Native.wgpuDeviceGetFeatures(@handle, supported)
@@ -260,12 +398,19 @@ module WGPU
         end
       end
       result
+    ensure
+      Native.wgpuSupportedFeaturesFreeMembers(supported) if supported
     end
 
+    # Reports whether a feature is enabled on the device.
+    # @param feature [Symbol] feature name
+    # @return [Boolean]
     def has_feature?(feature)
       features.include?(feature)
     end
 
+    # Returns resource limits supported by the device.
+    # @return [Hash{Symbol => Integer}]
     def limits
       supported = Native::SupportedLimits.new
       supported[:next_in_chain] = nil
@@ -273,6 +418,9 @@ module WGPU
       limits_to_hash(supported[:limits])
     end
 
+    # Processes device work, optionally waiting for queue progress.
+    # @param wait [Boolean] whether to wait for submitted work
+    # @return [Integer] native poll status
     def poll(wait: false)
       if Native.device_poll_available?
         Native.wgpuDevicePoll(@handle, wait ? 1 : 0, nil)
@@ -282,65 +430,68 @@ module WGPU
       end
     end
 
+    # Pushes a scope that captures matching GPU errors.
+    # Scopes belong to the pushing thread and serialize scoped work on this device.
+    # Pop on the same thread; do not wait here for another thread's scoped work.
+    # @param filter [Symbol, Integer] error filter
+    # @return [void]
     def push_error_scope(filter = :validation)
       filter_value = Native::EnumHelper.coerce(Native::ErrorFilter, filter, name: "error filter")
-      Native.wgpuDevicePushErrorScope(@handle, filter_value)
-    end
-
-    def pop_error_scope(timeout: nil)
-      error_holder = { done: false, status: nil, type: nil, message: nil }
-
-      callback = FFI::Function.new(
-        :void, [:uint32, :uint32, Native::StringView.by_value, :pointer, :pointer]
-      ) do |status, error_type, message, _userdata1, _userdata2|
-        error_holder[:done] = true
-        error_holder[:status] = Native::PopErrorScopeStatus[status]
-        error_holder[:type] = Native::ErrorType[error_type]
-        if message[:data] && !message[:data].null? && message[:length] > 0
-          error_holder[:message] = message[:data].read_string(message[:length])
-        end
-      end
-
-      callback_info = Native::PopErrorScopeCallbackInfo.new
-      callback_info[:next_in_chain] = nil
-      callback_info[:mode] = AsyncWaiter.callback_mode(instance: @adapter&.instance)
-      callback_info[:callback] = callback
-      callback_info[:userdata1] = nil
-      callback_info[:userdata2] = nil
-
-      callback_token = CallbackKeepalive.retain(self, callback)
+      error_scope_monitor.enter
       begin
-        future = Native.wgpuDevicePopErrorScope(@handle, callback_info)
-        AsyncWaiter.wait(
-          status_holder: error_holder,
-          instance: @adapter&.instance,
-          device: self,
-          future: future,
-          timeout: timeout
-        )
-      ensure
-        CallbackKeepalive.release(self, callback_token)
+        ensure_not_released!
+        Native.wgpuDevicePushErrorScope(@handle, filter_value)
+        @error_scope_depth = (@error_scope_depth || 0) + 1
+        @error_scope_owner = Thread.current
+      rescue StandardError
+        error_scope_monitor.exit
+        raise
       end
+    end
 
-      error_holder
+    # Pops the latest error scope and waits for its result.
+    # @param timeout [Numeric, nil] maximum wait time in seconds
+    # @return [Hash] native status, error type, and message
+    def pop_error_scope(timeout: nil)
+      timeout = AsyncWaiter.normalize_timeout(timeout)
+      error_holder, future = begin_pop_error_scope
+      wait_for_error_scope(error_holder, future, timeout: timeout)
     end
 
+    # Starts popping on the calling thread and waits for completion in a background task.
+    #
+    # @param timeout [Numeric, nil] maximum wait time in seconds
+    # @return [AsyncTask] task whose value is the error hash
     def pop_error_scope_async(timeout: nil)
-      AsyncTask.new { pop_error_scope(timeout: timeout) }
+      timeout = AsyncWaiter.normalize_timeout(timeout)
+      error_holder, future = begin_pop_error_scope
+      AsyncTask.new { wait_for_error_scope(error_holder, future, timeout: timeout) }
     end
 
+    # Pops the latest error scope as a typed error.
+    # @param timeout [Numeric, nil] maximum wait time in seconds
+    # @return [GPUError, nil]
     def pop_error_scope_typed(timeout: nil)
       GPUError.from_hash(pop_error_scope(timeout: timeout))
     end
 
+    # Runs a block inside an error scope and raises captured GPU errors.
+    # @param filter [Symbol, Integer] error filter
+    # @yieldreturn [Object] block result
+    # @return [Object] block result
     def with_error_scope(filter = :validation)
-      push_error_scope(filter)
-      result = yield
-      error = GPUError.from_hash(pop_error_scope)
-      error&.raise!
+      raise ArgumentError, "block is required" unless block_given?
+
+      result = nil
+      error = capture_error_scope(filter) { result = yield }
+      GPUError.from_hash(error)&.raise!
       result
     end
 
+    # Registers the handler for uncaptured GPU errors.
+    # @yieldparam error [GPUError] reported error
+    # @return [Device] this device
+    # @raise [ArgumentError] if no block is provided
     def on_uncaptured_error(&handler)
       raise ArgumentError, "on_uncaptured_error requires a block" unless handler
 
@@ -348,6 +499,11 @@ module WGPU
       self
     end
 
+    # Registers the handler invoked when the device is lost.
+    # @yieldparam reason [Symbol] native device-lost reason
+    # @yieldparam message [String] native diagnostic message
+    # @return [Device] this device
+    # @raise [ArgumentError] if no block is provided
     def on_device_lost(&handler)
       raise ArgumentError, "on_device_lost requires a block" unless handler
 
@@ -355,18 +511,26 @@ module WGPU
       self
     end
 
+    # Destroys device-owned native resources.
+    # @return [void]
     def destroy
       return if @handle.null?
       Native.wgpuDeviceDestroy(@handle)
     end
 
+    # Releases the default queue and native device handle.
+    #
+    # Device callbacks remain alive until all derived wrappers and pending
+    # callback operations have also completed their native releases.
+    #
+    # Calling this method more than once has no effect.
+    # @return [void]
     def release
       @queue&.release
       return if @handle.null?
       Native.wgpuDeviceRelease(@handle)
       @handle = FFI::Pointer::NULL
-      Array(@device_callback_tokens).each { |token| CallbackKeepalive.release(self, token) }
-      @device_callback_tokens&.clear
+      @device_callback_tokens = nil
     end
 
     def self.normalize_required_features(required_features)
@@ -416,12 +580,17 @@ module WGPU
       FFI::Function.new(
         :void, [:pointer, :uint32, Native::StringView.by_value, :pointer, :pointer]
       ) do |_device, type, message, _userdata1, _userdata2|
-        error = GPUError.new(
-          type: Native::ErrorType[type] || :unknown,
-          message: string_from_callback(message)
-        )
-        dispatch_device_callback(state, :uncaptured_error, error) do
-          warn "Uncaptured GPU error (#{error.type}): #{error.message}"
+        callback_lifetime = retain_device_callback_lifetime(state)
+        begin
+          error = GPUError.new(
+            type: Native::ErrorType[type] || :unknown,
+            message: string_from_callback(message)
+          )
+          dispatch_device_callback(state, :uncaptured_error, error) do
+            warn "Uncaptured GPU error (#{error.type}): #{error.message}"
+          end
+        ensure
+          callback_lifetime&.release
         end
       end
     end
@@ -430,14 +599,69 @@ module WGPU
       FFI::Function.new(
         :void, [:pointer, :uint32, Native::StringView.by_value, :pointer, :pointer]
       ) do |_device, reason, message, _userdata1, _userdata2|
-        reason_name = Native::DeviceLostReason[reason] || :unknown
-        message_text = string_from_callback(message)
-        dispatch_device_callback(state, :device_lost, reason_name, message_text) do
-          warn "GPU device lost (#{reason_name}): #{message_text}" unless reason_name == :destroyed
+        callback_lifetime = retain_device_callback_lifetime(state)
+        begin
+          reason_name = Native::DeviceLostReason[reason] || :unknown
+          message_text = string_from_callback(message)
+          dispatch_device_callback(state, :device_lost, reason_name, message_text) do
+            warn "GPU device lost (#{reason_name}): #{message_text}" unless reason_name == :destroyed
+          end
+        ensure
+          callback_lifetime&.release
         end
       end
     end
 
+    def self.retain_device_callback_lifetime(state)
+      state[:mutex].synchronize do
+        lifetime = state[:callback_lifetime]
+        lifetime&.retain
+        lifetime
+      end
+    end
+
+    def self.configure_device_callback_keepalive(state, owner:, tokens:)
+      state[:mutex].synchronize do
+        state[:callback_owner] = owner
+        state[:callback_tokens] = tokens
+        state[:callbacks_completed] = false
+      end
+    end
+
+    def self.transfer_device_callback_keepalive(state, new_owner)
+      state[:mutex].synchronize do
+        return [] if state[:callbacks_completed]
+
+        previous_owner = state[:callback_owner]
+        tokens = Array(state[:callback_tokens])
+        transferred = tokens.select do |token|
+          CallbackKeepalive.transfer(previous_owner, new_owner, token)
+        end
+        state[:callback_owner] = new_owner
+        state[:callback_tokens] = transferred
+        transferred
+      end
+    end
+
+    def self.release_device_callback_keepalive(state)
+      owner, tokens = state[:mutex].synchronize do
+        return if state[:callbacks_completed]
+
+        state[:callbacks_completed] = true
+        retained_owner = state.delete(:callback_owner)
+        retained_tokens = Array(state.delete(:callback_tokens))
+        state.delete(:callback_lifetime)
+        [retained_owner, retained_tokens]
+      end
+      tokens.each { |token| CallbackKeepalive.release(owner, token) } if owner
+    end
+
+    def self.release_abandoned_device(device, callback_state)
+      Native.wgpuDeviceRelease(device)
+    ensure
+      release_device_callback_keepalive(callback_state)
+    end
+
     def self.dispatch_device_callback(state, key, *args)
       handler = state[:mutex].synchronize { state[key] }
       handler ? handler.call(*args) : yield
@@ -453,12 +677,95 @@ module WGPU
 
     private_class_method :normalize_required_features, :normalize_feature_name,
       :build_required_limits, :canonical_limit_key, :build_uncaptured_error_callback,
-      :build_device_lost_callback, :dispatch_device_callback, :string_from_callback
+      :build_device_lost_callback, :retain_device_callback_lifetime,
+      :configure_device_callback_keepalive,
+      :transfer_device_callback_keepalive, :release_device_callback_keepalive,
+      :release_abandoned_device, :dispatch_device_callback, :string_from_callback
 
     private
 
-    def retain_device_callback(callback)
-      @device_callback_tokens << CallbackKeepalive.retain(self, callback)
+    def begin_pop_error_scope
+      unless @error_scope_owner == Thread.current && @error_scope_depth.to_i.positive?
+        raise DeviceError, "No error scope belongs to the current thread"
+      end
+
+      error_holder = { done: false, status: nil, type: nil, message: nil }
+
+      callback_lifetime_release = device_callback_lifetime_lease
+      callback_token = nil
+      callback = FFI::Function.new(
+        :void, [:uint32, :uint32, Native::StringView.by_value, :pointer, :pointer]
+      ) do |status, error_type, message, _userdata1, _userdata2|
+        begin
+          error_holder[:status] = Native::PopErrorScopeStatus[status]
+          error_holder[:type] = Native::ErrorType[error_type]
+          if message[:data] && !message[:data].null? && message[:length] > 0
+            error_holder[:message] = message[:data].read_string(message[:length])
+          end
+          error_holder[:done] = true
+        ensure
+          CallbackKeepalive.release(self, callback_token)
+          callback_lifetime_release.call
+        end
+      end
+
+      callback_info = Native::PopErrorScopeCallbackInfo.new
+      callback_info[:next_in_chain] = nil
+      callback_info[:mode] = AsyncWaiter.callback_mode(instance: @adapter&.instance)
+      callback_info[:callback] = callback
+      callback_info[:userdata1] = nil
+      callback_info[:userdata2] = nil
+
+      callback_token = CallbackKeepalive.retain(self, callback)
+      @error_scope_depth -= 1
+      @error_scope_owner = nil if @error_scope_depth.zero?
+      future =
+        begin
+          Native.wgpuDevicePopErrorScope(@handle, callback_info)
+        rescue StandardError
+          CallbackKeepalive.release(self, callback_token)
+          callback_lifetime_release.call
+          raise
+        ensure
+          error_scope_monitor.exit
+        end
+      [error_holder, future]
+    end
+
+    def wait_for_error_scope(error_holder, future, timeout:)
+      AsyncWaiter.wait(
+        status_holder: error_holder,
+        instance: @adapter&.instance,
+        device: self,
+        future: future,
+        timeout: timeout
+      )
+      error_holder
+    end
+
+    def error_scope_monitor
+      @error_scope_monitor ||= Monitor.new
+    end
+
+    # The reentrant scope lock spans push, the operation, and native pop.
+    def capture_error_scope(filter = :validation)
+      push_error_scope(filter)
+      begin
+        yield
+      ensure
+        active_error = $!
+        begin
+          error = pop_error_scope
+        rescue StandardError
+          raise unless active_error
+        end
+      end
+      error
+    end
+
+    def adopt_device_callback_keepalive
+      @device_callback_tokens =
+        self.class.send(:transfer_device_callback_keepalive, @device_callback_state, self)
     end
 
     def set_device_callback(name, handler)