procreate 1.0.0

data/COPYING

@@ -0,0 +1,20 @@
+Copyright (c) 2007-2010 Charles Lowe
+
+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/ChangeLog

@@ -0,0 +1,4 @@
+== 1.0.0 / 2011-11-04
+
+- First public release
+

data/README

@@ -0,0 +1,16 @@
+= Introduction
+
+The procreate library provides a simple but powerful api for process creation,
+with a thin, cross-platform wrapper around Open4.background.
+
+Ara Howard's Open4 library does the heavy lifting on POSIX systems, and a
+compatible Open4 implementation is included for windows use.
+
+The primary documentation is for the Process.create method.
+
+= TODO
+
+* Some useful tests.
+
+* Perhaps use separate platform gems so linux can depend on open4 gem, and
+  windows on windows api.

data/lib/procreate.rb

@@ -0,0 +1,74 @@
+if RUBY_PLATFORM =~ /mswin|mingw/
+	require 'procreate/win32/open4'
+else
+	require 'procreate/posix/open4'
+end
+
+module Process
+	# Return the pid of the process.
+	def pid
+		raise NotImplementedError
+	end
+
+	# Return the process exit status. Will block until the process finishes
+	# executing.
+	def exitstatus
+		raise NotImplementedError
+	end
+
+	#
+	# Process.create is a thin, cross-platform wrapper around Open4.background.
+	#
+	# The given +cmdline+ is run in a background process and a thread object is
+	# returned as a handle. The thread is extended with the Process module, to
+	# facilitate testing for a process object and provide an extension point.
+	# Methods are provided to retrieve the #pid or #exitstatus.
+	#
+	# It takes arguments for :stdin, :stdout, and :stderr redirection, and also a
+	# :shell parameter which determines whether or not the command line should be
+	# run by a shell.
+	#
+	# The default if no streams are provided is that output is thrown away. You
+	# need to explicitly pass eg :stdout => STDOUT if you want to keep STDOUT from
+	# process.
+	#
+	# Currently the shell is avoided where possible to ensure the pid is that of
+	# the actual process, so it can be signaled (ie killed) reliably. Otherwise,
+	# the pid is that of the shell, and any signalling to that pid works as per
+	# the shell's documentation.
+	#
+	def Process.create cmdline, params={}
+		params = params.dup
+		shell = params.delete(:shell) # default is false, so nil is okay
+		if RUBY_PLATFORM !~ /mswin|mingw/
+			if Array === cmdline
+				raise ArgumentError, 'unable to use shell with array command' if shell
+			elsif shell
+				# nothing to do. exec will use /bin/sh anyway
+			else
+				# avoid use of shell, so that #pid on return value is actual process pid
+				# not shell pid
+				require 'shellwords'
+				cmdline = Shellwords.shellwords cmdline.to_s
+				cmdline = [cmdline, cmdline].transpose if cmdline.length == 1
+			end
+			# just due to different behaviour for Open4 unix
+			params.update :status => true
+		else
+			if Array === cmdline
+				# the windows version doesn't support array form of cmdline (though could
+				# perhaps fake using some shell quoting thing).
+				raise ArgumentError, 'array arguments not supported on windows'
+			elsif shell
+				# it won't use the shell by default with CreateProcess.
+				# so force it to do so here:
+				# FIXME, this should really be ENV['COMSPEC'] or whatever.
+				cmdline = "cmd /c #{cmdline}"
+			else
+				# nothing to do
+			end
+		end
+		Open4.background(cmdline, params).extend(Process)
+	end
+end
+

data/lib/procreate/posix/open4.rb

