nice-ffi 0.1 → 0.2

data/README.rdoc

@@ -1,8 +1,8 @@
 
 = Nice-FFI
 
-Version::    0.1
-Date::       2009-07-05
+Version::    0.2
+Date::       2009-10-24
 
 Homepage::   http://github.com/jacius/nice-ffi/
 Author::     John Croisant <jacius@gmail.com>
@@ -12,22 +12,30 @@ Copyright::  2009  John Croisant
 == Description
 
 Nice-FFI is a layer on top of Ruby-FFI [1] (and compatible FFI
-systems) to augment it with features to aid development of
-FFI-based libraries.
+systems) with features to ease development of FFI-based libraries.
 
 Nice-FFI currently features:
 
-* NiceFFI::Struct: a stand-in for FFI::Struct that provides automatic
-  accessors for struct members, more instance initialization options,
-  pretty to_s and inspect methods, and other niceties.
-
 * NiceFFI::Library: a stand-in for FFI::Library that provides methods
   for easily finding and loading libraries on any platform, plus
   automatic wrapping of functions that return struct pointers.
 
+* NiceFFI::PathSet: a class with customizable rules for finding
+  library files on multiple operating system. PathSet is used by
+  NiceFFI::Library.load_library.
+
+* NiceFFI::Struct: a stand-in for FFI::Struct that provides automatic
+  accessors for struct members, optional automatic memory management,
+  more instance initialization options, pretty to_s and inspect
+  methods, and other niceties.
+
+* NiceFFI::OpaqueStruct: a base class for structs with no user-exposed
+  members. Useful when the struct definition is hidden by the
+  underlying C library.
+
 Nice-FFI was originally developed as part of Ruby-SDL-FFI [2].
 
-1. Ruby-FFI: http://kenai.com/projects/ruby-ffi/
+1. Ruby-FFI: http://github.com/ffi/ffi
 2. Ruby-SDL-FFI: http://github.com/jacius/ruby-sdl-ffi/
 
 
@@ -46,8 +54,12 @@ match the new API, then you should wait until version 1.0.
 
 == Requirements
 
-* Ruby-FFI  >= 0.3.0 (or compatible)
-* need      >= 1.1.0
+* Ruby-FFI  >= 0.4.0 (or compatible FFI implementation)
+
+
+== Usage
+
+See docs/usage.rdoc for usage information.
 
 
 == License

data/docs/usage.rdoc

@@ -30,14 +30,14 @@ of "extend FFI::Library", and use "load_library" instead of "ffi_lib":
 
   
   require 'nice-ffi'
-
+  
   module MyLibraryModule
     extend NiceFFI::Library
-
+  
     load_library("SDL")  # look for libSDL.so, SDL.dll, etc.
-
+  
     # structs, functions, etc. as usual.
-
+  
   end
   
 
@@ -47,53 +47,72 @@ As mentioned, load_library uses NiceFFI::PathSet to search for the
 library in likely directories. Specifically, it looks for:
 
   
