ffi 1.0.0 → 1.17.1

data/lib/ffi/tools/const_generator.rb

@@ -3,25 +3,41 @@ require 'open3'
 
 module FFI
 
-  ##
   # ConstGenerator turns C constants into ruby values.
-
+  #
+  # @example a simple example for stdio
+  #  require 'ffi/tools/const_generator'
+  #  cg = FFI::ConstGenerator.new('stdio') do |gen|
+  #    gen.const(:SEEK_SET)
+  #    gen.const('SEEK_CUR')
+  #    gen.const('seek_end')   # this constant does not exist
+  #  end            # #calculate called automatically at the end of the block
+  #
+  #  cg['SEEK_SET'] # => 0
+  #  cg['SEEK_CUR'] # => 1
+  #  cg['seek_end'] # => nil
+  #  cg.to_ruby     # => "SEEK_SET = 0\nSEEK_CUR = 1\n# seek_end not available"
   class ConstGenerator
     @options = {}
     attr_reader :constants
 
-    ##
     # Creates a new constant generator that uses +prefix+ as a name, and an
     # options hash.
     #
-    # The only option is :required, which if set to true raises an error if a
+    # The only option is +:required+, which if set to +true+ raises an error if a
     # constant you have requested was not found.
     #
-    # When passed a block, #calculate is automatically called at the end of
-    # the block, otherwise you must call it yourself.
-
+    # @param [#to_s] prefix
+    # @param [Hash] options
+    # @return
+    # @option options [Boolean] :required
+    # @overload initialize(prefix, options)
+    # @overload initialize(prefix, options) { |gen| ... }
+    #  @yieldparam [ConstGenerator] gen new generator is passed to the block
+    #  When passed a block, {#calculate} is automatically called at the end of
+    #  the block, otherwise you must call it yourself.
     def initialize(prefix = nil, options = {})
-      @includes = []
+      @includes = ['stdio.h', 'stddef.h']
       @constants = {}
       @prefix = prefix
 
@@ -33,23 +49,40 @@ module FFI
         calculate self.class.options.merge(options)
       end
     end
+    # Set class options
+    # These options are merged with {#initialize} options when it is called with a block.
+    # @param [Hash] options
+    # @return [Hash] class options
     def self.options=(options)
       @options = options
     end
+    # Get class options.
+    # @return [Hash] class options
     def self.options
       @options
     end
+    # @param [String] name
+    # @return constant value (converted if a +converter+ was defined).
+    # Access a constant by name.
     def [](name)
-      @constants[name].value
+      @constants[name].converted_value
     end
 
-    ##
-    # Request the value for C constant +name+.  +format+ is a printf format
-    # string to print the value out, and +cast+ is a C cast for the value.
-    # +ruby_name+ allows you to give the constant an alternate ruby name for
-    # #to_ruby.  +converter+ or +converter_proc+ allow you to convert the
-    # value from a string to the appropriate type for #to_ruby.
-
+    # Request the value for C constant +name+.
+    #
+    # @param [#to_s] name C constant name
+    # @param [String] format a printf format string to print the value out
+    # @param [String] cast a C cast for the value
+    # @param ruby_name alternate ruby name for {#to_ruby}
+    #
+    # @overload const(name, format=nil, cast='', ruby_name=nil, converter=nil)
+    #  +converter+ is a Method or a Proc.
+    #  @param [#call] converter convert the value from a string to the appropriate
+    #   type for {#to_ruby}.
+    # @overload const(name, format=nil, cast='', ruby_name=nil) { |value| ... }
+    #  Use a converter block. This block convert the value from a string to the
+    #  appropriate type for {#to_ruby}.
+    #  @yieldparam value constant value
     def const(name, format = nil, cast = '', ruby_name = nil, converter = nil,
               &converter_proc)
       format ||= '%d'
@@ -66,18 +99,20 @@ module FFI
       return const
     end
 
+    # Calculate constants values.
+    # @param [Hash] options
+    # @option options [String] :cppflags flags for C compiler
+    # @return [nil]
+    # @raise if a constant is missing and +:required+ was set to +true+ (see {#initialize})
     def calculate(options = {})
-      binary = File.join Dir.tmpdir, "rb_const_gen_bin_#{Process.pid}"
+      binary_path = nil
 
       Tempfile.open("#{@prefix}.const_generator") do |f|
-        f.puts "#include <stdio.h>"
-
+        binary_path = f.path + ".bin"
         @includes.each do |inc|
           f.puts "#include <#{inc}>"
         end
