lldb 0.2.0 → 0.3.0

data/lib/lldb/launch_info.rb

@@ -22,20 +22,21 @@ module LLDB
   end
 
   class LaunchInfo
+    prepend NativeLifecycle
+
     # @rbs args: Array[String]?
     # @rbs return: void
-    def initialize(args = nil)
-      argv = nil
-      if args && !args.empty?
-        argv = FFI::MemoryPointer.new(:pointer, args.length + 1)
-        args.each_with_index do |arg, i|
-          argv[i].put_pointer(0, FFI::MemoryPointer.from_string(arg))
-        end
-        argv[args.length].put_pointer(0, nil)
-      end
+    def initialize(args = nil, context: nil)
+      @arguments = if args && !args.empty?
+                     NativeStringArray.new(args)
+                   end
 
-      @ptr = FFIBindings.lldb_launch_info_create(argv) # : FFI::Pointer
-      ObjectSpace.define_finalizer(self, self.class.release(@ptr))
+      ptr = FFIBindings.lldb_launch_info_create(@arguments&.to_ptr)
+      initialize_native_object(
+        ptr,
+        release: ->(released) { FFIBindings.lldb_launch_info_destroy(released) },
+        context: context
+      )
     end
 
     # @rbs ptr: FFI::Pointer
@@ -44,26 +45,151 @@ module LLDB
       ->(_id) { FFIBindings.lldb_launch_info_destroy(ptr) unless ptr.null? }
     end
 
+    # @rbs return: bool
+    def valid?
+      !@ptr.null?
+    end
+
     # @rbs dir: String
     # @rbs return: void
     def working_directory=(dir)
+      NativeStringArray.validate!(dir)
       FFIBindings.lldb_launch_info_set_working_directory(@ptr, dir)
     end
 
-    # @rbs env: Hash[String, String]
+    # @rbs return: String?
+    def working_directory
+      FFIBindings.lldb_launch_info_get_working_directory(@ptr)
+    end
+
+    # @rbs env: Hash[String, String]?
     # @rbs append: bool
     # @rbs return: void
     def set_environment(env, append: true)
-      return unless env && !env.empty?
+      return if env.nil?
+      raise ArgumentError, 'environment must be a Hash' unless env.is_a?(Hash)
+
+      entries = env.map do |key, value|
+        key = NativeStringArray.validate!(key)
+        value = NativeStringArray.validate!(value)
+        raise ArgumentError, 'environment keys must not contain =' if key.include?('=')
+
+        "#{key}=#{value}"
+      end
+      strings = NativeStringArray.new(entries)
+      FFIBindings.lldb_launch_info_set_environment_entries(@ptr, strings.to_ptr, append ? 1 : 0)
+    end
+
+    # @rbs args: Array[String]
+    # @rbs append: bool
+    # @rbs return: void
+    def arguments=(args, append: false)
+      raise ArgumentError, 'arguments must be an Array' unless args.is_a?(Array)
+
+      @arguments = NativeStringArray.new(args)
+      FFIBindings.lldb_launch_info_set_arguments(@ptr, @arguments.to_ptr, append ? 1 : 0)
+    end
 
-      env_strings = env.map { |k, v| "#{k}=#{v}" }
-      envp = FFI::MemoryPointer.new(:pointer, env_strings.length + 1)
-      env_strings.each_with_index do |e, i|
-        envp[i].put_pointer(0, FFI::MemoryPointer.from_string(e))
+    # @rbs return: Array[String]
+    def arguments
+      count = FFIBindings.lldb_launch_info_get_num_arguments(@ptr)
+      (0...count).map { |index| FFIBindings.lldb_launch_info_get_argument_at_index(@ptr, index).to_s }
+    end
+
+    # @rbs return: Array[String]
+    def environment_entries
+      count = FFIBindings.lldb_launch_info_get_num_environment_entries(@ptr)
+      (0...count).map do |index|
+        FFIBindings.lldb_launch_info_get_environment_entry_at_index(@ptr, index).to_s
       end