-  NiceFFI::Library::DEFAULT_PATHS = NiceFFI::PathSet.new(
-
-    /linux|bsd/  => [ "/usr/local/lib/lib[NAME].so",
-                      "/usr/lib/lib[NAME].so",
-                      "[NAME]" ],
-
-    /darwin/     => [ "/usr/local/lib/lib[NAME].dylib",
-                      "/sw/lib/lib[NAME].dylib",
-                      "/opt/local/lib/lib[NAME].dylib",
-                      "~/Library/Frameworks/[NAME].framework/[NAME]",
-                      "/Library/Frameworks/[NAME].framework/[NAME]",
-                      "[NAME]" ],
-
-    /win32/      => [ "C:\\windows\\system32\\[NAME].dll",
-                      "C:\\windows\\system\\[NAME].dll",
-                      "[NAME]" ]
-  )
+  paths = {
+    /linux|bsd/  => [ "/usr/local/lib/",
+                      "/usr/lib/" ],
+  
+    /darwin/     => [ "/usr/local/lib/",
+                      "/sw/lib/",
+                      "/opt/local/lib/",
+                      "~/Library/Frameworks/",
+                      "/Library/Frameworks/" ],
+  
+    /windows/    => [ "C:\\windows\\system32\\",
+                      "C:\\windows\\system\\" ]
+  }
+  
+  files = {
+    /linux|bsd/  => [ "lib[NAME].so" ],
+  
+    /darwin/     => [ "lib[NAME].dylib",
+                      "[NAME].framework/[NAME]" ],
+  
+    /windows/    => [ "[NAME].dll" ]
+  }
+  
+  NiceFFI::PathSet::DEFAULT = NiceFFI::PathSet.new( paths, files )
   
 
-The string "[NAME]" is replaced with whatever string you pass to
+The paths hash tells PathSet where to look for libraries, and the
+files hash tells it the format of the library filename itself. The
+string "[NAME]" is replaced with whatever string you pass to
 load_library.
 
+Each key in the hash should be a Regexp that matches an OS name from
+FFI::Platform::OS. As of this writing (October 2009), the list of
+recognized OS names is:
+
+* "darwin" (MacOS X)
+* "freebsd"
+* "linux"
+* "openbsd"
+* "solaris"
+* "windows"
+
 So, if the user is running Linux and you try to load "SDL", it will
-first look for "/usr/local/lib/libSDL.so". If it couldn't find the
-first one, it will then look for "/usr/lib/libSDL.so", and finally it
-will just try loading "SDL" using ffi_lib (which does some
-platform-appropriate guesses too). It would also use those same
-paths for FreeBSD, because that OS matches /linux|bsd/, too.
-/darwin/ matches on MacOS X, and /win32/ matches on Windows.
+first look for "/usr/local/lib/libSDL.so". If it can't find that, it
+will then look for "/usr/lib/libSDL.so". It would also use those same
+paths for FreeBSD or OpenBSD, because those OS names also match the
+regexp /linux|bsd/.
+
+If the library could not be found in any of the given directories with
+the given file name formats, load_library will just try loading "SDL"
+using ffi_lib (which does some platform-appropriate guesses too). If
+that fails too, LoadError is raised.
 
 If you want to load from a different path, you can make a custom
 PathSet and pass it to load_library:
 
   
-  this_dir = File.dirname(__FILE__)
+  libs_dir = File.dirname(__FILE__) + "/libs/"
   
-  my_pathset = NiceFFI::Library::DEFAULT_PATHS.prepend(
-    /linux|bsd/  => [ "#{this_dir}/libs/lib[NAME].so" ],
-    /darwin/     => [ "#{this_dir}/libs/lib[NAME].dylib" ],
-    /win32/      => [ "#{this_dir}/libs/[NAME].dll" ]
-  )
+  pathset = NiceFFI::PathSet::DEFAULT.prepend( libs_dir )
   
   load_library( "SDL", my_pathset )
   
 
 The above example prepends (adds in front) the new paths so
-that load_library will look for the library in in "./libs/" first.
+that load_library will look for the library in "./libs/" first.
 See PathSet for other useful methods for modifying PathSets.
 
 
@@ -135,8 +154,12 @@ With TypedPointer, the wrapping happens automatically. Just attach
 the function with a TypedPointer instead of :pointer:
 
   
-  attach_function :get_my_struct, [:int], NiceFFI::TypedPointer( MyStruct )
+  attach_function :make_my_struct, [:int, :int], NiceFFI::TypedPointer( MyStruct )
   
+  # If MyStruct is based on NiceFFI::Struct, you can do this instead:
+  
+  attach_function :make_my_struct, [:int, :int], MyStruct.typed_pointer
+
 
 Then you automatically get a MyStruct instance when you call the function:
 
@@ -148,7 +171,6 @@ Then you automatically get a MyStruct instance when you call the function:
 Voila!
 
 
