ffi 1.2.1 → 1.3.0

data/ext/ffi_c/StructByReference.c

@@ -70,6 +70,12 @@ sbr_allocate(VALUE klass)
     return obj;
 }
 
+/*
+ * call-seq: initialize(struc_class)
+ * @param [Struct] struct_calss
+ * @return [self]
+ * A new instance of StructByReference.
+ */
 static VALUE
 sbr_initialize(VALUE self, VALUE rbStructClass)
 {
@@ -92,6 +98,11 @@ sbr_mark(StructByReference *sbr)
 }
 
 
+/*
+ * call-seq: struct_class
+ * @return [Struct]
+ * Get +struct_class+.
+ */
 static VALUE
 sbr_struct_class(VALUE self)
 {
@@ -102,12 +113,23 @@ sbr_struct_class(VALUE self)
     return sbr->rbStructClass;
 }
 
+/*
+ * call-seq: native_type
+ * @return [Class]
+ * Always get {FFI::Type}::POINTER.
+ */
 static VALUE
 sbr_native_type(VALUE self)
 {
     return rb_const_get(rbffi_TypeClass, rb_intern("POINTER"));
 }
 
+/*
+ * call-seq: to_native(value, ctx)
+ * @param [nil, Struct] value
+ * @param [nil] ctx
+ * @return [AbstractMemory] Pointer on +value+.
+ */
 static VALUE
 sbr_to_native(VALUE self, VALUE value, VALUE ctx)
 {
@@ -130,6 +152,13 @@ sbr_to_native(VALUE self, VALUE value, VALUE ctx)
     return s->rbPointer;
 }
 
