ffi 1.12.2-java → 1.14.2-java

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d97c965128bc43869069bde8cb5f0484c0653d5413828d138616092292610906
-  data.tar.gz: d0f9fd8a5d388d35d39a135fa27f6098c7b6fc1daec909c00cc1f5e81fd3c941
+  metadata.gz: 0bff6b764ee96e1b33db643522c7b3f89c903ac1fc1422f41b66f1cf601711fc
+  data.tar.gz: 845a681f7537a7d3c5533d241456f6a430bd2f1cccba58b8c03f48bdf4dc8687
 SHA512:
-  metadata.gz: cf9777eef5340b46d3cef2f411c8a3c79c1a16ba85a91b5db3d3c042aafa09b14a2fd41b76aace5950bcf3ec574ae220e227fbc951c61ab846758b14e4731c39
-  data.tar.gz: 189feebb9b9b503af06c5e20801d2340c043e82aa7273bfe079e4f41ed62c436b8efb9e15ca61dfc2a698fcb9eec74d4893367c281d4a240ae32e7d95afedba9
+  metadata.gz: d0207509609d10fb9ebae3652e844ef33422812992fa9791ac39741fc93a75c6534a3a4c8951937e0a5af7968a7d3640de7f302faf946bf8ee37f39483c59d28
+  data.tar.gz: adc882521c77e61803b5cd3d4ecbb9543f9f6ab0beae7094350ce96cf69e5297cf8b2002b7c9957a8679c2d4fba95bf2f2d0638d211e1ed6be0d632c475caf12

data/CHANGELOG.md

@@ -1,3 +1,85 @@
+1.14.2 / 2020-12-21
+-------------------
+
+Fixed:
+* Fix builtin libffi on newer Ubuntu caused by an outdated Makefile.in . #863
+
+
+1.14.1 / 2020-12-19
+-------------------
+
+Changed:
+* Revert changes to FFI::Pointer#write_string made in ffi-1.14.0.
+  It breaks compatibilty in a way that can cause hard to find errors. #857
+
+
+1.14.0 / 2020-12-18
+-------------------
+
+Added:
+* Add types.conf for x86_64-msys, x86_64-haiku, aarch64-openbsd and aarch64-darwin (alias arm64-darwin)
+* Add method AbstractMemory#size_limit? . #829
+* Add new extconf option --enable-libffi-alloc which is enabled per default on Apple M1 (arm64-darwin).
+
+Changed:
+* Do NULL pointer check only when array length > 0 . #305
+* Raise an error on an unknown order argument. #830
+* Change FFI::Pointer#write_string to terminate with a NUL byte like other string methods. #805
+* Update bundled libffi to latest master.
+
+Removed:
+* Remove win32/stdint.h and stdbool.h because of copyright issue.  #693
+
+Fixed:
+* Fix possible UTF-8 load error in loader script interpretation. #792
+* Fix segfault on non-array argument to #write_array_of_*
+* Fix memory leak in MethodHandle . #815
+* Fix possible segfault in combination with fiddle or other libffi using gems . #835
+* Fix possibility to use ffi ruby gem with JRuby-9.3 . #763
+* Fix a GC issue, when a callback Proc is used on more than 2 callback signatures. #820
+
+
+1.13.1 / 2020-06-09
+-------------------
+
+Changed:
+* Revert use of `ucrtbase.dll` as default C library on Windows-MINGW.
+  `ucrtbase.dll` is still used on MSWIN target. #790
+* Test for `ffi_prep_closure_loc()` to make sure we can use this function.
+  This fixes incorrect use of system libffi on MacOS Mojave (10.14). #787
+* Update types.conf on x86_64-dragonflybsd
+
+
+1.13.0 / 2020-06-01
+-------------------
+
+Added:
+* Add TruffleRuby support. Almost all specs are running on TruffleRuby and succeed. #768
+* Add ruby source files to the java gem. This allows to ship the Ruby library code per platform java gem and add it as a default gem to JRuby. #763
+* Add FFI::Platform::LONG_DOUBLE_SIZE
+* Add bounds checks for writing to an inline char[] . #756
+* Add long double as callback return value. #771
+* Update type definitions and add types from stdint.h and stddef.h on i386-windows, x86_64-windows, x86_64-darwin, x86_64-linux, arm-linux, powerpc-linux. #749
+* Add new type definitions for powerpc-openbsd and sparcv9-openbsd. #775, #778
+
+Changed:
+* Raise required ruby version to >= 2.3.
+* Lots of cleanups and improvements in library, specs and benchmarks.
+* Fix a lot of compiler warnings at the C-extension
+* Fix several install issues on MacOS:
+  * Look for libffi in SDK paths, since recent versions of macOS removed it from `/usr/include` . #757
+  * Fix error `ld: library not found for -lgcc_s.10.4`
+  * Don't built for i386 architecture as it is deprecated
+* Several fixes for MSVC build on Windows. #779
+* Use `ucrtbase.dll` as default C library on Windows instead of old `msvcrt.dll`. #779
+* Update builtin libffi to fix a Powerpc issue with parameters of type long
+* Allow unmodified sourcing of (the ruby code of) this gem in JRuby and TruffleRuby as a default gem. #747
+* Improve check to detect if a module has a #find_type method suitable for FFI. This fixes compatibility with stdlib `mkmf` . #776
+
+Removed:
+* Reject callback with `:string` return type at definition, because it didn't work so far and is not save to use. #751, #782
+
+
 1.12.2 / 2020-02-01
 -------------------
 

