process-group 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 026f8b1f40e77c491180b9faff360d884a6717fa
-  data.tar.gz: c4ecc9c7c932b7c662f420f3c82ece3ea0a6d7b1
+  metadata.gz: bd660d2e26e8b418c6e8a05b6bcc30b9d85b7eed
+  data.tar.gz: fbb0e6d195952d1911d248feac57d6088744fdd2
 SHA512:
-  metadata.gz: e364e21669e91dec753aff10d6100584c0d80057a52a4db539fcc3fb57df1b2a58b1d69220f66d9c9e8ce137383b5b7f9b62d780e51b292d295e0f5e38c283c0
-  data.tar.gz: c723127bf2fc53e8d9752f016e858ea1417f053548d687f4732866bfc29275fc80b0680f5609aee396c99fc0c2c8ad996d6396afa3d6b9a55ca6d7cf96731d5d
+  metadata.gz: bea0fb36a908dc45663e69f7606e934260c91f6665f056f82c1f56a31b7cd76aef4b4a645e2610c06053f548abd66e2abd2e7c1b2cbf76837787ea21cd373907
+  data.tar.gz: 021ca23fe4e15239b7da0715a541e56cf0c5bb2f0ea86657f96bdaca24bc9238e83d6235dd2d2013713c54c4074b881697ea8e6cca70b64db73d79cb268afc92

data/README.md

@@ -37,6 +37,8 @@ The simplest concurrent usage is as follows:
 	# Wait for all processes in group to finish:
 	group.wait
 
+The `group.wait` call is an explicit synchronisation point, and if it completes successfully, all processes/fibers have finished successfully. If an error is raised in a fiber, it will be passed back out through `group.wait` and this is the only failure condition. Even if this occurs, all children processes are guaranteed to be cleaned up.
+
 ### Explicit Fibers
 
 Items within a single fiber will execute sequentially. Processes (e.g. via `Group#spawn`) will run concurrently in multiple fibers.
@@ -97,6 +99,52 @@ It is possible to send a signal (kill) to the entire process group:
 
 If there are no running processes, this is a no-op (rather than an error).
 
+#### Handling Interrupts
+
+`Process::Graph` transparently handles `Interrupt` when raised within a `Fiber`. If `Interrupt` is raised, all children processes will be sent `kill(:INT)` and we will wait for all children to complete, but without resuming the controlling fibers. If `Interrupt` is raised during this process, children will be sent `kill(:TERM)`. After calling `Interrupt`, the fibers will not be resumed.
+
+### Process Timeout
+
+You can run a process group with a time limit by using a separate child process:
+
+	group = Process::Group.new
+	
+	class Timeout < StandardError
+	end
+	
+	Fiber.new do
+		# Wait for 2 seconds, let other processes run:
+		group.fork { sleep 2 }
+		
+		# If no other processes are running, we are done:
+		Fiber.yield unless group.running?
+		
+		# Send SIGINT to currently running processes:
+		group.kill(:INT)
+		
+		# Wait for 2 seconds, let other processes run:
+		group.fork { sleep 2 }
+		
+		# If no other processes are running, we are done:
+		Fiber.yield unless group.running?
+		
+		# Send SIGTERM to currently running processes:
+		group.kill(:TERM)
+		
+		# Raise an Timeout exception which is based back out:
+		raise Timeout
+	end.resume
+	
+	# Run some other long task:
+	group.run("sleep 10")
+	
+	# Wait for fiber to complete:
+	begin
+		group.wait
+	rescue Timeout
+		puts "Process group was terminated forcefully."
+	end
+
 ## Contributing
 
 1. Fork it

data/lib/process/group.rb

@@ -96,6 +96,10 @@ module Process
 			-@pgid
 		end
 
+		def running?
+			@running.size > 0
+		end
+
 		# Run a process, arguments have same meaning as Process#spawn.
 		def run(*arguments)
 			Fiber.new do
@@ -132,26 +136,35 @@ module Process
 		
 		# Wait for all processes to finish, naturally would schedule any fibers which are currently blocked.
 		def wait
-			while @running.size > 0
-				# Wait for processes in this group:
-				pid, status = Process.wait2(-@pgid)
-			
-				process = @running.delete(pid)
-			
-				raise RuntimeError.new("Process id=#{pid} is not part of group!") unless process
-			
+			while running?
+				process, status = wait_one
+				
 				schedule!
-			
+				
 				process.resume(status)
 			end
 			
 			# No processes, process group is no longer valid:
 			@pgid = nil
+		rescue Interrupt
+			# If the user interrupts the wait, interrupt the process group and wait for them to finish:
+			self.kill(:INT)
+			
+			# If user presses Ctrl-C again (or something else goes wrong), we will come out and kill(:TERM) in the ensure below:
+			wait_all
+			
+			raise
+		ensure
+			# You'd only get here with running processes if some unexpected error was thrown:
+			self.kill(:TERM)
+			
+			# Clean up zombie processes - if user presses Ctrl-C or for some reason something else blows up, exception would propagate back to caller:
+			wait_all
 		end
 		
 		# Send a signal to all processes.
 		def kill(signal)
-			if @running.size > 0
+			if running?
 				Process.kill(signal, id)
 			end
 		end
@@ -183,5 +196,27 @@ module Process
 				@running[pid] = process
 			end
 		end
+		
+		# Wait for all children to exit but without resuming any controlling fibers.
+		def wait_all
+			wait_one while running?
+		end
+		
+		# Wait for one process, should only be called when a child process has finished, otherwise would block.
+		def wait_one(flags = 0)
+			raise RuntimeError.new("Process group has no running children!") unless running?
+			
+			# Wait for processes in this group:
+			pid, status = Process.wait2(-@pgid, flags)
+		
+			return if flags & Process::WNOHANG and pid == nil
+		
+			process = @running.delete(pid)
+		
+			# This should never happen unless something very odd has happened:
+			raise RuntimeError.new("Process id=#{pid} is not part of group!") unless process
+			
+			return process, status
+		end
 	end
 end

