multiarray 0.11.3 → 0.11.4

data/lib/multiarray/composite.rb

@@ -103,6 +103,13 @@ module Hornetseye
 
     end
 
+    # Decompose composite number
+    #
+    # This method decomposes the composite number.
+    #
+    # @return [Node] Returns the requested component.
+    #
+    # @private
     def decompose( i )
       self.class.element_type.new @value.decompose( i )
     end

data/lib/multiarray/diagonal.rb

@@ -35,8 +35,18 @@ module Hornetseye
 
     # Constructor
     #
-    # @param [Node] value Initial value of injection
-    # @param [Node] index0 Index for 
+    # @param [Node] value Initial value of injection.
+    # @param [Node] index0 Index to select starting point of injection.
+    # @param [Node] index1 Index to diagonally iterate over +value+.
+    # @param [Node] index2 Index to diagonally iterate over +value+.
+    # @param [Node,NilClass] initial Initial value for injection.
+    # @param [Node] block Expression with body of injection.
+    # @param [Variable] var1 Variable for performing substitutions on body of
+    #        injection.
+    # @param [Variable] var2 Variable for performing substitutions on body of
+    #        injection.
+    #
+    # @private
     def initialize( value, index0, index1, index2, initial, block, var1,
                     var2 )
       @value, @index0, @index1, @index2, @initial, @block, @var1, @var2 =
@@ -67,7 +77,11 @@ module Hornetseye
     #
     # @private
     def array_type
-      Hornetseye::MultiArray @block.typecode, *@value.shape
+      retval = Hornetseye::MultiArray @block.typecode, *@value.shape
+      ( class << self; self; end ).instance_eval do
+        define_method( :array_type ) { retval }
+      end
+      retval
     end
 
     # Reevaluate computation
@@ -179,3 +193,4 @@ module Hornetseye
   end
 
 end
+

data/lib/multiarray/elementwise.rb

@@ -17,6 +17,7 @@
 # Namespace of Hornetseye computer vision library
 module Hornetseye
 
+  # Class for representing element-wise operations
   class ElementWise_ < Node
 
     class << self
@@ -26,7 +27,7 @@ module Hornetseye
       # @return [Proc] A closure with the operation.
       attr_accessor :operation
 
-      # Unique key to identify operation.
+      # Unique key to identify operation
       #
       # @return [Symbol,String] A unique key to identify this operation.
       attr_accessor :key
@@ -92,7 +93,11 @@ module Hornetseye
     # @private
     def array_type
       array_types = @values.collect { |value| value.array_type }
-      self.class.conversion.call *array_types
+      retval = self.class.conversion.call *array_types
+      ( class << self; self; end ).instance_eval do
+        define_method( :array_type ) { retval }
+      end
+      retval
     end
 
     # Reevaluate computation

data/lib/multiarray/float.rb

@@ -17,10 +17,16 @@
 # Namespace of Hornetseye computer vision library
 module Hornetseye
 
+  # Class for representing native floating point numbers
   class FLOAT_ < Element
 
     class << self
 
+      # Boolean indicating whether this number is single or double precision
+      #
+      # @return [Boolean] +true+ for double precision, +false+ for single precision.
+      #
+      # @private
       attr_accessor :double
 
       # Memory type required to store elements of this type
@@ -102,11 +108,15 @@ module Hornetseye
         double ? 'd' : 'f'
       end
 
-      # Return string with information about this class.
+      # Return string with information about this class
       #
       # @return [String] Returns a string (e.g. "SFLOAT").
       def inspect
-        "#{ double ? 'D' : 'S' }FLOAT"
+        retval = "#{ double ? 'D' : 'S' }FLOAT"
+        ( class << self; self; end ).instance_eval do
+          define_method( :inspect ) { retval }
+        end
+        retval
       end
 
       # Get unique descriptor of this class
@@ -129,7 +139,7 @@ module Hornetseye
         other.is_a? Class and other < FLOAT_ and double == other.double
       end
 
-      # Compute hash value for this class.
+      # Compute hash value for this class
       #
       # @return [Fixnum] Hash value
       #
@@ -151,6 +161,11 @@ module Hornetseye
 
     end
 
+    # Namespace containing method for matching elements of type FLOAT_
+    #
+    # @see FLOAT_
+    #
+    # @private
     module Match
 
       # Method for matching elements of type FLOAT_