-      envp[env_strings.length].put_pointer(0, nil)
+    end
+
+    # @rbs return: FileSpec?
+    def executable_file
+      file_ptr = FFIBindings.lldb_launch_info_get_executable_file(@ptr)
+      return nil if file_ptr.nil? || file_ptr.null?
+
+      FileSpec.from_ptr(file_ptr, context: context)
+    end
+
+    # @rbs file: FileSpec
+    # @rbs add_as_first_arg: bool
+    # @rbs return: void
+    def executable_file=(file, add_as_first_arg: false)
+      raise ArgumentError, 'file must be a FileSpec' unless file.is_a?(FileSpec)
+
+      FFIBindings.lldb_launch_info_set_executable_file(@ptr, file.to_ptr, add_as_first_arg ? 1 : 0)
+    end
+
+    # @rbs return: Listener?
+    def listener
+      listener_ptr = FFIBindings.lldb_launch_info_get_listener(@ptr)
+      return nil if listener_ptr.nil? || listener_ptr.null?
+
+      Listener.from_ptr(listener_ptr, context: context)
+    end
+
+    # @rbs value: Listener
+    # @rbs return: void
+    def listener=(value)
+      raise ArgumentError, 'listener must be a Listener' unless value.is_a?(Listener)
+
+      FFIBindings.lldb_launch_info_set_listener(@ptr, value.to_ptr)
+    end
+
+    # @rbs return: String?
+    def process_plugin_name
+      FFIBindings.lldb_launch_info_get_process_plugin_name(@ptr)
+    end
+
+    # @rbs value: String
+    # @rbs return: void
+    def process_plugin_name=(value)
+      NativeStringArray.validate!(value)
+      FFIBindings.lldb_launch_info_set_process_plugin_name(@ptr, value)
+    end
+
+    # @rbs return: String?
+    def shell
+      FFIBindings.lldb_launch_info_get_shell(@ptr)
+    end
+
+    # @rbs value: String
+    # @rbs return: void
+    def shell=(value)
+      NativeStringArray.validate!(value)
+      FFIBindings.lldb_launch_info_set_shell(@ptr, value)
+    end
+
+    # @rbs fd: Integer
+    # @rbs return: bool
+    def add_close_file_action(fd)
+      FFIBindings.lldb_launch_info_add_close_file_action(@ptr, fd) != 0
+    end
+
+    # @rbs fd: Integer
+    # @rbs dup_fd: Integer
+    # @rbs return: bool
+    def add_duplicate_file_action(fd, dup_fd)
+      FFIBindings.lldb_launch_info_add_duplicate_file_action(@ptr, fd, dup_fd) != 0
+    end
+
+    # @rbs fd: Integer
+    # @rbs path: String
+    # @rbs read: bool
+    # @rbs write: bool
+    # @rbs return: bool
+    def add_open_file_action(fd, path, read: false, write: false)
+      NativeStringArray.validate!(path)
+      FFIBindings.lldb_launch_info_add_open_file_action(@ptr, fd, path, read ? 1 : 0, write ? 1 : 0) != 0
+    end
 
-      FFIBindings.lldb_launch_info_set_environment_entries(@ptr, envp, append ? 1 : 0)
+    # @rbs fd: Integer
+    # @rbs read: bool
+    # @rbs write: bool
+    # @rbs return: bool
+    def add_suppress_file_action(fd, read: false, write: false)
+      FFIBindings.lldb_launch_info_add_suppress_file_action(@ptr, fd, read ? 1 : 0, write ? 1 : 0) != 0
     end
 
     # @rbs return: Integer

data/lib/lldb/line_entry.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module LLDB
+  class LineEntry
+    prepend NativeLifecycle
+
+    # @rbs target: Target?
+    # @rbs context: Context?
+    # @rbs return: void
+    def initialize(ptr, target: nil, context: nil)
+      @target = target
+      initialize_native_object(
+        ptr,
+        release: ->(released) { FFIBindings.lldb_line_entry_destroy(released) },
+        context: context || target&.context
+      )
+    end
+
+    # @rbs return: bool
+    def valid?
+      !@ptr.null? && FFIBindings.lldb_line_entry_is_valid(@ptr) != 0
+    end
+
+    # @rbs return: Address?
+    def start_address
+      return nil unless valid?
+
+      ptr = FFIBindings.lldb_line_entry_get_start_address(@ptr)
+      return nil if ptr.nil? || ptr.null?
+
+      Address.from_ptr(ptr, target: @target, context: context)
+    end
+
+    # @rbs return: Address?
+    def end_address
+      return nil unless valid?
+
+      ptr = FFIBindings.lldb_line_entry_get_end_address(@ptr)
+      return nil if ptr.nil? || ptr.null?
+
+      Address.from_ptr(ptr, target: @target, context: context)
+    end
+
+    # @rbs return: FileSpec?
+    def file_spec
+      return nil unless valid?
+
+      ptr = FFIBindings.lldb_line_entry_get_file_spec(@ptr)
+      return nil if ptr.nil? || ptr.null?
+
+      FileSpec.from_ptr(ptr, context: context)
+    end
+
+    # @rbs return: Integer
+    def line
+      return INVALID_LINE_NUMBER unless valid?
+
+      FFIBindings.lldb_line_entry_get_line(@ptr)
+    end
+
+    # @rbs return: Integer
+    def column
+      return 0 unless valid?
+
+      FFIBindings.lldb_line_entry_get_column(@ptr)
+    end
+
+    # @rbs return: FFI::Pointer
+    def to_ptr
+      @ptr
+    end
+  end
+end

