nice-ffi 0.1 → 0.2

data/lib/nice-ffi/{nicestruct.rb → struct.rb}

@@ -28,11 +28,6 @@
 #++
 
 
-require 'ffi'
-
-need{ 'typedpointer' }
-
-
 # A class to be used as a baseclass where you would use FFI::Struct.
 # It acts mostly like FFI::Struct, but with nice extra features and
 # conveniences to make life easier:
@@ -49,16 +44,32 @@ need{ 'typedpointer' }
 # * Implements a nicer #new method which allows you to create a new
 #   struct and set its data in one shot by passing an Array, Hash, or
 #   another instance of the class (to copy data). You can also use it
-#   to wrap a FFI::Pointer or FFI::MemoryPointer like FFI::Struct can.
+#   to wrap a FFI::Pointer like FFI::Struct can.
 # 
 # * Implements #to_ary and #to_hash to dump the struct data.
 # 
 # * Implements #to_s and #inspect for nice debugging output.
 # 
+# * Adds ::typed_pointer convenience alias to create a TypedPointer
+#   for this klass.
+#
+# * Provides automatic memory management for Pointers if you define
+#   MyClass.release( pointer). (This can be disabled per-instance by
+#   providing {:autorelease => false} as an option to #new).
+#
 class NiceFFI::Struct < FFI::Struct
+  include NiceFFI::AutoRelease
 
   class << self
 
+    # Returns a NiceFFI::TypedPointer instance for this class.
+    # Equivalent to NiceFFI::TypedPointer.new( this_class, options )
+    # 
+    def typed_pointer( options={} )
+      NiceFFI::TypedPointer.new(self, options)
+    end
+
+
     # Same syntax as FFI::Struct#layout, but also defines nice
     # accessors for the attributes.
     # 
@@ -254,11 +265,8 @@ class NiceFFI::Struct < FFI::Struct
       else
         self.class_eval do
           define_method( member ) do
-            begin
-              self[member]
-            rescue FFI::NullPointerError
-              nil
-            end
+            return nil if self.pointer.null?
+            return self[member]
           end
         end
       end
@@ -306,14 +314,27 @@ class NiceFFI::Struct < FFI::Struct
 
 
   # Create a new instance of the class, reading data from a Hash or
-  # Array of attributes, copying from another instance of the class,
-  # or wrapping (not copying!) a FFI::Pointer or FFI::MemoryPointer.
+  # Array of attributes, a bytestring of raw data, copying from
+  # another instance of the class, or wrapping (not copying!) a
+  # FFI::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 {:autorelease => false}
+  # in +options+.
   # 
-  def initialize( val )
+  # (Note: FFI::MemoryPointer and FFI::Buffer have built-in memory
+  # management, so MyClass.release is never called for them.)
+  # 
+  def initialize( val, options={} )
     # Stores certain kinds of member values so that we don't need
     # to create a new object every time they are read.
     @member_cache = {}
 
+    options = {:autorelease => true}.merge!( options )
+
     case val
 
     when Hash
@@ -325,11 +346,17 @@ class NiceFFI::Struct < FFI::Struct
       super()                       # Create empty struct
       init_from_array( val )        # Read the values from an Array.
 
-    when self.class
+    when String
       super()                       # Create empty struct
-      init_from_array( val.to_ary ) # Read the values from another instance.
+      init_from_bytes( val )        # Read the values from a bytestring.
+
+    when self.class
+      super()                         # Create empty struct
+      init_from_bytes( val.to_bytes ) # Read the values from another instance.
+
+    when FFI::Pointer
+      val = _make_autopointer( val, options[:autorelease] )
 
-    when FFI::Pointer, FFI::MemoryPointer
       # Normal FFI::Struct behavior to wrap the pointer.
       super( val )
 
@@ -356,6 +383,12 @@ class NiceFFI::Struct < FFI::Struct
   private :init_from_array
 
 
+  def init_from_bytes( val )  # :nodoc:
+    self.pointer.put_bytes(0, val)
+  end
+  private :init_from_bytes
+
+
 
   # Dump this instance as an Array of its struct data.
   # The array contains only the data, not the member names.
@@ -372,12 +405,20 @@ class NiceFFI::Struct < FFI::Struct
     members.collect{ |m| self[m] }
   end
 
+
+  # Dump this instance as a string of raw bytes of its struct data.
+  # 
+  def to_bytes
+    return self.pointer.get_bytes(0, self.size)
+  end
+
+
   # Dump this instance as a Hash containing {member => data} pairs
   # for every member in the struct.
   # 
   # Example:
   # 
