wgpu 1.2.0 → 1.2.1

data/lib/wgpu/core/device.rb

@@ -6,24 +6,67 @@ module WGPU
 
     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)
+      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 +124,89 @@ 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(adapter.handle, 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 TimeoutError
+        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 ? device.release : release_abandoned_device(handle, 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 +216,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 +241,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 +293,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 +309,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 +324,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 +342,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 +361,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 +381,8 @@ module WGPU
       )
     end
 
+    # Lists optional features enabled on the device.
+    # @return [Array<Symbol>]
     def features
       supported = Native::SupportedFeatures.new
       Native.wgpuDeviceGetFeatures(@handle, supported)
@@ -262,10 +396,15 @@ module WGPU
       result
     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 +412,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,22 +424,35 @@ module WGPU
       end
     end
 
+    # Pushes a scope that captures matching GPU errors.
+    # @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
 
+    # 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)
       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|
-        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])
+        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
 
@@ -309,30 +464,44 @@ module WGPU
       callback_info[:userdata2] = nil
 
       callback_token = CallbackKeepalive.retain(self, callback)
-      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)
-      end
+      future =
+        begin
+          Native.wgpuDevicePopErrorScope(@handle, callback_info)
+        rescue StandardError
+          CallbackKeepalive.release(self, callback_token)
+          callback_lifetime_release.call
+          raise
+        end
+      AsyncWaiter.wait(
+        status_holder: error_holder,
+        instance: @adapter&.instance,
+        device: self,
+        future: future,
+        timeout: timeout
+      )
 
       error_holder
     end
 
+    # Pops the latest error scope on a background thread.
+    #
+    # @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) }
     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
@@ -341,6 +510,10 @@ module WGPU
       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 +521,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 +533,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 +602,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,12 +621,67 @@ 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)
@@ -453,12 +699,16 @@ 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 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)

data/lib/wgpu/core/instance.rb

@@ -4,6 +4,8 @@ module WGPU
   class Instance
     attr_reader :handle
 
+    # Creates a WebGPU instance.
+    # @raise [InitializationError] if native instance creation fails
     def initialize
       desc = Native::InstanceDescriptor.new
       desc[:next_in_chain] = nil
@@ -15,6 +17,8 @@ module WGPU
       raise InitializationError, "Failed to create WebGPU instance" if @handle.null?
     end
 
+    # Requests an adapter matching the supplied preferences.
+    # @return [Adapter]
     def request_adapter(power_preference: :high_performance, backend: nil, feature_level: :core,
                         force_fallback_adapter: false, compatible_surface: nil, timeout: nil)
       Adapter.request(
@@ -28,6 +32,8 @@ module WGPU
       )
     end
 
+    # Requests an adapter on a background task.
+    # @return [AsyncTask] task yielding an {Adapter}
     def request_adapter_async(power_preference: :high_performance, backend: nil, feature_level: :core,
                               force_fallback_adapter: false, compatible_surface: nil, timeout: nil)
       AsyncTask.new do
@@ -42,6 +48,9 @@ module WGPU
       end
     end
 
+    # Lists adapters exposed by the instance.
+    # @param backends [Integer, nil] backend bit mask
+    # @return [Array<Adapter>]
     def enumerate_adapters(backends: nil)
       options = nil
       if backends
@@ -61,20 +70,31 @@ module WGPU
       end
     end
 
+    # Enumerates adapters on a background task.
+    # @return [AsyncTask] task yielding adapter objects
     def enumerate_adapters_async(backends: nil)
       AsyncTask.new do
         enumerate_adapters(backends: backends)
       end
     end
 
+    # Creates a canvas context from platform presentation information.
+    # @param present_info [Hash] platform surface information
+    # @return [CanvasContext]
     def get_canvas_context(present_info)
       CanvasContext.new(self, present_info)
     end
 
+    # Processes pending instance callbacks and events.
+    # @return [void]
     def process_events
       Native.wgpuInstanceProcessEvents(@handle)
     end
 
+    # Releases the native instance handle.
+    #
+    # Calling this method more than once has no effect.
+    # @return [void]
     def release
       return if @handle.null?
       Native.wgpuInstanceRelease(@handle)