wgpu 1.1.0 → 1.2.1

data/lib/wgpu/core/device.rb

@@ -6,19 +6,67 @@ module WGPU
 
     LIMIT_FIELDS = Native::Limits.members.freeze
 
-    def self.request(adapter, label: nil, required_features: [], required_limits: nil)
+    # 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
@@ -28,14 +76,16 @@ module WGPU
 
       device_lost_info = Native::DeviceLostCallbackInfo.new
       device_lost_info[:next_in_chain] = nil
-      device_lost_info[:mode] = 0
-      device_lost_info[:callback] = nil
+      device_lost_info[:mode] = AsyncWaiter.callback_mode(instance: adapter.instance)
+      device_lost_callback = build_device_lost_callback(device_callback_state)
+      device_lost_info[:callback] = device_lost_callback
       device_lost_info[:userdata1] = nil
       device_lost_info[:userdata2] = nil
 
       error_info = Native::UncapturedErrorCallbackInfo.new
       error_info[:next_in_chain] = nil
-      error_info[:callback] = nil
+      uncaptured_error_callback = build_uncaptured_error_callback(device_callback_state)
+      error_info[:callback] = uncaptured_error_callback
       error_info[:userdata1] = nil
       error_info[:userdata2] = nil
 
@@ -74,62 +124,163 @@ module WGPU
       callback_info[:userdata1] = nil
       callback_info[:userdata2] = nil
 
-      future = Native.wgpuAdapterRequestDevice(adapter.handle, desc, callback_info)
-      AsyncWaiter.wait(status_holder: status_holder, instance: adapter.instance, future: future)
+      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
+        AsyncWaiter.wait(
+          status_holder: status_holder,
+          instance: adapter.instance,
+          future: future,
+          timeout: timeout
+        )
+      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
 
-      new(handle, adapter: adapter)
+      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)
+    # 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,
+        device_lost: nil
+      }
+      @device_callback_tokens = []
       @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
 
-    def create_shader_module(label: nil, code:, compilation_hints: [])
-      ShaderModule.new(self, label: label, code: code, compilation_hints: compilation_hints)
+    # 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,
+        label: label,
+        code: code,
+        spirv: spirv,
+        compilation_hints: compilation_hints,
+        validate: validate
+      )
     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,
@@ -142,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(
@@ -156,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,
@@ -169,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,
@@ -185,8 +342,14 @@ module WGPU
       )
     end
 
-    def create_buffer_with_data(label: nil, data:, usage:)
-      data_ptr, byte_size = data_to_pointer(data)
+    # 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")
       buffer = create_buffer(
         label: label,
         size: byte_size,
@@ -198,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,
@@ -214,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)
@@ -227,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
@@ -238,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)
@@ -247,21 +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)
-      Native.wgpuDevicePushErrorScope(@handle, filter)
+      filter_value = Native::EnumHelper.coerce(Native::ErrorFilter, filter, name: "error filter")
+      Native.wgpuDevicePushErrorScope(@handle, filter_value)
     end
 
-    def pop_error_scope
+    # 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
 
@@ -272,40 +463,98 @@ module WGPU
       callback_info[:userdata1] = nil
       callback_info[:userdata2] = nil
 
-      future = Native.wgpuDevicePopErrorScope(@handle, callback_info)
-      AsyncWaiter.wait(status_holder: error_holder, instance: @adapter&.instance, device: self, future: future)
+      callback_token = CallbackKeepalive.retain(self, callback)
+      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
 
-    def pop_error_scope_async
-      AsyncTask.new { pop_error_scope }
+    # 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
-      error = pop_error_scope
-      if error[:type] && error[:type] != :no_error
-        raise Error, "GPU error (#{error[:type]}): #{error[:message]}"
-      end
+      error = GPUError.from_hash(pop_error_scope)
+      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
+
+      set_device_callback(:uncaptured_error, handler)
+      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
+
+      set_device_callback(:device_lost, handler)
+      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
+      @device_callback_tokens = nil
     end
 
-    private
-
     def self.normalize_required_features(required_features)
       Array(required_features).map do |feature|
         normalize_feature_name(feature)
@@ -316,10 +565,7 @@ module WGPU
       return feature if feature.is_a?(Integer)
 
       key = feature.to_s.strip.tr("-", "_").to_sym
-      value = Native::FeatureName[key]
-      raise ArgumentError, "Unknown feature name: #{feature}" if value.nil?
-
-      value
+      Native::EnumHelper.coerce(Native::FeatureName, key, name: "feature name")
     end
 
     def self.build_required_limits(adapter, required_limits)
@@ -352,21 +598,121 @@ module WGPU
       raise ArgumentError, "Unknown limit key: #{name}"
     end
 
-    def data_to_pointer(data)
-      case data
-      when String
-        ptr = FFI::MemoryPointer.new(:char, data.bytesize)
-        ptr.put_bytes(0, data)
-        [ptr, data.bytesize]
-      when Array
-        ptr = FFI::MemoryPointer.new(:float, data.size)
-        ptr.write_array_of_float(data)
-        [ptr, data.size * 4]
-      when FFI::Pointer
-        [data, data.size]
-      else
-        raise ArgumentError, "Unsupported data type: #{data.class}"
+    def self.build_uncaptured_error_callback(state)
+      FFI::Function.new(
+        :void, [:pointer, :uint32, Native::StringView.by_value, :pointer, :pointer]
+      ) do |_device, type, message, _userdata1, _userdata2|
+        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
+
+    def self.build_device_lost_callback(state)
+      FFI::Function.new(
+        :void, [:pointer, :uint32, Native::StringView.by_value, :pointer, :pointer]
+      ) do |_device, reason, message, _userdata1, _userdata2|
+        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
+    rescue StandardError => e
+      warn "WGPU #{key} handler failed: #{e.class}: #{e.message}"
+    end
+
+    def self.string_from_callback(message)
+      return "" if message[:data].nil? || message[:data].null? || message[:length].zero?
+
+      message[:data].read_string(message[:length])
+    end
+
+    private_class_method :normalize_required_features, :normalize_feature_name,
+      :build_required_limits, :canonical_limit_key, :build_uncaptured_error_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 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)
+      @device_callback_state[:mutex].synchronize { @device_callback_state[name] = handler }
     end
 
     def limits_to_hash(limits)