Class: TreeHaver::Backends::FFI::Language

Inherits:
Object
  • Object
show all
Includes:
Comparable
Defined in:
lib/tree_haver/backends/ffi.rb

Overview

Represents a tree-sitter language loaded via FFI

Holds a pointer to a TSLanguage struct from a loaded shared library.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(ptr, lib = nil, path: nil, symbol: nil) ⇒ Language

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of Language.

Parameters:

  • ptr (FFI::Pointer) —

    pointer to TSLanguage

  • lib (FFI::DynamicLibrary, nil) (defaults to: nil) —

    the opened dynamic library (kept as an instance variable to prevent it being GC’d/unloaded)

  • path (String, nil) (defaults to: nil) —

    path language was loaded from

  • symbol (String, nil) (defaults to: nil) —

    symbol name



293
294
295
296
297
298
299
300
301
302
303
304
 
# File 'lib/tree_haver/backends/ffi.rb', line 293

def initialize(ptr, lib = nil, path: nil, symbol: nil)
  @pointer = ptr
  @backend = :ffi
  @path = path
  @symbol = symbol
  # Keep a reference to the DynamicLibrary that produced the language
  # pointer so it isn't garbage-collected and unloaded while the
  # pointer is still in use by the parser. Not keeping this reference
  # can lead to the language pointer becoming invalid and causing
  # segmentation faults when passed to native functions.
  @library = lib
end

Instance Attribute Details

#backend ⇒ Symbol (readonly)

The backend this language is for

Returns:

  • (Symbol) 


277
278
279
 
# File 'lib/tree_haver/backends/ffi.rb', line 277

def backend
  @backend
end

#path ⇒ String? (readonly)

The path this language was loaded from (if known)

Returns:

  • (String, nil) 


281
282
283
 
# File 'lib/tree_haver/backends/ffi.rb', line 281

def path
  @path
end

#pointer ⇒ FFI::Pointer (readonly)

The FFI pointer to the TSLanguage struct

Returns:

  • (FFI::Pointer) 


273
274
275
 
# File 'lib/tree_haver/backends/ffi.rb', line 273

def pointer
  @pointer
end

#symbol ⇒ String? (readonly)

The symbol name (if known)

Returns:

  • (String, nil) 


285
286
287
 
# File 'lib/tree_haver/backends/ffi.rb', line 285

def symbol
  @symbol
end

Class Method Details

.from_library(path, symbol: nil, name: nil) ⇒ Object Also known as: from_path

Raises:



359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
 
# File 'lib/tree_haver/backends/ffi.rb', line 359

def from_library(path, symbol: nil, name: nil)
  raise TreeHaver::NotAvailable, "FFI not available" unless Backends::FFI.available?

  # Check for MRI backend conflict BEFORE loading the grammar
  # If ruby_tree_sitter has already loaded this grammar file, the dynamic
  # linker will return the cached library with symbols resolved against
  # MRI's statically-linked tree-sitter, causing segfaults when FFI
  # tries to use the pointer with its dynamically-linked libtree-sitter.
  if defined?(::TreeSitter::Language)
    # MRI backend has been loaded - check if it might have loaded this grammar
    # We can't reliably detect which grammars MRI loaded, so we warn and
    # attempt to proceed. The segfault will occur when setting language on parser.
    warn("TreeHaver: FFI backend loading grammar after ruby_tree_sitter (MRI backend). " \
      "This may cause segfaults due to tree-sitter symbol conflicts. " \
      "For reliable operation, use only one backend per process.") if $VERBOSE
  end

  # Ensure the core libtree-sitter runtime is loaded first so
  # the language shared library resolves its symbols against the
  # same runtime. This prevents cases where the language pointer
  # is incompatible with the parser (different lib instances).
  Native.try_load!

  begin
    # Prefer resolving symbols immediately and globally so the
    # language library links to the already-loaded libtree-sitter
    # (RTLD_NOW | RTLD_GLOBAL). If those constants are not present
    # fall back to RTLD_LAZY for maximum compatibility.
    flags = if defined?(::FFI::DynamicLibrary::RTLD_NOW) && defined?(::FFI::DynamicLibrary::RTLD_GLOBAL)
      ::FFI::DynamicLibrary::RTLD_NOW | ::FFI::DynamicLibrary::RTLD_GLOBAL
    else
      ::FFI::DynamicLibrary::RTLD_LAZY
    end

    dl = ::FFI::DynamicLibrary.open(path, flags)
  rescue LoadError, RuntimeError => e
    # TruffleRuby raises RuntimeError instead of LoadError when a shared library cannot be opened
    raise TreeHaver::NotAvailable, "Could not open language library at #{path}: #{e.message}"
  end

  requested = symbol || ENV["TREE_SITTER_LANG_SYMBOL"]
  # Use shared utility for consistent symbol derivation across backends
  guessed_symbol = LibraryPathUtils.derive_symbol_from_path(path)
  # If an override was provided (arg or ENV), treat it as strict and do not fall back.
  # Only when no override is provided do we attempt guessed and default candidates.
  candidates = if requested && !requested.to_s.empty?
    [requested]
  else
    [guessed_symbol, "tree_sitter_toml"].compact.uniq
  end

  func = nil
  last_err = nil
  candidates.each do |name|
    addr = dl.find_function(name)
    func = ::FFI::Function.new(:pointer, [], addr)
    break
  rescue StandardError => e
    last_err = e
  end
  unless func
    env_used = []
    env_used << "TREE_SITTER_LANG_SYMBOL=#{ENV["TREE_SITTER_LANG_SYMBOL"]}" if ENV["TREE_SITTER_LANG_SYMBOL"]
    detail = env_used.empty? ? "" : " Env overrides: #{env_used.join(", ")}."
    raise TreeHaver::NotAvailable, "Could not resolve language symbol in #{path} (tried: #{candidates.join(", ")}).#{detail} #{last_err&.message}"
  end

  # Only ensure the core lib is loaded when we actually need to interact with it
  # (e.g., during parsing). Creating the Language handle does not require core to be loaded.
  ptr = func.call
  raise TreeHaver::NotAvailable, "Language factory returned NULL for #{path}" if ptr.null?
  # Pass the opened DynamicLibrary into the Language instance so the
  # library handle remains alive for the lifetime of the Language.
  new(ptr, dl, path: path, symbol: symbol)
end

Instance Method Details

#<=>(other) ⇒ Integer?

Compare languages for equality

FFI languages are equal if they have the same backend, path, and symbol. Path and symbol uniquely identify a loaded language.

Parameters:

  • other (Object) —

    object to compare with

Returns:

  • (Integer, nil) —

    -1, 0, 1, or nil if not comparable



313
314
315
316
317
318
319
320
321
322
 
# File 'lib/tree_haver/backends/ffi.rb', line 313

def <=>(other)
  return unless other.is_a?(Language)
  return unless other.backend == @backend

  # Compare by path first, then symbol
  cmp = (@path || "") <=> (other.path || "")
  return cmp if cmp.nonzero?

  (@symbol || "") <=> (other.symbol || "")
end

#hash ⇒ Integer

Hash value for this language (for use in Sets/Hashes)

Returns:

  • (Integer) 


326
327
328
 
# File 'lib/tree_haver/backends/ffi.rb', line 326

def hash
  [@backend, @path, @symbol].hash
end

#to_ptr ⇒ FFI::Pointer

Convert to FFI pointer for passing to native functions

Returns:

  • (FFI::Pointer) 


336
337
338
 
# File 'lib/tree_haver/backends/ffi.rb', line 336

def to_ptr
  @pointer
end