data/lib/lldb/listener.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module LLDB
+  class Listener
+    prepend NativeLifecycle
+
+    # @rbs name: String?
+    # @rbs context: Context?
+    # @rbs pointer: FFI::Pointer?
+    # @rbs return: void
+    def initialize(name = nil, context: nil, pointer: nil)
+      ptr = pointer || FFIBindings.lldb_listener_create(name)
+      initialize_native_object(
+        ptr,
+        release: ->(released) { FFIBindings.lldb_listener_destroy(released) },
+        context: context
+      )
+    end
+
+    # @rbs ptr: FFI::Pointer
+    # @rbs context: Context?
+    # @rbs return: Listener
+    def self.from_ptr(ptr, context: nil)
+      new(context: context, pointer: ptr)
+    end
+
+    # @rbs return: bool
+    def valid?
+      !@ptr.null? && FFIBindings.lldb_listener_is_valid(@ptr) != 0
+    end
+
+    # @rbs broadcaster: Broadcaster
+    # @rbs event_mask: Integer
+    # @rbs return: Integer
+    def start_listening_for_events(broadcaster, event_mask)
+      ensure_open!
+      FFIBindings.lldb_listener_start_listening_for_events(@ptr, broadcaster.to_ptr, event_mask)
+    end
+
+    # @rbs broadcaster: Broadcaster
+    # @rbs event_mask: Integer
+    # @rbs return: bool
+    def stop_listening_for_events(broadcaster, event_mask)
+      ensure_open!
+      FFIBindings.lldb_listener_stop_listening_for_events(@ptr, broadcaster.to_ptr, event_mask) != 0
+    end
+
+    # @rbs timeout_seconds: Integer
+    # @rbs return: Event?
+    def wait_for_event(timeout_seconds: 0)
+      ensure_open!
+      timeout = normalize_timeout(timeout_seconds)
+      event_ptr = FFIBindings.lldb_listener_wait_for_event(@ptr, timeout)
+      event_from_ptr(event_ptr)
+    end
+
+    # @rbs return: Event?
+    def peek_event
+      ensure_open!
+      event_from_ptr(FFIBindings.lldb_listener_peek_event(@ptr))
+    end
+
+    # @rbs return: Event?
+    def next_event
+      ensure_open!
+      event_from_ptr(FFIBindings.lldb_listener_next_event(@ptr))
+    end
+
+    # @rbs return: FFI::Pointer
+    def to_ptr
+      @ptr
+    end
+
+    private
+
+    # @rbs timeout: Integer
+    # @rbs return: Integer
+    def normalize_timeout(timeout)
+      unless timeout.is_a?(Integer) && timeout >= 0 && timeout <= 0xFFFFFFFF
+        raise ArgumentError, 'timeout_seconds must be an Integer between 0 and UINT32_MAX'
+      end
+
+      timeout
+    end
+
+    # @rbs ptr: FFI::Pointer
+    # @rbs return: Event?
+    def event_from_ptr(ptr)
+      return nil if ptr.nil? || ptr.null?
+
+      Event.from_ptr(ptr, context: context)
+    end
+  end
+end

data/lib/lldb/memory_region_info.rb

@@ -5,11 +5,16 @@
 module LLDB
   # Represents information about a memory region in the target process.
   class MemoryRegionInfo
+    prepend NativeLifecycle
+
     # @rbs ptr: FFI::Pointer
     # @rbs return: void
-    def initialize(ptr)
-      @ptr = ptr # : FFI::Pointer
-      ObjectSpace.define_finalizer(self, self.class.release(@ptr))
+    def initialize(ptr, context: nil)
+      initialize_native_object(
+        ptr,
+        release: ->(released) { FFIBindings.lldb_memory_region_info_destroy(released) },
+        context: context
+      )
     end
 
     # @rbs ptr: FFI::Pointer

