right_popen 1.0.2-x86-mswin32-60 → 1.0.5-x86-mswin32-60

data/README.rdoc

@@ -41,8 +41,13 @@ to report issues.
 
   EM.run do
     EM.next_tick do
-      cmd = "ruby -e \"puts 'some stdout text'; $stderr.puts 'some stderr text'\; exit 99\""
-      RightScale.popen3(cmd, self, :on_read_stdout, :on_read_stderr, :on_exit)
+      command = "ruby -e \"puts 'some stdout text'; $stderr.puts 'some stderr text'\; exit 99\""
+      RightScale.popen3(:command        => command,
+                        :target         => self,
+                        :environment    => nil,
+                        :stdout_handler => :on_read_stdout,
+                        :stderr_handler => :on_read_stderr,
+                        :exit_handler   => :on_exit)
     end
     timer = EM::PeriodicTimer.new(0.1) do
       if @exit_status
@@ -90,7 +95,7 @@ The build can be tested using the RSpec gem. Create a link to the installed
 under Windows) and run the following command from the gem directory to execute
 the RightPopen tests:
 
-  spec spec/right_popen_spec.rb
+  rake spec
 
 
 == LICENSE

data/Rakefile

@@ -46,3 +46,8 @@ task :reinstall_gem do
    sh "gem uninstall right_popen"
    sh "rake install_gem"
 end
+
+desc 'Runs all spec tests'
+task :spec do
+  sh "spec spec/*_spec.rb"
+end

data/ext/win32/right_popen.c

@@ -1,24 +1,24 @@
-///////////////////////////////////////////////////////////////////////////////
-// Copyright (c) 2010 RightScale Inc
-//
-// 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.
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (c) 2010 RightScale Inc
+//
+// 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.
 ///////////////////////////////////////////////////////////////////////////////
 
 #include "right_popen.h"
@@ -60,6 +60,7 @@ static const DWORD CHILD_PROCESS_EXIT_WAIT_MSECS = 500;    // 0.5 secs
 
 static Open3ProcessData* win32_process_data_list = NULL;
 static DWORD win32_named_pipe_serial_number = 1;
+static HMODULE hUserEnvLib = NULL;
 
 // Summary:
 //  allocates a new Ruby I/O object.
@@ -219,6 +220,10 @@ static VALUE right_popen_close_io_array(VALUE vRubyIoObjectArray)
 //   bShowWindow
 //      true if process window is initially visible, false if process has no UI or is invisible
 //
+//   pszEnvironmentStrings
+//      enviroment strings in a double-nul terminated "str1\0str2\0...\0"
+//      block to give child process or NULL.
+//
 // Returns:
 //  true if successful, false otherwise (call GetLastError() for more information)
 static BOOL win32_create_process(char*     szCommand,
@@ -227,10 +232,12 @@ static BOOL win32_create_process(char*     szCommand,
                                  HANDLE    hStderr,
                                  HANDLE*   phProcess,
                                  rb_pid_t* pPid,
-                                 BOOL      bShowWindow)
+                                 BOOL      bShowWindow,
+                                 char*     pszEnvironmentStrings)
 {
     PROCESS_INFORMATION pi;
     STARTUPINFO si;
+    BOOL bResult = FALSE;
 
     ZeroMemory(&si, sizeof(STARTUPINFO));
 
@@ -246,7 +253,7 @@ static BOOL win32_create_process(char*     szCommand,
                       NULL,
                       TRUE,
                       0,
-                      NULL,
+                      pszEnvironmentStrings,
                       NULL,
                       &si,
                       &pi))
@@ -256,11 +263,11 @@ static BOOL win32_create_process(char*     szCommand,
 
         // Return process handle
         *phProcess = pi.hProcess;
-        *pPid = (rb_pid_t)pi.dwProcessId;
-        return TRUE;
+        *pPid      = (rb_pid_t)pi.dwProcessId;
+        bResult    = TRUE;
     }
 
-    return FALSE;
+    return bResult;
 }
 
 // Summary:
@@ -710,12 +717,16 @@ static VALUE ruby_create_io_object(rb_pid_t pid, int iFileMode, HANDLE hFile, BO
 //          false to read synchronously, true to read asynchronously. see
 //          also RightPopen::async_read() (defaults to Qfalse).
 //
+//      pszEnvironmentStrings
+//          enviroment strings in a double-nul terminated "str1\0str2\0...\0"
+//          block to give child process or NULL.
+//
 // Returns:
 //  a Ruby array containing [stdin write, stdout read, stderr read, pid]
 //
 // Throws:
 //  raises a Ruby RuntimeError on failure
-static VALUE win32_popen4(char* szCommand, int iMode, BOOL bShowWindow, BOOL bAsynchronousOutput)
+static VALUE win32_popen4(char* szCommand, int iMode, BOOL bShowWindow, BOOL bAsynchronousOutput, char* pszEnvironmentStrings)
 {
     VALUE vReturnArray = Qnil;
     HANDLE hProcess = NULL;
@@ -733,7 +744,8 @@ static VALUE win32_popen4(char* szCommand, int iMode, BOOL bShowWindow, BOOL bAs
                                   pData->childStderrPair.hWrite,
                                   &hProcess,
                                   &pid,
-                                  bShowWindow))
+                                  bShowWindow,
+                                  pszEnvironmentStrings))
     {
         DWORD dwLastError = GetLastError();
         win32_free_process_data(pData);
@@ -819,10 +831,12 @@ static VALUE right_popen_popen4(int argc, VALUE *argv, VALUE klass)
     VALUE vReturnArray = Qnil;
     VALUE vShowWindowFlag = Qfalse;
     VALUE vAsynchronousOutputFlag = Qfalse;
+    VALUE vEnvironmentStrings = Qnil;
     int iMode = 0;
     char* mode = "t";
+    char* pszEnvironmentStrings = NULL;
 
-    rb_scan_args(argc, argv, "13", &vCommand, &vMode, &vShowWindowFlag, &vAsynchronousOutputFlag);
+    rb_scan_args(argc, argv, "14", &vCommand, &vMode, &vShowWindowFlag, &vAsynchronousOutputFlag, &vEnvironmentStrings);
 
     if (!NIL_P(vMode))
     {
@@ -840,11 +854,16 @@ static VALUE right_popen_popen4(int argc, VALUE *argv, VALUE klass)
     {
         iMode = _O_BINARY;
     }
+    if (!NIL_P(vEnvironmentStrings))
+    {
+        pszEnvironmentStrings = StringValuePtr(vEnvironmentStrings);
+    }
 
     vReturnArray = win32_popen4(StringValuePtr(vCommand),
                                 iMode,
                                 Qfalse != vShowWindowFlag,
-                                Qfalse != vAsynchronousOutputFlag);
+                                Qfalse != vAsynchronousOutputFlag,
+                                pszEnvironmentStrings);
 
     // ensure handles are closed in block form.
     if (rb_block_given_p())
@@ -985,6 +1004,193 @@ static VALUE right_popen_async_read(VALUE vSelf, VALUE vRubyIoObject)
     }
 }
 