-  #   Rect.new( :x=>1, :y=>2, :w=>3, :h=>4 ).to_ary
+  #   Rect.new( :x=>1, :y=>2, :w=>3, :h=>4 ).to_hash
   #   # => {:h=>4, :w=>3, :x=>1, :y=>2}
   # 
   def to_hash
@@ -387,12 +428,16 @@ class NiceFFI::Struct < FFI::Struct
 
 
   def to_s
+    if self.pointer.null?
+      return "#<NULL %s:%#.x>"%[self.class.name, self.object_id]
+    end
+
     mems = members.collect{ |m|
       unless self.class.hidden?( m )
         val = self.send(m)
 
         # Cleanup/simplify for display
-        if val.is_a? FFI::NullPointer or val.nil?
+        if val.nil? or (val.is_a? FFI::Pointer and val.null?)
           val = "NULL" 
         elsif val.kind_of? FFI::Struct
           val = "#<#{val.class}:%#.x>"%val.object_id

data/lib/nice-ffi/typedpointer.rb

@@ -28,9 +28,6 @@
 #++
 
 
-require 'ffi'
-
-
 # TypedPointer represents a :pointer (FFI type) that is a specific
 # struct type. You can use TypedPointer( SomeStructClass ) instead
 # of :pointer in these situations:
@@ -46,22 +43,38 @@ class NiceFFI::TypedPointer
   # type must be a class (not an instance) which is a descendent of
   # FFI::Struct (or is FFI::Struct itself).
   # 
-  def initialize( type )
+  # options must be a Hash of zero or more options.
+  # The current meaningful options are:
+  # 
+  # * :autorelease - If false, instances of NiceStruct and
+  #   OpaqueStruct (and subclasses) created via this TypedPointer will
+  #   be passed {:autorelease => false} to disable automatic memory
+  #   management. Use this for return values of functions that should
+  #   not be autoreleased.
+  # 
+  def initialize( type, options={} )
     # unless type.is_a? Class and type.ancestors.include? FFI::Struct
     #   raise TypeError, "#{self.class} only wraps FFI::Struct and subclasses."
     # end
     @type = type
+    options = {:autorelease => true}.merge!( options )
+    @autorelease = options[:autorelease]
   end
 
   attr_reader :type
 
 
-  # Wrap a FFI::Pointer or FFI::MemoryPointer in a new struct of this type.
+  # Wrap a FFI::Pointer in a new struct of this type.
   def wrap( pointer )
-    unless pointer.is_a? FFI::Pointer or pointer.is_a? FFI::MemoryPointer
+    unless pointer.is_a? FFI::Pointer
       raise TypeError, "#{self.class}[ #{@type} ] cannot wrap #{pointer.type}"
     end
-    @type.new( pointer )
+
+    if @type.included_modules.include?( NiceFFI::AutoRelease )
+      @type.new( pointer, :autorelease => @autorelease )
+    else
+      @type.new( pointer )
+    end
   end
 
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: nice-ffi
 version: !ruby/object:Gem::Version 
-  version: "0.1"
+  version: "0.2"
 platform: ruby
 authors: 
 - John Croisant
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-07-05 00:00:00 -05:00
+date: 2009-10-24 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -20,22 +20,11 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        version: 0.3.0
-    version: 
-- !ruby/object:Gem::Dependency 
-  name: need
-  type: :runtime
-  version_requirement: 
-  version_requirements: !ruby/object:Gem::Requirement 
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: 1.1.0
+        version: 0.5.0
     version: 
 description: |
-  Nice-FFI is a layer on top of Ruby-FFI (and compatible FFI
-  systems) to augment that library with features to aide
-  development of FFI-based libraries.
+  Nice-FFI is a layer on top of Ruby-FFI (and compatible FFI systems)
+  with features to ease development of FFI-based libraries.
 
 email: jacius@gmail.com
 executables: []
@@ -48,10 +37,12 @@ files:
 - docs/usage.rdoc
 - TODO.rdoc
 - README.rdoc
+- lib/nice-ffi/autorelease.rb
 - lib/nice-ffi/pathset.rb
-- lib/nice-ffi/nicelibrary.rb
+- lib/nice-ffi/struct.rb
+- lib/nice-ffi/opaquestruct.rb
 - lib/nice-ffi/typedpointer.rb
-- lib/nice-ffi/nicestruct.rb
+- lib/nice-ffi/library.rb
 - lib/nice-ffi.rb
 - ChangeLog.txt
 has_rdoc: true
@@ -77,8 +68,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
   version: 
 requirements: []
 
-rubyforge_project: 
-rubygems_version: 1.3.3
+rubyforge_project: nice-ffi
+rubygems_version: 1.3.5
 signing_key: 
 specification_version: 3
 summary: Convenience layer atop Ruby-FFI