rexec 1.2.1 → 1.2.3

data/lib/rexec/environment.rb

@@ -1,14 +1,33 @@
+# Copyright (c) 2011 Samuel G. D. Williams. <http://www.oriontransfer.co.nz>
+# 
+# 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.
 
 module RExec
 	# Updates the global ENV for the duration of block. Not multi-thread safe.
 	def self.env (new_env = nil, &block)
-	  old_env = ENV.to_hash
+		old_env = ENV.to_hash
 
-	  ENV.update(new_env) if new_env
+		ENV.update(new_env) if new_env
 
-	  yield
+		yield
 
-	  ENV.clear
-	  ENV.update(old_env)
+		ENV.clear
+		ENV.update(old_env)
 	end
 end

data/lib/rexec/priviledges.rb

@@ -1,28 +1,47 @@
+# Copyright (c) 2011 Samuel G. D. Williams. <http://www.oriontransfer.co.nz>
+# 
+# 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 'etc'
 
 module RExec
-  
-  # Set the user of the current process. Supply either a user ID
-  # or a user name.
-  #
-  # Be aware that on Mac OS X / Ruby 1.8 there are bugs when the user id
-  # is negative (i.e. it doesn't work). For example "nobody" with uid -2
-  # won't work.
-  def self.change_user(user)
-    if user.kind_of?(String)
-      user = Etc.getpwnam(user).uid
-    end
-
-    Process::Sys.setuid(user)
-  end
-  
-  
-  # Get the user of the current process. Returns the user name.
-  def self.current_user
-    uid = Process::Sys.getuid
-    
-    Etc.getpwuid(uid).name
-  end
-  
+
+	# Set the user of the current process. Supply either a user ID
+	# or a user name.
+	#
+	# Be aware that on Mac OS X / Ruby 1.8 there are bugs when the user id
+	# is negative (i.e. it doesn't work). For example "nobody" with uid -2
+	# won't work.
+	def self.change_user(user)
+		if user.kind_of?(String)
+			user = Etc.getpwnam(user).uid
+		end
+
+		Process::Sys.setuid(user)
+	end
+
+
+	# Get the user of the current process. Returns the user name.
+	def self.current_user
+		uid = Process::Sys.getuid
+
+		Etc.getpwuid(uid).name
+	end
+
 end

data/lib/rexec/reverse_io.rb

@@ -1,70 +1,89 @@
+# Copyright (c) 2007, 2009, 2011 Samuel G. D. Williams. <http://www.oriontransfer.co.nz>
+# 
+# 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.
 
 class File