+// Summary:
+//  scans the given nul-terminated block of nul-terminated Unicode strings to
+//  convert the block from Unicode to Multi-Byte and determine the correct
+//  length of the converted block. the converted block is then used to create
+//  a Ruby string value containing multiple nul-terminated strings. in Ruby,
+//  the block must be scanned again using index(0.chr, ...) logic.
+//
+// Returns:
+//  a Ruby string representing the environment block
+static VALUE win32_unicode_environment_block_to_ruby(const void* pvEnvironmentBlock)
+{
+    const WCHAR* pszStart = (const WCHAR*)pvEnvironmentBlock;
+    const WCHAR* pszEnvString = pszStart;
+
+    VALUE vResult = Qnil;
+
+    while (*pszEnvString != 0)
+    {
+        const int iEnvStringLength = wcslen(pszEnvString);
+
+        pszEnvString += iEnvStringLength + 1;
+    }
+
+    // convert from wide to multi-byte.
+    {
+        int iBlockLength = (int)(pszEnvString - pszStart);
+        DWORD dwBufferLength = WideCharToMultiByte(CP_ACP, 0, pszStart, iBlockLength, NULL, 0, NULL, NULL);
+	    char* pszBuffer = (char*)malloc(dwBufferLength + 2);
+
+        // FIX: the Ruby kernel appears to use the CP_ACP code page for
+        // in-memory conversion, but I still have not seen a definitive
+        // statement on which code page should be used.
+        ZeroMemory(pszBuffer, dwBufferLength + 2);
+        WideCharToMultiByte(CP_ACP, 0, pszStart, iBlockLength, pszBuffer, dwBufferLength + 2, NULL, NULL);
+        vResult = rb_str_new(pszBuffer, dwBufferLength + 1);
+        free(pszBuffer);
+        pszBuffer = NULL;
+    }
+
+    return vResult;
+}
+
+// Summary:
+//  scans the given nul-terminated block of nul-terminated Multi-Byte strings
+//  to determine the correct length of the converted block. the converted block
+//  is then used to create a Ruby string value containing multiple nul-
+//  terminated strings. in Ruby, the block must be scanned again using
+//  index(0.chr, ...) logic.
+//
+// Returns:
+//  a Ruby string representing the environment block
+static VALUE win32_multibyte_environment_block_to_ruby(const void* pvEnvironmentBlock)
+{
+    const char* pszStart = (const char*)pvEnvironmentBlock;
+    const char* pszEnvString = pszStart;
+
+    while (*pszEnvString != 0)
+    {
+        const int iEnvStringLength = strlen(pszEnvString);
+
+        pszEnvString += iEnvStringLength + 1;
+    }
+
+    // convert from wide to multi-byte.
+    {
+        int iBlockLength = (int)(pszEnvString - pszStart);
+
+        return rb_str_new(pszStart, iBlockLength + 1);
+    }
+}
+
+// Summary:
+//  gets the environment strings from the registry for the current thread/process user.
+//
+// Returns:
+//  nul-terminated block of nul-terminated environment strings as a Ruby string value.
+static VALUE right_popen_get_current_user_environment(VALUE vSelf)
+{
+    typedef BOOL (STDMETHODCALLTYPE FAR * LPFN_CREATEENVIRONMENTBLOCK)(LPVOID* lpEnvironment, HANDLE hToken, BOOL bInherit);
+    typedef BOOL (STDMETHODCALLTYPE FAR * LPFN_DESTROYENVIRONMENTBLOCK)(LPVOID lpEnvironment);
+
+    HANDLE hToken = NULL;
+
+    // dynamically load "userenv.dll" once (because the MSVC 6.0 compiler
+    // doesn't have the .h or .lib for it).
+    if (NULL == hUserEnvLib)
+    {
+        // note we will intentionally leave library loaded for efficiency
+        // reasons even though it is proper to call FreeLibrary().
+        hUserEnvLib = LoadLibrary("userenv.dll");
+        if (NULL == hUserEnvLib)
+        {
+            rb_raise(rb_eRuntimeError, "LoadLibrary() failed: %s", win32_error_description(GetLastError()));
+        }
+    }
+
+    // get the calling thread's access token.
+    if (FALSE == OpenThreadToken(GetCurrentThread(), TOKEN_QUERY, TRUE, &hToken))
+    {
+        switch (GetLastError())
+        {
+        case ERROR_NO_TOKEN:
+            // retry against process token if no thread token exists.
+            if (FALSE == OpenProcessToken(GetCurrentProcess(), TOKEN_QUERY, &hToken))
+            {
+                rb_raise(rb_eRuntimeError, "OpenProcessToken() failed: %s", win32_error_description(GetLastError()));
+            }
+            break;
+        default:
+            rb_raise(rb_eRuntimeError, "OpenThreadToken() failed: %s", win32_error_description(GetLastError()));
+        }
+    }
+
+    // get user's environment (from registry) without inheriting from the
+    // current process environment.
+    {
+        LPVOID lpEnvironment = NULL;
+        BOOL bResult = FALSE;
+        {
+            LPFN_CREATEENVIRONMENTBLOCK lpfnCreateEnvironmentBlock = (LPFN_CREATEENVIRONMENTBLOCK)GetProcAddress(hUserEnvLib, "CreateEnvironmentBlock");
+
+            if (NULL != lpfnCreateEnvironmentBlock)
+            {
+                bResult = lpfnCreateEnvironmentBlock(&lpEnvironment, hToken, FALSE);
+            }
+        }
+
+        // check result.
+        {
+            DWORD dwLastError = GetLastError();
+
+            CloseHandle(hToken);
+            hToken = NULL;
+            SetLastError(dwLastError);
+            if (FALSE == bResult || NULL == lpEnvironment)
+            {
+                rb_raise(rb_eRuntimeError, "OpenThreadToken() failed: %s", win32_error_description(GetLastError()));
+            }
+        }
+
+        // merge environment.
+        //
+        // note that there is only a unicode form of this API call (instead of
+        // the usual _A and _W pair) and that the environment strings appear to
+        // always be Unicode (which the docs only hint at indirectly).
+        {
+            VALUE value = win32_unicode_environment_block_to_ruby(lpEnvironment);
+            LPFN_DESTROYENVIRONMENTBLOCK lpfnDestroyEnvironmentBlock = (LPFN_DESTROYENVIRONMENTBLOCK)GetProcAddress(hUserEnvLib, "DestroyEnvironmentBlock");
+
+            if (NULL != lpfnDestroyEnvironmentBlock)
+            {
+                lpfnDestroyEnvironmentBlock(lpEnvironment);
+                lpEnvironment = NULL;
+            }
+            CloseHandle(hToken);
+            hToken = NULL;
+
+            return value;
+        }
+    }
+}
+
+// Summary:
+//  gets the environment strings for the current process.
+//
+// Returns:
+//  nul-terminated block of nul-terminated environment strings as a Ruby string value.
+static VALUE right_popen_get_process_environment(VALUE vSelf)
+{
+    char* lpEnvironment = GetEnvironmentStringsA();
+
+    if (NULL == lpEnvironment)
+    {
+        rb_raise(rb_eRuntimeError, "GetEnvironmentStringsA() failed: %s", win32_error_description(GetLastError()));
+    }
+
+    // create a Ruby string from block.
+    {
+        VALUE value = win32_multibyte_environment_block_to_ruby(lpEnvironment);
+
+        FreeEnvironmentStrings(lpEnvironment);
+        lpEnvironment = NULL;
+
+        return value;
+    }
+}
+
 // Summary:
 //  'RightPopen' module entry point
 void Init_right_popen()