-
-        f.puts "#include <stddef.h>\n\n"
-        f.puts "int main(int argc, char **argv)\n{"
+        f.puts "\nint main(int argc, char **argv)\n{"
 
         @constants.each_value do |const|
           f.puts <<-EOF
@@ -90,7 +125,8 @@ module FFI
         f.puts "\n\treturn 0;\n}"
         f.flush
 
-        output = `gcc #{options[:cppflags]} -D_DARWIN_USE_64_BIT_INODE -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64 -x c -Wall -Werror #{f.path} -o #{binary} 2>&1`
+        cc = ENV['CC'] || 'gcc'
+        output = `#{cc} #{options[:cppflags]} -D_DARWIN_USE_64_BIT_INODE -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64 -x c -Wall -Werror #{f.path} -o #{binary_path} 2>&1`
 
         unless $?.success? then
           output = output.split("\n").map { |l| "\t#{l}" }.join "\n"
@@ -98,8 +134,8 @@ module FFI
         end
       end
 
-      output = `#{binary}`
-      File.unlink(binary + (FFI::Platform.windows? ? ".exe" : ""))
+      output = `#{binary_path}`
+      File.unlink(binary_path + (FFI::Platform.windows? ? ".exe" : ""))
       output.each_line do |line|
         line =~ /^(\S+)\s(.*)$/
         const = @constants[$1]
@@ -115,17 +151,19 @@ module FFI
       end
     end
 
+    # Dump constants to +io+.
+    # @param [#puts] io
+    # @return [nil]
     def dump_constants(io)
       @constants.each do |name, constant|
-        name = [@prefix, name].join '.'
+        name = [@prefix, name].join '.' if @prefix
         io.puts "#{name} = #{constant.converted_value}"
       end
     end
 
-    ##
     # Outputs values for discovered constants.  If the constant's value was
     # not discovered it is not omitted.
-
+    # @return [String]
     def to_ruby
       @constants.sort_by { |name,| name }.map do |name, constant|
         if constant.value.nil? then
@@ -136,17 +174,28 @@ module FFI
       end.join "\n"
     end
 
-    def include(i)
-      @includes << i
+    # Add additional C include file(s) to calculate constants from.
+    # @note +stdio.h+ and +stddef.h+ automatically included
+    # @param [List<String>, Array<String>] i include file(s)
+    # @return [Array<String>] array of include files
+    def include(*i)
+      @includes |= i.flatten
     end
 
   end
 
+  # This class hold constants for {ConstGenerator}
   class ConstGenerator::Constant
 
     attr_reader :name, :format, :cast
     attr_accessor :value
 
+    # @param [#to_s] name
+    # @param [String] format a printf format string to print the value out
+    # @param [String] cast a C cast for the value
+    # @param ruby_name alternate ruby name for {#to_ruby}
+    # @param [#call] converter convert the value from a string to the appropriate
+    #  type for {#to_ruby}.
     def initialize(name, format, cast, ruby_name = nil, converter=nil)
       @name = name
       @format = format
@@ -156,6 +205,8 @@ module FFI
       @value = nil
     end
 
+    # Return constant value (converted if a +converter+ was defined).
+    # @return constant value.
     def converted_value
       if @converter
         @converter.call(@value)
@@ -164,14 +215,18 @@ module FFI
       end
     end
 
+    # get constant ruby name
+    # @return [String]
     def ruby_name
       @ruby_name || @name
     end
 
+    # Get an evaluable string from constant.
+    # @return [String]
     def to_ruby
       "#{ruby_name} = #{converted_value}"
     end
 
-  end  
+  end
 
 end

data/lib/ffi/tools/generator.rb

@@ -1,4 +1,51 @@
+require 'ffi/tools/struct_generator'
+require 'ffi/tools/const_generator'
+
 module FFI