-  # Seek to the end of the file
-  def seek_end
-    seek(0, IO::SEEK_END)
-  end
-  
-  # Read a chunk of data and then move the file pointer backwards.
-  #
-  # Calling this function multiple times will return new data and traverse the file backwards.
-  #
-  def read_reverse(length)
-    offset = tell
-    
-    if offset == 0
-      return nil
-    end
-    
-    start = [0, offset-length].max
-    
-    seek(start, IO::SEEK_SET)
-    
-    buf = read(offset-start)
-    
-    seek(start, IO::SEEK_SET)
-    
-    return buf
-  end
-  
-  REVERSE_BUFFER_SIZE = 128
-
-  # This function is very similar to gets but it works in reverse.
-  #
-  # You can use it to efficiently read a file line by line backwards.
-  # 
-  # It returns nil when there are no more lines.
-  def reverse_gets(sep_string=$/)
-    end_pos = tell
-    
-    offset = nil
-    buf = ""
-    
-    while offset == nil
-      chunk = read_reverse(REVERSE_BUFFER_SIZE)
-      return (buf == "" ? nil : buf) if chunk == nil
-      
-      buf = chunk + buf
-      
-      offset = buf.rindex(sep_string)
-    end
-    
-    line = buf[offset...buf.size].sub(sep_string, "")
-    
-    seek((end_pos - buf.size) + offset, IO::SEEK_SET)
-    
-    return line
-  end
-  
-  # Similar to each_line but works in reverse. Don't forget to call
-  # seek_end before you start!
-  def reverse_each_line(sep_string=$/, &block)
-    line = reverse_gets(sep_string)
-    
-    while line != nil
-      yield line
-      
-      line = reverse_gets(sep_string)
-    end
-  end
+	# Seek to the end of the file
+	def seek_end
+		seek(0, IO::SEEK_END)
+	end
+
+	# Read a chunk of data and then move the file pointer backwards.
+	#
+	# Calling this function multiple times will return new data and traverse the file backwards.
+	#
+	def read_reverse(length)
+		offset = tell
+
+		if offset == 0
+			return nil
+		end
+
+		start = [0, offset-length].max
+
+		seek(start, IO::SEEK_SET)
+
+		buf = read(offset-start)
+
+		seek(start, IO::SEEK_SET)
+
+		return buf
+	end
+
+	REVERSE_BUFFER_SIZE = 128
+
+	# This function is very similar to gets but it works in reverse.
+	#
+	# You can use it to efficiently read a file line by line backwards.
+	# 
+	# It returns nil when there are no more lines.
+	def reverse_gets(sep_string=$/)
+		end_pos = tell
+
+		offset = nil
+		buf = ""
+
+		while offset == nil
+			chunk = read_reverse(REVERSE_BUFFER_SIZE)
+			return (buf == "" ? nil : buf) if chunk == nil
+
+			buf = chunk + buf
+
+			offset = buf.rindex(sep_string)
+		end
+
+		line = buf[offset...buf.size].sub(sep_string, "")
+
+		seek((end_pos - buf.size) + offset, IO::SEEK_SET)
+
+		return line
+	end
+
+	# Similar to each_line but works in reverse. Don't forget to call
+	# seek_end before you start!
+	def reverse_each_line(sep_string=$/, &block)
+		line = reverse_gets(sep_string)
+
+		while line != nil
+			yield line
+
+			line = reverse_gets(sep_string)
+		end
+	end
 end

data/lib/rexec/server.rb

@@ -1,62 +1,95 @@
-# Copyright (c) 2007 Samuel Williams. Released under the GNU GPLv3.
-#
-# This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
+# Copyright (c) 2007, 2011 Samuel G. D. Williams. <http://www.oriontransfer.co.nz>
 # 
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
+# 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:
 # 
-# You should have received a copy of the GNU General Public License
-# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+# 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 'pathname'
 require 'rexec/task'
 require 'rexec/connection'
 
 module RExec