@@ -993,4 +1199,6 @@ void Init_right_popen()
 
     rb_define_module_function(vModule, "popen4", (VALUE(*)(ANYARGS))right_popen_popen4, -1);
     rb_define_module_function(vModule, "async_read", (VALUE(*)(ANYARGS))right_popen_async_read, 1);
+    rb_define_module_function(vModule, "get_current_user_environment", (VALUE(*)(ANYARGS))right_popen_get_current_user_environment, 0);
+    rb_define_module_function(vModule, "get_process_environment", (VALUE(*)(ANYARGS))right_popen_get_process_environment, 0);
 }

data/ext/win32/right_popen.h

@@ -1,24 +1,24 @@
-///////////////////////////////////////////////////////////////////////////////
-// Copyright (c) 2010 RightScale Inc
-//
-// 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.
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (c) 2010 RightScale Inc
+//
+// 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.
 ///////////////////////////////////////////////////////////////////////////////
 
 #include "ruby.h"

data/lib/right_popen.rb

@@ -1,4 +1,4 @@
-#
+#--
 # Copyright (c) 2009 RightScale Inc
 #
 # Permission is hereby granted, free of charge, to any person obtaining
@@ -19,7 +19,7 @@
 # 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.
-#
+#++
 
 # RightScale.popen3 allows running external processes aynchronously
 # while still capturing their standard and error outputs.
@@ -30,3 +30,36 @@ if RUBY_PLATFORM =~ /mswin/
 else
   require File.expand_path(File.join(File.dirname(__FILE__), 'linux', 'right_popen'))
 end
+
+module RightScale
+
+  # Spawn process to run given command asynchronously, hooking all three
+  # standard streams of the child process.
+  #
+  # Streams the command's stdout and stderr to the given handlers. Time-
+  # ordering of bytes sent to stdout and stderr is not preserved.
+  #
+  # Calls given exit handler upon command process termination, passing in the
+  # resulting Process::Status.
+  #
+  # All handlers must be methods exposed by the given target.
+  #
+  # === Parameters
+  # options[:command](String):: Command to execute, including any arguments
+  # options[:environment](Hash):: Hash of environment variables values keyed by name
+  # options[:target](Object):: object defining handler methods to be called, optional (no handlers can be defined if not specified)
+  # options[:stdout_handler](String):: Stdout handler method name, optional
+  # options[:stderr_handler](String):: Stderr handler method name, optional
+  # options[:exit_handler](String):: Exit handler method name, optional
+  #
+  # === Returns
+  # true:: Always returns true
+  def self.popen3(options)
+    raise "EventMachine reactor must be started" unless EM.reactor_running?
+    raise "Missing command" unless options[:command]
+    raise "Missing target" unless options[:target] || !options[:stdout_handler] && !options[:stderr_handler] && !options[:exit_handler]
+    RightScale.popen3_imp(options)
+    true
+  end
+
+end

data/lib/win32/right_popen.rb

@@ -1,4 +1,4 @@
-#
+#--
 # Copyright (c) 2009 RightScale Inc
 #
 # Permission is hereby granted, free of charge, to any person obtaining
@@ -19,17 +19,13 @@
 # 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.
-#
-
-# RightScale.popen3 allows running external processes aynchronously
-# while still capturing their standard and error outputs.
-# It relies on EventMachine for most of its internal mechanisms.
+#++
 
 require 'rubygems'
 begin
   gem 'eventmachine', '=0.12.8.1'  # patched version for Windows-only socket close fix
 rescue Gem::LoadError
-  gem 'eventmachine', '=0.12.8'  # notify_readable is deprecated in 0.12.10
+  gem 'eventmachine', '=0.12.8'  # notify_readable is deprecated, so currently cannot use >=0.12.10 in Windows gem
 end
 require 'eventmachine'
 require 'win32/process'
@@ -81,15 +77,10 @@ module RightScale
 
     # === Parameters
     # target(Object):: Object defining handler methods to be called.
-    #
     # stdout_handler(String):: Token for stdout handler method name.
-    #
     # exit_handler(String):: Token for exit handler method name.
-    #
     # stderr_eventable(Connector):: EM object representing stderr handler.
-    #
     # stream_out(IO):: Standard output stream.
-    #
     # pid(Integer):: Child process ID.
     def initialize(target, stdout_handler, exit_handler, stderr_eventable, stream_out, pid)
       @target = target