-
 == NiceFFI::Struct
 
 NiceFFI::Struct is a replacement for FFI::Struct. It provides several
@@ -252,3 +274,88 @@ struct pointer, but if you specify a TypedPointer instead of
   # Seamlessly unwraps the struct and stores the pointer  
   struct.my = MyStruct.new([-4,-3])
   
+
+=== Automatic Memory Managment
+
+Ruby-FFI already provides automatic memory management when you create
+a FFI::MemoryPointer or FFI::Buffer instance. When those instances are
+garbage collected, their memory is automatically released so it can be
+used elsewhere.
+
+That feature is used by NiceFFI::Struct when you create a new instance
+by passing a Hash, Array, String, or another instance. In those cases,
+new memory is allocated for the struct instance, and automatically
+released when the struct instance is galbage collected.
+
+NiceFFI::Struct also provides an optional automatic memory management
+system for normal pointers. To use this system, define a "release"
+class method in your class. Then if you create a new struct instance
+with an FFI::Pointer, the release class method will automatically be
+called when the memory for a struct instance needs to be freed.
+
+(This also applies to attached functions with TypedPointer return
+values. The pointers returned from those functions are wrapped in the
+struct class, so if you have defined the release class method, they
+will be automatically memory managed.)
+
+The release class method must accept an FFI::Pointer and call an
+appropriate function to free the struct's memory. Here's an example
+from Ruby-SDL-FFI:
+
+  
+  class Surface < NiceFFI::Struct
+  
+    def self.release( pointer )
+      SDL.FreeSurface( pointer )
+    end
+  
+    # ...
+  
+  end
+  
+
+Note: the release class method should not have any side effects
+besides freeing the struct's memory. Don't be clever!
+
+The memory management system keeps a reference count for each pointer
+address, so the release class method will only be called when all
+struct instances that are using that memory have been garbage
+collected. That means it's safe to have many instances sharing the
+same memory.
+
+If you want to create an instance that doesn't use the memory
+management system, you can disable the :autorelease option when
+creating the instance, like so:
+
+  
+  struct = MyStructClass.new( a_pointer, :autorelease => false )
+  
+
+== NiceFFI::OpaqueStruct
+
+Some C libraries have structs with no publicly-visible layout.
+Instead, the internal details are hidden, and only modified by calling
+functions in the library.
+
+For example, the SDL_mixer library has this definition in its header
+file:
+
+  
+  typedef struct _Mix_Music Mix_Music;
+  
+
+"_Mix_Music" is a struct that is defined within SDL_mixer, but its
+internals are different depending on what features SDL_mixer was
+compiled with. The struct members are not revealed in the header file,
+so they can't be accessed like a normal struct.
+
+NiceFFI provides a class for handling special cases like this,
+NiceFFI::OpaqueStruct. OpaqueStruct has no layout and no members, and
+cannot be created by passing in Hashes, Arrays, etc. It simply holds a
+pointer to the struct memory. As with NiceStruct (and FFI::Struct),
+instances of OpaqueStruct-based classes can be passed directly to
+functions expecting a pointer of the appropriate struct type.
+
+OpaqueStruct features the same optional memory management system as
+NiceStruct. Read the "Automatic Memory Management" section above for
+information about how to use this feature.

data/lib/nice-ffi.rb

@@ -28,20 +28,26 @@
 #++
 
 
-require 'need'
+require 'ffi'
 
 
 module NiceFFI
 end
 
 
+this_dir = File.expand_path( File.dirname(__FILE__) )
+
 %w{
 
-  nicelibrary
-  nicestruct
+  typedpointer
+  pathset
+  library
+  autorelease
+  struct
+  opaquestruct
 
 }.each do |f|
 
-  need { File.join( 'nice-ffi', f ) }
+  require File.join( this_dir, 'nice-ffi', f )
 
 end

data/lib/nice-ffi/autorelease.rb