data/lib/lldb/module.rb

@@ -4,16 +4,21 @@
 
 module LLDB
   class Module
+    prepend NativeLifecycle
+
     # @rbs return: Target?
     attr_reader :target
 
     # @rbs ptr: FFI::Pointer
     # @rbs target: Target?
     # @rbs return: void
-    def initialize(ptr, target:)
-      @ptr = ptr # : FFI::Pointer
+    def initialize(ptr, target:, context: target&.context)
       @target = target
-      ObjectSpace.define_finalizer(self, self.class.release(@ptr))
+      initialize_native_object(
+        ptr,
+        release: ->(released) { FFIBindings.lldb_module_destroy(released) },
+        context: context
+      )
     end
 
     # @rbs ptr: FFI::Pointer
@@ -31,14 +36,34 @@ module LLDB
     def file_path
       return nil unless valid?
 
-      FFIBindings.lldb_module_get_file_path(@ptr)
+      file&.path
     end
 
     # @rbs return: String?
     def platform_file_path
       return nil unless valid?
 
-      FFIBindings.lldb_module_get_platform_file_path(@ptr)
+      platform_file&.path
+    end
+
+    # @rbs return: FileSpec?
+    def file
+      return nil unless valid?
+
+      file_ptr = FFIBindings.lldb_module_get_file(@ptr)
+      return nil if file_ptr.nil? || file_ptr.null?
+
+      FileSpec.from_ptr(file_ptr, context: context)
+    end
+
+    # @rbs return: FileSpec?
+    def platform_file
+      return nil unless valid?
+
+      file_ptr = FFIBindings.lldb_module_get_platform_file(@ptr)
+      return nil if file_ptr.nil? || file_ptr.null?
+
+      FileSpec.from_ptr(file_ptr, context: context)
     end
 
     # @rbs return: Integer
@@ -48,6 +73,22 @@ module LLDB
       FFIBindings.lldb_module_get_num_symbols(@ptr)
     end
 
+    # @rbs index: Integer
+    # @rbs return: Symbol?
+    def symbol_at_index(index)
+      raise InvalidObjectError, 'Module is not valid' unless valid?
+
+      symbol_ptr = FFIBindings.lldb_module_get_symbol_at_index(@ptr, index)
+      return nil if symbol_ptr.nil? || symbol_ptr.null?
+
+      Symbol.new(symbol_ptr, target: @target, context: context)
+    end
+
+    # @rbs return: Array[Symbol]
+    def symbols
+      (0...num_symbols).map { |index| symbol_at_index(index) }.compact
+    end
+
     # @rbs return: String
     def to_s
       file_path || '(unknown module)'

data/lib/lldb/native.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module LLDB
+  module Native
+    # @rbs status: Integer
+    # @rbs operation: String
+    # @rbs error: Error?
+    # @rbs return: bool
+    def self.check_status!(status, operation, error = nil)
+      return true if status == NativeStatus::OK
+
+      if status == NativeStatus::INTERNAL_ERROR
+        message = FFIBindings.lldb_wrapper_last_error_message || 'unknown native exception'
+        code = FFIBindings.lldb_wrapper_last_error_code
+        raise InternalBindingError.new(operation, message, code)
+      end
+
+      native_error = error || Error.new
+      unless native_error.fail?
+        native_error.set_error("native operation failed with status #{status}")
+      end
+      raise OperationError.new(operation, native_error)
+    end
+
+    # @rbs operation: String
+    # @rbs error: Error
+    # @rbs return: true
+    def self.check_error!(operation, error)
+      raise OperationError.new(operation, error) if error.fail?
+
+      true
+    end
+  end
+end

data/lib/lldb/native_buffer.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module LLDB
+  module NativeBuffer
+    # @rbs max_size: Integer?
+    # @rbs &reader: (FFI::Pointer?, Integer) -> Integer
+    # @rbs return: String
+    def self.read_c_string(max_size: nil, &reader)
+      raise ArgumentError, 'max_size must be non-negative' if max_size&.negative?
+      return '' if max_size == 0
+
+      required = reader.call(nil, 0)
+      capacity = if required.positive?
+                   max_size ? [required + 1, max_size].min : required + 1
+                 else
+                   max_size || 256
+                 end
+      capacity = 1 if capacity.zero?
+      loop do
+        buffer = FFI::MemoryPointer.new(:uint8, capacity)
+        written = reader.call(buffer, capacity)
+        bytes = buffer.get_bytes(0, [written, capacity].min).delete_suffix("\0")
+        return bytes if max_size && (capacity >= max_size || written < capacity - 1)
+        return bytes if written < capacity - 1
+
+        capacity = [capacity * 2, written + 2].max
+      end
+    end
+  end
+end

