ffi 1.2.1 → 1.3.0

data/README.md

@@ -22,9 +22,9 @@ using Ruby-FFI [here](http://wiki.github.com/ffi/ffi/why-use-ffi).
 require 'ffi'
 
 module MyLib
-extend FFI::Library
-ffi_lib 'c'
-attach_function :puts, [ :string ], :int
+  extend FFI::Library
+  ffi_lib 'c'
+  attach_function :puts, [ :string ], :int
 end
 
 MyLib.puts 'Hello, World using libc!'
@@ -38,7 +38,10 @@ For less minimalistic and more sane examples you may look at:
 
 ## Requirements
 
-* You need a sane building environment in order to compile the extension.
+You need a sane building environment in order to compile the extension.
+At a minimum, you will need:
+* A C compiler (e.g. Xcode on OSX, gcc on everything else)
+* libffi development library - this is commonly in the libffi-dev or libffi-devel
 
 ## Installation
 
@@ -54,7 +57,9 @@ or from the git repository on github:
 
 ## License
 
-See LICENSE file.
+The ffi library is covered by the LGPL3 license, also see the LICENSE file.
+The specs are shared with Rubyspec and are licensed by the same license
+as Rubyspec, see the LICENSE.SPECS file.
 
 ## Credits
 

data/ext/ffi_c/ArrayType.c

@@ -126,12 +126,16 @@ array_type_element_type(VALUE self)
 void
 rbffi_ArrayType_Init(VALUE moduleFFI)
 {
+    VALUE ffi_Type;
+
+    ffi_Type = rbffi_TypeClass;
+
     /*
      * Document-class: FFI::ArrayType < FFI::Type
      *
      * This is a typed array. The type is a {NativeType native type}.
      */
-    rbffi_ArrayTypeClass = rb_define_class_under(moduleFFI, "ArrayType", rbffi_TypeClass);
+    rbffi_ArrayTypeClass = rb_define_class_under(moduleFFI, "ArrayType", ffi_Type);
     /*
      * Document-variable: FFI::ArrayType
      */
@@ -139,7 +143,7 @@ rbffi_ArrayType_Init(VALUE moduleFFI)
     /*
      * Document-constant: FFI::Type::Array
      */
-    rb_define_const(rbffi_TypeClass, "Array", rbffi_ArrayTypeClass);
+    rb_define_const(ffi_Type, "Array", rbffi_ArrayTypeClass);
 
     rb_define_alloc_func(rbffi_ArrayTypeClass, array_type_s_allocate);
     rb_define_method(rbffi_ArrayTypeClass, "initialize", array_type_initialize, 2);

data/ext/ffi_c/Buffer.c

@@ -310,12 +310,14 @@ buffer_mark(Buffer* ptr)
 void
 rbffi_Buffer_Init(VALUE moduleFFI)
 {
+    VALUE ffi_AbstractMemory =  rbffi_AbstractMemoryClass;
+
     /*
      * Document-class: FFI::Buffer < FFI::AbstractMemory
      *
      * A Buffer is a function argument type. It should be use with functions playing with C arrays.
      */
-    BufferClass = rb_define_class_under(moduleFFI, "Buffer", rbffi_AbstractMemoryClass);
+    BufferClass = rb_define_class_under(moduleFFI, "Buffer", ffi_AbstractMemory);
 
     /*
      * Document-variable: FFI::Buffer

data/ext/ffi_c/Call.c

@@ -79,7 +79,6 @@ typedef int bool;
 
 static void* callback_param(VALUE proc, VALUE cbinfo);
 static inline void* getPointer(VALUE value, int type);
-static inline char* getString(VALUE value, int type);
 
 static ID id_to_ptr, id_map_symbol, id_to_native;
 
@@ -221,7 +220,18 @@ rbffi_SetupCallParams(int argc, VALUE* argv, int paramCount, Type** paramTypes,
 
 
             case NATIVE_STRING:
-                param->ptr = getString(argv[argidx++], type);
+                if (type == T_NIL) {
+                    param->ptr = NULL; 
+                
+                } else {
+                    if (rb_safe_level() >= 1 && OBJ_TAINTED(argv[argidx])) {
+                        rb_raise(rb_eSecurityError, "Unsafe string parameter");
+                    }
+
+                    param->ptr = StringValueCStr(argv[argidx]);
+                    ++argidx;
+                }
+
                 ADJ(param, ADDRESS);
                 break;
 
@@ -397,25 +407,6 @@ getPointer(VALUE value, int type)
     return NULL;
 }
 
-static inline char*
-getString(VALUE value, int type)
-{
-    if (type == T_STRING) {
-
-        if (rb_safe_level() >= 1 && OBJ_TAINTED(value)) {
-            rb_raise(rb_eSecurityError, "Unsafe string parameter");
-        }
-
-        return StringValueCStr(value);
-
-    } else if (type == T_NIL) {
-        return NULL;
-    }
-
-    rb_raise(rb_eArgError, "Invalid String value");
-}
-
-
 Invoker
 rbffi_GetInvoker(FunctionType *fnInfo)
 {

data/ext/ffi_c/FunctionInfo.c

@@ -91,6 +91,17 @@ fntype_free(FunctionType* fnInfo)
     xfree(fnInfo);
 }
 
+/*
+ * call-seq: initialize(return_type, param_types, options={})
+ * @param [Type, Symbol] return_type return type for the function
+ * @param [Array<Type, Symbol>] param_types array of parameters types
+ * @param [Hash] options
+ * @option options [Boolean] :blocking set to true if the C function is a blocking call
+ * @option options [Symbol] :convention calling convention see {FFI::Library#calling_convention}
+ * @option options [FFI::Enums] :enums
+ * @return [self]
+ * A new FunctionType instance.
+ */
 static VALUE
 fntype_initialize(int argc, VALUE* argv, VALUE self)
 {
@@ -186,6 +197,11 @@ fntype_initialize(int argc, VALUE* argv, VALUE self)
     return self;
 }
 
+/*
+ * call-seq: result_type
+ * @return [Type]
+ * Get the return type of the function type
+ */
 static VALUE
 fntype_result_type(VALUE self)
 {
@@ -196,6 +212,11 @@ fntype_result_type(VALUE self)
     return ft->rbReturnType;
 }
 
+/*
+ * call-seq: param_types
+ * @return [Array<Type>]
+ * Get parameters types.
+ */
 static VALUE
 fntype_param_types(VALUE self)
 {
@@ -209,10 +230,14 @@ fntype_param_types(VALUE self)
 void
 rbffi_FunctionInfo_Init(VALUE moduleFFI)
 {
+    VALUE ffi_Type;
+
+    ffi_Type = rbffi_TypeClass;
+
     /*
      * Document-class: FFI::FunctionType < FFI::Type
      */
-    rbffi_FunctionTypeClass = rb_define_class_under(moduleFFI, "FunctionType", rbffi_TypeClass);
+    rbffi_FunctionTypeClass = rb_define_class_under(moduleFFI, "FunctionType",ffi_Type);
     rb_global_variable(&rbffi_FunctionTypeClass);
     /*
      * Document-const: FFI::CallbackInfo = FFI::FunctionType
@@ -225,7 +250,7 @@ rbffi_FunctionInfo_Init(VALUE moduleFFI)
     /*
      * Document-const: FFI::Type::Function = FFI::FunctionType
      */
-    rb_define_const(rbffi_TypeClass, "Function", rbffi_FunctionTypeClass);
+    rb_define_const(ffi_Type, "Function", rbffi_FunctionTypeClass);
 
     rb_define_alloc_func(rbffi_FunctionTypeClass, fntype_allocate);
     rb_define_method(rbffi_FunctionTypeClass, "initialize", fntype_initialize, -1);

data/ext/ffi_c/MappedType.c

@@ -138,9 +138,8 @@ mapped_from_native(int argc, VALUE* argv, VALUE self)
 void
 rbffi_MappedType_Init(VALUE moduleFFI)
 {
-    
     /* 
-     * Document-class: FFI::Type::Mapped
+     * Document-class: FFI::Type::Mapped < FFI::Type
      */
     rbffi_MappedTypeClass = rb_define_class_under(rbffi_TypeClass, "Mapped", rbffi_TypeClass);
     

data/ext/ffi_c/MemoryPointer.c

@@ -63,6 +63,14 @@ memptr_allocate(VALUE klass)
     return obj;
 }
 
+/*
+ * call-seq: initialize(size, count=1, clear=true)
+ * @param [Fixnum, Bignum, Symbol, FFI::Type] size size of a memory cell (in bytes, or type whom size will be used)
+ * @param [Numeric] count number of cells in memory
+ * @param [Boolean] clear set memory to all-zero if +true+
+ * @return [self]
+ * A new instance of FFI::MeoryPointer.
+ */
 static VALUE
 memptr_initialize(int argc, VALUE* argv, VALUE self)
 {
@@ -71,7 +79,7 @@ memptr_initialize(int argc, VALUE* argv, VALUE self)
 
     memptr_malloc(self, rbffi_type_size(size), nargs > 1 ? NUM2LONG(count) : 1,
         RTEST(clear) || clear == Qnil);
-    
+
     if (rb_block_given_p()) {
         return rb_ensure(rb_yield, self, memptr_free, self);
     }
@@ -100,7 +108,7 @@ memptr_malloc(VALUE self, long size, long count, bool clear)
     /* ensure the memory is aligned on at least a 8 byte boundary */
     p->memory.address = (char *) (((uintptr_t) p->storage + 0x7) & (uintptr_t) ~0x7UL);;
     p->allocated = true;
-    
+
     if (clear && p->memory.size > 0) {
         memset(p->memory.address, 0, p->memory.size);
     }
@@ -136,6 +144,12 @@ memptr_release(Pointer* ptr)
     xfree(ptr);
 }
 
+/*
+ * call-seq: from_string(s)
+ * @param [String] s string
+ * @return [MemoryPointer]
+ * Create a {MemoryPointer} with +s+ inside.
+ */
 static VALUE
 memptr_s_from_string(VALUE klass, VALUE to_str)
 {
@@ -143,14 +157,31 @@ memptr_s_from_string(VALUE klass, VALUE to_str)
     VALUE args[] = { INT2FIX(1), LONG2NUM(RSTRING_LEN(s) + 1), Qfalse };
     VALUE obj = rb_class_new_instance(3, args, klass);
     rb_funcall(obj, rb_intern("put_string"), 2, INT2FIX(0), s);
-    
+
     return obj;
 }
 
 void
 rbffi_MemoryPointer_Init(VALUE moduleFFI)
 {
-    rbffi_MemoryPointerClass = rb_define_class_under(moduleFFI, "MemoryPointer", rbffi_PointerClass);
+    VALUE ffi_Pointer;
+
+    ffi_Pointer = rbffi_PointerClass;
+
+    /*
+     * Document-class: FFI::MemoryPointer < FFI::Pointer
+     * A MemoryPointer is a specific {Pointer}. It points to a memory composed of cells. All cells have the
+     * same size.
+     *
+     * @example Create a new MemoryPointer
+     *  mp = FFI::MemoryPointer.new(:long, 16)   # Create a pointer on a memory of 16 long ints.
+     * @example Create a new MemoryPointer from a String
+     *  mp1 = FFI::MemoryPointer.from_string("this is a string")
+     *  # same as:
+     *  mp2 = FFI::MemoryPointer.new(:char,16)
+     *  mp2.put_string("this is a string")
+     */
+    rbffi_MemoryPointerClass = rb_define_class_under(moduleFFI, "MemoryPointer", ffi_Pointer);
     rb_global_variable(&rbffi_MemoryPointerClass);
 
     rb_define_alloc_func(rbffi_MemoryPointerClass, memptr_allocate);

data/ext/ffi_c/Pointer.c

@@ -322,9 +322,9 @@ ptr_address(VALUE self)
 
 /*
  * Get or set +self+'s endianness
- * @overload ptr.order
+ * @overload order
  *  @return [:big, :little] endianness of +self+
- * @overload ptr.order(order)
+ * @overload order(order)
  *  @param  [Symbol] order endianness to set (+:little+, +:big+ or +:network+). +:big+ and +:network+ 
  *   are synonymous.
  *  @return [self]
@@ -449,8 +449,9 @@ void
 rbffi_Pointer_Init(VALUE moduleFFI)
 {
     VALUE rbNullAddress = ULL2NUM(0);
+    VALUE ffi_AbstractMemory =  rbffi_AbstractMemoryClass;
 
-    /* 
+    /*
      * Document-class: FFI::Pointer < FFI::AbstractMemory
      * Pointer class is used to manage C pointers with ease. A {Pointer} object is defined by his
      * {#address} (as a C pointer). It permits additions with an integer for pointer arithmetic.
@@ -459,7 +460,7 @@ rbffi_Pointer_Init(VALUE moduleFFI)
      * A pointer object may autorelease his contents when freed (by default). This behaviour may be
      * changed with {#autorelease=} method.
      */
-    rbffi_PointerClass = rb_define_class_under(moduleFFI, "Pointer", rbffi_AbstractMemoryClass);
+    rbffi_PointerClass = rb_define_class_under(moduleFFI, "Pointer", ffi_AbstractMemory);
     /*
      * Document-variable: Pointer
      */

data/ext/ffi_c/Struct.c

@@ -90,6 +90,13 @@ struct_allocate(VALUE klass)
     return obj;
 }
 
+/*
+ * call-seq: initialize
+ * @overload initialize(pointer, *args)
+ *  @param [AbstractMemory] pointer
+ *  @param [Array] args
+ * @return [self]
+ */
 static VALUE
 struct_initialize(int argc, VALUE* argv, VALUE self)
 {
@@ -124,6 +131,11 @@ struct_initialize(int argc, VALUE* argv, VALUE self)
     return self;
 }
 
+/*
+ * call-seq: initialize_copy(other)
+ * @return [nil]
+ * DO NOT CALL THIS METHOD
+ */
 static VALUE
 struct_initialize_copy(VALUE self, VALUE other)
 {
@@ -165,11 +177,11 @@ static VALUE
 struct_class_layout(VALUE klass)
 {
     VALUE layout;
-    if (!rb_cvar_defined(klass, id_layout_ivar)) {
+    if (!rb_ivar_defined(klass, id_layout_ivar)) {
         rb_raise(rb_eRuntimeError, "no Struct layout configured for %s", rb_class2name(klass));
     }
 
-    layout = rb_cvar_get(klass, id_layout_ivar);
+    layout = rb_ivar_get(klass, id_layout_ivar);
     if (!rb_obj_is_kind_of(layout, rbffi_StructLayoutClass)) {
         rb_raise(rb_eRuntimeError, "invalid Struct layout for %s", rb_class2name(klass));
     }
@@ -279,6 +291,11 @@ struct_field(Struct* s, VALUE fieldName)
     return rbField;
 }
 
+/*
+ * call-seq: struct[field_name]
+ * @param field_name field to access
+ * Acces to a Struct field.
+ */
 static VALUE
 struct_aref(VALUE self, VALUE fieldName)
 {
@@ -304,6 +321,13 @@ struct_aref(VALUE self, VALUE fieldName)
     }
 }
 
+/*
+ * call-seq: []=(field_name, value)
+ * @param field_name field to access
+ * @param value value to set to +field_name+
+ * @return [value]
+ * Set a field in Struct.
+ */
 static VALUE
 struct_aset(VALUE self, VALUE fieldName, VALUE value)
 {
@@ -338,6 +362,12 @@ struct_aset(VALUE self, VALUE fieldName, VALUE value)
     return value;
 }
 
+/*
+ * call-seq: pointer= pointer
+ * @param [AbstractMemory] pointer
+ * @return [self]
+ * Make Struct point to +pointer+.
+ */
 static VALUE
 struct_set_pointer(VALUE self, VALUE pointer)
 {
@@ -368,6 +398,11 @@ struct_set_pointer(VALUE self, VALUE pointer)
     return self;
 }
 
+/*
+ * call-seq: pointer
+ * @return [AbstractMemory]
+ * Get pointer to Struct contents.
+ */
 static VALUE
 struct_get_pointer(VALUE self)
 {
@@ -378,6 +413,12 @@ struct_get_pointer(VALUE self)
     return s->rbPointer;
 }
 
+/*
+ * call-seq: layout= layout
+ * @param [StructLayout] layout
+ * @return [self]
+ * Set the Struct's layout.
+ */
 static VALUE
 struct_set_layout(VALUE self, VALUE layout)
 {
@@ -396,6 +437,11 @@ struct_set_layout(VALUE self, VALUE layout)
     return self;
 }
 
+/*
+ * call-seq: layout
+ * @return [StructLayout]
+ * Get the Struct's layout.
+ */
 static VALUE
 struct_get_layout(VALUE self)
 {
@@ -406,7 +452,11 @@ struct_get_layout(VALUE self)
     return s->rbLayout;
 }
 
-
+/*
+ * call-seq: null?
+ * @return [Boolean]
+ * Test if Struct's pointer is NULL
+ */
 static VALUE
 struct_null_p(VALUE self)
 {
@@ -417,6 +467,9 @@ struct_null_p(VALUE self)
     return s->pointer->address == NULL ? Qtrue : Qfalse;
 }
 
+/*
+ * (see Pointer#order)
+ */
 static VALUE
 struct_order(int argc, VALUE* argv, VALUE self)
 {
@@ -435,7 +488,6 @@ struct_order(int argc, VALUE* argv, VALUE self)
     }
 }
 
-
 static VALUE
 inline_array_allocate(VALUE klass)
 {
@@ -456,6 +508,13 @@ inline_array_mark(InlineArray* array)
     rb_gc_mark(array->rbMemory);
 }
 
+/*
+ * Document-method: FFI::Struct::InlineArray#initialize
+ * call-seq: initialize(memory, field)
+ * @param [AbstractMemory] memory
+ * @param [StructField] field
+ * @return [self]
+ */
 static VALUE
 inline_array_initialize(VALUE self, VALUE rbMemory, VALUE rbField)
 {
@@ -480,6 +539,11 @@ inline_array_initialize(VALUE self, VALUE rbMemory, VALUE rbField)
     return self;
 }
 
+/*
+ * call-seq: size
+ * @return [Numeric]
+ * Get size
+ */
 static VALUE
 inline_array_size(VALUE self)
 {
@@ -500,6 +564,11 @@ inline_array_offset(InlineArray* array, int index)
     return (int) array->field->offset + (index * (int) array->componentType->ffiType->size);
 }
 
+/*
+ * call-seq: [](index)
+ * @param [Numeric] index
+ * @return [Type, Struct]
+ */
 static VALUE
 inline_array_aref(VALUE self, VALUE rbIndex)
 {
@@ -530,6 +599,12 @@ inline_array_aref(VALUE self, VALUE rbIndex)
     }
 }
 
+/*
+ * call-seq: []=(index, value)
+ * @param [Numeric] index
+ * @param [Type, Struct]
+ * @return [value]
+ */
 static VALUE
 inline_array_aset(VALUE self, VALUE rbIndex, VALUE rbValue)
 {
@@ -574,6 +649,10 @@ inline_array_aset(VALUE self, VALUE rbIndex, VALUE rbValue)
     return rbValue;
 }
 
+/*
+ * call-seq: each
+ * Yield block for each element of +self+.
+ */
 static VALUE
 inline_array_each(VALUE self)
 {
@@ -590,6 +669,11 @@ inline_array_each(VALUE self)
     return self;
 }
 
+/*
+ * call-seq: to_a
+ * @return [Array]
+ * Convert +self+ to an array.
+ */
 static VALUE
 inline_array_to_a(VALUE self)
 {
@@ -608,6 +692,12 @@ inline_array_to_a(VALUE self)
     return obj;
 }
 
+/*
+ * Document-method: FFI::StructLayout::CharArray#to_s
+ * call-seq: to_s
+ * @return [String]
+ * Convert +self+ to a string.
+ */
 static VALUE
 inline_array_to_s(VALUE self)
 {
@@ -627,7 +717,11 @@ inline_array_to_s(VALUE self)
     return rb_funcall2(array->rbMemory, rb_intern("get_string"), 2, argv);
 }
 
-
+/*
+ * call-seq: to_ptr
+ * @return [AbstractMemory]
+ * Get pointer to +self+ content.
+ */
 static VALUE
 inline_array_to_ptr(VALUE self)
 {
@@ -647,14 +741,37 @@ rbffi_Struct_Init(VALUE moduleFFI)
 
     rbffi_StructLayout_Init(moduleFFI);
 
-    rbffi_StructClass = StructClass = rb_define_class_under(moduleFFI, "Struct", rb_cObject);
+    /*
+     * Document-class: FFI::Struct
+     *
+     * A FFI::Struct means to mirror a C struct.
+     *
+     * A Struct is defined as:
+     *  class MyStruct < FFI::Struct
+     *    layout :value1, :int,
+     *           :value2, :double
+     *  end
+     * and is used as:
+     *  my_struct = MyStruct.new
+     *  my_struct[:value1] = 12
+     *
+     * For more information, see http://github.com/ffi/ffi/wiki/Structs
+     */
+    rbffi_StructClass = rb_define_class_under(moduleFFI, "Struct", rb_cObject);
+    StructClass = rbffi_StructClass; // put on a line alone to help RDoc
     rb_global_variable(&rbffi_StructClass);
 
+    /*
+     * Document-class: FFI::Struct::InlineArray
+     */
     rbffi_StructInlineArrayClass = rb_define_class_under(rbffi_StructClass, "InlineArray", rb_cObject);
     rb_global_variable(&rbffi_StructInlineArrayClass);
 
-    rbffi_StructLayoutCharArrayClass = rb_define_class_under(rbffi_StructLayoutClass,
-        "CharArray", rbffi_StructInlineArrayClass);
+    /*
+     * Document-class: FFI::StructLayout::CharArray < FFI::Struct::InlineArray
+     */
+    rbffi_StructLayoutCharArrayClass = rb_define_class_under(rbffi_StructLayoutClass, "CharArray", 
+                                                             rbffi_StructInlineArrayClass);
     rb_global_variable(&rbffi_StructLayoutCharArrayClass);