@@ -197,9 +212,31 @@ module Hornetseye
 
   end
 
+  # Boolean constant to use as a parameter for creating floating point classes
+  #
+  # The value is +false+.
+  #
+  # @see #FLOAT
   SINGLE = false
+
+  # Boolean constant to use as a parameter for creating floating point classes
+  #
+  # The value is +true+.
+  #
+  # @see #FLOAT
   DOUBLE = true
 
+  # Create a class deriving from +FLOAT_+
+  #
+  # Create a class deriving from +FLOAT_+. The parameters +double+ is assigned to the
+  # corresponding attributes of the resulting class.
+  #
+  # @param [Boolean] double Specify +SINGLE+ or +DOUBLE+ here.
+  #
+  # @return [Class] A class deriving from +FLOAT_+.
+  #
+  # @see FLOAT_
+  # @see FLOAT_.double
   def FLOAT( double )
     retval = Class.new FLOAT_
     retval.double = double
@@ -208,7 +245,10 @@ module Hornetseye
 
   module_function :FLOAT
 
+  # Single-precision floating-point number
   SFLOAT = FLOAT SINGLE
+
+  # Double-precision floating-point number
   DFLOAT = FLOAT DOUBLE
 
   # Shortcut for constructor

data/lib/multiarray/gcccache.rb

@@ -16,7 +16,10 @@
 
 # Namespace of Hornetseye computer vision library
 module Hornetseye
-  
+
+  # Class for holding methods compiled during runtime
+  # 
+  # @private  
   class GCCCache
   end
 

data/lib/multiarray/gcccontext.rb

@@ -16,30 +16,68 @@
 
 # Namespace of Hornetseye computer vision library
 module Hornetseye
-  
+
+  # Context object for creating a Ruby extension
+  #
+  # @private
   class GCCContext
 
+    # Ruby configuration
+    #
+    # @private
     CFG = RbConfig::CONFIG
+
     if CFG[ 'rubyhdrdir' ]
+      # GCC compiler flags
+      #
+      # @private
       CFLAGS = "-DNDEBUG #{CFG[ 'CFLAGS' ]} " +
         "-I#{CFG['rubyhdrdir']} -I#{CFG['rubyhdrdir']}/#{CFG['arch']}"
     else
       CFLAGS = "-DNDEBUG #{CFG[ 'CFLAGS' ]} " +
         "-I#{CFG['archdir']}"
     end
+
+    # Arguments for linking the Ruby extension
+    #
+    # @private
     LIBRUBYARG = "-L#{CFG[ 'libdir' ]} #{CFG[ 'LIBRUBYARG' ]} #{CFG[ 'LDFLAGS' ]} "
                  "#{CFG[ 'SOLIBS' ]} #{CFG[ 'DLDLIBS' ]}"
+
+    # Command for linking the Ruby extension
+    #
+    # @private
     LDSHARED = CFG[ 'LDSHARED' ]
+
+    # Shared library file extension under current operating system
+    #
+    # @private
     DLEXT = CFG[ 'DLEXT' ]
+
+    # Directory for storing the Ruby extensions
+    #
+    # @private
     DIRNAME = "#{Dir.tmpdir}/hornetseye-ruby#{RUBY_VERSION}-" +
               "#{ENV[ 'USER' ] || ENV[ 'USERNAME' ]}"
+
+    # Lock file to prevent conflicts
+    #
+    # @private
     LOCKFILE = "#{DIRNAME}/lock"
+
     Dir.mkdir DIRNAME, 0700 unless File.exist? DIRNAME
+
+    # The actual file lock
+    #
+    # @private
     @@lock = File.new LOCKFILE, 'w', 0600
     unless @@lock.flock File::LOCK_EX | File::LOCK_NB
       raise "Could not lock file \"#{LOCKFILE}\""
     end
 
+    # Next available base name for a Ruby extension
+    #
+    # @private
     @@lib_name = 'hornetseye_aaaaaaaa'
 
     if ENV[ 'HORNETSEYE_PRELOAD_CACHE' ]
@@ -51,6 +89,15 @@ module Hornetseye
 
     class << self
 
+      # Method for compiling Ruby to C
+      #
+      # @param [Proc] action The code block needs to accept a GCCContext object.
+      #
+      # @return [Object] Returns result of code block.
+      #
+      # @see GCCFunction.run
+      #
+      # @private
       def build( &action )
         lib_name, @@lib_name = @@lib_name, @@lib_name.succ
         new( lib_name ).build &action