data/Gemfile

@@ -0,0 +1,17 @@
+source 'https://rubygems.org'
+
+group :development do
+  gem 'rake', '~> 13.0'
+  gem 'rake-compiler', '~> 1.0.3'
+  gem 'rake-compiler-dock', '~> 1.0'
+  gem 'rspec', '~> 3.0'
+  # irb is a dependency of rubygems-tasks 0.2.5.
+  # irb versions > 1.1.1 depend on reline,
+  # which sometimes causes 'bundle install' to fail on Ruby <= 2.4: https://github.com/rubygems/rubygems/issues/3463
+  gem 'rubygems-tasks', '>= 0.2', '< 0.2.5', :require => 'rubygems/tasks'
+end
+
+group :doc do
+  gem 'kramdown'
+  gem 'yard', '~> 0.9'
+end

data/LICENSE.SPECS

@@ -0,0 +1,22 @@
+Copyright (c) 2008-2012 Ruby-FFI contributors
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -1,4 +1,4 @@
-# Ruby-FFI https://github.com/ffi/ffi/wiki [![Build Status](https://travis-ci.org/ffi/ffi.svg?branch=master)](https://travis-ci.org/ffi/ffi) [![Build status Windows](https://ci.appveyor.com/api/projects/status/r8wxn1sd4s794gg1/branch/master?svg=true)](https://ci.appveyor.com/project/larskanis/ffi-aofqa/branch/master)
+# Ruby-FFI https://github.com/ffi/ffi/wiki [![Build Status](https://travis-ci.com/ffi/ffi.svg?branch=master)](https://travis-ci.com/ffi/ffi) [![Build status Windows](https://ci.appveyor.com/api/projects/status/r8wxn1sd4s794gg1/branch/master?svg=true)](https://ci.appveyor.com/project/larskanis/ffi-aofqa/branch/master)
 
 ## Description
 
@@ -66,10 +66,18 @@ From rubygems:
 or from the git repository on github:
 
     git clone git://github.com/ffi/ffi.git
-    git submodule update --init --recursive
     cd ffi
+    git submodule update --init --recursive
+    bundle install
     rake install
 
+### Install options:
+
+* `--enable-system-libffi` : Force usage of system libffi
+* `--disable-system-libffi` : Force usage of builtin libffi
+* `--enable-libffi-alloc` : Force closure allocation by libffi
+* `--disable-libffi-alloc` : Force closure allocation by builtin method
+
 ## License
 
 The ffi library is covered by the BSD license, also see the LICENSE file.

data/Rakefile

@@ -1,7 +1,7 @@
 require 'rubygems/tasks'
 require 'rbconfig'
 require 'rake/clean'
-require File.expand_path("./lib/ffi/version")
+require_relative "lib/ffi/version"
 
 require 'date'
 require 'fileutils'
@@ -9,10 +9,6 @@ require 'rbconfig'
 require 'rspec/core/rake_task'
 require 'rubygems/package_task'
 
