модуль Fiddle

Обёртка libffi для Ruby.

Описание

Fiddle — это расширение для работы с интерфейсом вызова внешних функций (FFI) в Ruby.

Оно оборачивает libffi — популярную библиотеку C, предоставляющую переносимый интерфейс, который позволяет коду, написанному на одном языке, вызывать код, написанный на другом языке.

Пример

Здесь мы воспользуемся Fiddle::Function, чтобы обернуть floor(3) из libm

require 'fiddle'

libm = Fiddle.dlopen('/lib/libm.so.6')

floor = Fiddle::Function.new(
  libm['floor'],
  [Fiddle::TYPE_DOUBLE],
  Fiddle::TYPE_DOUBLE
)

puts floor.call(3.14159) #=> 3.0

Константы

ALIGN_BOOL

ALIGN_BOOL

Размер выравнивания типа bool

ALIGN_CHAR

ALIGN_CHAR

Размер выравнивания типа char

ALIGN_DOUBLE

ALIGN_DOUBLE

Размер выравнивания типа double

ALIGN_FLOAT

ALIGN_FLOAT

Размер выравнивания типа float

ALIGN_INT

ALIGN_INT

Размер выравнивания типа int

ALIGN_INT16_T

ALIGN_INT16_T

Размер выравнивания типа int16_t

ALIGN_INT32_T

ALIGN_INT32_T

Размер выравнивания типа int32_t

ALIGN_INT64_T

ALIGN_INT64_T

Размер выравнивания типа int64_t

ALIGN_INT8_T

ALIGN_INT8_T

Размер выравнивания типа int8_t

ALIGN_INTPTR_T

ALIGN_INTPTR_T

Размер выравнивания типа intptr_t

ALIGN_LONG

ALIGN_LONG

Размер выравнивания типа long

ALIGN_LONG_LONG

ALIGN_LONG_LONG

Размер выравнивания типа long long

ALIGN_PTRDIFF_T

ALIGN_PTRDIFF_T

Размер выравнивания типа ptrdiff_t

ALIGN_SHORT

ALIGN_SHORT

Размер выравнивания типа short

ALIGN_SIZE_T

ALIGN_SIZE_T

Размер выравнивания типа size_t

ALIGN_SSIZE_T

ALIGN_SSIZE_T

Размер выравнивания типа ssize_t

ALIGN_UINTPTR_T

ALIGN_UINTPTR_T

Размер выравнивания типа uintptr_t

ALIGN_VOIDP

ALIGN_VOIDP

Размер выравнивания типа void*

BUILD_RUBY_PLATFORM

BUILD_RUBY_PLATFORM

Платформа, для которой выполнена сборка (например, «x86_64-linux» и т. д.)

См. также RUBY_PLATFORM

NULL

Qfalse

Qfalse

Значение Qfalse

Qnil

Qnil

Значение Qnil

Qtrue

Qtrue

Значение Qtrue

Qundef

Qundef

Значение Qundef

RUBY_FREE

RUBY_FREE

Адрес функции ruby_xfree()

SIZEOF_BOOL

SIZEOF_BOOL

Размер типа bool

SIZEOF_CHAR

SIZEOF_CHAR

Размер типа char

SIZEOF_CONST_STRING

SIZEOF_CONST_STRING

Размер типа const char*

SIZEOF_DOUBLE

SIZEOF_DOUBLE

Размер типа double

SIZEOF_FLOAT

SIZEOF_FLOAT

Размер типа float

SIZEOF_INT

SIZEOF_INT

Размер типа int

SIZEOF_INT16_T

SIZEOF_INT16_T

Размер типа int16_t

SIZEOF_INT32_T

SIZEOF_INT32_T

Размер типа int32_t

SIZEOF_INT64_T

SIZEOF_INT64_T

Размер типа int64_t

SIZEOF_INT8_T

SIZEOF_INT8_T

Размер типа int8_t

SIZEOF_INTPTR_T

SIZEOF_INTPTR_T

Размер типа intptr_t

SIZEOF_LONG

SIZEOF_LONG

Размер типа long

SIZEOF_LONG_LONG

SIZEOF_LONG_LONG

Размер типа long long

SIZEOF_PTRDIFF_T

SIZEOF_PTRDIFF_T

Размер типа ptrdiff_t

SIZEOF_SHORT

SIZEOF_SHORT

Размер типа short

SIZEOF_SIZE_T

SIZEOF_SIZE_T

Размер типа size_t

SIZEOF_SSIZE_T