@@ -58,6 +105,11 @@ module Hornetseye
 
     end
 
+    # Initialises an empty Ruby extension
+    #
+    # @param [String] lib_name Base name of library to create later.
+    #
+    # @private
     def initialize( lib_name )
       @lib_name = lib_name
       @instructions = ''
@@ -65,39 +117,67 @@ module Hornetseye
       @registrations = ''
     end
 
+    # Create Ruby extension
+    #
+    # @param [Proc] action Code block accepting a GCCContext object.
+    #
+    # @return [Object] Returns result of code block.
+    #
+    # @private
     def build( &action )
       action.call self
     end
 
+    # Add a new function to the Ruby extension
+    #
+    # @param [String] descriptor Method name of function.
+    # @param [Array<GCCType>] param_types Array with parameter types.
+    #
+    # @return [GCCFunction] Object representing the function.
+    #
+    # @private
     def function( descriptor, *param_types )
       @instructions << <<EOS
-void #{descriptor}(#{
-if param_types.empty?
-  ''
-else
-  ' ' + param_types.collect do |t|
-    t.identifiers
-  end.flatten.collect_with_index do |ident,i|
-    "#{ident} param#{i}"
-  end.join( ', ' ) + ' '
-end
-}) {
+struct Arguments
+{
+#{
+param_types.collect do |t|
+  t.identifiers
+end.flatten.collect_with_index do |ident,i|
+  "  #{ident} param#{i};"
+end.join( "\n" )
+}
+};
+
+VALUE #{descriptor}( void *args )
+{
+#{
+param_types.collect do |t|
+  t.identifiers
+end.flatten.collect_with_index do |ident,i|
+  "  #{ident} param#{i} = ((struct Arguments *)args)->param#{i};"
+end.join( "\n" )
+}
 EOS
 
       @wrappers << <<EOS
 VALUE wrap#{descriptor.capitalize}( int argc, VALUE *argv, VALUE rbSelf )
 {
-  #{descriptor}(#{
-if param_types.empty?
-  ''
+  struct Arguments args;
+#{
+param_types.collect do |t|
+  t.r2c
+end.flatten.collect_with_index do |conv,i|
+  "  args.param#{i} = #{conv.call "argv[ #{i} ]"};"
+end.join( "\n" )
+}
+#{
+if RUBY_VERSION < '1.9.0'
+  "  #{descriptor}( &args );"
 else
-  s = ' ' + param_types.collect do |t|
-    t.r2c
-  end.flatten.collect_with_index do |conv,i|
-    conv.call "argv[ #{i} ]"
-  end.join( ', ' ) + ' '
+  "  rb_thread_blocking_region( &#{descriptor}, &args, RUBY_UBF_PROCESS, NULL );"
 end
-});
+}
   return Qnil;
 }
 EOS