-def java?
-  /java/ === RUBY_PLATFORM
-end
-
 BUILD_DIR = "build"
 BUILD_EXT_DIR = File.join(BUILD_DIR, "#{RbConfig::CONFIG['arch']}", 'ffi_c', RUBY_VERSION)
 
@@ -20,17 +16,8 @@ def gem_spec
   @gem_spec ||= Gem::Specification.load('ffi.gemspec')
 end
 
-TEST_DEPS = []
-if RUBY_PLATFORM == "java"
-  RSpec::Core::RakeTask.new(:spec) do |config|
-    config.rspec_opts = YAML.load_file 'spec/spec.opts'
-  end
-else
-  RSpec::Core::RakeTask.new(:spec => :compile) do |config|
-    config.rspec_opts = YAML.load_file 'spec/spec.opts'
-  end
-
-  TEST_DEPS.unshift :compile
+RSpec::Core::RakeTask.new(:spec => :compile) do |config|
+  config.rspec_opts = YAML.load_file 'spec/spec.opts'
 end
 
 desc "Build all packages"
@@ -50,6 +37,13 @@ CLEAN.include "pkg/ffi-*-{mingw32,java}"
 CLEAN.include 'lib/1.*'
 CLEAN.include 'lib/2.*'
 
+# clean all shipped files, that are not in git
+CLEAN.include(
+    gem_spec.files -
+    `git --git-dir ext/ffi_c/libffi/.git ls-files -z`.split("\x0").map { |f| File.join("ext/ffi_c/libffi", f) } -
+    `git ls-files -z`.split("\x0")
+)
+
 task :distclean => :clobber
 
 desc "Test the extension"
@@ -58,37 +52,29 @@ task :test => [ :spec ]
 
 namespace :bench do
   ITER = ENV['ITER'] ? ENV['ITER'].to_i : 100000
-  bench_libs = "-Ilib" unless RUBY_PLATFORM == "java"
-  bench_files = Dir["bench/bench_*.rb"].reject { |f| f == "bench/bench_helper.rb" }
+  bench_files = Dir["bench/bench_*.rb"].sort.reject { |f| f == "bench/bench_helper.rb" }
   bench_files.each do |bench|