@@ -186,34 +177,20 @@ module RightScale
   # Creates a child process and connects event handlers to the standard output
   # and error streams used by the created process. Connectors use named pipes
   # and asynchronous I/O in the native Windows implementation.
-  # 
-  # Streams the command's stdout and stderr to the given handlers. Time-
-  # ordering of bytes sent to stdout and stderr is not preserved.
-  #
-  # Calls given exit handler upon command process termination, passing in the
-  # resulting Process::Status.
-  #
-  # All handlers must be methods exposed by the given target.
   #
-  # === Parameters
-  # cmd(String): command to execute, including any arguments.
-  #
-  # target(Object): object defining handler methods to be called.
-  #
-  # stdout_handler(String): token for stdout handler method name.
-  #
-  # stderr_handler(String): token for stderr handler method name.
-  #
-  # exit_handler(String): token for exit handler method name.
-  def self.popen3(cmd, target, stdout_handler = nil, stderr_handler = nil, exit_handler = nil)
+  # See RightScale.popen3
+  def self.popen3_imp(options)
     raise "EventMachine reactor must be started" unless EM.reactor_running?
 
-    # launch cmd and request asynchronous output (which is only provided by
-    # the RightScale version of win32/open3 gem).
+    # merge and format environment strings, if necessary.
+    environment_hash = options[:environment] || {}
+    environment_strings = RightPopenEx.merge_environment(environment_hash)
+
+    # launch cmd and request asynchronous output.
     mode = "t"
     show_window = false
     asynchronous_output = true
-    stream_in, stream_out, stream_err, pid = RightPopen.popen4(cmd, mode, show_window, asynchronous_output)
+    stream_in, stream_out, stream_err, pid = RightPopen.popen4(options[:command], mode, show_window, asynchronous_output, environment_strings)
 
     # close input immediately.
     stream_in.close
@@ -221,8 +198,8 @@ module RightScale
     # attach handlers to event machine and let it monitor incoming data. the
     # streams aren't used directly by the connectors except that they are closed
     # on unbind.
-    stderr_eventable = EM.attach(stream_err, StdErrHandler, target, stderr_handler, stream_err) if stderr_handler
-    EM.attach(stream_out, StdOutHandler, target, stdout_handler, exit_handler, stderr_eventable, stream_out, pid)
+    stderr_eventable = EM.attach(stream_err, StdErrHandler, options[:target], options[:stderr_handler], stream_err) if options[:stderr_handler]
+    EM.attach(stream_out, StdOutHandler, options[:target], options[:stdout_handler], options[:exit_handler], stderr_eventable, stream_out, pid)
 
     # note that control returns to the caller, but the launched cmd continues
     # running and sends output to the handlers. the caller is not responsible
@@ -231,4 +208,222 @@ module RightScale
     # sent to the exit_handler on process termination.
   end
 