+
+  ##
+  # Generate files with C structs for FFI::Struct and C constants.
+  #
+  # == A simple example
+  #
+  # In file +zlib.rb.ffi+:
+  #   module Zlib
+  #     @@@
+  #     constants do |c|
+  #       c.include "zlib.h"
+  #       c.const :ZLIB_VERNUM
+  #     end
+  #     @@@
+  #
+  #     class ZStream < FFI::Struct
+  #
+  #       struct do |s|
+  #         s.name "struct z_stream_s"
+  #         s.include "zlib.h"
+  #
+  #         s.field :next_in,   :pointer
+  #         s.field :avail_in,  :uint
+  #         s.field :total_in,  :ulong
+  #       end
+  #       @@@
+  #     end
+  #   end
+  #
+  # Translate the file:
+  #   require "ffi/tools/generator"
+  #   FFI::Generator.new "zlib.rb.ffi", "zlib.rb"
+  #
+  # Generates the file +zlib.rb+ with constant values and offsets:
+  #   module Zlib
+  #   ZLIB_VERNUM = 4784
+  #
+  #   class ZStream < FFI::Struct
+  #     layout :next_in, :pointer, 0,
+  #            :avail_in, :uint, 8,
+  #            :total_in, :ulong, 16
+  #   end
+  #
+  # @see FFI::Generator::Task for easy integration in a Rakefile
   class Generator
 
     def initialize(ffi_name, rb_name, options = {})
@@ -16,7 +63,7 @@ module FFI
         indent = $1
         original_lines = $2.count "\n"
 
-        instance_eval $2
+        instance_eval $2, @ffi_name, $`.count("\n")
 
         new_lines = []
         @constants.each { |c| new_lines << c.to_ruby }
@@ -32,7 +79,7 @@ module FFI
       end
 
       open @rb_name, 'w' do |f|
-        f.puts "# This file is generated by rake. Do not edit."
+        f.puts "# This file is generated from `#{@ffi_name}'. Do not edit."
         f.puts
         f.puts new_file
       end

data/lib/ffi/tools/generator_task.rb

@@ -1,24 +1,21 @@
-begin
-  require 'ffi/struct_generator'
-  require 'ffi/const_generator'
-  require 'ffi/generator'
-rescue LoadError
-  # from Rakefile
-  require 'lib/ffi/struct_generator'
-  require 'lib/ffi/const_generator'
-  require 'lib/ffi/generator'
-end
-
+require 'ffi/tools/generator'
 require 'rake'
 require 'rake/tasklib'
-require 'tempfile'
 
 ##
-# Rake task that calculates C structs for FFI::Struct.
-
+# Add Rake tasks that generate files with C structs for FFI::Struct and C constants.
+#
+# @example a simple example for your Rakefile
+#   require "ffi/tools/generator_task"
+#   # Add a task to generate my_object.rb out of my_object.rb.ffi
+#   FFI::Generator::Task.new ["my_object.rb"], cflags: "-I/usr/local/mylibrary"
+#
+# The generated files are also added to the 'clear' task.
+#
+# @see FFI::Generator for a description of the file content
 class FFI::Generator::Task < Rake::TaskLib
 
-  def initialize(rb_names)
+  def initialize(rb_names, options={})
     task :clean do rm_f rb_names end
 
     rb_names.each do |rb_name|
@@ -27,7 +24,7 @@ class FFI::Generator::Task < Rake::TaskLib
       file rb_name => ffi_name do |t|
         puts "Generating #{rb_name}..." if Rake.application.options.trace
 
-        FFI::Generator.new ffi_name, rb_name
+        FFI::Generator.new ffi_name, rb_name, options
       end
     end
   end

data/lib/ffi/tools/struct_generator.rb

@@ -7,15 +7,15 @@ module FFI
   #
   # Given the @@@ portion in:
   #
-  #   module Zlib::ZStream < FFI::Struct
+  #   class Zlib::ZStream < FFI::Struct
   #     @@@
   #     name "struct z_stream_s"
   #     include "zlib.h"
-  #   
+  #
   #     field :next_in,   :pointer
   #     field :avail_in,  :uint
   #     field :total_in,  :ulong
-  #   
+  #
   #     # ...
   #     @@@
   #   end
@@ -82,7 +82,8 @@ module FFI
         f.puts "\n  return 0;\n}"
         f.flush
 
-        output = `gcc #{options[:cppflags]} #{options[:cflags]} -D_DARWIN_USE_64_BIT_INODE -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64 -x c -Wall -Werror #{f.path} -o #{binary} 2>&1`
+        cc = ENV['CC'] || 'gcc'
+        output = `#{cc} #{options[:cppflags]} #{options[:cflags]} -D_DARWIN_USE_64_BIT_INODE -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64 -x c -Wall -Werror #{f.path} -o #{binary} 2>&1`
 
         unless $?.success? then
           @found = false
@@ -90,7 +91,7 @@ module FFI
           raise "Compilation error generating struct #{@name} (#{@struct_name}):\n#{output}"
         end
       end
-      
+
       output = `#{binary}`.split "\n"
       File.unlink(binary + (FFI::Platform.windows? ? ".exe" : ""))
       sizeof = output.shift