@@ -0,0 +1,112 @@
+#--
+#
+# This file is one part of:
+#
+# Nice-FFI - Convenience layer atop Ruby-FFI
+#
+# Copyright (c) 2009 John Croisant
+#
+# 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.
+#
+#++
+
+
+
+#--
+# Don't scan this module for RDoc/RI.
+
+
+require 'thread' # for Mutex. JRuby doesn't load this by default.
+
+# A mixin module to provide automatic memory management for C structs.
+#
+module NiceFFI::AutoRelease
+
+  #  Sets up the class when this module is included. Adds the class
+  #  methods and defines class instance variables.
+  def self.included( klass )
+    class << klass
+
+      # Increment the reference count for this address.
+      def _incr_refcount( address )
+        @ptr_mutex ||= Mutex.new
+        @ptr_mutex.synchronize {
+          @ptr_refcounts ||= Hash.new(0)
+          @ptr_refcounts[address] += 1
+        }
+        return nil
+      end
+
+      # Decrement the counter for this pointer's address, and free
+      # the memory if the reference count falls below 1.
+      #
+      def _release( pointer )
+        @ptr_mutex ||= Mutex.new
+        @ptr_mutex.synchronize {
+          _decr_refcount(pointer.address)
+          if( @ptr_refcounts[pointer.address] < 1 )
+            release( pointer )
+          end
+        }
+      end
+
+      private
+
+      # Decrement the reference count for this address. If the count falls
+      # below 1, the address is removed from Hash altogether.
+      #
+      # Note: this method does not have a Mutex lock by itself, but you
+      # should use a lock in any methods that call it.
+      # 
+      def _decr_refcount( address )
+        @ptr_refcounts ||= Hash.new(0)
+        @ptr_refcounts[address] -= 1
+        if( @ptr_refcounts[address] < 1 )
+          @ptr_refcounts.delete(address)
+        end
+      end
+
+    end
+  end
+
+
+  private
+
+
+  def _make_autopointer( ptr, autorelease=true )
+    if( autorelease and
+        self.class.respond_to?(:release) and
+        ptr.is_a?(FFI::Pointer) and
+        not ptr.is_a?(FFI::MemoryPointer) and
+        not ptr.is_a?(FFI::Buffer) )
+
+      # Increment the reference count for this pointer address
+      self.class._incr_refcount( ptr.address )
+
+      # Wrap in an AutoPointer to call self.class._release when it's GC'd.
+      return FFI::AutoPointer.new( ptr, self.class.method(:_release) )
+
+    else
+      return ptr
+    end
+  end
+
+
+end

data/lib/nice-ffi/{nicelibrary.rb → library.rb}

@@ -28,49 +28,33 @@
 #++
 
 
-require 'ffi'
-
-need{ 'typedpointer' }
-need{ 'pathset' }
-
-
 # A module to be used in place of FFI::Library. It acts mostly
 # like FFI::Library, but with some nice extra features and
 # conveniences to make life easier:
 # 
+# * load_library method to help find and load libraries from common
+#   (or custom) places for the current OS. Use it instead of ffi_lib.
+# 
 # * attach_function accepts TypedPointers as return type,
 #   in which case it wraps the return value of the bound function
 #   in the TypedPointer's type.
 # 
+# * Shorthand aliases to improve code readability:
+#   * func = attach_function
+#   * var  = attach_variable
+# 
 module NiceFFI::Library
 
   def self.extend_object( klass )
     klass.extend FFI::Library