-  
-  class InvalidConnectionError < Exception
-  end
-  
-  @@connection_code = (Pathname.new(__FILE__).dirname + "connection.rb").read
-  @@client_code = (Pathname.new(__FILE__).dirname + "client.rb").read
-  
-  # Start a remote ruby server. This function is a structural cornerstone. This code runs the command you 
-  # supply (this command should start an instance of ruby somewhere), sends it the code in
-  # <tt>connection.rb</tt> and <tt>client.rb</tt> as well as the code you supply.
-  #
-  # Once the remote ruby instance is set up and ready to go, this code will return (or yield) the connection
-  # and pid of the executed command.
-  #
-  # From this point, you can send and receive objects, and interact with the code you provided within a
-  # remote ruby instance.
-  #
-  # If <tt>command</tt> is a shell such as "/bin/sh", and we need to start ruby separately, you can supply
-  # <tt>options[:ruby] = "/usr/bin/ruby"</tt> to explicitly start the ruby command.
-  def self.start_server(code, command, options = {}, &block)
-    options[:passthrough] = :err unless options[:passthrough]
-    
-    send_code = Proc.new do |cin|
-      cin.puts(@@connection_code)
-      cin.puts(@@client_code)
-      cin.puts(code)
-    end
-    
-    if block_given?
-      Task.open(command, options) do |process|
-        conn = Connection.build(process, options, &send_code)
-        
-        yield conn, process.pid
-      end
-    else
-      process = Task.open(command, options)
-      conn = Connection.build(process, options, &send_code)
-      
-      return conn, process.pid
-    end
-  end
+
+	# Indicates that a connection could not be established because the pipes were not available or not connected.
+	class InvalidConnectionError < Exception
+	end
+	
+	# The connection code which is sent to the client to be used for bi-directional communication.
+	CONNECTION_CODE = (Pathname.new(__FILE__).dirname + "connection.rb").read
+	
+	# The client code which sets up the connection object and initialises communciation.
+	CLIENT_CODE = (Pathname.new(__FILE__).dirname + "client.rb").read
+	
+	# Start a remote ruby server. This function is a structural cornerstone. This code runs the command you 
+	# supply (this command should start an instance of ruby somewhere), sends it the code in
+	# +connection.rb+ and +client.rb+ as well as the code you supply.
+	#
+	# Once the remote ruby instance is set up and ready to go, this code will return (or yield) the connection
+	# and pid of the executed command.
+	#
+	# From this point, you can send and receive objects, and interact with the code you provided within a
+	# remote ruby instance.
+	#
+	# For a local shell, you could specify +"ruby"+ as the command. For a remote shell via SSH, you could specify
+	# +"ssh example.com ruby"+.
+	# 
+	# ==== Example
+	# Create a file called +client.rb+ on the server. This file contains code to be executed on the client. This
+	# file can assume the existance of an object called +$connection+:
+	# 
+	# 	$connection.run do |object|
+	# 	  case(object[0])
+	# 	  when :bounce
+	# 	    $connection.send_object(object[1])
+	# 	  end
+	# 	end
+	# 
+	# Then, on the server, create a new program +server.rb+ which will be used to coordinate the execution of code:
+	#
+	# 	shell = "ssh example.com ruby"
+	# 	client_code = (Pathname.new(__FILE__).dirname + "./client.rb").read
+	# 	
+	# 	RExec::start_server(client_code, shell) do |connection, pid|
+	# 		connection.send_object([:bounce, "Hello World!"])
+	# 		result = connection.receive_object
+	# 	end
+	#
+	def self.start_server(code, command, options = {}, &block)
+		options[:passthrough] = :err unless options[:passthrough]
+
+		send_code = Proc.new do |cin|
+			cin.puts(CONNECTION_CODE)
+			cin.puts(CLIENT_CODE)
+			cin.puts(code)
+		end
+
+		if block_given?
+			Task.open(command, options) do |process|
+				conn = Connection.build(process, options, &send_code)
+
+				yield conn, process.pid
+				
+				conn.stop
+			end
+		else
+			process = Task.open(command, options)
+			conn = Connection.build(process, options, &send_code)
+
+			return conn, process.pid
+		end
+	end
 end

data/lib/rexec/task.rb

@@ -1,25 +1,34 @@
-# Copyright (c) 2007 Samuel Williams. Released under the GNU GPLv3.
-#
-# This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
+# Copyright (c) 2007, 2011 Samuel G. D. Williams. <http://www.oriontransfer.co.nz>
 # 
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
+# 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:
 # 
-# You should have received a copy of the GNU General Public License
-# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+# 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 'thread'
 
 module RExec
+	private
+	
 	RD = 0
 	WR = 1
+	
+	public
 
-	# This function closes all IO other than $stdin, $stdout, $stderr
+	# Cloose all IO other than $stdin, $stdout, $stderr (or those given by the argument except)
 	def self.close_io(except = [$stdin, $stdout, $stderr])
 		# Make sure all file descriptors are closed
 		ObjectSpace.each_object(IO) do |io|
@@ -29,6 +38,8 @@ module RExec
 		end
 	end
 
+	# Represents a running process, either a child process or a background/daemon process.
+	# Provides an easy high level interface for managing process life-cycle.
 	class Task
 		private
 		def self.pipes_for_options(options)
@@ -72,8 +83,10 @@ module RExec
 			return pipes
 		end
 
-		# Close all the supplied pipes
+		# The standard process pipes.
 		STDPIPES = [STDIN, STDOUT, STDERR]