+  protected
+
+  module RightPopenEx
+    # Key class for case-insensitive hash insertion/lookup.
+    class NoCaseKey
+      # Internal key
+      attr_reader :key
+
+      # Stringizes object to be used as key
+      def initialize key
+        @key = key.to_s
+       end
+
+      # Hash code
+      def hash
+        @key.downcase.hash
+      end
+
+      # Equality for hash
+      def eql? other
+        @key.downcase.hash == other.key.downcase.hash
+      end
+
+      # Sort operator
+      def <=> other
+        @key.downcase <=> other.key.downcase
+      end
+
+      # Stringizer
+      def to_s
+        @key
+      end
+
+      # Inspector
+      def inspect
+        "\"#{@key}\""
+      end
+    end
+
+    # Hash of known environment variable keys to special merge method proc.
+    SPECIAL_MERGE_ENV_KEY_HASH = {
+      NoCaseKey.new('PATH') => lambda { |from_value, to_value| merge_environment_path_value(from_value, to_value) }
+    }
+
+    # Merges the given environment hash with the current environment for this
+    # process and the current environment for the current thread user from the
+    # registry. The result is a nul-terminated block of nul-terminated strings
+    # suitable for use in creating the child process.
+    #
+    # === Parameters
+    # environment_hash(Hash):: Hash of environment key/value pairs or empty to
+    # only merge the current process and currend thread user environment.
+    #
+    # === Returns
+    # merged string block
+    def self.merge_environment(environment_hash)
+      current_user_environment_hash = get_current_user_environment
+      result_environment_hash = get_process_environment
+
+      # user environment from registry supercedes process.
+      merge_environment2(current_user_environment_hash, result_environment_hash)
+
+      # caller's environment supercedes all.
+      merge_environment2(environment_hash, result_environment_hash)
+
+      return environment_hash_to_string_block(result_environment_hash)
+    end
+
+    # Merges from hash to another with special handling for known env vars.
+    #
+    # === Parameters
+    # from_hash(Hash):: hash of string or environment keys to environment values
+    # to_hash(Hash):: resulting hash or environment keys to environment values
+    #
+    # === Returns
+    # to_hash(Hash):: merged 'to' hash
+    def self.merge_environment2(from_hash, to_hash)
+      from_hash.each do |from_key, from_value|
+        to_key = from_key.kind_of?(NoCaseKey) ?
+                 from_key :
+                 NoCaseKey.new(from_key)
+        to_value = to_hash[to_key]
+        if to_value
+          special_merge_proc = SPECIAL_MERGE_ENV_KEY_HASH[to_key]
+          if special_merge_proc
+            # special merge
+            to_hash[to_key] = special_merge_proc.call(from_value, to_value)
+          else
+            # 'from' value supercedes existing 'to' value
+            to_hash[to_key] = from_value
+          end
+        else
+          # 'from' value replaces missing 'to' value
+          to_hash[to_key] = from_value
+        end
+      end
+    end
+
+    # Merges a PATH-style variable by appending any missing subpaths on the
+    # 'to' side to the value on the 'from' side in order of appearance. note
+    # that the ordering of paths on the 'to' side is not preserved when some of
+    # the paths also appear on the 'from' side. This is because paths on the
+    # 'from' side always take precedence. This is an issue if two paths
+    # reference similarly named executables and swapping the order of paths
+    # would cause the wrong executable to be invoked. To resolve this, the
+    # higher precedence path can be changed to ensure that the conflicting paths
+    # are both specified in the proper order. There is no trivial algorithm
+    # which can predict the proper ordering of such paths.
+    #
+    # === Parameters
+    # from_value(String):: value to merge from
+    # to_value(String):: value to merge to
+    #
+    # === Returns
+    # merged_value(String):: merged value
+    def self.merge_environment_path_value(from_value, to_value)
+      # normalize to backslashes for Windows-style PATH variable.
+      from_value = from_value.gsub(File::SEPARATOR, File::ALT_SEPARATOR)
+      to_value = to_value.gsub(File::SEPARATOR, File::ALT_SEPARATOR)
+
+      # quick outs.
+      return from_value if to_value.empty?
+      return to_value if from_value.empty?
+
+      # Windows paths are case-insensitive, so we want to match paths efficiently
+      # while being case-insensitive. we will make use of NoCaseKey again.
+      from_value_hash = {}
+      from_value.split(File::PATH_SEPARATOR).each { |path| from_value_hash[NoCaseKey.new(path)] = true }
+      appender = ""
+      to_value.split(File::PATH_SEPARATOR).each do |path|
+        if not from_value_hash[NoCaseKey.new(path)]
+          appender += File::PATH_SEPARATOR + path
+        end
+      end
+
+      return from_value + appender
+    end
+
+    # Queries the environment strings from the current thread/process user's
+    # environment (which is stored in the registry on Windows as a combination of
+    # system and user-specific environment variables). The resulting hash
+    # represents any variables set for the persisted user context but any set
+    # dynamically in the current process context.
+    #
+    # === Returns
+    # environment_hash(Hash):: hash of environment key (String) to value (String).
+    def self.get_current_user_environment
+      environment_strings = RightPopen.get_current_user_environment
+
+      return string_block_to_environment_hash(environment_strings)
+    end
+
+    # Queries the environment strings from the process environment (which is kept
+    # in memory for each process and generally begins life as a copy of the
+    # process user's environment context plus any changes made by ancestral
+    # processes).
+    #
+    # === Returns
+    # environment_hash(Hash):: hash of environment key (String) to value (String).
+    def self.get_process_environment
+      environment_strings = RightPopen.get_process_environment
+
+      return string_block_to_environment_hash(environment_strings)
+    end
+
+    # Converts a nul-terminated block of nul-terminated strings to a hash by
+    # splitting the block on nul characters until the empty string is found.
+    # splits substrings on the '=' character which is used to delimit key from
+    # value in Windows environment blocks.
+    #
+    # === Paramters
+    # string_block(String):: string containing nul-terminated substrings followed
+    # by a nul-terminator.
+    #
+    # === Returns
+    # string_hash(Hash):: hash of string to string
+    def self.string_block_to_environment_hash(string_block)
+      result_hash = {}
+      last_offset = 0
+      string_block_length = string_block.length
+      while last_offset < string_block_length
+        offset = string_block.index(0.chr, last_offset)
+        if offset.nil?
+          offset = string_block.length
+        end
+        env_string = string_block[last_offset, offset - last_offset]
+        break if env_string.empty?
+        last_offset = offset + 1
+
+        # note that Windows uses "=C:=C:\" notation for working directory info, so
+        # ignore equals if it is the first character.
+        equals_offset = env_string.index('=', 1)
+        if equals_offset
+          env_key = env_string[0, equals_offset]
+          env_value = env_string[equals_offset + 1..-1]
+          result_hash[NoCaseKey.new(env_key)] = env_value
+        end
+      end
+
+      return result_hash
+    end
+
+    # Converts a hash of string to string to a string block by combining pairs
+    # into a single string delimited by the '=' character and then placing nul-
+    # terminators after each pair, followed by a final nul-terminator.
+    #
+    # === Parameters
+    # environment_hash(Hash):: hash of
+    def self.environment_hash_to_string_block(environment_hash)
+      result_block = ""
+      environment_hash.keys.sort.each do |key|
+        result_block += "#{key}=#{environment_hash[key]}\0"
+      end
+
+      return result_block + "\0"
+    end
+
+  end
 end

