comp_tree 0.7.0 → 0.7.1

data/CHANGES

@@ -1,6 +1,11 @@
 
 = CompTree ChangeLog
 
+== Version 0.7.1
+
+* rename README to README.rdoc for github display
+* internal cleanup 
+
 == Version 0.7.0
 
 * remove fork and discard_result options

data/{README → README.rdoc}

@@ -54,7 +54,7 @@ function you define must explicitly depend on the data it uses.
   }
 
 Unless <em>offset</em> is really a constant, the result of
-<tt>driver.compute(:area, :num_threads => n)</tt> is not well-defined
+<tt>driver.compute(:area, :threads => n)</tt> is not well-defined
 for _n_ > 1.
 
 Just as depending on some changeable state is bad, it is likewise bad
@@ -64,12 +64,12 @@ to affect a state (to produce a <em>side effect</em>).
   # BAD example: affecting state
   #
   driver.define(:area, :width, :height) { |width, height|
-    ACCUMULATOR.add "more data"
+    accumulator.add "more data"
     width*height
   }
 
-Given a tree where nodes are modifying _ACCUMULATOR_, the end state of
-_ACCUMULATOR_ is not well-defined.  Moreover if _ACCUMULATOR_ is not
+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
@@ -80,7 +80,7 @@ depends on that state</em>.  This is the principle under which
 
   % gem install comp_tree
 
-Or for the regular (non-gem) .tgz package,
+Or for the (non-gem) .tgz package,
 
   % ruby install.rb [--uninstall]
 

data/comp_tree.gemspec