-    task File.basename(bench, ".rb")[6..-1] => TEST_DEPS do
-      sh %{#{Gem.ruby} #{bench_libs} #{bench} #{ITER}}
+    task File.basename(bench, ".rb")[6..-1] => :compile do
+      sh %{#{Gem.ruby} #{bench} #{ITER}}
     end
   end
-  task :all => TEST_DEPS do
+  task :all => :compile do
     bench_files.each do |bench|
-      sh %{#{Gem.ruby} #{bench_libs} #{bench}}
+      sh %{#{Gem.ruby} #{bench}}
     end
   end
 end
 
-task 'spec:run' => TEST_DEPS
-task 'spec:specdoc' => TEST_DEPS
+task 'spec:run' => :compile
+task 'spec:specdoc' => :compile
 
 task :default => :spec
 
 namespace 'java' do
 
-  java_gem_spec = Gem::Specification.new do |s|
-    s.name = gem_spec.name
-    s.version = gem_spec.version
-    s.author = gem_spec.author
-    s.email = gem_spec.email
-    s.homepage = gem_spec.homepage
-    s.summary = gem_spec.summary
-    s.description = gem_spec.description
-    s.files = %w(LICENSE COPYING README.md CHANGELOG.md Rakefile)
-    s.license = gem_spec.license
+  java_gem_spec = gem_spec.dup.tap do |s|
+    s.files.reject! { |f| File.fnmatch?("ext/*", f) }
+    s.extensions = []
     s.platform = 'java'
   end
 
@@ -101,7 +87,7 @@ end
 
 task 'gem:java' => 'java:gem'
 
-unless java?
+if RUBY_ENGINE == 'ruby' || RUBY_ENGINE == 'rbx'
   require 'rake/extensiontask'
   Rake::ExtensionTask.new('ffi_c', gem_spec) do |ext|
     ext.name = 'ffi_c'                                        # indicate the name of the extension.
@@ -124,13 +110,17 @@ unless java?
       sh "x86_64-w64-mingw32-strip -S build/x64-mingw32/stage/lib/#{ruby_version[/^\d+\.\d+/]}/ffi_c.so"
     end
   end
+else
+  task :compile do
+    STDERR.puts "Nothing to compile on #{RUBY_ENGINE}"
+  end
 end
 
 desc "build a windows gem without all the ceremony"
 task "gem:windows" do
   require "rake_compiler_dock"
   sh "bundle package"
-  RakeCompilerDock.sh "sudo apt-get update && sudo apt-get install -y libltdl-dev && bundle --local && rake cross native gem MAKE='nice make -j`nproc`'"
+  RakeCompilerDock.sh "sudo apt-get update && sudo apt-get install -y libltdl-dev && bundle --local && rake cross native gem MAKE='nice make -j`nproc`' RUBY_CC_VERSION=${RUBY_CC_VERSION/:2.2.2/}"
 end
 
 directory "ext/ffi_c/libffi"
@@ -158,16 +148,15 @@ end.each do |f|
   end
 end
 
-$LOAD_PATH.unshift File.join(File.dirname(__FILE__), 'lib')
-require 'ffi/platform'
+require_relative "lib/ffi/platform"
 types_conf = File.expand_path(File.join(FFI::Platform::CONF_DIR, 'types.conf'))
 logfile = File.join(File.dirname(__FILE__), 'types_log')
 
-file types_conf => File.join("lib", "ffi", "version.rb") do |task|
+task types_conf do |task|
   require 'fileutils'
-  require 'ffi/tools/types_generator'
+  require_relative "lib/ffi/tools/types_generator"
   options = {}
-  FileUtils.mkdir_p(File.dirname(task.name), { :mode => 0755 })
+  FileUtils.mkdir_p(File.dirname(task.name), mode: 0755 )
   File.open(task.name, File::CREAT|File::TRUNC|File::RDWR, 0644) do |f|
     f.puts FFI::TypesGenerator.generate(options)
   end
@@ -177,8 +166,7 @@ file types_conf => File.join("lib", "ffi", "version.rb") do |task|
 end
 
 desc "Create or update type information for platform #{FFI::Platform::NAME}"
-task :types_conf => types_conf do
-end
+task :types_conf => types_conf
 
 Gem::Tasks.new do |t|
   t.scm.tag.format = '%s'

data/ffi.gemspec

@@ -0,0 +1,43 @@
+require File.expand_path("../lib/#{File.basename(__FILE__, '.gemspec')}/version", __FILE__)
+
+Gem::Specification.new do |s|
+  s.name = 'ffi'
+  s.version = FFI::VERSION
+  s.author = 'Wayne Meissner'
+  s.email = 'wmeissner@gmail.com'
+  s.homepage = 'https://github.com/ffi/ffi/wiki'
+  s.summary = 'Ruby FFI'
+  s.description = 'Ruby FFI library'
+  if s.respond_to?(:metadata)
+    s.metadata['bug_tracker_uri'] = 'https://github.com/ffi/ffi/issues'
+    s.metadata['changelog_uri'] = 'https://github.com/ffi/ffi/blob/master/CHANGELOG.md'
+    s.metadata['documentation_uri'] = 'https://github.com/ffi/ffi/wiki'
+    s.metadata['wiki_uri'] = 'https://github.com/ffi/ffi/wiki'
+    s.metadata['source_code_uri'] = 'https://github.com/ffi/ffi/'
+    s.metadata['mailing_list_uri'] = 'http://groups.google.com/group/ruby-ffi'
+  end
+  s.files = `git ls-files -z`.split("\x0").reject do |f|
+    f =~ /^(\.|bench|gen|libtest|nbproject|spec)/
+  end
+
+  # Add libffi git files
+  lfs = `git --git-dir ext/ffi_c/libffi/.git ls-files -z`.split("\x0")
+  # Add autoconf generated files of libffi
+  lfs += %w[ configure config.guess config.sub install-sh ltmain.sh missing fficonfig.h.in ]
+  # Add automake generated files of libffi
+  lfs += `git --git-dir ext/ffi_c/libffi/.git ls-files -z *.am */*.am`.gsub(".am\0", ".in\0").split("\x0")
+  s.files += lfs.map do |f|
+    File.join("ext/ffi_c/libffi", f)
+  end
+
+  s.extensions << 'ext/ffi_c/extconf.rb'
+  s.rdoc_options = %w[--exclude=ext/ffi_c/.*\.o$ --exclude=ffi_c\.(bundle|so)$]
+  s.license = 'BSD-3-Clause'
+  s.require_paths << 'ext/ffi_c'
+  s.required_ruby_version = '>= 2.3'
+  s.add_development_dependency 'rake', '~> 13.0'
+  s.add_development_dependency 'rake-compiler', '~> 1.0'
+  s.add_development_dependency 'rake-compiler-dock', '~> 1.0'
+  s.add_development_dependency 'rspec', '~> 2.14.1'
+  s.add_development_dependency 'rubygems-tasks', "~> 0.2.4"
+end

data/lib/ffi.rb

@@ -0,0 +1,28 @@
+if RUBY_ENGINE == 'ruby' || RUBY_ENGINE == 'rbx'
+  Object.send(:remove_const, :FFI) if defined?(::FFI)
+  begin
+    require RUBY_VERSION.split('.')[0, 2].join('.') + '/ffi_c'
+  rescue Exception
+    require 'ffi_c'
+  end
+
+  require 'ffi/ffi'
+
+elsif RUBY_ENGINE == 'jruby' && (RUBY_ENGINE_VERSION.split('.').map(&:to_i) <=> [9, 3]) >= 0
+  JRuby::Util.load_ext("org.jruby.ext.ffi.FFIService")
+  require 'ffi/ffi'
+
+elsif RUBY_ENGINE == 'truffleruby' && (RUBY_ENGINE_VERSION.split('.').map(&:to_i) <=> [20, 1, 0]) >= 0
+  require 'truffleruby/ffi_backend'
+  require 'ffi/ffi'
+
+else
+  # Remove the ffi gem dir from the load path, then reload the internal ffi implementation
+  $LOAD_PATH.delete(File.dirname(__FILE__))
+  $LOAD_PATH.delete(File.join(File.dirname(__FILE__), 'ffi'))
+  unless $LOADED_FEATURES.nil?
+    $LOADED_FEATURES.delete(__FILE__)
+    $LOADED_FEATURES.delete('ffi.rb')
+  end
+  require 'ffi.rb'
+end

data/lib/ffi/abstract_memory.rb

@@ -0,0 +1,44 @@
+#
+# Copyright (C) 2020 Lars Kanis
+#
+# This file is part of ruby-ffi.
+#
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# * 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.
+#
+# 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.#
+
+
+module FFI
+  class AbstractMemory
+    LONG_MAX = FFI::Pointer.new(1).size
+    private_constant :LONG_MAX
+
+    # Return +true+ if +self+ has a size limit.
+    #
+    # @return [Boolean]
+    def size_limit?
+      size != LONG_MAX
+    end
+  end
+end

data/lib/ffi/autopointer.rb

@@ -0,0 +1,203 @@
+#
+# Copyright (C) 2008-2010 Wayne Meissner
+# Copyright (C) 2008 Mike Dalessio
+#
+# This file is part of ruby-ffi.
+#
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# * 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.
+#
+# 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.
+
+module FFI
+  class AutoPointer < Pointer
+    extend DataConverter
+
+    # @overload initialize(pointer, method)
+    #   @param pointer [Pointer]
+    #   @param method [Method]
+    #   @return [self]
+    #   The passed Method will be invoked at GC time.
+    # @overload initialize(pointer, proc)
+    #   @param pointer [Pointer]
+    #   @return [self]
+    #   The passed Proc will be invoked at GC time (SEE WARNING BELOW!)
+    #   @note WARNING: passing a proc _may_ cause your pointer to never be
+    #     GC'd, unless you're careful to avoid trapping a reference to the
+    #     pointer in the proc. See the test specs for examples.
+    # @overload initialize(pointer) { |p| ... }
+    #   @param pointer [Pointer]
+    #   @yieldparam [Pointer] p +pointer+ passed to the block
+    #   @return [self]
+    #   The passed block will be invoked at GC time.
+    #   @note
+    #     WARNING: passing a block will cause your pointer to never be GC'd.
+    #     This is bad.
+    # @overload initialize(pointer)
+    #   @param pointer [Pointer]
+    #   @return [self]
+    #   The pointer's release() class method will be invoked at GC time.
+    #
+    # @note The safest, and therefore preferred, calling
+    #  idiom is to pass a Method as the second parameter. Example usage:
+    #
+    #   class PointerHelper
+    #     def self.release(pointer)
+    #       ...
+    #     end
+    #   end
+    #
+    #   p = AutoPointer.new(other_pointer, PointerHelper.method(:release))
+    #
+    #  The above code will cause PointerHelper#release to be invoked at GC time.
+    #
+    # @note
+    #  The last calling idiom (only one parameter) is generally only
+    #  going to be useful if you subclass {AutoPointer}, and override
+    #  #release, which by default does nothing.
+    def initialize(ptr, proc=nil, &block)
+      super(ptr.type_size, ptr)
+      raise TypeError, "Invalid pointer" if ptr.nil? || !ptr.kind_of?(Pointer) \
+        || ptr.kind_of?(MemoryPointer) || ptr.kind_of?(AutoPointer)
+
+      @releaser = if proc
+                    if not proc.respond_to?(:call)
+                      raise RuntimeError.new("proc must be callable")
+                    end
+                    CallableReleaser.new(ptr, proc)
+
+                  else
+                    if not self.class.respond_to?(:release)
+                      raise RuntimeError.new("no release method defined")
+                    end
+                    DefaultReleaser.new(ptr, self.class)
+                  end
+
+      ObjectSpace.define_finalizer(self, @releaser)
+      self
+    end
+
+    # @return [nil]
+    # Free the pointer.
+    def free
+      @releaser.free
+    end
+
+    # @param [Boolean] autorelease
+    # @return [Boolean] +autorelease+
+    # Set +autorelease+ property. See {Pointer Autorelease section at Pointer}.
+    def autorelease=(autorelease)
+      @releaser.autorelease=(autorelease)
+    end
+
+    # @return [Boolean] +autorelease+
+    # Get +autorelease+ property. See {Pointer Autorelease section at Pointer}.
+    def autorelease?
+      @releaser.autorelease
+    end
+
+    # @abstract Base class for {AutoPointer}'s releasers.
+    #
+    #  All subclasses of Releaser should define a +#release(ptr)+ method.
+    # A releaser is an object in charge of release an {AutoPointer}.
+    class Releaser
+      attr_accessor :autorelease
+
+      # @param [Pointer] ptr
+      # @param [#call] proc
+      # @return [nil]
+      # A new instance of Releaser.
+      def initialize(ptr, proc)
+        @ptr = ptr
+        @proc = proc
+        @autorelease = true
+      end
+
+      # @return [nil]
+      # Free pointer.
+      def free
+        if @ptr
+          release(@ptr)
+          @autorelease = false
+          @ptr = nil
+          @proc = nil
+        end
+      end
+
+      # @param args
+      # Release pointer if +autorelease+ is set.
+      def call(*args)
+        release(@ptr) if @autorelease && @ptr
+      end
+    end
+
+    # DefaultReleaser is a {Releaser} used when an {AutoPointer} is defined
+    # without Proc or Method. In this case, the pointer to release must be of
+    # a class derived from AutoPointer with a {release} class method.
+    class DefaultReleaser < Releaser
+      # @param [Pointer] ptr
+      # @return [nil]
+      # Release +ptr+ using the {release} class method of its class.
+      def release(ptr)
+        @proc.release(ptr)
+      end
+    end
+
+    # CallableReleaser is a {Releaser} used when an {AutoPointer} is defined with a
+    # Proc or a Method.
+    class CallableReleaser < Releaser
+      # Release +ptr+ by using Proc or Method defined at +ptr+
+      # {AutoPointer#initialize initialization}.
+      #
+      # @param [Pointer] ptr
+      # @return [nil]
+      def release(ptr)
+        @proc.call(ptr)
+      end
+    end
+
+    # Return native type of AutoPointer.
+    #
+    # Override {DataConverter#native_type}.
+    # @return [Type::POINTER]
+    # @raise {RuntimeError} if class does not implement a +#release+ method
+    def self.native_type
+      if not self.respond_to?(:release)
+        raise RuntimeError.new("no release method defined for #{self.inspect}")
+      end
+      Type::POINTER
+    end
+
+    # Create a new AutoPointer.
+    #
+    # Override {DataConverter#from_native}.
+    # @overload self.from_native(ptr, ctx)
+    #   @param [Pointer] ptr
+    #   @param ctx not used. Please set +nil+.
+    # @return [AutoPointer]
+    def self.from_native(val, ctx)
+      self.new(val)
+    end
+  end
+
+end