ruby-changes:25860
From: zzak <ko1@a...>
Date: Wed, 28 Nov 2012 11:09:03 +0900 (JST)
Subject: [ruby-changes:25860] zzak:r37917 (trunk): * ext/fiddle/closure.c: Documentation for Fiddle
zzak 2012-11-28 11:08:39 +0900 (Wed, 28 Nov 2012) New Revision: 37917 http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=37917 Log: * ext/fiddle/closure.c: Documentation for Fiddle * ext/fiddle/lib/fiddle/import.rb: ditto * ext/fiddle/lib/fiddle/value.rb: ditto * ext/fiddle/lib/fiddle/pack.rb: ditto * ext/fiddle/lib/fiddle/cparser.rb: ditto * ext/fiddle/lib/fiddle/struct.rb: ditto * ext/fiddle/lib/fiddle/function.rb: ditto Modified files: trunk/ChangeLog trunk/ext/fiddle/closure.c trunk/ext/fiddle/lib/fiddle/cparser.rb trunk/ext/fiddle/lib/fiddle/function.rb trunk/ext/fiddle/lib/fiddle/import.rb trunk/ext/fiddle/lib/fiddle/pack.rb trunk/ext/fiddle/lib/fiddle/struct.rb trunk/ext/fiddle/lib/fiddle/value.rb Index: ChangeLog =================================================================== --- ChangeLog (revision 37916) +++ ChangeLog (revision 37917) @@ -1,3 +1,13 @@ +Wed Nov 28 11:07:00 2012 Zachary Scott <zachary@z...> + + * ext/fiddle/closure.c: Documentation for Fiddle + * ext/fiddle/lib/fiddle/import.rb: ditto + * ext/fiddle/lib/fiddle/value.rb: ditto + * ext/fiddle/lib/fiddle/pack.rb: ditto + * ext/fiddle/lib/fiddle/cparser.rb: ditto + * ext/fiddle/lib/fiddle/struct.rb: ditto + * ext/fiddle/lib/fiddle/function.rb: ditto + Wed Nov 28 09:15:51 2012 Ryan Davis <ryand-ruby@z...> * ext/strscan/strscan.c: Added #charpos for multibyte string position. Index: ext/fiddle/lib/fiddle/pack.rb =================================================================== --- ext/fiddle/lib/fiddle/pack.rb (revision 37916) +++ ext/fiddle/lib/fiddle/pack.rb (revision 37917) @@ -1,7 +1,7 @@ require 'fiddle' module Fiddle - module PackInfo + module PackInfo # :nodoc: all ALIGN_MAP = { TYPE_VOIDP => ALIGN_VOIDP, TYPE_CHAR => ALIGN_CHAR, @@ -60,7 +60,7 @@ module_function :align end - class Packer + class Packer # :nodoc: all include PackInfo def self.[](*types) Index: ext/fiddle/lib/fiddle/cparser.rb =================================================================== --- ext/fiddle/lib/fiddle/cparser.rb (revision 37916) +++ ext/fiddle/lib/fiddle/cparser.rb (revision 37917) @@ -1,12 +1,25 @@ module Fiddle - # Methods for parsing C struct and C prototype signatures. + # A mixin that provides methods for parsing C struct and prototype signatures. + # + # == Example + # require 'fiddle/import' + # + # include Fiddle::CParser + # #=> Object + # + # parse_ctype('int increment(int)') + # #=> ["increment", Fiddle::TYPE_INT, [Fiddle::TYPE_INT]] + # module CParser # Parses a C struct's members # # Example: # + # include Fiddle::CParser + # #=> Object + # # parse_struct_signature(['int i', 'char c']) - # => [[Fiddle::TYPE_INT, Fiddle::TYPE_CHAR], ["i", "c"]] + # #=> [[Fiddle::TYPE_INT, Fiddle::TYPE_CHAR], ["i", "c"]] # def parse_struct_signature(signature, tymap=nil) if( signature.is_a?(String) ) @@ -45,13 +58,17 @@ # Parses a C prototype signature # + # If Hash +tymap+ is provided, the return value and the arguments from the + # +signature+ are expected to be keys, and the value will be the C type to + # be looked up. + # # Example: # # include Fiddle::CParser - # => Object + # #=> Object # # parse_signature('double sum(double, double)') - # => ["sum", Fiddle::TYPE_DOUBLE, [Fiddle::TYPE_DOUBLE, Fiddle::TYPE_DOUBLE]] + # #=> ["sum", Fiddle::TYPE_DOUBLE, [Fiddle::TYPE_DOUBLE, Fiddle::TYPE_DOUBLE]] # def parse_signature(signature, tymap=nil) tymap ||= {} @@ -74,24 +91,27 @@ end end - # Given a String of C type +ty+, return the corresponding DL constant. + # Given a String of C type +ty+, returns the corresponding Fiddle constant. # - # +ty+ can also accept an Array of C type Strings, and will returned in a - # corresponding Array. + # +ty+ can also accept an Array of C type Strings, and will be returned in + # a corresponding Array. # # If Hash +tymap+ is provided, +ty+ is expected to be the key, and the # value will be the C type to be looked up. # # Example: # + # include Fiddle::CParser + # #=> Object + # # parse_ctype('int') - # => Fiddle::TYPE_INT + # #=> Fiddle::TYPE_INT # # parse_ctype('double') - # => Fiddle::TYPE_DOUBLE + # #=> Fiddle::TYPE_DOUBLE # # parse_ctype('unsigned char') - # => -Fiddle::TYPE_CHAR + # #=> -Fiddle::TYPE_CHAR # def parse_ctype(ty, tymap=nil) tymap ||= {} Index: ext/fiddle/lib/fiddle/struct.rb =================================================================== --- ext/fiddle/lib/fiddle/struct.rb (revision 37916) +++ ext/fiddle/lib/fiddle/struct.rb (revision 37917) @@ -36,14 +36,14 @@ # # Example: # - # require 'dl/struct' - # require 'dl/cparser' + # require 'fiddle/struct' + # require 'fiddle/cparser' # # include Fiddle::CParser # # types, members = parse_struct_signature(['int i','char c']) # - # MyStruct = Fiddle::CStructBuilder.create(CUnion, types, members) + # MyStruct = Fiddle::CStructBuilder.create(Fiddle::CUnion, types, members) # # obj = MyStruct.allocate # @@ -80,18 +80,21 @@ include PackInfo include ValueUtil - # Allocates a C struct the +types+ provided. The C function +func+ is - # called when the instance is garbage collected. + # Allocates a C struct with the +types+ provided. + # + # When the instance is garbage collected, the C function +func+ is called. def CStructEntity.malloc(types, func = nil) addr = Fiddle.malloc(CStructEntity.size(types)) CStructEntity.new(addr, types, func) end - # Given +types+, returns the offset for the packed sizes of those types + # Returns the offset for the packed sizes for the given +types+. # - # Fiddle::CStructEntity.size([Fiddle::TYPE_DOUBLE, Fiddle::TYPE_INT, Fiddle::TYPE_CHAR, - # Fiddle::TYPE_VOIDP]) - # => 24 + # Fiddle::CStructEntity.size( + # [ Fiddle::TYPE_DOUBLE, + # Fiddle::TYPE_INT, + # Fiddle::TYPE_CHAR, + # Fiddle::TYPE_VOIDP ]) #=> 24 def CStructEntity.size(types) offset = 0 @@ -108,10 +111,11 @@ PackInfo.align(offset, max_align) end - # Wraps the C pointer +addr+ as a C struct with the given +types+. The C - # function +func+ is called when the instance is garbage collected. + # Wraps the C pointer +addr+ as a C struct with the given +types+. # - # See also Fiddle::CPtr.new + # When the instance is garbage collected, the C function +func+ is called. + # + # See also Fiddle::Pointer.new def initialize(addr, types, func = nil) set_ctypes(types) super(addr, @size, func) @@ -122,8 +126,7 @@ @members = members end - # Given +types+, calculate the offsets and sizes for the types in the - # struct. + # Calculates the offsets and sizes for the given +types+ in the struct. def set_ctypes(types) @ctypes = types @offset = [] @@ -207,25 +210,29 @@ class CUnionEntity < CStructEntity include PackInfo - # Allocates a C union the +types+ provided. The C function +func+ is - # called when the instance is garbage collected. + # Allocates a C union the +types+ provided. + # + # When the instance is garbage collected, the C function +func+ is called. def CUnionEntity.malloc(types, func=nil) addr = Fiddle.malloc(CUnionEntity.size(types)) CUnionEntity.new(addr, types, func) end - # Given +types+, returns the size needed for the union. + # Returns the size needed for the union with the given +types+. # - # Fiddle::CUnionEntity.size([Fiddle::TYPE_DOUBLE, Fiddle::TYPE_INT, Fiddle::TYPE_CHAR, - # Fiddle::TYPE_VOIDP]) - # => 8 + # Fiddle::CUnionEntity.size( + # [ Fiddle::TYPE_DOUBLE, + # Fiddle::TYPE_INT, + # Fiddle::TYPE_CHAR, + # Fiddle::TYPE_VOIDP ]) #=> 8 def CUnionEntity.size(types) types.map { |type, count = 1| PackInfo::SIZE_MAP[type] * count }.max end - # Given +types+, calculate the necessary offset and for each union member + # Calculate the necessary offset and for each union member with the given + # +types+ def set_ctypes(types) @ctypes = types @offset = Array.new(types.length, 0) Index: ext/fiddle/lib/fiddle/function.rb =================================================================== --- ext/fiddle/lib/fiddle/function.rb (revision 37916) +++ ext/fiddle/lib/fiddle/function.rb (revision 37917) @@ -6,6 +6,7 @@ # The address of this function attr_reader :ptr + # The integer memory location of this function def to_i ptr.to_i end Index: ext/fiddle/lib/fiddle/import.rb =================================================================== --- ext/fiddle/lib/fiddle/import.rb (revision 37916) +++ ext/fiddle/lib/fiddle/import.rb (revision 37917) @@ -3,15 +3,25 @@ require 'fiddle/cparser' module Fiddle + + # Used internally by Fiddle::Importer class CompositeHandler + # Create a new handler with the open +handlers+ + # + # Used internally by Fiddle::Importer.dlload def initialize(handlers) @handlers = handlers end + # Array of the currently loaded libraries. def handlers() @handlers end + # Returns the address as an Integer from any handlers with the function + # named +symbol+. + # + # Raises a DLError if the handle is closed. def sym(symbol) @handlers.each{|handle| if( handle ) @@ -25,32 +35,40 @@ return nil end + # See Fiddle::CompositeHandler.sym def [](symbol) sym(symbol) end end - # DL::Importer includes the means to dynamically load libraries and build + # A DSL that provides the means to dynamically load libraries and build # modules around them including calling extern functions within the C # library that has been loaded. # # == Example # - # require 'dl' - # require 'dl/import' + # require 'fiddle' + # require 'fiddle/import' # # module LibSum - # extend DL::Importer + # extend Fiddle::Importer # dlload './libsum.so' # extern 'double sum(double*, int)' # extern 'double split(double)' # end - # + # module Importer include Fiddle include CParser extend Importer + # Creates an array of handlers for the given +libs+, can be an instance of + # Fiddle::Handle, Fiddle::Importer, or will create a new istance of + # Fiddle::Handle using Fiddle.dlopen + # + # Raises a DLError if the library cannot be loaded. + # + # See Fiddle.dlopen def dlload(*libs) handles = libs.collect{|lib| case lib @@ -73,10 +91,13 @@ @type_alias = {} end + # Sets the type alias for +alias_type+ as +orig_type+ def typealias(alias_type, orig_type) @type_alias[alias_type] = orig_type end + # Returns the sizeof +ty+, using Fiddle::Importer.parse_ctype to determine + # the C type and the appropriate Fiddle constant. def sizeof(ty) case ty when String @@ -126,6 +147,7 @@ end private :parse_bind_options + # Creates a global method from the given C +signature+. def extern(signature, *opts) symname, ctype, argtype = parse_signature(signature, @type_alias) opt = parse_bind_options(opts) @@ -148,6 +170,8 @@ f end + # Creates a global method from the given C +signature+ using the given + # +opts+ as bind parameters with the given block. def bind(signature, *opts, &blk) name, ctype, argtype = parse_signature(signature, @type_alias) h = parse_bind_options(opts) @@ -190,10 +214,15 @@ Fiddle::CStructBuilder.create(CUnion, tys, mems) end + # Returns the function mapped to +name+, that was created by either + # Fiddle::Importer.extern or Fiddle::Importer.bind def [](name) @func_map[name] end + # Creates a class to wrap the C struct with the value +ty+ + # + # See also Fiddle::Importer.struct def create_value(ty, val=nil) s = struct([ty + " value"]) ptr = s.malloc() @@ -204,16 +233,28 @@ end alias value create_value + # Returns a new instance of the C struct with the value +ty+ at the +addr+ + # address. def import_value(ty, addr) s = struct([ty + " value"]) ptr = s.new(addr) return ptr end + + # The Fiddle::CompositeHandler instance + # + # Will raise an error if no handlers are open. def handler @handler or raise "call dlload before importing symbols and functions" end + # Returns a new Fiddle::Pointer instance at the memory address of the given + # +name+ symbol. + # + # Raises a DLError if the +name+ doesn't exist. + # + # See Fiddle::CompositeHandler.sym and Fiddle::Handle.sym def import_symbol(name) addr = handler.sym(name) if( !addr ) @@ -222,6 +263,18 @@ Pointer.new(addr) end + # Returns a new Fiddle::Function instance at the memory address of the given + # +name+ function. + # + # Raises a DLError if the +name+ doesn't exist. + # + # * +argtype+ is an Array of arguments, passed to the +name+ function. + # * +ctype+ is the return type of the function + # * +call_type+ is the ABI of the function + # + # See also Fiddle:Function.new + # + # See Fiddle::CompositeHandler.sym and Fiddle::Handler.sym def import_function(name, ctype, argtype, call_type = nil) addr = handler.sym(name) if( !addr ) @@ -230,6 +283,14 @@ Function.new(addr, argtype, ctype, call_type) end + # Returns a new closure wrapper for the +name+ function. + # + # * +ctype+ is the return type of the function + # * +argtype+ is an Array of arguments, passed to the callback function + # * +call_type+ is the abi of the closure + # * +block+ is passed to the callback + # + # See Fiddle::Closure def bind_function(name, ctype, argtype, call_type = nil, &block) closure = Class.new(Fiddle::Closure) { define_method(:call, block) Index: ext/fiddle/lib/fiddle/value.rb =================================================================== --- ext/fiddle/lib/fiddle/value.rb (revision 37916) +++ ext/fiddle/lib/fiddle/value.rb (revision 37917) @@ -1,7 +1,7 @@ require 'fiddle' module Fiddle - module ValueUtil + module ValueUtil #:nodoc: all def unsigned_value(val, ty) case ty.abs when TYPE_CHAR Index: ext/fiddle/closure.c =================================================================== --- ext/fiddle/closure.c (revision 37916) +++ ext/fiddle/closure.c (revision 37917) @@ -289,7 +289,7 @@ * Construct a new Closure object. * * * +ret+ is the C type to be returned - * * +args+ are passed the callback + * * +args+is an Array of arguments, passed to the callback function * * +abi+ is the abi of the closure * * If there is an error in preparing the ffi_cif or ffi_prep_closure, -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/