data/right_popen.gemspec

@@ -1,14 +1,16 @@
 require 'rubygems'
 
-spec = Gem::Specification.new do |spec|
-  is_windows = RUBY_PLATFORM =~ /mswin/
+def is_windows?
+  return RUBY_PLATFORM =~ /mswin/
+end
 
+spec = Gem::Specification.new do |spec|
   spec.name      = 'right_popen'
-  spec.version   = '1.0.2'
+  spec.version   = '1.0.5'
   spec.authors   = ['Scott Messier', 'Raphael Simon']
   spec.email     = 'scott@rightscale.com'
   spec.homepage  = 'https://github.com/rightscale/right_popen'
-  if is_windows
+  if is_windows?
     spec.platform = 'x86-mswin32-60'
   else
     spec.platform  = Gem::Platform::RUBY
@@ -27,7 +29,7 @@ of its internal mechanisms. The Linux implementation is valid for any Linux
 platform but there is also a native implementation for Windows platforms.
 EOF
 
-  if is_windows
+  if is_windows?
     extension_dir = "ext,"
   else
     extension_dir = ""
@@ -38,7 +40,7 @@ EOF
     item.include?("Makefile") || item.include?(".obj") || item.include?(".pdb") || item.include?(".def") || item.include?(".exp") || item.include?(".lib")
   end
   candidates = candidates.delete_if do |item|
-    if is_windows
+    if is_windows?
       item.include?("/linux/")
     else
       item.include?("/win32/")
@@ -46,9 +48,13 @@ EOF
   end
   spec.files = candidates.sort!
 
-  # Current implementation doesn't support > 0.12.8, but support any patched 0.12.8.x versions.
-  spec.add_runtime_dependency(%q<eventmachine>, [">= 0.12.8", "< 0.12.9"])
-  if is_windows
+  # Current implementation supports >= 0.12.8
+  spec.add_runtime_dependency(%q<eventmachine>, [">= 0.12.8"])
+  if is_windows?
+    # Windows implementation currently depends on deprecated behavior from
+    # 0.12.8, but we also need to support the 0.12.8.1 patch version. the Linux
+    # side is free to use 0.12.10+
+    spec.add_runtime_dependency(%q<eventmachine>, ["< 0.12.9"])
     spec.add_runtime_dependency(%q<win32-process>, [">= 0.6.1"])
   end
 end

data/spec/print_env.rb

@@ -0,0 +1,2 @@
+puts "__test__=#{ENV['__test__']}" if ENV['__test__']
+puts "PATH=#{ENV['PATH']}"

data/spec/right_popen_spec.rb

@@ -1,5 +1,4 @@
 require File.join(File.dirname(__FILE__), 'spec_helper')
-require 'right_popen'
 
 RUBY_CMD         = 'ruby'
 STANDARD_MESSAGE = 'Standard message'
@@ -10,32 +9,82 @@ EXIT_STATUS      = 146
 # for a quick smoke test
 LARGE_OUTPUT_COUNTER = 1000
 
+# bump up count for most exhaustive leak detection.
+REPEAT_TEST_COUNTER = 256
+
+def is_windows?
+  return RUBY_PLATFORM =~ /mswin/
+end
+
 describe 'RightScale::popen3' do
 
   module RightPopenSpec
 
     class Runner
       def initialize
-        @done        = false
+        @done           = false
+        @output_text    = nil
+        @error_text     = nil
+        @status         = nil
+        @last_exception = nil
+        @last_iteration = 0
+      end
+
+      attr_reader :output_text, :error_text, :status
+
+      def do_right_popen(command, env=nil)
         @output_text = ''
         @error_text  = ''
         @status      = nil
+        RightScale.popen3(:command        => command, 
+                          :target         => self, 
+                          :environment    => env,
+                          :stdout_handler => :on_read_stdout, 
+                          :stderr_handler => :on_read_stderr, 
+                          :exit_handler   => :on_exit)
       end
 
-      attr_reader :output_text, :error_text, :status
-
-      def run_right_popen(command)
+      def run_right_popen(command, env=nil, count = 1)
+        puts "#{count}>" if count > 1
+        last_iteration = 0
         EM.next_tick do
