rexec 1.2.1 → 1.2.3

data/README.rdoc

@@ -1,14 +1,61 @@
 = RExec
 
-Author::    Samuel Williams (http://www.oriontransfer.co.nz/)
-Copyright:: Copyright (C) 2009, 2010 Samuel Williams
-License::   GPLv3
-
-RExec stands for Ruby Execute or Remote Execute (depending on how you use it). It provides a number of different things to assist with running Ruby code:
-
-* A framework to send Ruby code to a remote server for execution
-* A framework for writing command line daemons (i.e. <tt>start</tt>, <tt>restart</tt>, <tt>stop</tt>, <tt>status</tt>)
-* A comprehensive <tt>Task</tt> class for launching tasks, managing input and output, exit status, etc
-* Basic privilege management code for changing the processes owner
-* A bunch of helpers for various different things (such as reading a file backwards)
-* <tt>daemon-exec</tt> executable for running regular shell tasks in the background
+Author::    Samuel G. D. Williams (http://www.oriontransfer.co.nz)
+Copyright:: Copyright (C) 2007, 2009, 2011 Samuel G. D. Williams
+License::   MIT
+
+RExec stands for Remote Execute and provides support for executing processes 
+both locally and remotely. It provides a number of different tools to assist
+with running Ruby code:
+
+* A framework to send Ruby code to a remote server for execution.
+* A framework for writing command line daemons (i.e. +start+, +restart+, +stop+, +status+).
+* A comprehensive +Task+ class for launching tasks, managing input and output, exit status, etc.
+* Basic privilege management code for changing the processes owner.
+* A bunch of helpers for various different things (such as reading a file backwards).
+* +daemon-exec+ executable for running regular shell tasks in the background.
+
+== Comprehensive process management
+
++RExec::Task+ provides a comprehensive wrapper for low level process execution
+and life-cycle management. You can easy spawn new child processes, background
+processes and execute Ruby code in a child instance.
+
+== Light weight bi-directional communication
+
+The +RExec::Connection+ provides a simple process based API for communicating 
+with distant instances of Ruby. These can either be local or remote, such
+as over SSH.
+
+== Simple daemonization
+
+The +RExec::Daemon+ module provides the foundation to develop long-running
+background processes. Simply create a daemon class which inherits from 
++RExec::Daemon::Base+ and you can have a fully featured background daemon 
+with the standard command line interface, e.g. +start+, +restart+, +status+
+and +stop+.
+
+Along with this, a executable is included called +daemon-exec+ which allows
+for any standard shell script to be run as a background process.
+
+== License
+
+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.

data/bin/daemon-exec

@@ -1,19 +1,24 @@
 #!/usr/bin/env ruby
 
-# Copyright (c) 2010 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) 2010, 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 'rubygems'
 

data/lib/rexec.rb

@@ -1,33 +1,29 @@
-# 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, 2009, 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/>.
-
-# = Summary =
-# This gem provides a very simple connection based API for communicating 
-# with remote instances of ruby. These can either be local, or remote, such
-# as over SSH.
-#
-# The API is very simple and deals with sending and receiving objects using 
-# Marshal. One of the primary goals was to impose as little structure as
-# possible on the end user of this library, while still maintaining a level
-# of convenience.
-#
-# Author::    Samuel Williams (samuel AT oriontransfer DOT org)
-# Copyright:: Copyright (c) 2009 Samuel Williams.
-# License::   Released under the GNU GPLv3.
+# 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 'rexec/version'
 require 'rexec/connection'
 require 'rexec/server'
 require 'rexec/priviledges'
+
+## RExec is a tool to assist with the execution of other processes.
+module RExec
+	
+end

data/lib/rexec/client.rb

@@ -1,17 +1,5 @@
-# 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.
-# 
-# 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.
-# 
-# You should have received a copy of the GNU General Public License
-# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+# Copyright (c) 2007, 2011 Samuel G. D. Williams. <http://www.oriontransfer.co.nz>
+# Released under the MIT license. Please see LICENSE.txt for license details.
 
 # This code is executed in a remote ruby process.
 

data/lib/rexec/connection.rb

@@ -1,153 +1,145 @@
-# 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.
-# 
-# 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.
-# 
-# You should have received a copy of the GNU General Public License
-# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+# Copyright (c) 2007, 2011 Samuel G. D. Williams. <http://www.oriontransfer.co.nz>
+# Released under the MIT license. Please see LICENSE.txt for license details.
 
 # This class is as small and independant as possible as it will get sent to clients for execution.
 
 require 'thread'
 
 module RExec
-  
-  # This class represents an abstract connection to another ruby process. The interface does not impose
-  # any structure on the way this communication link works, except for the fact you can send and receive
-  # objects. You can implement whatever kind of idiom you need for communication on top of this library.
-  #
-  # Depending on how you set things up, this can connect to a local ruby process, or a remote ruby process
-  # via SSH (for example).
-  class Connection
-    public
-
-    def self.build(process, options, &block)
-      cin = process.input
-      cout = process.output
-      cerr = process.error
-      
-      # We require both cin and cout to be connected in order for connection to work
-      raise InvalidConnectionError.new("Input (#{cin}) or Output (#{cout}) is not connected!") unless cin and cout
-      
-      yield cin
-      
-      cin.puts("\004")
-      
-      return self.new(cout, cin, cerr)
-    end
-
-    # Create a new connection. You need to supply a pipe for reading input, a pipe for sending output,
-    # and optionally a pipe for errors to be read from.
-    def initialize(input, output, error = nil)
-      @input = input
-      @output = output
-      @running = true
-
-      @error = error
-
-      @receive_mutex = Mutex.new
-      @send_mutex = Mutex.new
-    end
-
-    # The pipe used for reading data
-    def input
-      @input
-    end
-
-    # The pipe used for writing data
-    def output
-      @output
-    end
-
-    # The pipe used for receiving errors. On the client side this pipe is writable, on the server 
-    # side this pipe is readable. You should avoid using it on the client side and simply use $stderr.
-    def error
-      @error
-    end
-
-    # Stop the connection, and close the output pipe.
-    def stop
-      @running = false
-      @output.close
-    end
-    
-    # Return whether or not the connection is running.
-    def running?
-      @running
-    end
-
-    # This is a very simple runloop. It provides an object when it is received.
-    def run(&block)
-      while @running
-        pipes = IO.select([@input])
-
-        if pipes[0].size > 0
-          object = receive_object
-          
-          if object == nil
-            @running = false
-            return
-          end
-          
-          begin
-            yield object
-          rescue Exception => ex
-            send_object(ex)
-          end
-        end
-      end
-    end
-
-    # Dump any text which has been written to $stderr in the child process.
-    def dump_errors(to = $stderr)
-      if @error and !@error.closed?
-        while true
-          result = IO.select([@error], [], [], 0)
-
-          break if result == nil
-
-          to.puts @error.readline.chomp
-        end
-      end
-    end
-    
-    # Receive an object from the connection. This function is thread-safe. This function may block.
-    def receive_object
-      object = nil
-
-      @receive_mutex.synchronize do
-        begin
-          object = Marshal.load(@input)
-        rescue EOFError
-          object = nil
-          @running = false
-        end
-      end
-      
-      if object and object.kind_of?(Exception)
-        raise object
-      end
-      
-      return object
-    end
-
-    # Send object(s). This function is thread-safe.
-    def send_object(*objects)
-      @send_mutex.synchronize do
-        objects.each do |o|
-          data = Marshal.dump(o)
-          @output.write(data)
-        end
-        
-        @output.flush
-      end
-    end
-  end
+
+	# This class represents an abstract connection to another ruby process. The interface does not impose
+	# any structure on the way this communication link works, except for the fact you can send and receive
+	# objects. You can implement whatever kind of idiom you need for communication on top of this library.
+	#
+	# Depending on how you set things up, this could connect to a local ruby process, or a remote ruby process
+	# via `ssh`.
+	#
+	# To set up a connection, you need to use {start_server}.
+	class Connection
+		public
+
+		def self.build(process, options, &block)
+			cin = process.input
+			cout = process.output
+			cerr = process.error
+
+			# We require both cin and cout to be connected in order for connection to work
+			raise InvalidConnectionError.new("Input (#{cin}) or Output (#{cout}) is not connected!") unless cin and cout
+
+			yield cin
+
+			cin.puts("\004")
+
+			return self.new(cout, cin, cerr)
+		end
+
+		# Create a new connection. You need to supply a pipe for reading input, a pipe for sending output,
+		# and optionally a pipe for errors to be read from.
+		def initialize(input, output, error = nil)
+			@input = input
+			@output = output
+			@running = true
+
+			@error = error
+
+			@receive_mutex = Mutex.new
+			@send_mutex = Mutex.new
+		end
+
+		# The pipe used for reading data
+		def input
+			@input
+		end
+
+		# The pipe used for writing data
+		def output
+			@output
+		end
+
+		# The pipe used for receiving errors. On the client side this pipe is writable, on the server 
+		# side this pipe is readable. You should avoid using it on the client side and simply use $stderr.
+		def error
+			@error
+		end
+
+		# Stop the connection, and close the output pipe.
+		def stop
+			if @running
+				@running = false
+				@output.close
+			end
+		end
+
+		# Return whether or not the connection is running.
+		def running?
+			@running
+		end
+
+		# This is a very simple runloop. It provides an object when it is received.
+		def run(&block)
+			while @running
+				pipes = IO.select([@input])
+
+				if pipes[0].size > 0
+					object = receive_object
+
+					if object == nil
+						@running = false
+						return
+					end
+
+					begin
+						yield object
+					rescue Exception => ex
+						send_object(ex)
+					end
+				end
+			end
+		end
+
+		# Dump any text which has been written to $stderr in the child process.
+		def dump_errors(to = $stderr)
+			if @error and !@error.closed?
+				while true
+					result = IO.select([@error], [], [], 0)
+
+					break if result == nil
+
+					to.puts @error.readline.chomp
+				end
+			end
+		end
+
+		# Receive an object from the connection. This function is thread-safe. This function may block.
+		def receive_object
+			object = nil
+
+			@receive_mutex.synchronize do
+				begin
+					object = Marshal.load(@input)
+				rescue EOFError
+					object = nil
+					@running = false
+				end
+			end
+
+			if object and object.kind_of?(Exception)
+				raise object
+			end
+
+			return object
+		end
+
+		# Send object(s). This function is thread-safe.
+		def send_object(*objects)
+			@send_mutex.synchronize do
+				objects.each do |o|
+					data = Marshal.dump(o)
+					@output.write(data)
+				end
+
+				@output.flush
+			end
+		end
+	end
 end