+		
+		# Close all the supplied pipes.
 		def self.close_pipes(*pipes)
 			pipes = pipes.compact.reject{|pipe| STDPIPES.include?(pipe)}
 
@@ -112,16 +125,15 @@ module RExec
 
 		# Very simple method to spawn a child daemon. A daemon is detatched from the controlling tty, and thus is
 		# not killed when the parent process finishes.
-		# <tt>
-		# spawn_daemon do
-		#   Dir.chdir("/")
-		#   File.umask 0000
-		#   puts "Hello from daemon!"
-		#   sleep(600)
-		#   puts "This code will not quit when parent process finishes..."
-		#   puts "...but $stdout might be closed unless you set it to a file."
-		# end
-		# </tt>
+		#
+		#	spawn_daemon do
+		#		Dir.chdir("/")
+		#		File.umask 0000
+		#		puts "Hello from daemon!"
+		#		sleep(600)
+		#		puts "This code will not quit when parent process finishes..."
+		#		puts "...but $stdout might be closed unless you set it to a file."
+		#	end
 		def self.spawn_daemon(&block)
 			pid_pipe = IO.pipe
 
@@ -147,11 +159,10 @@ module RExec
 		end
 
 		# Very simple method to spawn a child process
-		# <tt>
-		# spawn_child do 
-		#   puts "Hello from child!"
-		# end
-		# </tt>
+		# 
+		#	spawn_child do
+		#		puts "Hello from child!"
+		#	end
 		def self.spawn_child(&block)
 			pid = fork do
 				yield
@@ -162,30 +173,87 @@ module RExec
 			return pid
 		end
 
-		# Open a process. Similar to IO.popen, but provides a much more generic interface to stdin, stdout, 
-		# stderr and the pid. We also attempt to tidy up as much as possible given some kind of error or
-		# exception. You are expected to write to output, and read from input and error.
+		# Open a process. Similar to +IO.popen+, but provides a much more generic interface to +stdin+, +stdout+,
+		# +stderr+ and the +pid+. We also attempt to tidy up as much as possible given some kind of error or
+		# exception. You may write to +output+, and read from +input+ and +error+.
+		#
+		# Typical usage looks similar to +IO.popen+:
+		# 	count = 0
+		# 	result = Task.open(["ls", "-la"], :passthrough => :err) do |task|
+		# 		count = task.output.read.split(/\n/).size
+		# 	end
+		# 	puts "Count: #{count}" if result.exitstatus == 0
+		#
+		# The basic command can simply be a string, and this will be passed to +Kernel#exec+ which will perform
+		# shell expansion on the arguments.
+		#
+		# If the command passed is an array, this will be executed without shell expansion.
+		#
+		# If a +Proc+ (or anything that +respond_to? :call+) is provided, this will be executed in the child
+		# process. Here is an example of a long running background process:
+		#
+		# 	daemon = Proc.new do
+		# 		# Long running process
+		# 		sleep(1000)
+		# 	end
+		# 	
+		# 	task = Task.open(daemon, :daemonize => true, :in => ..., :out => ..., :err => ...)
+		# 	exit(0)
+		#
+		# ==== Options
 		#
-		# = Options =
+		# [+:passthrough+, +:in+, +:out+, +:err+]
+		#   The current process (e.g. ruby) has a set of existing pipes +$stdin+, +$stdout+ and 
+		#   +$stderr+. These pipes can also be used by the child process. The passthrough option
+		#   allows you to specify which pipes are retained from the parent process by the child.
+		#   
+		#   Typically it is useful to passthrough $stderr, so that errors in the child process
+		#   are printed out in the terminal of the parent process:
+		#   	Task.open([...], :passthrough => :err)
+		#   	Task.open([...], :passthrough => [:in, :out, :err])
+		#   	Task.open([...], :passthrough => :all)
+		#   
+		#   It is also possible to redirect to files, which can be useful if you want to keep a
+		#   a log file:
+		#   	Task.open([...], :out => File.open("output.log"))
+		#   
+		#   The default behaviour is to create a new pipe, but any pipe (e.g. a network socket)
+		#   could be used:
+		#   	Task.open([...], :in => IO.pipe)
+		#   
+		# [+:daemonize+]
+		#   The process that is opened may be detached from the parent process. This allows the
+		#   child process to exist even if the parent process exits. In this case, you will also
+		#   probably want to specify the +:passthrough+ option for log files:
+		#   	Task.open([...],
+		#   		:daemonize => true,
+		#   		:in => File.open("/dev/null"),
+		#   		:out => File.open("/var/log/child.log", "a"),
+		#   		:err => File.open("/var/log/child.err", "a")
+		#   	)
 		#
