process-group 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: a8d207f2d37df9b65b6e179ac9109dd9e3a5a443
+  data.tar.gz: 4422d1d9fc5171dc8dc5236b4b9745fbe81dda5b
+SHA512:
+  metadata.gz: f2c49a5f6980e9bb4b44c90f5577e5a664611bef83e22da9f3e5bfbc1525870a76a4ff11cffa36340b30f77e594e75e8de3b55f04132537d10b92bce2a85452c
+  data.tar.gz: 348213c1cf609dace2d8228a9111b53232cc4bf36cde8c548d62e93bc5ee4e3bb1a5fac5fe5083e2029298201e3b6636e91f8d17319946510bb74e00800aa9d5

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.travis.yml

@@ -0,0 +1,5 @@
+language: ruby
+rvm:
+  - "1.9.3"
+  - "2.0"
+  - "2.1"

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in process-pool.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Samuel Williams
+
+MIT License
+
+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/README.md

@@ -0,0 +1,130 @@
+# Process::Group
+
+`Process::Group` allows for multiple fibers to run system processes concurrently with minimal overhead.
+
+[![Build Status](https://travis-ci.org/ioquatix/process-group.png?branch=master)](https://travis-ci.org/ioquatix/process-group)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'process-group'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install process-group
+
+## Usage
+
+The simplest concurrent usage is as follows:
+
+	# Create a new process group:
+	group = Process::Group.new
+	
+	# Run the command (non-blocking):
+	group.run("sleep 1") do |exit_status|
+		# Running in a separate fiber, will execute this code once the process completes:
+		puts "Command finished with status: #{exit_status}"
+	end
+	
+	# Do something else here:
+	sleep(1)
+	
+	# Wait for all processes in group to finish:
+	group.wait
+
+### Explicit Fibers
+
+Items within a single fiber will execute sequentially. Processes (e.g. via `Group#spawn`) will run concurrently in multiple fibers.
+
+	group = Process::Group.new
+	
+	# Explicity manage concurrency in this fiber:
+	Fiber.new do
+		# These processes will be run sequentially:
+		group.spawn("sleep 1")
+		group.spawn("sleep 1")
+	end.resume
+	
+	# Implicitly run this task concurrently as the above fiber:
+	group.run("sleep 2")
+	
+	# Wait for fiber to complete:
+	group.wait
+
+`Group#spawn` is theoretically identical to `Process#spawn` except the processes are run concurrently if possible.
+
+### Specify Options
+
+You can specify options to `Group#run` and `Group#spawn` just like `Process::spawn`:
+
+	group = Process::Group.new
+	
+	env = {'FOO' => 'BAR'}
+	
+	# Arguments are essentially the same as Process::spawn.
+	group.run(env, "sleep 1", chdir: "/tmp")
+	
+	group.wait
+
+### Process Limit
+
+The process group can be used as a way to spawn multiple processes, but sometimes you'd like to limit the number of parallel processes to something relating to the number of processors in the system. A number of options exist.
+
+	# 'facter' gem - found a bit slow to initialise, but most widely supported.
+	require 'facter'
+	group = Process::Group.new(limit: Facter.processorcount)
+	
+	# 'system' gem - found very fast, less wide support (but nothing really important).
+	require 'system'
+	group = Process::Group.new(limit: System::CPU.count)
+	
+	# hardcoded - set to n (8 < n < 32) and let the OS scheduler worry about it.
+	group = Process::Group.new(limit: 32)
+	
+	# unlimited - default.
+	group = Process::Group.new
+
+### Kill Group
+
+It is possible to send a signal (kill) to the entire process group:
+
+	group.kill(:TERM)
+
+If there are no running processes, this is a no-op (rather than an error).
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## License
+
+Released under the MIT license.
+
+Copyright, 2014, by [Samuel G. D. Williams](http://www.codeotaku.com/samuel-williams).
+
+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,9 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new do |t|
+	t.libs << 'test'
+end
+
+desc "Run tests"
+task :default => :test

data/lib/process/group.rb

@@ -0,0 +1,145 @@
+# Copyright, 2014, 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 'fiber'
+
+module Process
+	# A group of tasks which can be run asynchrnously using fibers. Someone must call Group#wait to ensure that all fibers eventually resume.
+	class Group
+		class Command
+			def initialize(arguments, options, fiber = Fiber.current)
+				@arguments = arguments
+				@options = options
+			
+				@fiber = fiber
+			end
+		
+			attr :arguments
+			attr :options
+		
+			def run(options = {})
+				Process.spawn(*@arguments, @options.merge(options))
+			end
+		
+			def resume(*arguments)
+				@fiber.resume(*arguments)
+			end
+		end
+		
+		# Create a new process group. Can specify `options[:limit]` which limits the maximum number of concurrent processes.
+		def initialize(options = {})
+			@commands = []
+			@limit = options[:limit]
+		
+			@running = {}
+			@fiber = nil
+		
+			@pgid = nil
+		end
+		
+		# A table of currently running processes.
+		attr :running
+		
+		# The maximum number of processes to run concurrently, or zero 
+		attr_accessor :limit
+
+		# The id of the process group, only valid if processes are currently running.
+		def id
+			raise RuntimeError.new("No processes in group, no group id available.") if @running.size == 0
+			
+			-@pgid
+		end
+
+		# Run a process, arguments have same meaning as Process#spawn.
+		def run(*arguments)
+			Fiber.new do
+				exit_status = self.spawn(*arguments)
+				
+				yield exit_status if block_given?
+			end.resume
+		end
+		
+		def spawn(*arguments)
+			# Could be nice to use ** splat, but excludes ruby < 2.0.
+			options = Hash === arguments.last ? arguments.pop : {}
+	
+			@commands << Command.new(arguments, options)
+	
+			schedule!
+	
+			Fiber.yield
+		end
+		
+		# Whether not not calling run would be scheduled immediately.
+		def available?
+			if @limit
+				@running.size < @limit
+			else
+				true
+			end
+		end
+		
+		# Whether or not calling run would block the caller.
+		def blocking?
+			not available?
+		end
+		
+		# 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)
+			
+				command = @running.delete(pid)
+			
+				raise RuntimeError.new("Process #{pid} is not part of group!") unless command
+			
+				schedule!
+			
+				command.resume(status)
+			end
+		end
+		
+		# Send a signal to all processes.
+		def kill(signal)
+			if @running.size > 0
+				Process.kill(signal, id)
+			end
+		end
+		
+		private
+		
+		# Run any commands while space is available in the group.
+		def schedule!
+			while available? and @commands.size > 0
+				command = @commands.shift
+			
+				if @running.size == 0
+					pid = command.run(:pgroup => true)
+					@pgid = Process.getpgid(pid)
+				else
+					pid = command.run(:pgroup => @pgid)
+				end
+			
+				@running[pid] = command
+			end
+		end
+	end
+end

data/lib/process/group/version.rb

@@ -0,0 +1,5 @@
+module Process
+	class Group
+		VERSION = "0.0.1"
+	end
+end

data/process-group.gemspec

@@ -0,0 +1,25 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'process/group/version'
+
+Gem::Specification.new do |spec|
+	spec.name          = "process-group"
+	spec.version       = Process::Group::VERSION
+	spec.authors       = ["Samuel Williams"]
+	spec.email         = ["samuel.williams@oriontransfer.co.nz"]
+	spec.description   = <<-EOF
+	Manages 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.
+	EOF
+	spec.summary       = %q{Run processes concurrently in separate fibers with predictable behaviour.}
+	spec.homepage      = ""
+	spec.license       = "MIT"
+
+	spec.files         = `git ls-files`.split($/)
+	spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+	spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+	spec.require_paths = ["lib"]
+
+	spec.add_development_dependency "bundler", "~> 1.3"
+	spec.add_development_dependency "rake"
+end

data/test/test_group.rb

@@ -0,0 +1,106 @@
+# 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 'process/group'
+
+class TestGroup < Test::Unit::TestCase
+	def test_fibers
+		group = Process::Group.new
+		
+		start_time = Time.now
+		
+		Fiber.new do
+			result = group.spawn("sleep 1")
+			assert_equal 0, result
+		end.resume
+		
+		Fiber.new do
+			result = group.spawn("sleep 2")
+			assert_equal 0, result
+		end.resume
+		
+		group.wait
+		
+		end_time = Time.now
+		
+		# Check that the execution time was roughly 2 seconds:
+		assert (1.9..2.1).include?(end_time - start_time)
+	end
+	
+	def test_kill_commands
+		group = Process::Group.new
+		
+		start_time = Time.now
+		
+		group.run("sleep 1") do |exit_status|
+			assert_not_equal 0, exit_status
+		end
+		
+		group.run("sleep 2") do |exit_status|
+			assert_not_equal 0, exit_status
+		end
+		
+		group.kill(:KILL)
+		
+		group.wait
+		
+		end_time = Time.now
+		
+		# Check that the execution time was roughly 2 seconds:
+		assert (end_time - start_time) < 0.1
+	end
+	
+	def test_environment_options
+		group = Process::Group.new
+		
+		env = {'FOO' => 'BAR'}
+		
+		# Make a pipe to receive output from child process:
+		input, output = IO.pipe
+		
+		group.run(env, "echo $FOO", out: output) do |exit_status|
+			output.close
+		end
+		
+		group.wait
+		
+		assert_equal "BAR\n", input.read
+	end
+	
+	def test_yield
+		group = Process::Group.new
+		
+		start_time = Time.now
+		
+		group.run("sleep 1")
+		
+		group.run("sleep 1") do |exit_status|
+		end
+		
+		group.wait
+		
+		end_time = Time.now
+		
+		# Check that the execution time was roughly 1 second:
+		assert (0.9..1.1).include?(end_time - start_time)
+	end
+end

metadata

@@ -0,0 +1,85 @@
+--- !ruby/object:Gem::Specification
+name: process-group
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Samuel Williams
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-03-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  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"
+email:
+- samuel.williams@oriontransfer.co.nz
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .travis.yml
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/process/group.rb
+- lib/process/group/version.rb
+- process-group.gemspec
+- test/test_group.rb
+homepage: ''
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.3
+signing_key: 
+specification_version: 4
+summary: Run processes concurrently in separate fibers with predictable behaviour.
+test_files:
+- test/test_group.rb