tork 18.2.4 → 19.0.0

data/lib/tork/master.rb

@@ -4,37 +4,44 @@ require 'tork/config'
 module Tork
 class Master < Server
 
+  # detect the number of CPUs available in the system
+  # http://stackoverflow.com/questions/891537#6420817
+  MAX_CONCURRENT_WORKERS = [
+    'fgrep -c processor /proc/cpuinfo', # Linux
+    'sysctl -n hw.ncpu',                # BSD
+    'hwprefs cpu_count',                # Darwin 9
+    'hwprefs thread_count',             # Darwin 10
+  ].
+  map {|cmd| `#{cmd} 2>/dev/null`.to_i }.push(1).max
+
   def initialize
     super
+    Tork.config :master
+    send @clients, [:absorb]
 
-    @worker_number_pool = (0 ... Config.max_forked_workers).to_a
+    @worker_number_pool = (0 ... MAX_CONCURRENT_WORKERS).to_a
     @command_by_worker_pid = {}
   end
 
-  def load paths, files
-    $LOAD_PATH.unshift(*paths)
-
-    @overhead_files = files.each do |file|
-      branch, leaf = File.split(file)
-      file = leaf if paths.include? branch
-      require file.sub(/\.rb$/, '')
-    end
-
-    @client.send @command
+  def loop
+    super
+  ensure
+    stop :SIGKILL
   end
 
   def test test_file, line_numbers
-    return if @overhead_files.include? test_file
-
     # throttle forking rate to meet the maximum concurrent workers limit
-    sleep 1 until @command_by_worker_pid.size < Config.max_forked_workers
+    sleep 1 until @command_by_worker_pid.size < @worker_number_pool.size
 
     log_file = test_file + '.log'
     worker_number = @worker_number_pool.shift
+    @command.push log_file, worker_number
 
-    Config.before_fork_hooks.each do |hook|
-      hook.call test_file, line_numbers, log_file, worker_number
-    end
+    $tork_test_file = test_file
+    $tork_line_numbers = line_numbers
+    $tork_log_file = log_file
+    $tork_worker_number = worker_number
+    Tork.config :onfork
 
     worker_pid = fork do
       # make the process title Test::Unit friendly and ps(1) searchable
@@ -50,9 +57,7 @@ class Master < Server
       # which makes it difficult to understand interleaved output thereof
       STDERR.reopen(STDOUT.reopen(log_file, 'w')).sync = true
 
-      Config.after_fork_hooks.each do |hook|
-        hook.call test_file, line_numbers, log_file, worker_number
-      end
+      Tork.config :worker
 
       # after loading the user's test file, the at_exit() hook of the user's
       # testing framework will take care of running the tests and reflecting
@@ -61,30 +66,25 @@ class Master < Server
       Kernel.load test_file if test_file.end_with? '.rb'
     end
 
-    @command_by_worker_pid[worker_pid] = @command.push(log_file, worker_number)
-    @client.send @command
+    @command_by_worker_pid[worker_pid] = @command
+    send @clients, @command
 
     # wait for the worker to finish and report its status to the client
-    Thread.new do # the reaping thread
-      worker_status = Process.wait2(worker_pid).last
-      command = @command_by_worker_pid.delete(worker_pid)
+    Thread.new(worker_pid) do |pid| # the reaping thread
+      status = Process.wait2(pid).last
+      command = @command_by_worker_pid.delete(pid)
       @worker_number_pool.push command.last
-      command[0] = if worker_status.success? then :pass else :fail end
-      @client.send command.push(worker_status.to_i, worker_status.inspect)
+      command[0] = status.success? && :pass || :fail
+      send @clients, command.push(status.to_i, status.inspect)
     end
   end
 
-  def stop
+  def stop signal=:SIGTERM
     # the reaping threads registered above will reap these killed workers
-    Process.kill :SIGTERM, *@command_by_worker_pid.keys.map {|pid| -pid }
+    Process.kill signal, *@command_by_worker_pid.keys.map {|pid| -pid }
   rescue ArgumentError, SystemCallError
     # some workers might have already exited before we sent them the signal
   end
 
