comp_tree 0.5.0

data/README

@@ -0,0 +1,153 @@
+
+= CompTree -- Parallel Computation Tree
+
+== Synopsis
+  
+  require 'comp_tree'
+  
+  CompTree::Driver.new { |driver|
+
+    # Define a function named 'area' taking these three arguments.
+    driver.define_area(:width, :height, :offset) { |width, height, offset|
+      width*height - offset
+    }
+    
+    # Define a function 'width' which takes a 'border' argument.
+    driver.define_width(:border) { |border|
+      2 + border
+    }
+    
+    # Ditto for 'height'.
+    driver.define_height(:border) { |border|
+      3 + border
+    }
+    
+    # Define a constant function 'border'.
+    driver.define_border {
+      5
+    }
+    
+    # Ditto for 'offset'.
+    driver.define_offset {
+      7
+    }
+    
+    # Compute the area using four parallel threads.
+    area = driver.compute(:area, :threads => 4)
+
+    # We've done this computation.
+    if area == (2 + 5)*(3 + 5) - 7
+      puts "It worked!"
+    else
+      puts "Send bug report to ..."
+    end
+  }
+
+=== Alternative Forms for Function Definitions
+
+This form evals a lambda, saving you the repeat parameter list:
+
+  driver.define_area :width, :height, :offset, %{
+    width*height - offset
+  }
+  
+  driver.define_width :border, %{
+    2 + border
+  }
+  
+Notice the '<code>%</code>' before the brace.  The lambda is created
+just once, during the time of definition.
+
+Finally there is the raw form which uses no +eval+ or
++method_missing+ tricks:
+
+  driver.define(:area, :width, :height, :offset) { |width, height, offset|
+    width*height - offset
+  }
+        
+  driver.define(:width, :border) { |border|
+    2 + border
+  }
+
+== Important Notes
+
+The user should have a basic understanding of <em>functional
+programming</em> (see for example
+http://en.wikipedia.org/wiki/Functional_programming) and the meaning
+of <em>side effects</em>.
+
+CompTree requires the user to adopt a functional style.  Every
+function you define must explicitly depend on the data it uses.
+
+  #
+  # BAD example: depending on state -- offset not listed as a parameter
+  #
+  driver.define_area(:width, :height) { |width, height|
+    width*height - offset
+  }
+
+Unless <em>offset</em> is really a constant, the result of
+<tt>driver.compute(:area, :num_threads => n)</tt> is not well-defined
+for _n_ > 1.
+
+Just as depending on some changeable state is bad, it is likewise bad
+to affect a state (to produce a <em>side effect</em>).
+
+  #
+  # BAD example: affecting state
+  #
+  driver.define_area(:width, :height, :offset) { |width, height, offset|
+    ACCUMULATOR.add "more data"
+    width*height - offset
+  }
+
+Given a tree where nodes are modifying _ACCUMULATOR_, the end state of
+_ACCUMULATOR_ is not well-defined.  Moreover if _ACCUMULATOR_ is not
+thread-safe, the result will be even worse.
+
+Note however it is OK affect a state as long as <em>no other function
+depends on that state</em>.  This is the principle under which
++comp_tree+ parallelizes Rake tasks (http://drake.rubyforge.org).
+
+== Install
+
+  % gem install comp_tree
+
+Or for the regular (non-gem) .tgz package,
+
+  % ruby install.rb [--uninstall]
+
+== Links
+
+* Download: http://rubyforge.org/frs/?group_id=6917
+* Rubyforge home: http://rubyforge.org/projects/comptree
+* Repository: http://github.com/quix/comp_tree
+
+== Author
+
+* James M. Lawrence <quixoticsycophant@gmail.com>
+
+== License
+  
+  Copyright (c) 2008 James M. Lawrence.  All rights reserved.
+  
+  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/Rakefile

@@ -0,0 +1,152 @@
+$LOAD_PATH.unshift "contrib/quix/lib"
+
+require 'rake/gempackagetask'
+require 'rake/contrib/rubyforgepublisher'
+require 'quix/subpackager'
+
+$VERBOSE = nil
+require 'rdoc/rdoc'
+$VERBOSE = true
+
+require 'fileutils'
+include FileUtils
+
+gemspec = eval(File.read("comp_tree.gemspec"))
+package_name = gemspec.name 
+package_name_in_ruby = "CompTree"
+
+# I would prefer "doc", but "html" is hard-coded for rubyforgepublisher
+doc_dir = "html"
+
+######################################################################
+# clean
+
+task :clean => [:clobber, :clean_doc] do
+end
+
+task :clean_doc do
+  rm_rf(doc_dir)
+end
+
+######################################################################
+# test
+
+task :test do
+  require 'test/all'
+end
+
+######################################################################
+# package
+
+task :package => :clean
+
+Rake::GemPackageTask.new(gemspec) { |t|
+  t.need_tar = true
+}
+
+######################################################################
+# doc
+
+task :doc => :clean_doc do 
+  files = %w(README) + %w(driver error node task_node).map { |name|
+    "lib/comp_tree/#{name}.rb"
+  }
+
+  options = [
+    "-o", doc_dir,
+    "--title", "comp_tree: #{gemspec.summary}",
+    "--main", "README"
+  ]
+
+  RDoc::RDoc.new.document(files + options)
+end
+
+######################################################################
+# repackage files from contrib/
+
+task :generate_rb do
+  packages = {
+    :comp_tree => {
+      :name_in_ruby => "CompTree",
+      :lib_dir => "./lib",
+      :subpackages => {
+        :quix => {
+          :name_in_ruby => "Quix",
+          :sources => [
+            "diagnostic",
+            "kernel",
+            "builtin/kernel/tap",
+          ],
+          :lib_dir => "./contrib/quix/lib",
+          :ignore_root_rb => true,
+        },
+      },
+    },
+  }
+  Quix::Subpackager.run(packages)
+end
+
+######################################################################
+# git
+
+def git(*args)
+  cmd = ["git"] + args
+  sh(*cmd)
+end
+
+task :init_contrib do
+  unless `git remote`.split.include? "quix"
+    git(*%w!remote add -f quix git@github.com:quix/quix.git!)
+  end
+end
+
+task :add_contrib_first_time => :init_contrib do
+  git(*%w!merge --squash -s ours --no-commit quix/master!)
+  git(*%w!read-tree --prefix=contrib/quix -u quix/master!)
+  git("commit", "-m", "add quix utils")
+end
+
+task :run_pull_contrib do
+  git(*%w!pull --no-commit -s subtree quix master!)
+end
+
+task :pull_contrib => [ :init_contrib, :run_pull_contrib, :generate_rb ]
+
+######################################################################
+# publisher
+
+task :publish => :doc do
+  Rake::RubyForgePublisher.new('comptree', 'quix').upload
+end
+
+######################################################################
+# release
+
+task :prerelease => :clean do
+  rm_rf(doc_dir)
+  rm_rf("pkg")
+  unless `git status` =~ %r!nothing to commit \(working directory clean\)!
+    raise "Directory not clean"
+  end
+end
+
+task :finish_release do
+  %w(gem tgz).each_with_index { |ext, index|
+    sh("rubyforge",
+       (index == 0 ? "add_release" : "add_file"), 
+       gemspec.rubyforge_project,
+       gemspec.rubyforge_project,
+       gemspec.version.to_s,
+       "pkg/#{gemspec.name}-#{gemspec.version}.#{ext}")
+  }
+  git("tag", gemspec.version.to_s)
+  git("push")
+end
+
+task :release =>
+  [
+   :prerelease,
+   :package,
+   :publish,
+   :finish_release,
+  ]

data/comp_tree.gemspec

@@ -0,0 +1,38 @@
+
+Gem::Specification.new { |t|
+  t.author = "James M. Lawrence"
+  t.email = "quixoticsycophant@gmail.com"
+  t.summary = "Parallel Computation Tree"
+  t.name = "comp_tree"
+  t.rubyforge_project = "comptree"
+  t.homepage = "comptree.rubyforge.org"
+  t.version = "0.5.0"
+  t.description = "Build a computation tree and execute it with N " +
+    "parallel threads.  Optionally fork computation nodes into new processes."
+
+  t.files = %w{README comp_tree.gemspec} +
+    Dir["./**/*.rb"] +
+    Dir["./**/Rakefile"]
+
+  rdoc_exclude = %w{
+    test
+    contrib
+    install
+    quix
+    fork
+    diagnostic
+    algorithm
+    bucket
+    comp_tree\.rb
+  }
+  t.has_rdoc = true
+  t.extra_rdoc_files = %w{README}
+  t.rdoc_options += [
+    "--main",
+    "README",
+    "--title",
+    "comp_tree: #{t.summary}",
+  ] + rdoc_exclude.inject(Array.new) { |acc, pattern|
+    acc + ["--exclude", pattern]
+  }
+}

data/contrib/quix/Rakefile

@@ -0,0 +1,16 @@
+$LOAD_PATH.unshift "./lib"
+
+require 'quix/simple_installer'
+require 'quix/config'
+
+task :test do
+  load './test/all.rb'
+end
+
+task :install do
+  Quix::SimpleInstaller.new.install
+end
+
+task :uninstall do
+  Quix::SimpleInstaller.new.uninstall
+end

data/contrib/quix/install.rb

@@ -0,0 +1,3 @@
+$LOAD_PATH.unshift "./lib"
+require 'quix/simple_installer'
+Quix::SimpleInstaller.new.run

data/contrib/quix/lib/quix/builtin/dir/casefold_brackets.rb

@@ -0,0 +1,7 @@
+
+class << Dir
+   remove_method :[]
+   def [](pattern)
+      Dir.glob(pattern, File::FNM_CASEFOLD)
+   end
+end

data/contrib/quix/lib/quix/builtin/kernel/tap.rb

@@ -0,0 +1,9 @@
+
+unless respond_to? :tap
+  module Kernel
+    def tap
+      yield self
+      self
+    end
+  end
+end

data/contrib/quix/lib/quix/builtin/module/include.rb

@@ -0,0 +1,21 @@
+
+if $DEBUG and !(defined?($NO_DEBUG_INCLUDE) and $NO_DEBUG_INCLUDE)
+  class Module
+    orig_include = instance_method(:include)
+    remove_method(:include)
+    define_method(:include) { |*mods|
+      mods.each { |mod|
+        if mod.class == Module
+          mod.instance_methods(true).each { |name|
+            if self.instance_methods(true).include?(name)
+              STDERR.puts("Note: replacing #{self.inspect}##{name} " +
+                "with #{mod.inspect}##{name}")
+            end
+          }
+        end
+        orig_include.bind(self).call(*mods)
+      }
+    }
+  end
+end
+

data/contrib/quix/lib/quix/builtin/module/private.rb

@@ -0,0 +1,41 @@
+
+class Module
+  alias_method :private__original, :private
+  def private(*args, &block)
+    private__original(*args)
+    if block
+      singleton_class = (class << self ; self ; end)
+      caller_self = block.binding.eval("self")
+      method_added__original =
+        if (t = method(:method_added)) and t.owner == singleton_class
+          t
+        else
+          nil
+        end
+      begin
+        singleton_class.instance_eval {
+          define_method(:method_added) { |name|
+            caller_self.instance_eval {
+              private__original(name.to_sym)
+            }
+            if t = method_added__original
+              t.call(name)
+            end
+          }
+        }
+        block.call
+      ensure
+        if t = method_added__original
+          t.owner.instance_eval {
+            define_method(:method_added, t)
+          }
+        else
+          singleton_class.instance_eval {
+            remove_method(:method_added)
+          }
+        end
+      end
+    end
+  end
+end
+

data/contrib/quix/lib/quix/config.rb

@@ -0,0 +1,37 @@
+
+require 'rbconfig'
+
+module Quix
+  module Config
+    CONFIG = ::Config::CONFIG
+
+    def ruby_executable
+      File.join(CONFIG["bindir"], CONFIG["RUBY_INSTALL_NAME"])
+    end
+    
+    def version_gt(version) ; version_compare( :>, version) ; end
+    def version_lt(version) ; version_compare( :<, version) ; end
+    def version_eq(version) ; version_compare(:==, version) ; end
+    def version_ge(version) ; version_compare(:>=, version) ; end
+    def version_le(version) ; version_compare(:<=, version) ; end
+    def version_ne(version) ; version_compare(:"!=", version) ; end
+    
+    def version_compare(op, version)
+      major, minor, teeny =
+        version.split(".").map { |n| n.to_i }
+      
+      this_major, this_minor, this_teeny = 
+        %w(MAJOR MINOR TEENY).map { |v| CONFIG[v].to_i }
+      
+      if this_major == major and this_minor == minor
+        this_teeny.send(op, teeny)
+      elsif this_major == major
+        this_minor.send(op, minor)
+      else
+        this_major.send(op, major)
+      end
+    end
+    
+    extend self
+  end
+end

data/contrib/quix/lib/quix/cygwin.rb

@@ -0,0 +1,60 @@
+
+unless RUBY_PLATFORM =~ %r!cygwin!
+  raise NotImplementedError, "cygwin-only module"
+end
+
+require 'fileutils'
+require 'thread'
+
+module Quix
+  module Cygwin
+    def run_batchfile(file, *args)
+      dos_pwd_env {
+        sh("cmd", "/c", dos_path(file), *args)
+      }
+    end
+    
+    def normalize_path(path)
+      path.sub(%r!/+\Z!, "")
+    end
+    
+    def unix2dos(string)
+      string.
+        gsub("\n", "\r\n").
+        gsub(%r!\r+!, "\r")
+    end
+    
+    def dos_path(unix_path)
+      `cygpath -w #{normalize_path(unix_path)}`.chomp
+    end
+  
+    def unix_path(dos_path)
+      escaped_path = dos_path.sub(%r!\\+\Z!, "").gsub("\\", "\\\\\\\\")
+      `cygpath #{escaped_path}`.chomp
+    end
+    
+    def dos_pwd_env
+      Thread.exclusive {
+        orig = ENV["PWD"]
+        ENV["PWD"] = dos_path(Dir.pwd)
+        begin
+          yield
+        ensure
+          ENV["PWD"] = orig
+        end
+      }
+    end
+    
+    def avoid_dll(file)
+      temp_file = file + ".avoiding-link"
+      FileUtils.mv(file, temp_file)
+      begin
+        yield
+      ensure
+        FileUtils.mv(temp_file, file)
+      end
+    end
+
+    extend self
+  end
+end

data/contrib/quix/lib/quix/diagnostic.rb

@@ -0,0 +1,44 @@
+
+require 'quix/builtin/kernel/tap'
+
+module Quix
+  module Diagnostic
+    def show(desc = nil, stream = STDOUT, &block)
+      if desc
+        stream.puts(desc)
+      end
+      if block
+        expression = block.call
+        eval(expression, block.binding).tap { |result|
+          stream.printf("%-16s => %s\n", expression, result.inspect)
+        }
+      end
+    end
+
+    if $DEBUG
+      def debug
+        yield
+      end
+
+      def debugging?
+        true
+      end
+
+      def trace(desc = nil, &block)
+        if desc
+          show("#{desc}.".sub(%r!\.\.+\Z!, ""), STDERR, &block)
+        else
+          show(nil, STDERR, &block)
+        end
+      end
+    else
+      # non-$DEBUG
+      def debug ; end
+      def debugging? ; end
+      def trace(*args) ; end
+    end
+
+    extend self
+  end
+end
+

data/contrib/quix/lib/quix/enumerable.rb

@@ -0,0 +1,33 @@
+
+require 'quix/builtin/kernel/tap'
+
+module Quix
+  module Enumerable
+    def inject_with_index(*args)
+      index = 0
+      inject(*args) { |acc, elem|
+        yield(acc, elem, index).tap {
+            index += 1
+        }
+      }
+    end
+
+    def map_with_index
+      Array.new.tap { |result|
+        each_with_index { |elem, index|
+          result << yield(elem, index)
+        }
+      }
+    end
+
+    def select_with_index
+      Array.new.tap { |result|
+        each_with_index { |elem, index|
+          if yield(elem, index)
+            result << elem
+          end
+        }
+      }
+    end
+  end
+end

data/contrib/quix/lib/quix/fileutils.rb

@@ -0,0 +1,37 @@
+
+require 'tmpdir'
+require 'quix/builtin/kernel/tap'
+
+module Quix
+  module FileUtils
+    def rename_file(file, new_name)
+      #
+      # For case-insensitive systems, we must move the file elsewhere
+      # before changing case.
+      #
+      temp = File.join(Dir.tmpdir, File.basename(file))
+      ::FileUtils.mv(file, temp)
+      begin
+        ::FileUtils.mv(temp, new_name)
+      rescue
+        ::FileUtils.mv(temp, file)
+        raise
+      end
+    end
+    
+    def replace_file(file)
+      old_contents = File.read(file)
+      yield(old_contents).tap { |new_contents|
+        File.open(file, "w") { |output|
+          output.print(new_contents)
+        }
+      }
+    end
+    
+    def stem(file)
+      file.sub(%r!#{File.extname(file)}\Z!, "")
+    end
+
+    extend self
+  end
+end

data/contrib/quix/lib/quix/hash_struct.rb

@@ -0,0 +1,27 @@
+
+require 'quix/builtin/kernel/tap'
+require 'ostruct'
+
+module Quix
+  class HashStruct < OpenStruct
+    def method_missing(sym, *args, &block)
+      if table.respond_to? sym
+        table.send(sym, *args, &block)
+      else
+        super
+      end
+    end
+    
+    class << self
+      def recursive_new(hash)
+        new.tap { |s|
+          hash.each_pair { |key, value|
+            s.send(
+              :"#{key}=", 
+              value.is_a?(Hash) ? recursive_new(value) : value)
+          }
+        }
+      end
+    end
+  end
+end