-          RightScale.popen3(command, self, :on_read_stdout, :on_read_stderr, :on_exit)
+          do_right_popen(command, env)
         end
         EM.run do
-          timer = EM::PeriodicTimer.new(0.1) do
-            if @done
+          timer = EM::PeriodicTimer.new(0.05) do
+            begin
+              if @done || @last_exception
+                last_iteration = last_iteration + 1
+                if @last_exception.nil? && last_iteration < count
+                  @done = false
+                  EM.next_tick do
+                    if count > 1
+                      print '+'
+                      STDOUT.flush
+                    end
+                    do_right_popen(command, env)
+                  end
+                else
+                  puts "<" if count > 1
+                  timer.cancel
+                  EM.stop
+                end
+              end
+            rescue Exception => e
+              @last_exception = e
               timer.cancel
               EM.stop
             end
           end
         end
+        if @last_exception
+          if count > 1
+            message = "<#{last_iteration + 1}\n#{last_exception.message}"
+          else
+            message = last_exception.message
+          end
+          raise @last_exception.class, "#{message}\n#{@last_exception.backtrace.join("\n")}"
+        end
       end
 
       def on_read_stdout(data)
@@ -121,5 +170,50 @@ describe 'RightScale::popen3' do
     end
     runner.error_text.should == results
   end
+  
+  it 'should setup environment variables' do
+    command = "\"#{RUBY_CMD}\" \"#{File.expand_path(File.join(File.dirname(__FILE__), 'print_env.rb'))}\""
+    runner = RightPopenSpec::Runner.new
+    runner.run_right_popen(command)
+    runner.status.exitstatus.should == 0
+    runner.output_text.should_not include('_test_')
+    runner.run_right_popen(command, :__test__ => '42')
+    runner.status.exitstatus.should == 0
+    runner.output_text.should match(/^__test__=42$/)
+  end
+
+  it 'should restore environment variables' do
+    ENV['__test__'] = '41'
+    old_envs = {}
+    ENV.each { |k, v| old_envs[k] = v }
+    command = "\"#{RUBY_CMD}\" \"#{File.expand_path(File.join(File.dirname(__FILE__), 'print_env.rb'))}\""
+    runner = RightPopenSpec::Runner.new
+    runner.run_right_popen(command, :__test__ => '42')
+    runner.status.exitstatus.should == 0
+    runner.output_text.should match(/^__test__=42$/)
+    ENV.each { |k, v| old_envs[k].should == v }
+    old_envs.each { |k, v| ENV[k].should == v }
+  end
+
+  if is_windows?
+    # FIX: this behavior is currently specific to Windows but should probably be
+    # implemented for Linux.
+    it 'should merge the PATH variable instead of overriding it' do
+      command = "\"#{RUBY_CMD}\" \"#{File.expand_path(File.join(File.dirname(__FILE__), 'print_env.rb'))}\""
+      runner = RightPopenSpec::Runner.new
+      runner.run_right_popen(command, 'PATH' => "c:/bogus\\bin")
+      runner.status.exitstatus.should == 0
+      runner.output_text.should include('PATH=c:\\bogus\\bin;')
+    end
+  end
+
+  it 'should run repeatedly without leaking resources' do
+    command = "\"#{RUBY_CMD}\" \"#{File.expand_path(File.join(File.dirname(__FILE__), 'produce_output.rb'))}\" \"#{STANDARD_MESSAGE}\" \"#{ERROR_MESSAGE}\""
+    runner = RightPopenSpec::Runner.new
+    runner.run_right_popen(command, nil, REPEAT_TEST_COUNTER)
+    runner.status.exitstatus.should == 0
+    runner.output_text.should == STANDARD_MESSAGE + "\n"
+    runner.error_text.should == ERROR_MESSAGE + "\n"
+  end
 
 end

data/spec/spec_helper.rb

@@ -1,2 +1,4 @@
 require 'rubygems'
-$:.push File.join(File.dirname(__FILE__), '..', 'lib')
+require 'spec'
+require 'eventmachine'
+require File.join(File.dirname(__FILE__), '..', 'lib', 'right_popen')

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: right_popen
 version: !ruby/object:Gem::Version 
-  version: 1.0.2
+  version: 1.0.5
 platform: x86-mswin32-60
 authors: 
 - Scott Messier
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-02-18 00:00:00 -08:00
+date: 2010-02-23 00:00:00 -08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -22,6 +22,13 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version 
         version: 0.12.8
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: eventmachine
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
     - - <
       - !ruby/object:Gem::Version 
         version: 0.12.9
@@ -58,6 +65,7 @@ files:
 - lib/win32/right_popen.rb
 - lib/win32/right_popen.so
 - right_popen.gemspec
+- spec/print_env.rb
 - spec/produce_mixed_output.rb
 - spec/produce_output.rb
 - spec/produce_status.rb