Class: FFI::AutoPointer

Inherits:
Pointer show all
Extended by:
DataConverter
Defined in:
lib/ffi/autopointer.rb

Defined Under Namespace

Classes: CallableReleaser, DefaultReleaser, Releaser

Constant Summary

Constant Summary

Constants inherited from Pointer

Pointer::NULL, Pointer::SIZE

Class Method Summary (collapse)

Instance Method Summary (collapse)

Methods included from DataConverter

from_native, native_type, to_native

Methods inherited from Pointer

#+, #==, #address, #initialize_copy, #inspect, #null?, #order, #read_array_of_type, #read_string, #read_string_length, #read_string_to_null, size, #slice, #to_s, #type_size, #write_array_of_type, #write_string, #write_string_length

Methods inherited from AbstractMemory

#[], #__copy_from__, #clear, #get_array_of_float32, #get_array_of_float64, #get_array_of_pointer, #get_array_of_string, #get_bytes, #get_float32, #get_float64, #get_pointer, #get_string, #put_array_of_float32, #put_array_of_float64, #put_array_of_pointer, #put_bytes, #put_float32, #put_float64, #put_pointer, #put_string, #read_array_of_double, #read_array_of_float, #read_array_of_pointer, #read_bytes, #read_double, #read_float, #read_pointer, #total, #type_size, #write_array_of_double, #write_array_of_float, #write_array_of_pointer, #write_bytes, #write_double, #write_float, #write_pointer

Constructor Details

- (self) initialize(pointer, method) - (self) initialize(pointer, proc) - (self) initialize(pointer) {|p| ... } - (self) initialize(pointer)

Note:

The safest, and therefore preferred, calling idiom is to pass a Method as the second parameter. Example usage:

class PointerHelper
  def self.release(pointer)
    ...
  end
end

p = AutoPointer.new(other_pointer, PointerHelper.method(:release))

The above code will cause PointerHelper#release to be invoked at GC time.

Note:

The last calling idiom (only one parameter) is generally only going to be useful if you subclass FFI::AutoPointer, and override #release, which by default does nothing.

Returns a new instance of AutoPointer

Overloads:

  • - (self) initialize(pointer, method)

    The passed Method will be invoked at GC time.

  • - (self) initialize(pointer, proc)
    Note:

    WARNING: passing a proc may cause your pointer to never be GC'd, unless you're careful to avoid trapping a reference to the pointer in the proc. See the test specs for examples.

    The passed Proc will be invoked at GC time (SEE WARNING BELOW!)

  • - (self) initialize(pointer) {|p| ... }
    Note:

    WARNING: passing a block will cause your pointer to never be GC'd. This is bad.

    The passed block will be invoked at GC time.

    Yield Parameters:

    • p (Pointer)

      pointer passed to the block

  • - (self) initialize(pointer)

    The pointer's release() class method will be invoked at GC time.

Raises:

  • (TypeError)


76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
# File 'lib/ffi/autopointer.rb', line 76

def initialize(ptr, proc=nil, &block)
  super(ptr.type_size, ptr)
  raise TypeError, "Invalid pointer" if ptr.nil? || !ptr.kind_of?(Pointer) \
    || ptr.kind_of?(MemoryPointer) || ptr.kind_of?(AutoPointer)

  @releaser = if proc
                raise RuntimeError.new("proc must be callable") unless proc.respond_to?(:call)
                CallableReleaser.new(ptr, proc)

              else
                raise RuntimeError.new("no release method defined") unless self.class.respond_to?(:release)
                DefaultReleaser.new(ptr, self.class)
              end

  ObjectSpace.define_finalizer(self, @releaser)
  self
end

Class Method Details

+ (AutoPointer) self.from_native(ptr, ctx)

Create a new AutoPointer.

Override DataConverter#from_native.



189
190
191
# File 'lib/ffi/autopointer.rb', line 189

def self.from_native(val, ctx)
  self.new(val)
end

+ (Type::POINTER) native_type

Return native type of AutoPointer.

Override DataConverter#native_type.

Raises:

  • (RuntimeError)

    if class does not implement a #release method



177
178
179
180
# File 'lib/ffi/autopointer.rb', line 177

def self.native_type
  raise RuntimeError.new("no release method defined for #{self.inspect}") unless self.respond_to?(:release)
  Type::POINTER
end

Instance Method Details

- (Boolean) autorelease=(autorelease)

Set autorelease property. See Autorelease section at Pointer.



103
104
105
# File 'lib/ffi/autopointer.rb', line 103

def autorelease=(autorelease)
  @releaser.autorelease=(autorelease)
end

- (Boolean) autorelease?

Get autorelease property. See Autorelease section at Pointer.



109
110
111
# File 'lib/ffi/autopointer.rb', line 109

def autorelease?
  @releaser.autorelease
end

- (nil) free

Free the pointer.



96
97
98
# File 'lib/ffi/autopointer.rb', line 96

def free
  @releaser.free
end