-		# We can specify a pipe that will be redirected to the current processes pipe. A typical one is
-		# :err, so that errors in the child process are printed directly to $stderr of the parent process.
-		# <tt>:passthrough => :err</tt>
-		# <tt>:passthrough => [:in, :out, :err]</tt> or <tt>:passthrough => :all</tt>
+		# [+:env+, +:env!+]
+		#   Provide a environment which will be used by the child process. Use +:env+ to update
+		#   the exsting environment and +:env!+ to replace it completely.
+		#   	Task.open([...], :env => {'foo' => 'bar'})
 		#
-		# We can specify a set of pipes other than the standard ones for redirecting to other things, eg
-		# <tt>:out => File.open("output.log", "a")</tt>
+		# [+:umask+]
+		#    Set the umask for the new process, as per +File.umask+.
 		#
-		# If you need to supply a pipe manually, you can do that too:
-		# <tt>:in => IO.pipe</tt>
+		# [+:chdir+]
+		#    Set the current working directory for the new process, as per +Dir.chdir+.
 		#
-		# You can specify <tt>:daemonize => true</tt> to cause the child process to detatch. In this
-		# case you will generally want to specify files for <tt>:in, :out, :err</tt> e.g.
-		# <tt>
-		#   :in => File.open("/dev/null"),
-		#   :out => File.open("/var/log/my.log", "a"),
-		#   :err => File.open("/var/log/my.err", "a")
-		# </tt>
+		# [+:preflight+]
+		#    Similar to a proc based command, but executed before execing the given process.
+		#    	preflight = Proc.new do |command, options|
+		#    		# Setup some default state before exec the new process.
+		#    	end
+		#    	
+		#    	Task.open([...], :preflight => preflight)
+		#    
+		#    The options hash is passed directly so you can supply custom arguments to the preflight
+		#    function.
+		
 		def self.open(command, options = {}, &block)
 			cin, cout, cerr = pipes_for_options(options)
 			spawn = options[:daemonize] ? :spawn_daemon : :spawn_child
@@ -197,6 +265,25 @@ module RExec
 				STDOUT.reopen(cout[WR]) if cout[WR]
 				STDERR.reopen(cerr[WR]) if cerr[WR]
 
+				if options[:env!]
+					ENV.clear
+					ENV.update(options[:env!])
+				elsif options[:env]
+					ENV.update(options[:env])
+				end
+
+				if options[:umask]
+					File.umask(options[:umask])
+				end
+
+				if options[:chdir]
+					Dir.chdir(options[:chdir])
+				end
+
+				if options[:preflight]
+					preflight.call(command, options)
+				end
+
 				if command.respond_to? :call
 					command.call
 				elsif Array === command
@@ -233,7 +320,7 @@ module RExec
 			end
 		end
 
-		def initialize(input, output, error, pid)
+		def initialize(input, output, error, pid) # :nodoc:
 			@input = input
 			@output = output
 			@error = error
@@ -246,10 +333,19 @@ module RExec
 			@result_available = ConditionVariable.new
 		end
 
+		# Standard input to the running task.
 		attr :input
+		
+		# Standard output from the running task.
 		attr :output
+		
+		# Standard error from the running task.
 		attr :error
+		
+		# The PID of the running task.
 		attr :pid
+		
+		# The status of the task after calling task.wait.
 		attr :result
 
 		# Returns true if the current task is still running