Class: NiceFFI::OpaqueStruct

Inherits:
Object
  • Object
show all
Includes:
AutoRelease
Defined in:
lib/nice-ffi/opaquestruct.rb

Overview

OpaqueStruct represents a Struct with an unknown layout. This is meant to be used when the C library designer has intentionally hidden the layout (e.g. to prevent user access).

Because the size of an OpaqueStruct is unknown, you should only use methods provided by the C library to allocate, modify, or free the struct’s memory.

OpaqueStruct supports the same memory autorelease system as NiceStruct. Define MyClass.release( pointer ) to call the library function to free the struct, and pass an FFI::Pointer to #new. You can disable autorelease for an individual instance by providing => false as an option to #new

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from AutoRelease

included

Constructor Details

#initialize(val, options = {}) ⇒ OpaqueStruct

Create a new instance of the class, wrapping (not copying!) a FFI::Pointer. You can pass another instance of this class to create a new instance wrapping the same pointer.

If val is an instance of FFI::Pointer and you have defined MyClass.release, the pointer will be passed to MyClass.release when the memory is no longer being used. Use MyClass.release to free the memory for the struct, as appropriate for your class. To disable autorelease for this instance, set => false in options.

(Note: FFI::MemoryPointer and FFI::Buffer have built-in memory management, so MyClass.release is never called for them.)



69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
 
# File 'lib/nice-ffi/opaquestruct.rb', line 69

def initialize( val, options={} )
  options = {:autorelease => true}.merge!( options )

  case val

  when self.class
    initialize( val.pointer, options )

  when FFI::AutoPointer
    @pointer = val

  when FFI::Pointer
    if val.is_a? FFI::MemoryPointer or val.is_a? FFI::Buffer
      raise TypeError, "unsupported pointer type #{val.class.name}"
    elsif val.null?
      @pointer = val
    else
      @pointer = _make_autopointer( val, options[:autorelease] )
    end

  else
    raise TypeError, "cannot create new #{self.class} from #{val.inspect}"

  end
end

Instance Attribute Details

#pointer ⇒ Object (readonly)

Returns the value of attribute pointer.



96
97
98
 
# File 'lib/nice-ffi/opaquestruct.rb', line 96

def pointer
  @pointer
end

Class Method Details

.typed_pointer ⇒ Object

Returns a NiceFFI::TypedPointer instance for this class.



50
51
52
 
# File 'lib/nice-ffi/opaquestruct.rb', line 50

def self.typed_pointer
  @typed_pointer or (@typed_pointer = NiceFFI::TypedPointer.new(self))
end

Instance Method Details

#to_ptr ⇒ Object 



98
99
100
 
# File 'lib/nice-ffi/opaquestruct.rb', line 98

def to_ptr
  @pointer
end

#to_s ⇒ Object Also known as: inspect 



103
104
105
 
# File 'lib/nice-ffi/opaquestruct.rb', line 103

def to_s
  "#<%s:%#.x>"%[self.class.name, self.object_id]
end