-  def quit
-    stop
-    super
-  end
-
 end
 end

data/lib/tork/server.rb

@@ -1,31 +1,132 @@
-require 'tork/client'
+require 'socket'
+require 'thread'
+require 'json'
+require 'shellwords'
 
 module Tork
 class Server
 
-  def initialize
-    trap(:SIGTERM){ quit }
+  def self.address program=$0
+    ".#{program}.sock"
   end
 
-  def quit
-    Thread.exit # kill Client::Receiver in loop()
+  def initialize
+    # only JSON messages are supposed to be emitted on STDOUT
+    # so make puts() in the user code write to STDERR instead
+    @stdout = STDOUT.dup
+    STDOUT.reopen STDERR
+
+    @clients = [STDIN]
+    @servers = []
   end
 
   def loop
-    @client = Client::Transmitter.new(STDOUT.dup)
-    STDOUT.reopen(STDERR).sync = true
-
-    Client::Receiver.new(STDIN) do |command|
-      if command.first != __method__ # prevent loops
-        @command = command
-        begin
-          __send__(*command)
-        rescue => error
-          warn "#{$0}: #{error}"
-          warn error.backtrace.join("\n")
+    server = UNIXServer.open(Server.address)
+    @servers << server
+    catch :quit do
+      while @clients.include? STDIN
+        IO.select(@servers + @clients).first.each do |stream|
+          @client = stream
+
+          if stream == server
+            @clients << stream.accept
+
+          elsif (stream.eof? rescue true)
+            @clients.delete stream
+
+          elsif @command = hear(stream, stream.gets)
+            recv stream, @command
+          end
         end
       end