data/lib/ffi/tools/types_generator.rb

@@ -1,6 +1,8 @@
 require 'tempfile'
 
 module FFI
+
+  # @private
   class TypesGenerator
 
     ##
@@ -45,27 +47,40 @@ module FFI
       typedefs = nil
       Tempfile.open 'ffi_types_generator' do |io|
         io.puts <<-C
+#include <stdint.h>
+#include <stddef.h>
 #include <sys/types.h>
+#if !(defined(WIN32))
 #include <sys/socket.h>
+#include <netinet/in.h>
 #include <sys/resource.h>
+#endif
         C
 
         io.close
-        typedefs = `gcc -E -x c #{options[:cppflags]} -D_DARWIN_USE_64_BIT_INODE -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64 -c #{io.path}`
+        cc = ENV['CC'] || 'gcc'
+        cmd = "#{cc} -E -x c #{options[:cppflags]} -D_DARWIN_USE_64_BIT_INODE -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64 -c"
+        if options[:input]
+          typedefs = File.read(options[:input])
+        elsif options[:remote]
+          typedefs = `ssh #{options[:remote]} #{cmd} - < #{io.path}`
+        else
+          typedefs = `#{cmd} #{io.path}`
+        end
       end
-      
-      code = ""
+
+      code = []
 
       typedefs.each_line do |type|
         # We only care about single line typedef
         next unless type =~ /typedef/
         # Ignore unions or structs
         next if type =~ /union|struct/
-        
+
         # strip off the starting typedef and ending ;
         type.gsub!(/^(.*typedef\s*)/, "")
         type.gsub!(/\s*;\s*$/, "")
-    
+
         parts = type.split(/\s+/)
         def_type   = parts.join(" ")
 
@@ -87,7 +102,7 @@ module FFI
           else
             final_type = parts.pop
           end
-          
+
           def_type = case type
                      when /__QI__/   then "char"
                      when /__HI__/   then "short"
@@ -102,22 +117,21 @@ module FFI
           final_type = parts.pop
           def_type   = parts.join(" ")
         end
-        
+
         if type = TYPE_MAP[def_type]
-          code << "rbx.platform.typedef.#{final_type} = #{type}\n"
+          code << "rbx.platform.typedef.#{final_type} = #{type}"
           TYPE_MAP[final_type] = TYPE_MAP[def_type]
         else
           # Fallback to an ordinary pointer if we don't know the type
           if def_type =~ /\*/
-            code << "rbx.platform.typedef.#{final_type} = pointer\n"
+            code << "rbx.platform.typedef.#{final_type} = pointer"
             TYPE_MAP[final_type] = :pointer
           end
         end
       end
 
-      code
+      code.sort.join("\n")
     end
-
   end
 end
 

data/lib/ffi/types.rb

@@ -1,51 +1,109 @@
 #
 # Copyright (C) 2008-2010 Wayne Meissner
-# All rights reserved.
+# Copyright (c) 2007, 2008 Evan Phoenix
 #
 # This file is part of ruby-ffi.
 #
-# This code is free software: you can redistribute it and/or modify it under
-# the terms of the GNU Lesser General Public License version 3 only, as
-# published by the Free Software Foundation.
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
 #
-# This code is distributed in the hope that it will be useful, but WITHOUT
-# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
-# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License
-# version 3 for more details.
+# * Redistributions of source code must retain the above copyright notice, this
+#   list of conditions and the following disclaimer.
+# * Redistributions in binary form must reproduce the above copyright notice
+#   this list of conditions and the following disclaimer in the documentation
+#   and/or other materials provided with the distribution.
+# * Neither the name of the Ruby FFI project nor the names of its contributors
+#   may be used to endorse or promote products derived from this software
+#   without specific prior written permission.
 #
-# You should have received a copy of the GNU Lesser General Public License
-# version 3 along with this work.  If not, see <http://www.gnu.org/licenses/>.
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
+# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 #
 
+# see {file:README}
 module FFI
 
-  def self.typedef(old, add)
-    TypeDefs[add] = self.find_type(old)
+  # Unless custom_typedefs already defined in the C-ext?
+  unless defined?(custom_typedefs)
+    # Truffleruby and JRuby don't support Ractor so far.
+    # So they don't need separation between builtin and custom types.
+    def self.custom_typedefs
+      TypeDefs
+    end
+    writable_typemap = true
   end
 
-  def self.add_typedef(old, add)
-    typedef old, add
-  end
+  class << self
 