+/*
+ * call-seq: from_native(value, ctx)
+ * @param [AbstractMemory] value
+ * @param [nil] ctx
+ * @return [Struct]
+ * Create a struct from content of memory +value+.
+ */
 static VALUE
 sbr_from_native(VALUE self, VALUE value, VALUE ctx)
 {
@@ -144,6 +173,10 @@ sbr_from_native(VALUE self, VALUE value, VALUE ctx)
 void
 rbffi_StructByReference_Init(VALUE moduleFFI)
 {
+    /*
+     * Document-class: FFI::StructByReference
+     * This class includes {FFI::DataConverter} module.
+     */
     rbffi_StructByReferenceClass = rb_define_class_under(moduleFFI, "StructByReference", rb_cObject);
     rb_global_variable(&rbffi_StructByReferenceClass);
     rb_include_module(rbffi_StructByReferenceClass, rb_const_get(moduleFFI, rb_intern("DataConverter")));

data/ext/ffi_c/StructByValue.c

@@ -77,9 +77,9 @@ sbv_initialize(VALUE self, VALUE rbStructClass)
     StructLayout* layout = NULL;
     VALUE rbLayout = Qnil;
 
-    rbLayout = rb_cvar_get(rbStructClass, rb_intern("@layout"));
+    rbLayout = rb_ivar_get(rbStructClass, rb_intern("@layout"));
     if (!rb_obj_is_instance_of(rbLayout, rbffi_StructLayoutClass)) {
-        rb_raise(rb_eTypeError, "wrong type in @layout cvar (expected FFI::StructLayout)");
+        rb_raise(rb_eTypeError, "wrong type in @layout ivar (expected FFI::StructLayout)");
     }
 
     Data_Get_Struct(rbLayout, StructLayout, layout);

data/ext/ffi_c/StructLayout.c

@@ -78,6 +78,14 @@ struct_field_mark(StructField* f)
     rb_gc_mark(f->rbName);
 }
 
+/*
+ * call-seq: initialize(name, offset, type)
+ * @param [String,Symbol] name
+ * @param [Fixnum] offset
+ * @param [FFI::Type] type
+ * @return [self]
+ * A new FFI::StructLayout::Field instance.
+ */
 static VALUE
 struct_field_initialize(int argc, VALUE* argv, VALUE self)
 {
@@ -126,6 +134,11 @@ struct_field_initialize(int argc, VALUE* argv, VALUE self)
     return self;
 }
 
+/*
+ * call-seq: offset
+ * @return [Numeric]
+ * Get the field offset.
+ */
 static VALUE
 struct_field_offset(VALUE self)
 {
@@ -134,6 +147,11 @@ struct_field_offset(VALUE self)
     return UINT2NUM(field->offset);
 }
 
+/*
+ * call-seq: size
+ * @return [Numeric]
+ * Get the field size.
+ */
 static VALUE
 struct_field_size(VALUE self)
 {
@@ -142,6 +160,11 @@ struct_field_size(VALUE self)
     return UINT2NUM(field->type->ffiType->size);
 }
 
+/*
+ * call-seq: alignment
+ * @return [Numeric]
+ * Get the field alignment.
+ */
 static VALUE
 struct_field_alignment(VALUE self)
 {
@@ -150,6 +173,11 @@ struct_field_alignment(VALUE self)
     return UINT2NUM(field->type->ffiType->alignment);
 }
 
+/*
+ * call-seq: type
+ * @return [Type]
+ * Get the field type.
+ */
 static VALUE
 struct_field_type(VALUE self)
 {
@@ -159,6 +187,11 @@ struct_field_type(VALUE self)
     return field->rbType;
 }
 
+/*
+ * call-seq: name
+ * @return [Symbol]
+ * Get the field name.
+ */
 static VALUE
 struct_field_name(VALUE self)
 {
@@ -167,6 +200,12 @@ struct_field_name(VALUE self)
     return field->rbName;
 }
 
+/*
+ * call-seq: get(pointer)
+ * @param [AbstractMemory] pointer pointer on a {Struct}
+ * @return [Object]
+ * Get an object of type {#type} from memory pointed by +pointer+.
+ */
 static VALUE
 struct_field_get(VALUE self, VALUE pointer)
 {
@@ -181,6 +220,13 @@ struct_field_get(VALUE self, VALUE pointer)
     return (*f->memoryOp->get)(MEMORY(pointer), f->offset);
 }
 
+/*
+ * call-seq: put(pointer, value)
+ * @param [AbstractMemory] pointer pointer on a {Struct}
+ * @param [Object] value this object must be a kind of {#type}
+ * @return [self]
+ * Put an object to memory pointed by +pointer+.
+ */
 static VALUE
 struct_field_put(VALUE self, VALUE pointer, VALUE value)
 {
@@ -197,6 +243,12 @@ struct_field_put(VALUE self, VALUE pointer, VALUE value)
     return self;
 }
 
+/*
+ * call-seq: get(pointer)
+ * @param [AbstractMemory] pointer pointer on a {Struct}
+ * @return [Function]
+ * Get a {Function} from memory pointed by +pointer+.
+ */
 static VALUE
 function_field_get(VALUE self, VALUE pointer)
 {
@@ -207,6 +259,15 @@ function_field_get(VALUE self, VALUE pointer)
     return rbffi_Function_NewInstance(f->rbType, (*rbffi_AbstractMemoryOps.pointer->get)(MEMORY(pointer), f->offset));
 }
 
+/*
+ * call-seq: put(pointer, proc)
+ * @param [AbstractMemory] pointer pointer to a {Struct}
+ * @param [Function, Proc] proc
+ * @return [Function]
+ * Set a {Function} to memory pointed by +pointer+ as a function. 
+ *
+ * If a Proc is submitted as +proc+, it is automatically transformed to a {Function}.
+ */
 static VALUE
 function_field_put(VALUE self, VALUE pointer, VALUE proc)
 {
@@ -235,6 +296,12 @@ isCharArray(ArrayType* arrayType)
             || arrayType->componentType->nativeType == NATIVE_UINT8;
 }
 
+/*
+ * call-seq: get(pointer)
+ * @param [AbstractMemory] pointer pointer on a {Struct}
+ * @return [FFI::StructLayout::CharArray, FFI::Struct::InlineArray]
+ * Get an array from a {Struct}.
+ */
 static VALUE
 array_field_get(VALUE self, VALUE pointer)
 {
@@ -252,6 +319,13 @@ array_field_get(VALUE self, VALUE pointer)
             ? rbffi_StructLayoutCharArrayClass : rbffi_StructInlineArrayClass);
 }
 
+/*
+ * call-seq: put(pointer, value)
+ * @param [AbstractMemory] pointer pointer on a {Struct}
+ * @param [String, Array] value +value+ may be a String only if array's type is a kind of +int8+
+ * @return [value]
+ * Set an array in a {Struct}.
+ */
 static VALUE
 array_field_put(VALUE self, VALUE pointer, VALUE value)
 {
@@ -346,6 +420,14 @@ struct_layout_allocate(VALUE klass)
     return obj;
 }
 
+/*
+ * call-seq: initialize(fields, size, align)
+ * @param [Array<StructLayout::Field>] fields
+ * @param [Numeric] size
+ * @param [Numeric] align
+ * @return [self]
+ * A new StructLayout instance.
+ */
 static VALUE
 struct_layout_initialize(VALUE self, VALUE fields, VALUE size, VALUE align)
 {
@@ -411,6 +493,12 @@ struct_layout_initialize(VALUE self, VALUE fields, VALUE size, VALUE align)
     return self;
 }
 