-    end.join
+    end
+  ensure
+    # UNIX domain socket files are not deleted automatically upon closing
+    File.delete server.path if server
+  end
+
+  def quit
+    throw :quit
+  end
+
+protected
+
+  JSON_REGEXP = /\A\s*[\[\{]/.freeze
+
+  # On failure to decode the message, warns the sender and returns nil.
+  def hear sender, message
+    if message =~ JSON_REGEXP
+      JSON.load message
+
+    # accept non-JSON "command lines" from clients
+    elsif @clients.include? sender
+      Shellwords.split message
+
+    # forward tell() output from children to clients
+    elsif @servers.include? sender
+      tell @clients, message, false
+      nil
+    end
+  rescue JSON::ParserError => error
+    tell sender, error
+    nil
+  end
+
+  def recv client, command
+    __send__(*command)
+  rescue => error
+    tell client, error
+    nil
+  end
+
+  def send one_or_more_clients, message
+    tell one_or_more_clients, JSON.dump(message), false
+  end
+
+  def tell one_or_more_clients, message, prefix=true
+    if message.kind_of? Exception
+      message = [message.inspect, message.backtrace]
+    end
+
+    if prefix
+      message = Array(message).join("\n").gsub(/^/, "#{$0}: ")
+    end
+
+    targets =
+      if one_or_more_clients.kind_of? IO
+        [one_or_more_clients]
+      else
+        Array(one_or_more_clients)
+      end
+
+    targets.each do |target|
+      target = @stdout if target == STDIN
+      target.puts message
+      target.flush
+    end
+  end
+
+  def popen command
+    child = IO.popen(command, 'r+')
+    @servers << child
+    child
+  end
+
+  def pclose child
+    return unless @servers.delete child
+
+    # this should be enough to stop programs that use Tork::Server#loop
+    # because their IO.select() loop terminates on the closing of STDIN
+    child.close_write
+
+    # but some programs like tork-herald(1) need to be killed explicitly
+    # because they do not follow this convention of exiting on STDIN close
+    Process.kill :SIGTERM, child.pid
+    Process.waitpid child.pid
+
+    # this will block until the child process has exited so we must kill it
+    # explicitly (as above) to ensure that this program does not hang here
+    child.close_read
   end
 
 end

data/lib/tork/version.rb

@@ -1,3 +1,3 @@
 module Tork
-  VERSION = "18.2.4"
+  VERSION = "19.0.0"
 end

data/man/man1/tork-driver.1

@@ -1,4 +1,4 @@
-.TH TORK\-DRIVER 1 2012\-10\-10 18.2.4
+.TH TORK\-DRIVER 1 2012\-10\-17 19.0.0
 .SH NAME
 .PP
 tork\-driver \- drives 
@@ -11,61 +11,189 @@ when files change
 .PP
 This program drives 
 .BR tork-engine (1) 
-according to 
-.BR tork-herald (1)'s 
-observations.
-It reads the following single\-line commands (JSON arrays) from its standard
-input stream and performs the respective actions as described below.  It also
-funnels the standard output stream of 
-.BR tork-engine (1) 
-into its own.
+when 
+.BR tork-herald (1) 
+reports files changes.
+.PP
+This program can be controlled remotely by multiple 
+.BR tork-remote (1) 
+instances.
+.SS Input
+.PP
+This program reads the following commands, which are single\-line JSON arrays,
+from stdin and performs the actions described respectively.
 .TP
 \fB\fC["run_all_test_files"]\fR
 Runs all test files found within and beneath the current working directory.
 .TP
-\fB\fC["reabsorb_overhead_files"]\fR
-Stops any test files that are currently running, reabsorbs the test
-execution overhead, and resumes running those interrupted test files.
-.TP
 \fI...\fP
-This program accepts 
+Commands for 
 .BR tork-engine (1) 
-commands and delegates them accordingly.
+are also accepted here.
+.SS Output
 .PP
-When 
-.BR tork-herald (1) 
-reports that a file belonging to the test execution
-overhead has been modified, this program replaces 
-.BR tork-master (1) 
-with a new
-instance, which then absorbs the modified test execution overhead into itself.
-.PP
-This program emits the following single\-line status messages (JSON arrays) on
-its standard output stream to provide notifications about its activity:
+This program prints the following messages, which are single\-line JSON arrays,
+to stdout.
+.TP
+\fB\fC["reabsorb",\fR \fIoverhead_file\fP\fB\fC]\fR
+Test execution overhead is being reabsorbed because \fIoverhead_file\fP has
+changed.
 .TP
-\fB\fC["over",\fR \fIoverhead_file\fP\fB\fC]\fR
-The test execution overhead is currently being reabsorbed, by replacing
+\fI...\fP
+Messages from 
+.BR tork-engine (1) 
+and 
 .BR tork-master (1) 
-with a new instance, because \fIoverhead_file\fP has changed.
+are also reproduced here.
 .SH OPTIONS
 .TP
 \fB\fC-h\fR, \fB\fC--help\fR
 Show this help manual.
 .SH FILES
 .TP
-\fI.tork.rb\fP
-Optional Ruby script for configuring 
-.BR tork (1).
-.SH ENVIRONMENT
+\fI.tork/config.rb\fP
+Optional Ruby script that is loaded inside the driver process on startup.
+It can read and change the \fB\fCENV['TORK_CONFIGS']\fR environment variable.
+.TP
+\fB\fC.tork/driver.rb\fR
+Optional Ruby script that is loaded inside the driver process on startup.
+It can read and change the following variables.
+.PP
+.RS
+.TP
+\fB\fCTork::Driver::REABSORB_FILE_GREPS\fR
+Array of strings or regular expressions that match the paths of overhead
+files.  If any of these equal or match the path of a changed file
+reported by 
+.BR tork-herald (1), 
+then the test execution overhead will be
+reabsorbed in 
+.BR tork-master (1).
+.TP
+\fB\fCTork::Driver::ALL_TEST_FILE_GLOBS\fR
+Array of file globbing patterns that describe the set of all test files
+in your Ruby application.
 .TP
-\fB\fCTORK_CONFIGS\fR
-A single\-line JSON array containing paths to actual files or names of
-helper libraries in the tork/config/ namespace of Ruby's load path.
-These configuration files are loaded just before \fI.tork.rb\fP is loaded.
+\fB\fCTork::Driver::TEST_FILE_GLOBBERS\fR
+Hash that maps (1) a regular expression describing a set of file paths
+to (2) a lambda function that accepts a \fB\fCMatchData\fR object containing
+the results of the regular expression matching against the path of a
+changed file, and yields one or more file globbing patterns (a single
+string, or an array of strings) that describe a set of test files that
+need to be run.
+.IP
+The results of these functions are recursively expanded (fed back into
+them) to construct an entire dependency tree of test files that need to
+be run.  For instance, if one function returns a glob that yields files
+matched by another function, then that second function will be called to
+glob more test files.  This process repeats until all dependent test
+files have been accounted for.
+.PP
+.RS
+\s+2\fBSingle glob expansion\fP\s-2
+.PP
+For example, if test files had the same names as their source files
+followed by an underscore and the file name in reverse like this:
+.RS
+.IP \(bu 2
+lib/hello.rb => test/hello_olleh.rb
+.IP \(bu 2
+app/world.rb => spec/world_ldrow.rb
+.RE
+.PP
+Then you would add the following to your configuration file:
+.PP
+.RS
+.nf
+Tork::Driver::TEST_FILE_GLOBBERS.update(
+  %r{^(lib|app)/.*?([^/]+?)\\.rb$} => lambda do |matches|
+    name = matches[2]
+    "{test,spec}/**/#{name}_#{name.reverse}.rb"
+  end
+)
+.fi
+.RE
+.PP
+\s+2\fBMulti\-glob expansion\fP\s-2
+.PP
+For example, if test files could optionally have "test" or "spec"
+prefixed or appended to their already peculiar names, like so:
+.RS
+.IP \(bu 2
+lib/hello.rb => test/hello_olleh_test.rb
+.IP \(bu 2
+lib/hello.rb => test/test_hello_olleh.rb
+.IP \(bu 2
+app/world.rb => spec/world_ldrow_spec.rb
+.IP \(bu 2
+app/world.rb => spec/spec_world_ldrow.rb
+.RE
+.PP
+Then you would add the following to your configuration file:
+.PP
+.RS
+.nf
+Tork::Driver::TEST_FILE_GLOBBERS.update(
+  %r{^(lib|app)/.*?([^/]+?)\\.rb$} => lambda do |matches|
+    name = matches[2]
+    ["{test,spec}/**/#{name}_#{name.reverse}.rb",
+     "{test,spec}/**/#{name}_#{name.reverse}_{test,spec}.rb",
+     "{test,spec}/**/{test,spec}_#{name}_#{name.reverse}.rb"]
+  end
+)
+.fi
+.RE
+.PP
+\s+2\fBRecursive expansion\fP\s-2
+.PP
+For example, if you wanted to run test files associated with
+\fB\fClib/hello.rb\fR whenever the \fB\fCapp/world.rb\fR file changed, then you would
+write:
+.PP
+.RS
+.nf
+Tork::Driver::TEST_FILE_GLOBBERS.update(
+  %r{^app/world\\.rb$} => lambda do |matches|
+    'lib/hello.rb'
+  end
+)
+.fi
+.RE
+.PP
+This effectively aliases one file onto another, but not in both
+directions.
+.PP
+\s+2\fBSuppressing expansion\fP\s-2
+.PP
+These lambda functions can return \fB\fCnil\fR if they do not wish for a
+particular source file to be tested.  For example, to ignore tests for
+all source files except those within a \fB\fCmodels/\fR directory, you would
+write:
+.PP
+.RS
+.nf
+Tork::Driver::TEST_FILE_GLOBBERS.update(
+  %r{^(lib|app)(/.*?)([^/]+?)\\.rb$} => lambda do |matches|
+    if matches[2].include? '/models/'
+      ["{test,spec}/**/#{matches[3]}_{test,spec}.rb",
+       "{test,spec}/**/{test,spec}_#{matches[3]}.rb"]
+    #else     # implied by the Ruby language
+      #nil    # implied by the Ruby language
+    end
+  end
+)
+.fi
+.RE
+.RE
+.RE
+.SH ENVIRONMENT
+.PP
+See 
+.BR tork (1).
 .SH SEE ALSO
 .PP
 .BR tork (1), 
+.BR tork-remote (1), 
 .BR tork-herald (1), 
-.BR tork-driver (1), 
 .BR tork-engine (1), 
 .BR tork-master (1)