SIZEOF_SSIZE_T

Размер типа ssize_t

SIZEOF_UCHAR

SIZEOF_UCHAR

Размер типа unsigned char

SIZEOF_UINT

SIZEOF_UINT

Размер типа unsigned int

SIZEOF_UINT16_T

SIZEOF_UINT16_T

Размер типа uint16_t

SIZEOF_UINT32_T

SIZEOF_UINT32_T

Размер типа uint32_t

SIZEOF_UINT64_T

SIZEOF_UINT64_T

Размер типа uint64_t

SIZEOF_UINT8_T

SIZEOF_UINT8_T

Размер типа uint8_t

SIZEOF_UINTPTR_T

SIZEOF_UINTPTR_T

Размер типа uintptr_t

SIZEOF_ULONG

SIZEOF_ULONG

Размер типа unsigned long

SIZEOF_ULONG_LONG

SIZEOF_ULONG_LONG

Размер типа unsigned long long

SIZEOF_USHORT

SIZEOF_USHORT

Размер типа unsigned short

SIZEOF_VOIDP

SIZEOF_VOIDP

Размер типа void*

VERSION

WINDOWS

Возвращает логическое значение, указывающее, является ли хост системой WIN32

Общедоступные методы класса

dlopen(library) → Fiddle::Handle Показать исходный код

# File ext/fiddle/lib/fiddle.rb, line 91
def dlopen library
  begin
    Fiddle::Handle.new(library)
  rescue DLError => error
    case RUBY_PLATFORM
    when /linux/
      case error.message
      when /\A(\/.+?): (?:invalid ELF header|file too short)/
        # This may be a linker script:
        # https://sourceware.org/binutils/docs/ld.html#Scripts
        path = $1
      else
        raise
      end
    else
      raise
    end

    File.open(path) do |input|
      input.each_line do |line|
        case line
        when /\A\s*(?:INPUT|GROUP)\s*\(\s*([^\s,\)]+)/
          # TODO: Should we support multiple files?
          first_input = $1
          if first_input.start_with?("-l")
            first_input = "lib#{first_input[2..-1]}.so"
          end
          return dlopen(first_input)
        end
      end
    end

    # Not found
    raise
  end
end

Создаёт новый обработчик, открывающий library, и возвращает экземпляр Fiddle::Handle.

Если для library задано nil, используется Fiddle::Handle::DEFAULT, что эквивалентно RTLD_DEFAULT. Подробнее см. man 3 dlopen.

lib = Fiddle.dlopen(nil)

Значение по умолчанию зависит от ОС и предоставляет дескриптор для всех уже загруженных библиотек. Например, в большинстве случаев с его помощью можно получить доступ к функциям libc или к функциям Ruby, таким как rb_str_new.

Подробнее см. Fiddle::Handle.new.

dlunwrap(addr) Показать исходный код

VALUE
rb_fiddle_ptr2value(VALUE self, VALUE addr)
{
    return (VALUE)NUM2PTR(addr);
}

Возвращает объект Ruby, хранящийся по адресу памяти addr

Пример:

x = Object.new
# => #<Object:0x0000000107c7d870>
Fiddle.dlwrap(x)
# => 4425504880
Fiddle.dlunwrap(_)
# => #<Object:0x0000000107c7d870>

dlwrap(val) Показать исходный код

static VALUE
rb_fiddle_value2ptr(VALUE self, VALUE val)
{
    return PTR2NUM((void*)val);
}

Возвращает адрес памяти объекта Ruby, хранящегося в val

Пример:

x = Object.new
# => #<Object:0x0000000107c7d870>
Fiddle.dlwrap(x)
# => 4425504880

Если val не является объектом, выделенным в куче, этот метод вернёт значение помеченного указателя.

Пример:

Fiddle.dlwrap(123)
# => 247

free(addr) Показать исходный код

VALUE
rb_fiddle_free(VALUE self, VALUE addr)
{
    void *ptr = NUM2PTR(addr);

    ruby_xfree(ptr);
    return Qnil;
}

Освобождает память по адресу addr

last_error () Показать исходный код

# File ext/fiddle/lib/fiddle.rb, line 57
def self.last_error
  if RUBY_ENGINE == 'jruby'
    errno = FFI.errno
    errno == 0 ? nil : errno
  else
    Thread.current[:__FIDDLE_LAST_ERROR__]
  end
end

Возвращает последнюю Error текущего выполняющегося Thread или nil, если её нет

last_error= (error) Показать исходный код