+/* 
+ * call-seq: [](field)
+ * @param [Symbol] field
+ * @return [StructLayout::Field]
+ * Get a field from the layout.
+ */
 static VALUE
 struct_layout_union_bang(VALUE self) 
 {
@@ -455,6 +543,11 @@ struct_layout_aref(VALUE self, VALUE field)
     return rb_hash_aref(layout->rbFieldMap, field);
 }
 
+/*
+ * call-seq: fields
+ * @return [Array<StructLayout::Field>]
+ * Get fields list.
+ */
 static VALUE
 struct_layout_fields(VALUE self)
 {
@@ -465,6 +558,11 @@ struct_layout_fields(VALUE self)
     return rb_ary_dup(layout->rbFields);
 }
 
+/*
+ * call-seq: members
+ * @return [Array<Symbol>]
+ * Get list of field names.
+ */
 static VALUE
 struct_layout_members(VALUE self)
 {
@@ -475,6 +573,11 @@ struct_layout_members(VALUE self)
     return rb_ary_dup(layout->rbFieldNames);
 }
 
+/*
+ * call-seq: to_a
+ * @return [Array<StructLayout::Field>]
+ * Get an array of fields.
+ */
 static VALUE
 struct_layout_to_a(VALUE self)
 {
@@ -507,24 +610,55 @@ struct_layout_free(StructLayout *layout)
 void
 rbffi_StructLayout_Init(VALUE moduleFFI)
 {
-    rbffi_StructLayoutClass = rb_define_class_under(moduleFFI, "StructLayout", rbffi_TypeClass);
+    VALUE ffi_Type = rbffi_TypeClass;
+
+    /*
+     * Document-class: FFI::StructLayout < FFI::Type
+     *
+     * This class aims at defining a struct layout.
+     */
+    rbffi_StructLayoutClass = rb_define_class_under(moduleFFI, "StructLayout", ffi_Type);
     rb_global_variable(&rbffi_StructLayoutClass);
     
+    /*
+     * Document-class: FFI::StructLayout::Field
+     * A field in a {StructLayout}.
+     */
     rbffi_StructLayoutFieldClass = rb_define_class_under(rbffi_StructLayoutClass, "Field", rb_cObject);
     rb_global_variable(&rbffi_StructLayoutFieldClass);
 
+    /*
+     * Document-class: FFI::StructLayout::Number
+     * A numeric {Field} in a {StructLayout}.
+     */
     rbffi_StructLayoutNumberFieldClass = rb_define_class_under(rbffi_StructLayoutClass, "Number", rbffi_StructLayoutFieldClass);
     rb_global_variable(&rbffi_StructLayoutNumberFieldClass);
 
+    /*
+     * Document-class: FFI::StructLayout::String
+     * A string {Field} in a {StructLayout}.
+     */
     rbffi_StructLayoutStringFieldClass = rb_define_class_under(rbffi_StructLayoutClass, "String", rbffi_StructLayoutFieldClass);
     rb_global_variable(&rbffi_StructLayoutStringFieldClass);
 
+    /*
+     * Document-class: FFI::StructLayout::Pointer
+     * A pointer {Field} in a {StructLayout}.
+     */
     rbffi_StructLayoutPointerFieldClass = rb_define_class_under(rbffi_StructLayoutClass, "Pointer", rbffi_StructLayoutFieldClass);
     rb_global_variable(&rbffi_StructLayoutPointerFieldClass);
 
+    /*
+     * Document-class: FFI::StructLayout::Function
+     * A function pointer {Field} in a {StructLayout}.
+     */
     rbffi_StructLayoutFunctionFieldClass = rb_define_class_under(rbffi_StructLayoutClass, "Function", rbffi_StructLayoutFieldClass);
     rb_global_variable(&rbffi_StructLayoutFunctionFieldClass);
 
+    /*
+     * Document-class: FFI::StructLayout::Array
+     * An array {Field} in a {StructLayout}.
+     */
     rbffi_StructLayoutArrayFieldClass = rb_define_class_under(rbffi_StructLayoutClass, "Array", rbffi_StructLayoutFieldClass);
     rb_global_variable(&rbffi_StructLayoutArrayFieldClass);
 

data/ext/ffi_c/Type.c

@@ -100,6 +100,7 @@ type_size(VALUE self)
 /*
  * call-seq: type.alignment
  * @return [Fixnum]
+ * Get Type alignment.
  */
 static VALUE
 type_alignment(VALUE self)

data/ext/ffi_c/extconf.rb

@@ -1,6 +1,6 @@
 #!/usr/bin/env ruby
 
-if !defined?(RUBY_ENGINE) || RUBY_ENGINE == "ruby"
+if !defined?(RUBY_ENGINE) || RUBY_ENGINE == 'ruby' || RUBY_ENGINE == 'rbx'
   require 'mkmf'
   require 'rbconfig'
   dir_config("ffi_c")

data/ffi.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name = 'ffi'
-  s.version = '1.2.1'
+  s.version = '1.3.0'
   s.author = 'Wayne Meissner'
   s.email = 'wmeissner@gmail.com'
   s.homepage = 'http://wiki.github.com/ffi/ffi'

data/lib/ffi.rb

@@ -1,4 +1,5 @@
-if !defined?(RUBY_ENGINE) || RUBY_ENGINE == "ruby"
+if !defined?(RUBY_ENGINE) || RUBY_ENGINE == 'ruby' || RUBY_ENGINE == 'rbx'
+  Object.send(:remove_const, :FFI) if defined?(::FFI)
   begin
     if RUBY_VERSION =~ /1.8/
       require '1.8/ffi_c'

data/lib/ffi/library.rb

@@ -84,6 +84,8 @@ module FFI
     # @raise {LoadError} if a library cannot be opened
     # Load native libraries.
     def ffi_lib(*names)
+      raise LoadError.new("library names list must not be empty") if names.empty?
+
       lib_flags = defined?(@ffi_lib_flags) ? @ffi_lib_flags : FFI::DynamicLibrary::RTLD_LAZY | FFI::DynamicLibrary::RTLD_LOCAL
       ffi_libs = names.map do |name|
 

data/lib/ffi/managedstruct.rb

@@ -1,50 +1,50 @@
 module FFI
   #
-  #  FFI::ManagedStruct allows custom garbage-collection of your FFI::Structs.
-  #
-  #  The typical use case would be when interacting with a library
-  #  that has a nontrivial memory management design, such as a linked
-  #  list or a binary tree.
-  #
-  #  When the Struct instance is garbage collected, FFI::ManagedStruct will
-  #  invoke the class's release() method during object finalization.
-  #
-  #  Example usage:
-  #    module MyLibrary
-  #      ffi_lib "libmylibrary"
-  #      attach_function :new_dlist, [], :pointer
-  #      attach_function :destroy_dlist, [:pointer], :void
+  # FFI::ManagedStruct allows custom garbage-collection of your FFI::Structs.
+  #
+  # The typical use case would be when interacting with a library
+  # that has a nontrivial memory management design, such as a linked
+  # list or a binary tree.
+  #
+  # When the {Struct} instance is garbage collected, FFI::ManagedStruct will
+  # invoke the class's release() method during object finalization.
+  #
+  # @example Example usage:
+  #  module MyLibrary
+  #    ffi_lib "libmylibrary"
+  #    attach_function :new_dlist, [], :pointer
+  #    attach_function :destroy_dlist, [:pointer], :void
+  #  end
+  #  
+  #  class DoublyLinkedList < FFI::ManagedStruct
+  #    @@@
+  #    struct do |s|
+  #      s.name 'struct dlist'
+  #      s.include 'dlist.h'
+  #      s.field :head, :pointer
+  #      s.field :tail, :pointer
   #    end
+  #    @@@
   #
-  #    class DoublyLinkedList < FFI::ManagedStruct
-  #      @@@
-  #      struct do |s|
-  #        s.name 'struct dlist'
-  #        s.include 'dlist.h'
-  #        s.field :head, :pointer
-  #        s.field :tail, :pointer
-  #      end
-  #      @@@
-  #
-  #      def self.release ptr
-  #        MyLibrary.destroy_dlist(ptr)
-  #      end
+  #    def self.release ptr
+  #      MyLibrary.destroy_dlist(ptr)
   #    end
+  #  end
   #
-  #    begin
-  #      ptr = DoublyLinkedList.new(MyLibrary.new_dlist)
-  #      #  do something with the list
-  #    end
-  #    # struct is out of scope, and will be GC'd using DoublyLinkedList#release
+  #  begin
+  #    ptr = DoublyLinkedList.new(MyLibrary.new_dlist)
+  #    #  do something with the list
+  #  end
+  #  # struct is out of scope, and will be GC'd using DoublyLinkedList#release
   #
   #
   class ManagedStruct < FFI::Struct
 
-    # call-seq:
-    #   ManagedStruct.new(pointer)
-    #   ManagedStruct.new
-    #
-    # When passed a pointer, create a new ManagedStruct which will invoke the class method release() on 
+    # @overload initialize(pointer)
+    #  @param [Pointer] pointer
+    #  Create a new ManagedStruct which will invoke the class method #release on 
+    # @overload initialize
+    # A new instance of FFI::ManagedStruct.
     def initialize(pointer=nil)
       raise NoMethodError, "release() not implemented for class #{self}" unless self.class.respond_to? :release
       raise ArgumentError, "Must supply a pointer to memory for the Struct" unless pointer