@@ -107,6 +187,15 @@ EOS
                     RUBY_METHOD_FUNC( wrap#{descriptor.capitalize} ), -1 ); 
 EOS
     end
+
+    # Compile the Ruby extension
+    #
+    # This method writes the source code to a file and calls GCC to compile it.
+    # Finally the Ruby extension is loaded.
+    #
+    # @return [Boolean] Returns of loading the Ruby extension.
+    #
+    # @private
     def compile
       template = <<EOS
 #include <ruby.h>
@@ -140,6 +229,15 @@ EOS
       require "#{DIRNAME}/#{@lib_name}"
     end
 
+    # Add instructions to Ruby extension
+    #
+    # The given string is appended to the source code of the Ruby extension.
+    #
+    # @param [String] str String with source code fragment of Ruby extension.
+    #
+    # @return [GCCContext] Returns +self+.
+    #
+    # @private
     def <<( str )
       @instructions << str
       self

data/lib/multiarray/gccfunction.rb

@@ -16,17 +16,41 @@
 
 # Namespace of Hornetseye computer vision library
 module Hornetseye
-  
+ 
+  # Class representing a compiled function 
   class GCCFunction
 
     class << self
 
+      # Compile a block of Ruby code if not compiled already and run it
+      #
+      # @param [Node] block Expression to compile and run.
+      #
+      # @return [Object] Result returned by the compiled function.
+      #
+      # @private
       def run( block )
         keys, values, term = block.strip
         labels = Hash[ *keys.zip( ( 0 ... keys.size ).to_a ).flatten ]
         method_name = ( '_' + term.descriptor( labels ) ).
                             tr( '(),+\-*/%.@?~&|^<=>',
                                 '0123\456789ABCDEFGH' )
+        compile method_name, term, *keys
+        args = values.collect { |arg| arg.values }.flatten
+        GCCCache.send method_name, *args
+      end
+
+      # Compile a block of Ruby code if not compiled already
+      #
+      # @param [String] method_name Unique method name of function.
+      # @param [Node] term Stripped expression to compile.
+      # @param [Array<Variable>] keys Variables for performing substitutions on
+      #        +term+.
+      #
+      # @return [Object] The return value should be ignored.
+      #
+      # @private
+      def compile( method_name, term, *keys )
         unless GCCCache.respond_to? method_name
           GCCContext.build do |context|
             function = GCCFunction.new context, method_name,
@@ -43,12 +67,17 @@ module Hornetseye
             function.compile
           end
         end
-        args = values.collect { |arg| arg.values }.flatten
-        GCCCache.send method_name, *args
       end
 
     end
 
+    # Constructor
+    #
+    # @param [GCContext] context Context object for compiling function.
+    # @param [String] method_name Unique method name.
+    # @param [Array<Class>] param_types Native types of parameters.
+    #
+    # @private
     def initialize( context, method_name, *param_types )
       context.function method_name, *param_types.collect { |t| GCCType.new t }
       @context = context
@@ -58,31 +87,70 @@ module Hornetseye
       @ids = 0
     end
 
+    # Close the function and compile it
+    #
+    # @return [GCCFunction] Returns +self+.
+    #
+    # @private
     def compile
       self << '}'
       @context.compile
       self
     end
 
+    # Create a new identifier unique to this function
+    #
+    # @param [String] prefix Prefix for constructing the identifier.
+    #
+    # @return [String] A new identifier.
+    #
+    # @private
     def id( prefix )
       @ids += 1
       "%s%02d"% [ prefix, @ids ]
     end
 
+    # Create a new C variable of given type
+    #
+    # @param [Class] typecode Native type of variable.
+    # @param [String] prefix Prefix for creating variable name.
+    #
+    # @return [GCCValue] GCC value object refering to the C variable.
+    #
+    # @private
     def variable( typecode, prefix )
       retval = GCCValue.new( self, id( prefix ) )
       self << "#{indent}#{GCCType.new( typecode ).identifier} #{retval};\n"
       retval
     end
 
+    # Auxiliary method for code intendation
+    #
+    # @return [String] String to use for indentation.
+    #
+    # @private
     def indent
       '  ' * @indent
     end
 
+    # Increase/decrease amount of indentation
+    #
+    # @param [Integer] offset Offset to add to current amount of indentation.
+    #
+    # @return [Integer] Resulting amount of indentation.
+    #
+    # @private
     def indent_offset( offset )
       @indent += offset
     end
 
+    # Retrieve a parameter
+    #
+    # @param [Integer] i Parameter to retrieve.
+    #
+    # @return [Node] Object for handling the parameter.
+    #
+    # @private
     def param( i )
       offset = ( 0 ... i ).inject( 0 ) do |s,idx|
         s + GCCType.new( @param_types[ idx ] ).identifiers.size
@@ -92,14 +160,35 @@ module Hornetseye
       @param_types[ i ].construct *args
     end
 
+    # Call the native method
+    #
+    # @param [Array<Node>] args Arguments of method call.
+    #
+    # @return The return value of the native method.
+    #
+    # @private
     def call( *args )
       @context.send @method_name, *args.collect { |v| v.get }
     end
 
+    # Add return instruction to native method
+    #
+    # @param [Object,NilClass] value Return value or +nil+.
+    #
+    # @return [GCCFunction] Returns +self+.
+    #
+    # @private
     def insn_return( value = nil )
       self << "#{indent}return#{ value ? ' ' + value.get.to_s : '' };\n"
     end
 
+    # Add instructions to C function
+    #
+    # @param [String] str C code fragment.
+    #
+    # @return [GCCFunction] Returns +self+.
+    #
+    # @private
     def <<( str )
       @context << str
       self