# File ext/fiddle/lib/fiddle.rb, line 67
def self.last_error= error
  if RUBY_ENGINE == 'jruby'
    FFI.errno = error || 0
  else
    Thread.current[:__DL2_LAST_ERROR__] = error
    Thread.current[:__FIDDLE_LAST_ERROR__] = error
  end
end

Устанавливает последнюю Error текущего выполняющегося Thread в значение error

malloc(size) Показать исходный код

static VALUE
rb_fiddle_malloc(VALUE self, VALUE size)
{
    void *ptr;
    ptr = (void*)ruby_xcalloc(1, NUM2SIZET(size));
    return PTR2NUM(ptr);
}

Выделяет size байт памяти и возвращает целочисленный адрес выделенной памяти.

realloc(addr, size) Показать исходный код

static VALUE
rb_fiddle_realloc(VALUE self, VALUE addr, VALUE size)
{
    void *ptr = NUM2PTR(addr);

    ptr = (void*)ruby_xrealloc(ptr, NUM2SIZET(size));
    return PTR2NUM(ptr);
}

Изменяет размер памяти, выделенной по адресу addr, на size байт. Возвращает адрес перераспределённой памяти, который может отличаться от переданного адреса.

win32_last_error () Показать исходный код

# File ext/fiddle/lib/fiddle.rb, line 16
def self.win32_last_error
  if RUBY_ENGINE == 'jruby'
    errno = FFI.errno
    errno == 0 ? nil : errno
  else
    Thread.current[:__FIDDLE_WIN32_LAST_ERROR__]
  end
end

Возвращает последнюю ошибку win32 Error текущего выполняющегося Thread или nil, если её нет

win32_last_error= (error) Показать исходный код

# File ext/fiddle/lib/fiddle.rb, line 26
def self.win32_last_error= error
  if RUBY_ENGINE == 'jruby'
    FFI.errno = error || 0
  else
    Thread.current[:__FIDDLE_WIN32_LAST_ERROR__] = error
  end
end

Устанавливает последнюю ошибку win32 Error текущего выполняющегося Thread в значение error

win32_last_socket_error () Показать исходный код

# File ext/fiddle/lib/fiddle.rb, line 36
def self.win32_last_socket_error
  if RUBY_ENGINE == 'jruby'
    errno = FFI.errno
    errno == 0 ? nil : errno
  else
    Thread.current[:__FIDDLE_WIN32_LAST_SOCKET_ERROR__]
  end
end

Возвращает последнюю ошибку сокета win32 Error текущего выполняющегося Thread или nil, если её нет

win32_last_socket_error= (error) Показать исходный код

# File ext/fiddle/lib/fiddle.rb, line 47
def self.win32_last_socket_error= error
  if RUBY_ENGINE == 'jruby'
    FFI.errno = error || 0
  else
    Thread.current[:__FIDDLE_WIN32_LAST_SOCKET_ERROR__] = error
  end
end

Устанавливает последнюю ошибку сокета win32 Error текущего выполняющегося Thread в значение error

Закрытые методы экземпляра

dlopen(library) → Fiddle::Handle Показать исходный код

# File ext/fiddle/lib/fiddle.rb, line 91
def dlopen library
  begin
    Fiddle::Handle.new(library)
  rescue DLError => error
    case RUBY_PLATFORM
    when /linux/
      case error.message
      when /\A(\/.+?): (?:invalid ELF header|file too short)/
        # This may be a linker script:
        # https://sourceware.org/binutils/docs/ld.html#Scripts
        path = $1
      else
        raise
      end
    else
      raise
    end

    File.open(path) do |input|
      input.each_line do |line|
        case line
        when /\A\s*(?:INPUT|GROUP)\s*\(\s*([^\s,\)]+)/
          # TODO: Should we support multiple files?
          first_input = $1
          if first_input.start_with?("-l")
            first_input = "lib#{first_input[2..-1]}.so"
          end
          return dlopen(first_input)
        end
      end
    end

    # Not found
    raise
  end
end

Создаёт новый обработчик, открывающий library, и возвращает экземпляр Fiddle::Handle.

Если для library задано nil, используется Fiddle::Handle::DEFAULT, что эквивалентно RTLD_DEFAULT. Подробнее см. man 3 dlopen.

lib = Fiddle.dlopen(nil)

Подробнее см. Fiddle::Handle.new.

Ruby Core © 1993–2025 Yukihiro Matsumoto
Licensed under the Ruby License.
Ruby Standard Library © contributors
Licensed under their own licenses.