-    super
-  end
-
-
-  # The default paths to look for libraries. See PathSet 
-  # and #load_library.
-  # 
-  DEFAULT_PATHS = NiceFFI::PathSet.new(
-
-    /linux|bsd/  => [ "/usr/local/lib/lib[NAME].so",
-                      "/usr/lib/lib[NAME].so",
-                      "[NAME]" ],
-
-    /darwin/     => [ "/usr/local/lib/lib[NAME].dylib",
-                      "/sw/lib/lib[NAME].dylib",
-                      "/opt/local/lib/lib[NAME].dylib",
-                      "~/Library/Frameworks/[NAME].framework/[NAME]",
-                      "/Library/Frameworks/[NAME].framework/[NAME]",
-                      "[NAME]" ],
 
-    /win32/      => [ "C:\\windows\\system32\\[NAME].dll",
-                      "C:\\windows\\system\\[NAME].dll",
-                      "[NAME]" ]
+    super
 
-  )
+    class << klass
+      alias :func :attach_function
+      alias :var  :attach_variable
+    end
+  end
 
 
   # Try to find and load a library (e.g. "SDL_ttf") into an FFI
@@ -81,22 +65,14 @@ module NiceFFI::Library
   # 
   # Raises LoadError if it could not find or load the library.
   # 
-  def load_library( names, search_paths=NiceFFI::Library::DEFAULT_PATHS )
+  def load_library( names, search_paths=NiceFFI::PathSet::DEFAULT_PATHS )
 
     names = [names] unless names.kind_of? Array
 
     paths = search_paths.find( *names )
 
-    pretty_names = if names.size == 1
-                    names[0]
-                  else
-                    names[0..-2].join(", ") + ", or " + names[-1]
-                  end
-
-    # Oops, couldn't find it anywhere.
-    if paths.empty?
-      raise LoadError, "Could not find #{pretty_names}. Is it installed?"
-    end
+    # Try just the plain library name(s), as last resort.
+    paths += names
 
     # Try loading each path until one works.
     loaded = paths.find { |path| 
@@ -111,8 +87,14 @@ module NiceFFI::Library
       end
     }
 
-    # Oops, none of them worked.
     if loaded.nil?
+      # Oops, none of them worked.
+      pretty_names = if names.size == 1
+                       names[0]
+                     else
+                       names[0..-2].join(", ") + ", or " + names[-1]
+                     end
+
       raise( LoadError, "Could not load #{pretty_names}." )
     else
       # Return the one that did work
@@ -130,10 +112,10 @@ module NiceFFI::Library
     # 2. methname, funcname, args, retrn_type
     # 
     funcname, args, retrn_type = if arg1.kind_of?(Array)
-                                    [methname, arg1, arg2]
-                                  else
-                                    [arg1, arg2, arg3]
-                                  end
+                                   [methname, arg1, arg2]
+                                 else
+                                   [arg1, arg2, arg3]
+                                 end
 
     unless retrn_type.kind_of? NiceFFI::TypedPointer
       # Normal FFI::Library.attach_function behavior.
@@ -169,4 +151,50 @@ module NiceFFI::Library
     end
 
   end
+
+
+  # Calls the given block, but rescues and prints a warning if
+  # FFI::NotFoundError is raised. If warn_message is nil, the
+  # error message is printed instead.
+  # 
+  # This is intended to be used around #attach_function for cases
+  # where the function may not exist (e.g. because the user has an
+  # old version of the library) and the library should continue loading
+  # anyway (with the function missing).
+  # 
+  # 
+  # Example:
+  # 
+  #   module Foo
+  #     extend NiceFFI::Library
+  #   
+  #     load_library( "libfoo" )
+  #     
+  #     optional( "Warning: Your libfoo doesn't have opt_func()" ) do
+  #       attach_function :opt_func, [], :int
+  #     end
+  #   end
+  # 
+  def optional( warn_message=nil, &block )
+    raise LocalJumpError, "no block given" unless block_given?
+    begin
+      block.call()
+    rescue FFI::NotFoundError => e
+      if warn_message
+        puts warn_message
+      else
+        puts "Warning: #{e.message}"
+      end
+    end
+  end
+
+
+  # Like #attach_function, but wrapped in #optional.
+  def optional_function( *args )
+    optional {  attach_function( *args )  }
+  end
+
+  alias :optfunc :optional_function
+
+
 end