+    private :custom_typedefs
 
-  def self.find_type(name, type_map = nil)
-    if name.is_a?(Type)
-      name
+    # @param [Type, DataConverter, Symbol] old type definition used by {FFI.find_type}
+    # @param [Symbol] add new type definition's name to add
+    # @return [Type]
+    # Add a definition type to type definitions.
+    #
+    # The type definition is local per Ractor.
+    def typedef(old, add)
+      tm = custom_typedefs
+      tm[add] = find_type(old)
+    end
 
-    elsif type_map && type_map.has_key?(name)
-      type_map[name]
+    # (see FFI.typedef)
+    def add_typedef(old, add)
+      typedef old, add
+    end
 
-    elsif TypeDefs.has_key?(name)
-      TypeDefs[name]
+    private def __typedef(old, add)
+      TypeDefs[add] = find_type(old, TypeDefs)
+    end
 
-    elsif name.is_a?(DataConverter)
-      (type_map || TypeDefs)[name] = Type::Mapped.new(name)
-    
-    else
-      raise TypeError, "unable to resolve type '#{name}'"
+    # @param [Type, DataConverter, Symbol] name
+    # @param [Hash] type_map if nil, {FFI::TypeDefs} is used
+    # @return [Type]
+    # Find a type in +type_map+ ({FFI::TypeDefs}, by default) from
+    # a type objet, a type name (symbol). If +name+ is a {DataConverter},
+    # a new {Type::Mapped} is created.
+    def find_type(name, type_map = nil)
+      if name.is_a?(Type)
+        name
+
+      elsif type_map&.has_key?(name)
+        type_map[name]
+
+      elsif (tm=custom_typedefs).has_key?(name)
+        tm[name]
+
+      elsif TypeDefs.has_key?(name)
+        TypeDefs[name]
+
+      elsif name.is_a?(DataConverter)
+        # Add a typedef so next time the converter is used, it hits the cache
+        tm = (type_map || custom_typedefs)
+        tm[name] = Type::Mapped.new(name)
+      else
+        raise TypeError, "unable to resolve type '#{name}'"
+      end
+    end
+
+    # @param type +type+ is an instance of class accepted by {FFI.find_type}
+    # @return [Integer]
+    # Get +type+ size, in bytes.
+    def type_size(type)
+      find_type(type).size
     end
   end
 
+  # List of type definitions
   TypeDefs.merge!({
       # The C void type; only useful for function return types
       :void => Type::VOID,
@@ -89,6 +147,9 @@ module FFI
       # C double precision float
       :double => Type::DOUBLE,
 
+      # C long double
+      :long_double => Type::LONGDOUBLE,
+
       # Native memory address
       :pointer => Type::POINTER,
 
@@ -120,22 +181,27 @@ module FFI
       :varargs => Type::VARARGS,
   })
 
-  # Returns a [ String, Pointer ] tuple so the C memory for the string can be freed
+  # This will convert a pointer to a Ruby string (just like `:string`), but
+  # also allow to work with the pointer itself. This is useful when you want
+  # a Ruby string already containing a copy of the data, but also the pointer
+  # to the data for you to do something with it, like freeing it, in case the
+  # library handed the memory off to the caller (Ruby-FFI).
+  #
+  # It's {typedef}'d as +:strptr+.
   class StrPtrConverter
     extend DataConverter
     native_type Type::POINTER
 
+    # @param [Pointer] val
+    # @param ctx not used
+    # @return [Array(String, Pointer)]
+    # Returns a [ String, Pointer ] tuple so the C memory for the string can be freed
     def self.from_native(val, ctx)
-      [ val.null? ? Qnil : val.get_string(0), val ]
+      [ val.null? ? nil : val.get_string(0), val ]
     end
-
   end
 
-  typedef(StrPtrConverter, :strptr)
-
-  def self.type_size(type)
-    find_type(type).size
-  end
+  __typedef(StrPtrConverter, :strptr)
 
   # Load all the platform dependent types
   begin
@@ -144,10 +210,13 @@ module FFI
       f.each_line { |line|
         if line.index(prefix) == 0
           new_type, orig_type = line.chomp.slice(prefix.length..-1).split(/\s*=\s*/)
-          typedef(orig_type.to_sym, new_type.to_sym)
+          __typedef(orig_type.to_sym, new_type.to_sym)
         end
       }
     end
+    __typedef :pointer, :caddr_t
   rescue Errno::ENOENT
   end
+
+  FFI.make_shareable(TypeDefs) unless writable_typemap
 end