data/lib/process/group/version.rb

@@ -1,5 +1,5 @@
 module Process
 	class Group
-		VERSION = "0.1.0"
+		VERSION = "0.1.2"
 	end
 end

data/process-group.gemspec

@@ -22,4 +22,5 @@ Gem::Specification.new do |spec|
 
 	spec.add_development_dependency "bundler", "~> 1.3"
 	spec.add_development_dependency "rake"
+	spec.add_development_dependency "mocha"
 end

data/test/test_interrupt.rb

@@ -0,0 +1,151 @@
+# Copyright, 2012, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# 
+# 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.
+
+require 'test/unit'
+require 'mocha/test_unit'
+
+require 'process/group'
+
+class TestInterrupt < Test::Unit::TestCase
+	def test_raise_interrupt
+		group = Process::Group.new
+		checkpoint = ""
+		
+		Fiber.new do
+			checkpoint += 'X'
+			
+			result = group.fork { sleep 0.1 }
+			assert_equal 0, result
+			
+			checkpoint += 'Y'
+			
+			# Simulate the user pressing Ctrl-C after 0.5 seconds:
+			raise Interrupt
+		end.resume
+		
+		Fiber.new do
+			checkpoint += 'A'
+			
+			# This never returns:
+			result = group.fork { sleep 0.2 }
+			
+			checkpoint += 'B'
+		end.resume
+		
+		group.expects(:kill).with(:INT).once
+		group.expects(:kill).with(:TERM).once
+		
+		assert_raises Interrupt do
+			group.wait
+		end
+		
+		assert_equal 'XAY', checkpoint
+	end
+	
+	def test_raise_exception
+		group = Process::Group.new
+		checkpoint = ""
+		
+		Fiber.new do
+			checkpoint += 'X'
+			
+			result = group.fork { sleep 0.1 }
+			assert_equal 0, result
+			
+			checkpoint += 'Y'
+			
+			# Raises a RuntimeError
+			fail "Error"
+		end.resume
+		
+		Fiber.new do
+			checkpoint += 'A'
+			
+			# This never returns:
+			result = group.fork { sleep 0.2 }
+			
+			checkpoint += 'B'
+		end.resume
+		
+		assert_raises RuntimeError do
+			group.expects(:kill).with(:TERM).once
+			
+			group.wait
+		end
+		
+		assert_equal 'XAY', checkpoint
+	end
+	
+	class Timeout < StandardError
+	end
+	
+	def test_timeout
+		group = Process::Group.new
+		checkpoint = ""
+		
+		Fiber.new do
+			# Wait for 2 seconds, let other processes run:
+			group.fork { sleep 2 }
+			checkpoint += 'A'
+			#puts "Finished waiting #1..."
+		
+			# If no other processes are running, we are done:
+			Fiber.yield unless group.running?
+			checkpoint += 'B'
+			#puts "Sending SIGINT..."
+		
+			# Send SIGINT to currently running processes:
+			group.kill(:INT)
+		
+			# Wait for 2 seconds, let other processes run:
+			group.fork { sleep 2 }
+			checkpoint += 'C'
+			#puts "Finished waiting #2..."
+		
+			# If no other processes are running, we are done:
+			Fiber.yield unless group.running?
+			checkpoint += 'D'
+			#puts "Sending SIGTERM..."
+		
+			# Send SIGTERM to currently running processes:
+			group.kill(:TERM)
+		
+			# Raise an Timeout exception which is based back out:
+			raise Timeout
+		end.resume
+	
+		# Run some other long task:
+		group.run("sleep 10")
+		
+		start_time = Time.now
+		
+		# Wait for fiber to complete:
+		assert_nothing_raised Timeout do
+			group.wait
+			checkpoint += 'E'
+		end
+		
+		end_time = Time.now
+		
+		assert_equal 'ABCE', checkpoint
+		
+		assert (3.9..4.1).include?(end_time - start_time)
+	end
+end

data/test/test_spawn.rb

@@ -29,12 +29,12 @@ class TestSpawn < Test::Unit::TestCase
 		start_time = Time.now
 		
 		Fiber.new do
-			result = group.spawn("sleep 1")
+			result = group.fork { sleep 1.0 }
 			assert_equal 0, result
 		end.resume
 		
 		Fiber.new do
-			result = group.spawn("sleep 2")
+			result = group.fork { sleep 2.0 }
 			
 			assert_equal 0, result
 		end.resume
@@ -66,7 +66,7 @@ class TestSpawn < Test::Unit::TestCase
 		
 		end_time = Time.now
 		
-		# Check that the execution time was roughly 2 seconds:
+		# Check that processes killed almost immediately:
 		assert (end_time - start_time) < 0.1
 	end
 	

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: process-group
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Samuel Williams
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-03-13 00:00:00.000000000 Z
+date: 2014-03-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -38,6 +38,20 @@ dependencies:
     - - '>='
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: "\tManages a unix process group for running multiple processes, keeps
   track of multiple processes and leverages fibers to provide predictable behaviour
   in complicated process-based scripts.\n"
@@ -57,6 +71,7 @@ files:
 - lib/process/group/version.rb
 - process-group.gemspec
 - test/test_fork.rb
+- test/test_interrupt.rb
 - test/test_spawn.rb
 homepage: ''
 licenses:
@@ -84,4 +99,5 @@ specification_version: 4
 summary: Run processes concurrently in separate fibers with predictable behaviour.
 test_files:
 - test/test_fork.rb
+- test/test_interrupt.rb
 - test/test_spawn.rb