data/lib/lldb/native_handle.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module LLDB
+  class NativeHandle
+    NULL_POINTER = FFI::Pointer.new(0)
+
+    # @rbs ptr: FFI::Pointer
+    # @rbs release: ^(FFI::Pointer) -> void
+    # @rbs return: void
+    def initialize(ptr, release:)
+      # The resource is detached with Array#shift, which is a single Ruby VM
+      # operation. Finalizers cannot safely acquire a Mutex on all supported
+      # Rubies, so the detach itself must not depend on one.
+      @state = [[ptr, release]]
+      ObjectSpace.define_finalizer(self, self.class.finalizer(@state))
+    end
+
+    # @rbs return: FFI::Pointer
+    def to_ptr
+      resource = @state.first
+      resource ? resource.first : NULL_POINTER
+    end
+
+    # @rbs return: bool
+    def closed?
+      @state.empty?
+    end
+
+    # @rbs return: bool
+    def close
+      resource = @state.shift
+      return false unless resource
+
+      pointer, release = resource
+
+      release.call(pointer) unless pointer.null?
+      true
+    end
+
+    # @rbs state: Array[Array[untyped]]
+    # @rbs return: ^(Integer) -> void
+    def self.finalizer(state)
+      ->(_object_id) do
+        resource = state.shift
+        next unless resource
+
+        pointer, release = resource
+        next unless pointer && !pointer.null?
+
+        begin
+          release.call(pointer)
+        rescue StandardError
+          # Finalizers must never raise into an unrelated Ruby thread.
+        end
+      end
+    end
+  end
+end

data/lib/lldb/native_lifecycle.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module LLDB
+  module NativeLifecycle
+    # @rbs return: bool
+    def closed?
+      @native_handle ? @native_handle.closed? : false
+    end
+
+    # @rbs return: bool
+    def close
+      return false unless @native_handle
+      return false if @native_handle.closed?
+
+      send(:close_context) if respond_to?(:close_context, true)
+      @native_handle.close
+      @ptr = NativeHandle::NULL_POINTER
+      true
+    end
+
+    # @rbs return: FFI::Pointer
+    def to_ptr
+      return NativeHandle::NULL_POINTER if closed?
+
+      super
+    end
+
+    # @rbs return: void
+    def ensure_open!
+      raise ClosedObjectError, "#{self.class} is closed" if closed?
+      @context&.ensure_open!
+    end
+
+    # @rbs ptr: FFI::Pointer
+    # @rbs release: ^(FFI::Pointer) -> void
+    # @rbs context: Context?
+    # @rbs return: void
+    def initialize_native_object(ptr, release:, context: nil)
+      @ptr = ptr
+      @context = context
+      @native_handle = NativeHandle.new(ptr, release: release)
+      context&.register(@native_handle)
+    end
+
+    # @rbs return: Context?
+    def context
+      @context
+    end
+
+    # @rbs return: Context
+    def context!
+      context || raise(LifecycleError, 'LLDB object has no context')
+    end
+
+    # @rbs return: bool
+    def valid?
+      return false if closed? || @context&.closed?
+
+      super
+    end
+  end
+end

data/lib/lldb/native_string_array.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module LLDB
+  class NativeStringArray
+    # @rbs strings: Array[String]
+    # @rbs return: void
+    def initialize(strings)
+      @strings = strings.map { |string| NativeStringArray.validate!(string) }
+      @string_pointers = @strings.map { |string| FFI::MemoryPointer.from_string(string) }
+      @pointer_array = FFI::MemoryPointer.new(:pointer, @string_pointers.length + 1)
+
+      @string_pointers.each_with_index do |pointer, index|
+        @pointer_array[index].put_pointer(0, pointer)
+      end
+      @pointer_array[@string_pointers.length].put_pointer(0, nil)
+    end
+
+    # @rbs value: String
+    # @rbs return: String
+    def self.validate!(value)
+      raise ArgumentError, 'native string values must be String' unless value.is_a?(String)
+      raise ArgumentError, 'native strings must not contain NUL bytes' if value.include?("\0")
+
+      value
+    end
+
+    # @rbs return: FFI::Pointer
+    def to_ptr
+      @pointer_array
+    end
+  end
+end