@@ -6,11 +6,11 @@ Gem::Specification.new { |g|
   g.name = "comp_tree"
   g.rubyforge_project = "comptree"
   g.homepage = "comptree.rubyforge.org"
-  g.version = "0.7.0"
+  g.version = "0.7.1"
   g.description =
     "Build a computation tree and execute it with N parallel threads."
 
-  readme = "README"
+  readme = "README.rdoc"
 
   g.files = %W[
     CHANGES
@@ -19,14 +19,15 @@ Gem::Specification.new { |g|
     #{g.name}.gemspec
     install.rb
   ] + %w[lib rakelib test].inject(Array.new) { |acc, dir|
-    acc + Dir[dir + "/**/*.rb"]
+    acc + Dir[dir + "/**/*.{rake,rb}"]
   }
   g.has_rdoc = true
   rdoc_files = [
     readme,
     "lib/comp_tree.rb",
     "lib/comp_tree/driver.rb",
-    "lib/comp_tree/error.rb"
+    "lib/comp_tree/error.rb",
+    "lib/comp_tree/node.rb",
   ]
   g.extra_rdoc_files += [readme]
 

data/lib/comp_tree.rb

@@ -25,19 +25,21 @@ require 'comp_tree/driver'
 #
 # CompTree -- Parallel Computation Tree.
 #
-# See README.
+# See README.rdoc.
 #
 module CompTree
   class << self
     #
-    # Build and run a new computation tree.
+    # :call-seq:
+    #   build { |driver| ... }
     #
-    # A Driver instance is passed to the given block.
+    # Build a new computation tree. A Driver instance is passed to the
+    # given block.
     #
     # Options hash:
     #
-    # <tt>:node_class</tt> -- (Class) CompTree::Node subclass from
-    # which nodes are created.
+    # <tt>:node_class</tt> -- CompTree::Node subclass from which nodes
+    # are created.
     #
     # Example:
     #   CompTree.build do |driver|

data/lib/comp_tree/algorithm.rb

@@ -1,6 +1,9 @@
 
 module CompTree
   module Algorithm
+    LEAVE = :__comp_tree_leave
+    AGAIN = :__comp_tree_again
+
     module_function
 
     def loop_with(leave, again)
@@ -13,13 +16,12 @@ module CompTree
       }
     end
 
-    def compute_multithreaded(root, num_threads)
+    def compute_parallel(root, num_threads)
       #trace "Computing #{root.name} with #{num_threads} threads"
       finished = nil
       tree_mutex = Mutex.new
-      node_finished_condition = ConditionVariable.new
-      thread_wake_condition = ConditionVariable.new
-      num_threads_in_use = 0
+      condition = ConditionVariable.new
+      num_threads_ready = 0
 
       threads = (0...num_threads).map { |thread_index|
         Thread.new {
@@ -28,17 +30,17 @@ module CompTree
           #
           tree_mutex.synchronize {
             #trace "Thread #{thread_index} waiting to start"
-            num_threads_in_use += 1
-            thread_wake_condition.wait(tree_mutex)
+            num_threads_ready += 1
+            condition.wait(tree_mutex)
           }
 
-          loop_with(:leave, :again) {
+          loop_with(LEAVE, AGAIN) {
             node = tree_mutex.synchronize {
               #trace "Thread #{thread_index} acquired tree lock; begin search"
               if finished
                 #trace "Thread #{thread_index} detected finish"
-                num_threads_in_use -= 1
-                throw :leave
+                num_threads_ready -= 1
+                throw LEAVE
               else
                 #
                 # Find a node.  The node we obtain, if any, will be locked.
@@ -49,8 +51,8 @@ module CompTree
                   node
                 else
                   #trace "Thread #{thread_index}: no node found; sleeping."
-                  thread_wake_condition.wait(tree_mutex)
-                  throw :again
+                  condition.wait(tree_mutex)
+                  throw AGAIN
                 end
               end
             }
@@ -92,7 +94,7 @@ module CompTree
               #
               # Tell the main thread that another node was computed.
               #
-              node_finished_condition.signal
+              condition.signal
             }
           }
           #trace "Thread #{thread_index} exiting"
@@ -100,15 +102,15 @@ module CompTree
       }
 
       #trace "Main: waiting for threads to launch and block."
-      until tree_mutex.synchronize { num_threads_in_use == num_threads }
+      until tree_mutex.synchronize { num_threads_ready == num_threads }
         Thread.pass
       end
 
       tree_mutex.synchronize {
         #trace "Main: entering main loop"
-        until num_threads_in_use == 0
+        until num_threads_ready == 0
           #trace "Main: waking threads"
-          thread_wake_condition.broadcast
+          condition.broadcast
 
           if finished
             #trace "Main: detected finish."
@@ -116,21 +118,13 @@ module CompTree
           end
 
           #trace "Main: waiting for a node"
-          node_finished_condition.wait(tree_mutex)
+          condition.wait(tree_mutex)
           #trace "Main: got a node"
         end
       }
 
       #trace "Main: waiting for threads to finish."
-      loop_with(:leave, :again) {
-        tree_mutex.synchronize {
-          if threads.all? { |thread| thread.status == false }
-            throw :leave
-          end
-          thread_wake_condition.broadcast
-        }
-        Thread.pass
-      }
+      threads.each { |t| t.join }
 
       #trace "Main: computation done."
       if finished.is_a? Exception

data/lib/comp_tree/driver.rb

@@ -14,21 +14,15 @@ module CompTree
     include Algorithm
 
     #
-    # Build and run a new computation tree.
+    # See CompTree.build.
     #
-    # Options hash:
-    #
-    # <tt>:node_class</tt> -- (Class) CompTree::Node subclass from
-    # which nodes are created.
-    #
-    def initialize(opts = nil)
-      @node_class = (
+    def initialize(opts = nil)  #:nodoc:
+      @node_class =
         if opts and opts[:node_class]
           opts[:node_class]
         else
           Node
         end
-      )
       @nodes = Hash.new
     end
 
@@ -38,13 +32,15 @@ module CompTree
     attr_reader :nodes
 
     #
-    # Define a computation node.
+    # _name_ -- unique node identifier (for example a symbol).
     #
-    # The first argument is the name of the node to define.
-    # Subsequent arguments are the names of this node's children.
+    # _child_names_ -- unique node identifiers for children.
+    #
+    # Define a computation node.
     #
-    # The values of the child nodes are passed to the block.  The
-    # block returns the result of this node.
+    # During a computation, the results of the child nodes are passed
+    # to the block.  The block returns the result of this node's
+    # computation.
     #
     # In this example, a computation node named +area+ is defined
     # which depends on the nodes +width+ and +height+.
@@ -53,27 +49,18 @@ module CompTree
     #     width*height
     #   }
     #
-    def define(*args, &block)
-      parent_name = args.first
-      children_names = args[1..-1]
-      
-      unless parent_name
-        raise ArgumentError, "No name given for node"
-      end
-      
+    def define(name, *child_names, &block)
       #
       # retrieve or create parent and children
       #
-      parent = @nodes[parent_name] || (
-        @nodes[parent_name] = @node_class.new(parent_name)
-      )
 
+      parent = @nodes[name] || (@nodes[name] = @node_class.new(name))
       if parent.function
         raise RedefinitionError, "Node `#{parent.name.inspect}' redefined."
       end
       parent.function = block
       
-      children = children_names.map { |child_name|
+      children = child_names.map { |child_name|
         @nodes[child_name] || (
           @nodes[child_name] = @node_class.new(child_name)
         )
@@ -89,25 +76,21 @@ module CompTree
     end
 
     #
-    # Mark this node and all its children as uncomputed.
+    # _name_ -- unique node identifier (for example a symbol).
     #
-    # Arguments:
-    #
-    # +name+ -- unique node identifier (usually a symbol).
+    # Mark this node and all its children as uncomputed.
     #
     def reset(name)
       @nodes[name].reset
     end
 
+    #
+    # _name_ -- unique node identifier (for example a symbol).
     #
     # Check for a cyclic graph below the given node.  If found,
     # returns the names of the nodes (in order) which form a loop.
     # Otherwise returns nil.
     #
-    # Arguments:
-    #
-    # +name+ -- unique node identifier (usually a symbol).
-    #
     def check_circular(name)
       helper = Proc.new { |root, chain|
         if chain.include? root
@@ -122,30 +105,27 @@ module CompTree
     end
 
     #
-    # Compute this node.
+    # :call-seq:
+    #   compute(name, threads)
+    #   compute(name, :threads => threads)
     #
-    # Arguments:
+    # _name_ -- unique node identifier (for example a symbol).
     #
-    # +name+ -- unique node identifier (usually a symbol).
+    # _threads_ -- number of threads.
     #
-    # +threads+ -- (Integer) number of threads.
+    # Compute this node, returning its result.
     #
-    # compute(:volume, :threads => 4) syntax is also accepted.
+    # Any uncomputed children are computed first.
     #
     def compute(name, opts)
       threads = opts.is_a?(Hash) ? opts[:threads] : opts
       root = @nodes[name]
-
-      if threads < 1
-        raise ArgumentError, "threads is #{threads}"
-      end
-
       if root.computed
         root.result
       elsif threads == 1
         root.result = root.compute_now
       else
-        compute_multithreaded(root, threads)
+        compute_parallel(root, threads)
       end
     end
   end

data/lib/comp_tree/error.rb

@@ -3,20 +3,18 @@ module CompTree
   # Base class for CompTree errors.
   class Error < StandardError ; end
     
-  # Internal error inside CompTree.  Please send a bug report.
-  class AssertionFailedError < Error ; end
-  
-  # Bad arguments were passed to a method.
-  class ArgumentError < Error ; end
-  
   #
   # Attempt to redefine a Node.
   #
   # If you wish to only replace the function, set
-  #   driver.nodes[name].function = some_new_lambda
+  #   driver.nodes[name].function = lambda { ... }
   #
   class RedefinitionError < Error ; end
   
-  # No function was defined for this node.
+  # Encountered a node without a function during a computation.
   class NoFunctionError < Error ; end
+
+  #debug {
+  #  class AssertionFailedError < Error ; end
+  #}
 end

data/lib/comp_tree/node.rb

@@ -69,8 +69,8 @@ module CompTree
     end
 
     #
-    # Force computation of all children; intended for
-    # single-threaded mode.
+    # Force all children and self to be computed; no locking required.
+    # Intended to be used outside of parallel computations.
     #
     def compute_now #:nodoc:
       unless @children_results

data/rakelib/jumpstart.rake

@@ -0,0 +1,365 @@
+$LOAD_PATH.unshift File.dirname(__FILE__)
+
+require 'rake/gempackagetask'
+require 'rake/contrib/sshpublisher'
+require 'rake/clean'
+require 'rdoc/rdoc'
+
+require "jumpstart/simple_installer"
+require "jumpstart/ruby"
+
+######################################################################
+# constants
+
+unless defined?(RUBYFORGE_USER)
+  RUBYFORGE_USER = "quix"
+end
+
+GEMSPEC = eval(File.read(Dir["*.gemspec"].last))
+
+DOC_DIR = "documentation"
+SPEC_FILES = Dir['spec/*_spec.rb'] + Dir['examples/*_example.rb']
+TEST_FILES = Dir['test/test_*.rb']
+RCOV_DIR = "coverage"
+SPEC_OUTPUT = "spec.html"
+
+RCOV_OPTIONS = Dir["*"].select { |file|
+  File.directory?(file) and file != "lib"
+}.inject(Array.new) { |acc, file|
+  acc + ["--exclude", file + "/"]
+}
+
+######################################################################
+# spec
+
+unless SPEC_FILES.empty?
+  require 'spec/rake/spectask'
+
+  desc "run specs"
+  Spec::Rake::SpecTask.new('spec') do |t|
+    t.spec_files = SPEC_FILES
+  end
+  
+  desc "run specs with text output"
+  Spec::Rake::SpecTask.new('text_spec') do |t|
+    t.spec_files = SPEC_FILES
+    t.spec_opts = ['-fs']
+  end
+  
+  desc "run specs with html output"
+  Spec::Rake::SpecTask.new('full_spec') do |t|
+    t.spec_files = SPEC_FILES
+    t.rcov = true
+    t.rcov_opts = RCOV_OPTIONS
+    t.spec_opts = ["-fh:#{SPEC_OUTPUT}"]
+  end
+  
+  desc "run full_spec then open browser"
+  task :show_spec => :full_spec do
+    open_browser(SPEC_OUTPUT, RCOV_DIR + "/index.html")
+  end
+
+  desc "run specs individually"
+  task :spec_deps do
+    run_ruby_on_each(*SPEC_FILES)
+  end
+
+  task :prerelease => :spec_deps
+
+  task :default => :spec
+
+  CLEAN.include(SPEC_OUTPUT)
+end
+
+######################################################################
+# test
+
+unless TEST_FILES.empty?
+  desc "run tests"
+  task :test do
+    TEST_FILES.each { |file|
+      require file
+    }
+  end
+
+  desc "run tests with rcov"
+  task :full_test do
+    previous = RakeFileUtils.verbose_flag
+    begin
+      sh("rcov", "-o", RCOV_DIR, *(TEST_FILES + RCOV_OPTIONS))
+    ensure
+      RakeFileUtils.verbose_flag = previous
+    end
+  end
+
+  desc "run full_test then open browser"
+  task :show_test => :full_test do
+    open_browser(RCOV_DIR + "/index.html")
+  end
+
+  desc "run tests individually"
+  task :test_deps do
+    run_ruby_on_each(*TEST_FILES)
+  end
+
+  task :prerelease => :test_deps
+  task :default => :test
+
+  CLEAN.include RCOV_DIR
+end
+
+######################################################################
+# clean
+
+task :clean do
+  Rake::Task[:clobber].invoke
+end
+
+######################################################################
+# package
+
+task :package => :clean
+task :gem => :clean
+
+Rake::GemPackageTask.new(GEMSPEC) { |t|
+  t.need_tar = true
+}
+
+######################################################################
+# doc
+
+#
+# Try to mimic the gem documentation
+#
+desc "run rdoc"
+task :doc => :clean_doc do
+  args = (
+    GEMSPEC.rdoc_options +
+    GEMSPEC.require_paths.clone +
+    GEMSPEC.extra_rdoc_files +
+    ["-o", DOC_DIR]
+  ).flatten.map { |t| t.to_s }
+  RDoc::RDoc.new.document args
+end
+
+task :clean_doc do
+  # normally rm_rf, but mimic rake/clean
+  rm_r(DOC_DIR) rescue nil
+end
+
+desc "run rdoc then open browser"
+task :show_doc => :doc do
+  open_browser(DOC_DIR + "/index.html")
+end
+
+task :rdoc => :doc
+task :clean => :clean_doc
+
+######################################################################
+# publisher
+
+desc "upload docs"
+task :publish => [:clean_doc, :doc] do
+  Rake::SshDirPublisher.new(
+    "#{RUBYFORGE_USER}@rubyforge.org",
+    "/var/www/gforge-projects/#{GEMSPEC.rubyforge_project}",
+    DOC_DIR
+  ).upload
+end
+
+######################################################################
+# install/uninstall
+
+desc "direct install (no gem)"
+task :install do
+  Jumpstart::SimpleInstaller.new.run([])
+end
+
+desc "direct uninstall (no gem)"
+task :uninstall do
+  Jumpstart::SimpleInstaller.new.run(["--uninstall"])
+end
+
+######################################################################
+# debug
+
+def comment_src_dst(on)
+  on ? ["", "#"] : ["#", ""]
+end
+
+def comment_regions(on, contents, start)
+  src, dst = comment_src_dst(on)
+  contents.gsub(%r!^(\s+)#{src}#{start}.*?^\1#{src}(\}|end)!m) { |chunk|
+    indent = $1
+    chunk.gsub(%r!^#{indent}#{src}!, "#{indent}#{dst}")
+  }
+end
+
+def comment_lines(on, contents, start)
+  src, dst = comment_src_dst(on)
+  contents.gsub(%r!^(\s*)#{src}#{start}!) { 
+    $1 + dst + start
+  }
+end
+
+def debug_info(enable)
+  Find.find("lib", "test") { |path|
+    if path =~ %r!\.rb\Z!
+      replace_file(path) { |contents|
+        result1 = comment_regions(!enable, contents, "def trace_")
+        result2 = comment_regions(!enable, result1, "debug")
+        comment_lines(!enable, result2, "trace")
+      }
+    end
+  }
+end
+
+desc "enable debug and trace calls"
+task :debug_on do
+  debug_info(true)
+end
+
+desc "disable debug and trace calls"
+task :debug_off do
+  debug_info(false)
+end
+
+######################################################################
+# check columns
+
+desc "check for columns > 80"
+task :check_columns do
+  Dir["**/*.rb"].each { |file|
+    File.read(file).scan(%r!^.{81}!) { |match|
+      unless match =~ %r!http://!
+        raise "#{file} greater than 80 columns"
+      end
+    }
+  }
+end
+
+task :prerelease => :check_columns
+
+######################################################################
+# comments
+
+task :comments do
+  write_file("comments") {
+    Array.new.tap { |result|
+      (["Rakefile"] + Dir["**/*.{rb,rake}"]).each { |file|
+        File.read(file).scan(%r!\#[^\{].*$!) { |match|
+          result << match
+        }
+      }
+    }.join("\n")
+  }
+end
+
+######################################################################
+# release
+
+def git(*args)
+  sh("git", *args)
+end
+
+task :prerelease => :clean do
+  unless `git status` =~ %r!nothing to commit \(working directory clean\)!
+    raise "Directory not clean"
+  end
+  %w[github.com rubyforge.org].each { |server|
+    cmd = "ping " + (
+      if Config::CONFIG["host"] =~ %r!darwin!
+        "-c2 #{server}"
+      else
+        "#{server} 2 2"
+      end
+    )
+    unless `#{cmd}` =~ %r!0% packet loss!
+      raise "No ping for #{server}"
+    end
+  }
+end
+
+def rubyforge(command, file)
+  sh(
+    "rubyforge",
+    command,
+    GEMSPEC.rubyforge_project,
+    GEMSPEC.rubyforge_project,
+    GEMSPEC.version.to_s,
+    file
+  )
+end
+
+task :finish_release do
+  gem, tgz = %w(gem tgz).map { |ext|
+    "pkg/#{GEMSPEC.name}-#{GEMSPEC.version}.#{ext}"
+  }
+
+  gem_md5, tgz_md5 = [gem, tgz].map { |file|
+    "#{file}.md5".tap { |md5|
+      sh("md5sum #{file} > #{md5}")
+    }
+  }
+
+  rubyforge("add_release", gem)
+  [gem_md5, tgz, tgz_md5].each { |file|
+    rubyforge("add_file", file)
+  }
+
+  git("tag", "#{GEMSPEC.name}-" + GEMSPEC.version.to_s)
+  git(*%w(push --tags origin master))
+end
+
+task :release =>
+  [
+   :prerelease,
+   :package,
+   :publish,
+   :finish_release,
+  ]
+
+######################################################################
+# util
+
+def open_browser(*files)
+  if Config::CONFIG["host"] =~ %r!darwin!
+    sh("open", "/Applications/Firefox.app", *files)
+  else
+    sh("firefox", *files)
+  end
+end
+
+unless respond_to? :tap
+  class Object
+    def tap
+      yield self
+      self
+    end
+  end
+end 
+
+def replace_file(file)
+  old_contents = File.read(file)
+  yield(old_contents).tap { |new_contents|
+    if old_contents != new_contents
+      File.open(file, "wb") { |output|
+        output.print(new_contents)
+      }
+    end
+  }
+end
+
+def write_file(file)
+  yield.tap { |contents|
+    File.open(file, "wb") { |out|
+      out.print(contents)
+    }
+  }
+end
+
+def run_ruby_on_each(*files)
+  files.each { |file|
+    Jumpstart::Ruby.run_or_raise("-w", file)
+  }
+end

data/test/test_basic.rb

@@ -51,7 +51,7 @@ class TestBasic < Test::Unit::TestCase
 
   def test_malformed
     CompTree.build { |driver|
-      assert_raise(CompTree::ArgumentError) {
+      assert_raise(ArgumentError) {
         driver.define {
         }
       }
@@ -61,16 +61,6 @@ class TestBasic < Test::Unit::TestCase
         driver.define(:a) {
         }
       }
-      assert_raise(CompTree::ArgumentError) {
-        driver.define(:b) {
-        }
-        driver.compute(:b, 0)
-      }
-      assert_raise(CompTree::ArgumentError) {
-        driver.define(:c) {
-        }
-        driver.compute(:c, -1)
-      }
     }
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: comp_tree
 version: !ruby/object:Gem::Version 
-  version: 0.7.0
+  version: 0.7.1
 platform: ruby
 authors: 
 - James M. Lawrence
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-04-09 00:00:00 -04:00
+date: 2009-04-12 00:00:00 -04:00
 default_executable: 
 dependencies: []
 
@@ -20,10 +20,10 @@ executables: []
 extensions: []
 
 extra_rdoc_files: 
-- README
+- README.rdoc
 files: 
 - CHANGES
-- README
+- README.rdoc
 - Rakefile
 - comp_tree.gemspec
 - install.rb
@@ -32,6 +32,7 @@ files:
 - lib/comp_tree/error.rb
 - lib/comp_tree/node.rb
 - lib/comp_tree.rb
+- rakelib/jumpstart.rake
 - rakelib/jumpstart/ruby.rb
 - rakelib/jumpstart/simple_installer.rb
 - test/common.rb
@@ -47,7 +48,7 @@ homepage: comptree.rubyforge.org
 post_install_message: 
 rdoc_options: 
 - --main
-- README
+- README.rdoc
 - --title
 - "comp_tree: Parallel Computation Tree"
 - --exclude
@@ -61,7 +62,7 @@ rdoc_options:
 - --exclude
 - lib/comp_tree/algorithm.rb
 - --exclude
-- lib/comp_tree/node.rb
+- rakelib/jumpstart.rake
 - --exclude
 - rakelib/jumpstart/ruby.rb
 - --exclude