@@ -0,0 +1,102 @@
+require 'open4'
+
+module PosixOpen4 = Open4
+	#
+	# This is a rewritten version of Open4.background. The reason for this is
+	# two-fold:
+	#
+	# * The existing function returns a thread that is extended to have a #pid
+	#   method. This in turn waits on a queue, which will never have a pid pushed
+	#   to it if there are any problems spawning. This version instead doesn't
+	#   create the separate background thread until after the popen4 has
+	#   succeeded, meaning any exceptions related to spawn are thrown immediately
+	#   and there is no need for a pid queue.
+	# * The existing spawn function calls flatten! on its argv parameter. This is
+	#   because it was trying to support either splatted or not-splatted array,
+	#   but that falls over for the 1-arg array form of Kernel#exec (eg, to launch
+	#   a command that has spaces in its name, without using the shell.)
+	#
+	def background argv, opts={}
+		cmd = [argv].flatten.join(' ')
+
+		getopt = getopts opts
+
+		ignore_exit_failure = getopt[ 'ignore_exit_failure', getopt['quiet', false] ]
+		ignore_exec_failure = getopt[ 'ignore_exec_failure', !getopt['raise', true] ]
+		exitstatus = getopt[ %w( exitstatus exit_status status ) ]
+		stdin = getopt[ %w( stdin in i 0 ) << 0 ]
+		stdout = getopt[ %w( stdout out o 1 ) << 1 ]
+		stderr = getopt[ %w( stderr err e 2 ) << 2 ]
+		timeout = getopt[ %w( timeout spawn_timeout ) ]
+		stdin_timeout = getopt[ %w( stdin_timeout ) ]
+		stdout_timeout = getopt[ %w( stdout_timeout io_timeout ) ]
+		stderr_timeout = getopt[ %w( stderr_timeout ) ]
+		status = getopt[ %w( status ) ]
+		cwd = getopt[ %w( cwd dir ) ]
+
+		exitstatus =
+			case exitstatus
+				when TrueClass, FalseClass
+					ignore_exit_failure = true if exitstatus
+					[0]
+				else
+					[*(exitstatus || 0)].map{|i| Integer i}
+			end
+
+		stdin  ||= '' if stdin_timeout
+		stdout ||= '' if stdout_timeout
+		stderr ||= '' if stderr_timeout
+
+		started = false
+		begin
+			chdir(cwd) do
+				pid, i, o, e = popen4(*argv)
+				started = true
+
+				thread = Thread.new do
+					begin
+						# the semantics of this timeout have been changed slightly, in
+						# that it doesn't include the popen4 call itself anymore. i think
+						# the intention however was for it to apply primarily to the
+						# Process.waitpid
+						Timeout::timeout timeout do
+							te = ThreadEnsemble.new pid
+							te.add_thread(i, stdin) do |i, stdin|
+								relay stdin, i, stdin_timeout
+								i.close rescue nil
+							end
+							te.add_thread(o, stdout) do |o, stdout|
+								relay o, stdout, stdout_timeout
+							end
+							te.add_thread(e, stderr) do |o, stderr|
+								relay e, stderr, stderr_timeout
+							end
+							te.run
+
+							status = Process.waitpid2(pid).last
+							unless ignore_exit_failure or (status.nil? and ignore_exec_failure) or exitstatus.include?(status.exitstatus)
+								raise SpawnError.new(cmd, status)
+							end
+							status
+						end
+					ensure
+						[i, o, e].each { |fd| fd.close unless fd.closed? }
+					end
+				end
+
+				sc = class << thread; self; end
+				sc.module_eval do
+					define_method(:pid) { pid }
+					define_method(:spawn_status) { value }
+					define_method(:exitstatus) { spawn_status.exitstatus }
+				end
+
+				thread
+			end
+		rescue
+			raise unless not started and ignore_exec_failure
+		end
+	end
+	module_function :background
+end
+

data/lib/procreate/win32/open4.rb

