From 9c831edbf4f30fdcf90d8c991ded624c27898874 Mon Sep 17 00:00:00 2001 From: zzak Date: Tue, 27 Nov 2012 23:26:07 +0000 Subject: * ext/fiddle/closure.c: Documentation for Fiddle * ext/fiddle/pointer.c: ditto * ext/fiddle/function.c: ditto * ext/fiddle/lib/fiddle.rb: ditto * ext/fiddle/fiddle.c: ditto * ext/fiddle/handle.c: ditto git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@37909 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- ext/fiddle/closure.c | 6 ++-- ext/fiddle/fiddle.c | 27 +++++++++++++++- ext/fiddle/function.c | 23 ++++++++------ ext/fiddle/handle.c | 28 +++++++++------- ext/fiddle/lib/fiddle.rb | 6 ++++ ext/fiddle/pointer.c | 83 +++++++++++++++++++++++++++++++----------------- 6 files changed, 118 insertions(+), 55 deletions(-) (limited to 'ext') diff --git a/ext/fiddle/closure.c b/ext/fiddle/closure.c index a9a5e14511..3c6dccf51b 100644 --- a/ext/fiddle/closure.c +++ b/ext/fiddle/closure.c @@ -271,11 +271,11 @@ Init_fiddle_closure() * 10 * end * }.new(Fiddle::TYPE_INT, []) - * => #<#:0x0000000150d240> + * #=> #<#:0x0000000150d240> * func = Fiddle::Function.new(closure, [], Fiddle::TYPE_INT) - * => # + * #=> # * func.call - * => 10 + * #=> 10 */ cFiddleClosure = rb_define_class_under(mFiddle, "Closure", rb_cObject); diff --git a/ext/fiddle/fiddle.c b/ext/fiddle/fiddle.c index 06b08639f4..c4b590ca84 100644 --- a/ext/fiddle/fiddle.c +++ b/ext/fiddle/fiddle.c @@ -135,9 +135,34 @@ Init_fiddle(void) /* * Document-module: Fiddle * + * A libffi wrapper for Ruby. + * * == Description * - * A libffi wrapper. + * Fiddle is an extension to translate a foreign function interface (FFI) + * with ruby. + * + * It wraps {libffi}[http://sourceware.org/libffi/], a popular C library + * which provides a portable interface that allows code written in one + * language to clal code written in another language. + * + * == Example + * + * Here we will use Fiddle::Function to wrap {floor(3) from + * libm}[http://linux.die.net/man/3/floor] + * + * require 'fiddle' + * + * libm = Fiddle.dlopen('/lib/libm.so.6') + * + * floor = Fiddle::Function.new( + * libm['floor'], + * [Fiddle::TYPE_DOUBLE], + * Fiddle::TYPE_DOUBLE + * ) + * + * puts floor.call(3.14159) #=> 3.0 + * * */ mFiddle = rb_define_module("Fiddle"); diff --git a/ext/fiddle/function.c b/ext/fiddle/function.c index 7fc5127f9f..4c4bc13abc 100644 --- a/ext/fiddle/function.c +++ b/ext/fiddle/function.c @@ -161,25 +161,28 @@ Init_fiddle_function(void) * * === 'strcpy' * - * @libc = DL.dlopen "/lib/libc.so.6" - * => # - * f = Fiddle::Function.new(@libc['strcpy'], [TYPE_VOIDP, TYPE_VOIDP], TYPE_VOIDP) - * => # + * @libc = Fiddle.dlopen "/lib/libc.so.6" + * #=> # + * f = Fiddle::Function.new( + * @libc['strcpy'], + * [Fiddle::TYPE_VOIDP, Fiddle::TYPE_VOIDP], + * Fiddle::TYPE_VOIDP) + * #=> # * buff = "000" - * => "000" + * #=> "000" * str = f.call(buff, "123") - * => # + * #=> # * str.to_s * => "123" * * === ABI check * * @libc = DL.dlopen "/lib/libc.so.6" - * => # + * #=> # * f = Fiddle::Function.new(@libc['strcpy'], [TYPE_VOIDP, TYPE_VOIDP], TYPE_VOIDP) - * => # + * #=> # * f.abi == Fiddle::Function::DEFAULT - * => true + * #=> true */ cFiddleFunction = rb_define_class_under(mFiddle, "Function", rb_cObject); @@ -218,7 +221,7 @@ Init_fiddle_function(void) * call-seq: new(ptr, *args, ret_type, abi = DEFAULT) * * Constructs a Function object. - * * +ptr+ is a referenced function, of a DL::Handle + * * +ptr+ is a referenced function, of a Fiddle::Handle * * +args+ is an Array of arguments, passed to the +ptr+ function * * +ret_type+ is the return type of the function * * +abi+ is the ABI of the function diff --git a/ext/fiddle/handle.c b/ext/fiddle/handle.c index 346635f6e5..832ff3319a 100644 --- a/ext/fiddle/handle.c +++ b/ext/fiddle/handle.c @@ -56,8 +56,9 @@ static const rb_data_type_t fiddle_handle_data_type = { /* * call-seq: close * - * Close this Fiddle::Handle. Calling close more than once will raise a - * Fiddle::DLError exception. + * Close this handle. + * + * Calling close more than once will raise a Fiddle::DLError exception. */ static VALUE rb_fiddle_handle_close(VALUE self) @@ -112,7 +113,7 @@ predefined_fiddle_handle(void *handle) /* * call-seq: - * initialize(lib = nil, flags = Fiddle::RTLD_LAZY | Fiddle::RTLD_GLOBAL) + * new(lib = nil, flags = Fiddle::RTLD_LAZY | Fiddle::RTLD_GLOBAL) * * Create a new handler that opens library named +lib+ with +flags+. If no * library is specified, RTLD_DEFAULT is used. @@ -194,7 +195,7 @@ rb_fiddle_handle_initialize(int argc, VALUE argv[], VALUE self) /* * call-seq: enable_close * - * Enable a call to dlclose() when this Fiddle::Handle is garbage collected. + * Enable a call to dlclose() when this handle is garbage collected. */ static VALUE rb_fiddle_handle_enable_close(VALUE self) @@ -209,7 +210,7 @@ rb_fiddle_handle_enable_close(VALUE self) /* * call-seq: disable_close * - * Disable a call to dlclose() when this Fiddle::Handle is garbage collected. + * Disable a call to dlclose() when this handle is garbage collected. */ static VALUE rb_fiddle_handle_disable_close(VALUE self) @@ -224,8 +225,9 @@ rb_fiddle_handle_disable_close(VALUE self) /* * call-seq: close_enabled? * - * Returns +true+ if dlclose() will be called when this Fiddle::Handle is - * garbage collected. + * Returns +true+ if dlclose() will be called when this handle is garbage collected. + * + * See man(3) dlclose() for more info. */ static VALUE rb_fiddle_handle_close_enabled_p(VALUE self) @@ -256,7 +258,6 @@ static VALUE fiddle_handle_sym(void *handle, const char *symbol); /* * Document-method: sym - * Document-method: [] * * call-seq: sym(name) * @@ -284,12 +285,13 @@ rb_fiddle_handle_sym(VALUE self, VALUE sym) /* * Document-method: sym - * Document-method: [] * * call-seq: sym(name) * * Get the address as an Integer for the function named +name+. The function - * is searched via dlsym on RTLD_NEXT. See man(3) dlsym() for more info. + * is searched via dlsym on RTLD_NEXT. + * + * See man(3) dlsym() for more info. */ static VALUE rb_fiddle_handle_s_sym(VALUE self, VALUE sym) @@ -386,6 +388,8 @@ Init_fiddle_handle(void) * @handle = Fiddle::Handle.new(libc_so, Fiddle::RTLD_LAZY | Fiddle::RTLD_GLOBAL) * => # * + * See RTLD_LAZY and RTLD_GLOBAL + * * === Addresses to symbols * * strcpy_addr = @handle['strcpy'] @@ -447,8 +451,8 @@ Init_fiddle_handle(void) * * If this value is specified or the environment variable LD_BIND_NOW is * set to a nonempty string, all undefined symbols in the library are - * resolved before dlopen() returns. If this cannot be done an error is - * returned. + * resolved before Fiddle.dlopen returns. If this cannot be done an error + * is returned. */ rb_define_const(rb_cHandle, "RTLD_NOW", INT2NUM(RTLD_NOW)); diff --git a/ext/fiddle/lib/fiddle.rb b/ext/fiddle/lib/fiddle.rb index 1c68b7b0ec..c8a7ef1b05 100644 --- a/ext/fiddle/lib/fiddle.rb +++ b/ext/fiddle/lib/fiddle.rb @@ -27,6 +27,12 @@ module Fiddle Thread.current[:__FIDDLE_LAST_ERROR__] = error end + # call-seq: dlopen(library) => Fiddle::Handle + # + # Creates a new handler that opens +library+, and returns an instance of + # Fiddle::Handle. + # + # See Fiddle::Handle.new for more. def dlopen library Fiddle::Handle.new library end diff --git a/ext/fiddle/pointer.c b/ext/fiddle/pointer.c index 7cf8212cda..8f5fdeb60c 100644 --- a/ext/fiddle/pointer.c +++ b/ext/fiddle/pointer.c @@ -140,11 +140,12 @@ rb_fiddle_ptr_s_allocate(VALUE klass) /* * call-seq: - * Fiddle::Pointer.new(address) => fiddle_cptr - * Fiddle::Pointer.new(address, size) => fiddle_cptr - * Fiddle::Pointer.new(address, size, freefunc) => fiddle_cptr + * Fiddle::Pointer.new(address) => fiddle_cptr + * new(address, size) => fiddle_cptr + * new(address, size, freefunc) => fiddle_cptr * * Create a new pointer to +address+ with an optional +size+ and +freefunc+. + * * +freefunc+ will be called when the instance is garbage collected. */ static VALUE @@ -191,6 +192,7 @@ rb_fiddle_ptr_initialize(int argc, VALUE argv[], VALUE self) * * Allocate +size+ bytes of memory and associate it with an optional * +freefunc+ that will be called when the pointer is garbage collected. + * * +freefunc+ must be an address pointing to a function or an instance of * Fiddle::Function */ @@ -223,7 +225,7 @@ rb_fiddle_ptr_s_malloc(int argc, VALUE argv[], VALUE klass) /* * call-seq: to_i * - * Returns the integer memory location of this DL::CPtr. + * Returns the integer memory location of this pointer. */ static VALUE rb_fiddle_ptr_to_i(VALUE self) @@ -237,7 +239,7 @@ rb_fiddle_ptr_to_i(VALUE self) /* * call-seq: to_value * - * Cast this CPtr to a ruby object. + * Cast this pointer to a ruby object. */ static VALUE rb_fiddle_ptr_to_value(VALUE self) @@ -250,7 +252,9 @@ rb_fiddle_ptr_to_value(VALUE self) /* * call-seq: ptr * - * Returns a DL::CPtr that is a dereferenced pointer for this DL::CPtr. + * Returns a new Fiddle::Pointer instance that is a dereferenced pointer for + * this pointer. + * * Analogous to the star operator in C. */ static VALUE @@ -265,7 +269,9 @@ rb_fiddle_ptr_ptr(VALUE self) /* * call-seq: ref * - * Returns a DL::CPtr that is a reference pointer for this DL::CPtr. + * Returns a new Fiddle::Pointer instance that is a reference pointer for this + * pointer. + * * Analogous to the ampersand operator in C. */ static VALUE @@ -280,7 +286,7 @@ rb_fiddle_ptr_ref(VALUE self) /* * call-seq: null? * - * Returns true if this is a null pointer. + * Returns +true+ if this is a null pointer. */ static VALUE rb_fiddle_ptr_null_p(VALUE self) @@ -294,7 +300,8 @@ rb_fiddle_ptr_null_p(VALUE self) /* * call-seq: free=(function) * - * Set the free function for this pointer to the DL::CFunc in +function+. + * Set the free function for this pointer to +function+ in the given + * Fiddle::Function. */ static VALUE rb_fiddle_ptr_free_set(VALUE self, VALUE val) @@ -308,9 +315,13 @@ rb_fiddle_ptr_free_set(VALUE self, VALUE val) } /* - * call-seq: free + * call-seq: free => Fiddle::Function * - * Get the free function for this pointer. Returns Fiddle::Function. + * Get the free function for this pointer. + * + * Returns a new instance of Fiddle::Function. + * + * See Fiddle::Function.new */ static VALUE rb_fiddle_ptr_free_get(VALUE self) @@ -339,9 +350,14 @@ rb_fiddle_ptr_free_get(VALUE self) * ptr.to_s => string * ptr.to_s(len) => string * - * Returns the pointer contents as a string. When called with no arguments, - * this method will return the contents until the first NULL byte. When - * called with +len+, a string of +len+ bytes will be returned. + * Returns the pointer contents as a string. + * + * When called with no arguments, this method will return the contents until + * the first NULL byte. + * + * When called with +len+, a string of +len+ bytes will be returned. + * + * See to_str */ static VALUE rb_fiddle_ptr_to_s(int argc, VALUE argv[], VALUE self) @@ -372,9 +388,14 @@ rb_fiddle_ptr_to_s(int argc, VALUE argv[], VALUE self) * ptr.to_str => string * ptr.to_str(len) => string * - * Returns the pointer contents as a string. When called with no arguments, - * this method will return the contents with the length of this pointer's - * +size+. When called with +len+, a string of +len+ bytes will be returned. + * Returns the pointer contents as a string. + * + * When called with no arguments, this method will return the contents with the + * length of this pointer's +size+. + * + * When called with +len+, a string of +len+ bytes will be returned. + * + * See to_s */ static VALUE rb_fiddle_ptr_to_str(int argc, VALUE argv[], VALUE self) @@ -403,7 +424,7 @@ rb_fiddle_ptr_to_str(int argc, VALUE argv[], VALUE self) * call-seq: inspect * * Returns a string formatted with an easily readable representation of the - * internal state of the DL::CPtr + * internal state of the pointer. */ static VALUE rb_fiddle_ptr_inspect(VALUE self) @@ -442,8 +463,9 @@ rb_fiddle_ptr_eql(VALUE self, VALUE other) * call-seq: * ptr <=> other => -1, 0, 1, or nil * - * Returns -1 if less than, 0 if equal to, 1 if greater than +other+. Returns - * nil if +ptr+ cannot be compared to +other+. + * Returns -1 if less than, 0 if equal to, 1 if greater than +other+. + * + * Returns nil if +ptr+ cannot be compared to +other+. */ static VALUE rb_fiddle_ptr_cmp(VALUE self, VALUE other) @@ -464,7 +486,7 @@ rb_fiddle_ptr_cmp(VALUE self, VALUE other) * call-seq: * ptr + n => new cptr * - * Returns a new DL::CPtr that has been advanced +n+ bytes. + * Returns a new pointer instance that has been advanced +n+ bytes. */ static VALUE rb_fiddle_ptr_plus(VALUE self, VALUE other) @@ -482,7 +504,7 @@ rb_fiddle_ptr_plus(VALUE self, VALUE other) * call-seq: * ptr - n => new cptr * - * Returns a new DL::CPtr that has been moved back +n+ bytes. + * Returns a new pointer instance that has been moved back +n+ bytes. */ static VALUE rb_fiddle_ptr_minus(VALUE self, VALUE other) @@ -501,9 +523,10 @@ rb_fiddle_ptr_minus(VALUE self, VALUE other) * ptr[index] -> an_integer * ptr[start, length] -> a_string * - * Returns integer stored at _index_. If _start_ and _length_ are given, - * a string containing the bytes from _start_ of length _length_ will be - * returned. + * Returns integer stored at _index_. + * + * If _start_ and _length_ are given, a string containing the bytes from + * _start_ of _length_ will be returned. */ static VALUE rb_fiddle_ptr_aref(int argc, VALUE argv[], VALUE self) @@ -536,9 +559,11 @@ rb_fiddle_ptr_aref(int argc, VALUE argv[], VALUE self) * ptr[index] = int -> int * ptr[start, length] = string or cptr or addr -> string or dl_cptr or addr * - * Set the value at +index+ to +int+. Or, set the memory at +start+ until - * +length+ with the contents of +string+, the memory from +dl_cptr+, or the - * memory pointed at by the memory address +addr+. + * Set the value at +index+ to +int+. + * + * Or, set the memory at +start+ until +length+ with the contents of +string+, + * the memory from +dl_cptr+, or the memory pointed at by the memory address + * +addr+. */ static VALUE rb_fiddle_ptr_aset(int argc, VALUE argv[], VALUE self) @@ -603,8 +628,8 @@ rb_fiddle_ptr_size_get(VALUE self) /* * call-seq: - * Fiddle::Pointer.to_ptr(val) => cptr * Fiddle::Pointer[val] => cptr + * to_ptr(val) => cptr * * Get the underlying pointer for ruby object +val+ and return it as a * Fiddle::Pointer object. -- cgit v1.2.3