@@ -0,0 +1,289 @@
+require 'windows/api'
+
+module Open4 # :nodoc:
+end
+
+#
+# An implementation of Open4 for windows, based largely on a post by Simon
+# Kröger to comp.lang.ruby - "Problem with popen on windows"
+# (http://groups.google.com/group/comp.lang.ruby/browse_thread/thread/a40bac71df1f4a4c).
+#
+# Provides an api that loosely matches Ara Howard's Open4 (at least for
+# Open4.background so far).
+#
+module Win32Open4 = Open4
+	# Import necessary raw kernel32 functions
+	module Kernel32 # :nodoc:
+		API = Windows::API
+		API.auto_namespace = 'Win32Open4::Kernel32'
+		API.auto_constant  = true
+		API.auto_method    = true
+		API.auto_unicode   = true
+
+		ERROR_SUCCESS                  = 0x00
+		FORMAT_MESSAGE_FROM_SYSTEM     = 0x1000
+		FORMAT_MESSAGE_ARGUMENT_ARRAY  = 0x2000
+
+		WAIT_OBJECT_0                  = 0
+		WAIT_TIMEOUT                   = 0x102
+		WAIT_ABANDONED                 = 128
+		WAIT_ABANDONED_0               = WAIT_ABANDONED
+		WAIT_FAILED                    = 0xFFFFFFFF
+
+		NORMAL_PRIORITY_CLASS          = 0x00000020
+		STARTUP_INFO_SIZE              = 68
+		PROCESS_INFO_SIZE              = 16
+		SECURITY_ATTRIBUTES_SIZE       = 12
+
+		HANDLE_FLAG_INHERIT            = 1
+		HANDLE_FLAG_PROTECT_FROM_CLOSE = 2
+
+		STARTF_USESHOWWINDOW           = 0x00000001
+		STARTF_USESTDHANDLES           = 0x00000100
+
+		API.new('GetLastError', '', 'L', 'kernel32')
+		API.new('CloseHandle', 'L', 'I', 'kernel32')
+		API.new('WaitForSingleObject', 'LL', 'L')
+		API.new('GetExitCodeProcess', 'LP', 'B')
+
+		params = [
+			'L', # IN DWORD dwFlags,
+			'P', # IN LPCVOID lpSource,
+			'L', # IN DWORD dwMessageId,
+			'L', # IN DWORD dwLanguageId,
+			'P', # OUT LPSTR lpBuffer,
+			'L', # IN DWORD nSize,
+			'P', # IN va_list *Arguments
+		]
+		API.new('FormatMessage', params.join, 'L', 'kernel32')
+
+		params = [
+			'P', # pointer to read handle
+			'P', # pointer to write handle
+			'P', # pointer to security attributes
+			'L'  # pipe size
+		]
+		API.new('CreatePipe', params.join, 'I', 'kernel32')
+
+		params = [
+			'L', # handle to an object
+			'L', # specifies flags to change
+			'L'  # specifies new values for flags
+		]
+		API.new('SetHandleInformation', params.join, 'I', 'kernel32')
+
+		params = [
+			'L', # IN LPCSTR lpApplicationName
+			'P', # IN LPSTR lpCommandLine
+			'L', # IN LPSECURITY_ATTRIBUTES lpProcessAttributes
+			'L', # IN LPSECURITY_ATTRIBUTES lpThreadAttributes
+			'L', # IN BOOL bInheritHandles
+			'L', # IN DWORD dwCreationFlags
+			'L', # IN LPVOID lpEnvironment
+			'L', # IN LPCSTR lpCurrentDirectory
+			'P', # IN LPSTARTUPINFOA lpStartupInfo
+			'P'  # OUT LPPROCESS_INFORMATION lpProcessInformation
+		]
+		API.new('CreateProcess', params.join, 'I', 'kernel32')
+
+		params = [
+			'L', # handle to file to write to
+			'P', # pointer to data to write to file
+			'L', # number of bytes to write
+			'P', # pointer to number of bytes written
+			'L'  # pointer to structure for overlapped I/O
+		]
+		API.new('WriteFile', params.join, 'I', 'kernel32')
+
+		params = [
+			'L', # handle of file to read
+			'P', # pointer to buffer that receives data
+			'L', # number of bytes to read
+			'P', # pointer to number of bytes read
+			'L'  # pointer to structure for data
+		]
+		API.new('ReadFile', params.join, 'I', 'kernel32')
+
+		params = [
+			'L', # handle to pipe to copy from
+			'L', # pointer to data buffer
+			'L', # size, in bytes, of data buffer
+			'L', # pointer to number of bytes read
+			'P', # pointer to total number of bytes available
+			'L'  # pointer to unread bytes in this message
+		]
+		API.new('PeekNamedPipe', params.join, 'I', 'kernel32')
+	end
+
+	# Now add wrapper functions
+	module Kernel32 # :nodoc:
+		extend self
+
+		class Kernel32Error < StandardError # :nodoc:
+		end
+
+		module_function
+
+		def raise_last_error!
+			errorCode = GetLastError()
+			if errorCode != ERROR_SUCCESS
+				msg = ' ' * 255
+				msgLength = FormatMessageA(FORMAT_MESSAGE_FROM_SYSTEM | FORMAT_MESSAGE_ARGUMENT_ARRAY, '', errorCode, 0, msg, 255, '')
+				msg.delete! 0.chr
+				msg.strip!
+				raise Kernel32Error, msg
+			else
+				raise Kernel32Error, 'GetLastError returned ERROR_SUCCESS'
+			end
+		end
+
+		# returns read and write handle
+		def create_pipe
+			read_handle, write_handle = Array.new(2) { [0].pack('I') }
+			sec_attrs = [SECURITY_ATTRIBUTES_SIZE, 0, 1].pack('III')
+			raise_last_error! if CreatePipe(read_handle, write_handle, sec_attrs, 0).zero?
+			[read_handle.unpack('I')[0], write_handle.unpack('I')[0]]
+		end
+
+		def set_handle_information(handle, flags, value)
+			raise_last_error! if SetHandleInformation(handle, flags, value).zero?
+		end
+
+		def close_handle(handle)
+			raise_last_error! if CloseHandle(handle).zero?
+		end
+
+		def create_process(command, stdin, stdout, stderr)
+			startupInfo = [
+				STARTUP_INFO_SIZE,
+				0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+				STARTF_USESTDHANDLES | STARTF_USESHOWWINDOW,
+				0, 0, 0,
+				stdin, stdout, stderr
+			].pack('IIIIIIIIIIIISSIIII')
+			processInfo = [0, 0, 0, 0].pack('IIII')
+			command = command + 0.chr
+			raise_last_error! if CreateProcessA(0, command, 0, 0, 1, 0, 0, 0, startupInfo, processInfo).zero?
+			# hProcess, hThread, dwProcessId, dwThreadId
+			processInfo.unpack('LLLL')
+		end
+
+		def write_file(hFile, buffer)
+			written = [0].pack('I')
+			raise_last_error! if WriteFile(hFile, buffer, buffer.size, written, 0).zero?
+			written.unpack('I')[0]
+		end
+
+		def read_file(hFile, size=1024)
+			number = [0].pack('I')
+			buffer = ' ' * size
+			# FIXME? we're masking errors here and just returning an empty string...
+			return '' if ReadFile(hFile, buffer, size, number, 0).zero?
+			buffer[0...number.unpack('I')[0]]
+		end
+
+		def peek_named_pipe(hFile)
+			available = [0].pack('I')
+			# FIXME? as above
+			return -1 if PeekNamedPipe(hFile, 0, 0, 0, available, 0).zero?
+			available.unpack('I')[0]
+		end
+	end
+
+	# Responsible for launching a process, forwarding its stdout & stderr, and
+	# catching its error code.
+	# TODO: stdin is not currently handled in the ProcessHandler#relay method,
+	# though it should be fairly straightforward to add.
+	class ProcessHandler # :nodoc:
+		include Win32Open4::Kernel32
+
+		def initialize cmdline, params={}
+			stdin, @stdout, @stderr = params.values_at :stdin, :stdout, :stderr
+			if stdin
+				raise NotImplementError, 'no stdin forwarding yet'
+			end
+
+			# create 3 pipes
+			pw, pr, pe = Array.new(3) { create_pipe }
+
+			set_handle_information pw.last,  HANDLE_FLAG_INHERIT, 0
+			set_handle_information pr.first, HANDLE_FLAG_INHERIT, 0
+			set_handle_information pe.first, HANDLE_FLAG_INHERIT, 0
+
+			@phandle, hThread, @processId, dwThreadId = create_process cmdline.to_s, pw.first, pr.last, pe.last
+
+			# we have to close the handles, so the pipes terminate with the process
+			close_handle pw.first
+			close_handle pr.last
+			close_handle pe.last
+
+			finalizer = self.class.finalizer [@phandle, pw.last, pr.first, pe.first]
+			ObjectSpace.define_finalizer self, finalizer
+
+			@pr, @pe = pr, pe
+		end
+
+		def self.finalizer handles
+			proc do
+				handles.each { |h| close_handle h }
+			end
+		end
+
+		def run
+			loop do
+				relay
+
+				case WaitForSingleObject @phandle, 10
+				when WAIT_TIMEOUT
+					# ok...
+				when WAIT_OBJECT_0
+					relay
+					exit_code = [0].pack 'L'
+					if GetExitCodeProcess @phandle, exit_code
+						exit_status = exit_code.unpack('L')[0]
+					end
+					return exit_status
+				when -1, WAIT_ABANDONED, WAIT_FAILED
+					raise_last_error!
+				end
+
+				sleep 0.01
+			end
+		end
+
+		def relay
+			stdout = ''
+			avail = peek_named_pipe(@pr.first)
+			stdout = read_file(@pr.first, avail) if avail > 0
+
+			stderr = ''
+			avail = peek_named_pipe(@pe.first)
+			stderr = read_file(@pe.first, avail) if avail > 0
+
+			@stdout << stdout if !stdout.empty? and @stdout
+			@stderr << stderr if !stderr.empty? and @stderr
+		end
+	end
+
+	#
+	# Launches a process asynchronously, and returns a thread that can be used to
+	# retrieve exit status, or wait for completion. All calls used are
+	# non-blocking such that it works safely with ruby's green threads.
+	#
+	# Note that while broadly compatible there are a number of differences from
+	# original Open4.background - eg parameters like :status are ignored (in fact
+	# it works like :status => true in that it won't throw exceptions).
+	#
+	def self.background cmdline, params={}
+		ph = ProcessHandler.new cmdline, params
+		pid = ph.instance_variable_get :@processId
+		thread = Thread.new { ph.run }
+		sc = class << thread; self; end
+		sc.module_eval do
+			define_method(:pid) { pid }
+			define_method(:exitstatus) { value }
+		end
+		thread
+	end
+end
+

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification 
+name: procreate
+version: !ruby/object:Gem::Version 
+  hash: 23
+  prerelease: false
+  segments: 
+  - 1
+  - 0
+  - 0
+  version: 1.0.0
+platform: ruby
+authors: 
+- Charles Lowe
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-11-04 00:00:00 -04:00
+default_executable: 
+dependencies: []
+
+description: A library for process creation with a simple but powerful api, built on Open4. Includes compatible Win32 Open4 implementation.
+email: aquasync@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+- ChangeLog
+files: 
+- README
+- COPYING
+- ChangeLog
+- lib/procreate/posix/open4.rb
+- lib/procreate/win32/open4.rb
+- lib/procreate.rb
+has_rdoc: true
+homepage: http://github.com/aquasync/procreate
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --main
+- README
+- --title
+- procreate documentation
+- --tab-width
+- "2"
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Create processes in a flexible and cross-platform way.
+test_files: []
+