dia 1.5.pre → 1.5.pre.2

data/NEWS.md

@@ -1,25 +1,36 @@
 ## NEWS
 
 ### 1.5
-* Dia::Sandbox#running?, Dia::Sandbox#exit_status, and Dia::Sandbox#terminate will return nil if you call them before
-  calling Dia::Sandbox#run().
-* Added Dia::Sandbox#exit_status for collecting the exit status of a child process running under a sandbox.
-* Dia::Sandbox#run was not returning the PID of the process running under a sandbox like told in the documentation - it is now.
+* Added Dia::Sandbox#exception() for inspecting an exception raised in a sandbox
+  from the parent process.
+* Fixed a small bug introduced in 1.5.pre - a typo, only encountered if
+  Dia::SandboxException was raised.
+* Dia::Sandbox#running?, Dia::Sandbox#exit_status, and Dia::Sandbox#terminate 
+  will return nil if you call them before calling Dia::Sandbox#run().
+* Added Dia::Sandbox#exit_status for collecting the exit status of a child 
+  process running under a sandbox.
+* Dia::Sandbox#run was not returning the PID of the process running under a 
+  sandbox like told in the documentation - it is now.
 
 ### 1.4
-* A typo broke support for launching applications in a sandbox. (Bug affects 1.3 and all the 1.4 *pre* releases)
+* A typo broke support for launching applications in a sandbox. 
+ (Bug affects 1.3 and all the 1.4 *pre* releases)
 * Mac OSX 10.5 reported as working! (Bug fix)  
   Many thanks to Josh Creek for reporting and helping me debug this bug.
 * Use ffi\_lib() to explicitly load the dynamic library "sandbox", or "System"
 * Depend explicitly on FFI v0.6.2
-* Dia::Sandbox#run accepts a variable amount of arguments that will be passed onto the block supplied to the constructer.
+* Dia::Sandbox#run accepts a variable amount of arguments that will be passed 
+  onto the block supplied to the constructer.
 * Added "test/\*\*/*.rb" to the gem specification as test files..
 
 ### 1.3
-* Added Dia::Sandbox#running? to check if a process running a sandbox is alive or not.
-* Dia::Sandbox only exposes its instance variables through getters now. No more setters.
+* Added Dia::Sandbox#running? to check if a process running a sandbox is alive 
+  or not.
+* Dia::Sandbox only exposes its instance variables through getters now. 
+  No more setters.
 * Dia::Sandbox#app_path is now Dia::Sandbox#app
-* Removed run\_with\_block in favor of passing a block to the constructer. Dia::Sandbox#run is used to execute a block or an application now, 
+* Removed run\_with\_block in favor of passing a block to the constructer. 
+  Dia::Sandbox#run is used to execute a block or an application now, 
   but only one or the other may be supplied to the constructer.
 * Removed Dia::SandBox in favor of Dia::Sandbox.
 * Added "has_rdoc = 'yard'" to the gem spec.
@@ -27,19 +38,25 @@
 * SandBoxException becomes SandboxException.
 
 ### 1.2
-* I've decided to use Dia::Sandbox instead of Dia::SandBox but it won't be removed until 1.3 .. (Deprecated for 1.2)
-* I've decided to remove the explicit exit() call in a sandbox spawned with run\_with\_block .. (Introduced in 1.1 Final)
+* I've decided to use Dia::Sandbox instead of Dia::SandBox but it won't 
+  be removed until 1.3 .. (Deprecated for 1.2)
+* I've decided to remove the explicit exit() call in a sandbox spawned with 
+  run\_with\_block .. (Introduced in 1.1 Final)
 * Added Dia::Sandbox#terminate for terminating a sandbox.
-* Process.detach(*sandbox pid*) is used in the parent process that spawns a sandbox to avoid collecting zombies ..
+* Process.detach(*sandbox pid*) is used in the parent process that spawns a 
+  sandbox to avoid collecting zombies ..
 
 ### 1.1 (final)
-* Dia::SandBox#run\_with\_block will exit the child process spawned by itself incase the user forgets to ..
+* Dia::SandBox#run\_with\_block will exit the child process spawned by itself 
+  incase the user forgets to ..
 * Added some tests for Dia::Sandbox.new#run\_with\_block ..  
   We ain't got full coverage but we're getting there.
 * A person reported that ffi 0.6.0 does not work with dia ..  
   Supplied an explicit dependency on ffi 0.5.4 until I figure it out.
-* You can run a block of ruby under a sandbox now but I had to change the order of arguments in the constructer ..  
-  First argument is the profile, and (optionally) the second is the application path.  
+* You can run a block of ruby under a sandbox now but I had to change the order 
+  of arguments in the constructer ..  
+  First argument is the profile, and (optionally) the second is the application 
+  path.  
   If you're running a block of ruby, you can forget about the second.
 * I documented my methods!
 

data/README.md

@@ -86,6 +86,41 @@ If you need to check if a sandbox you have spawned is still running, you can use
     puts sandbox.running? # => true
 
 
+**Collecting the exit status of a sandbox**  
+
+The sandbox environment is run in a child process, and you can collect its 
+exit status through the #exit_status() method. This method is only available
+from 0.5.pre onwards.
+
+    require 'rubygems'
+    require 'dia'
+    sandbox = Dia::Sandbox.new(Dia::Profiles::NO_OS_SERVICES) do
+      exit(10)
+    end
+
+    sandbox.run()
+    sandbox.exit_status() # => 10
+
+**Accessing an exception raised in a sandbox**
+
+Since 1.5, an exception raised in a sandbox can be accessed from the parent
+process. This only works as long as you don't try to capture the exception
+raised in a block by yourself or if you do, you re-raise the exception after 
+capturing it so Dia can forward the exception to the parent process.
+
+    require 'rubygems'
+    require 'dia'
+    sandbox = Dia::Sandbox.new(Dia::Profiles::NO_OS_SERVICES) do
+      raise()
+    end
+
+    sandbox.run()
+    sleep(0.1) # Let the parent receive the exception.
+               # Only neccesary for scenarios where an exception is raised
+               # rather quickly.
+
+    puts sandbox.exception().class # prints "RuntimeError"
+
 .. Please see the yardoc [documentation](http://yardoc.org/docs/robgleeson-Dia) for more in-depth coverage of these methods, 
 in particular the documentation for the `Dia::Sandbox` class.
 

data/lib/dia.rb

@@ -5,7 +5,7 @@ require File.join(File.dirname(__FILE__), 'dia/commonapi.rb')
 require File.join(File.dirname(__FILE__), 'dia/sandbox.rb')
 
 module Dia
-  VERSION = '1.5.pre'
+  VERSION = '1.5.pre.2'
   class SandboxException < StandardError; end
 end
 

data/lib/dia/sandbox.rb

@@ -2,13 +2,15 @@ module Dia
   
   class Sandbox
   
+    require('io/wait')
+
     include Dia::CommonAPI
     
     attr_reader :app
     attr_reader :profile
     attr_reader :pid
     attr_reader :blk
-    
+
     # The constructer accepts a profile as the first parameter, and an 
     # application path _or_ block as its second parameter.  
     #
@@ -48,8 +50,35 @@ module Dia
       @blk      = blk
       @profile  = profile
       @pid      = nil
+      initialize_streams()
     end
-    
+
+    # The exception() method returns an instance or subclass instance of 
+    # Exception which has been raised in a sandbox. 
+    #
+    # This method can be used if you need access(from the parent process)
+    # to an exception raised in your sandbox.
+    #
+    # If the sandbox raises an exception rather quickly, you might need to
+    # sleep(X) (0.3-0.5s on my machine) before the parent process 
+    # recieves the exception.
+    # 
+    # @return [Exception, nil]  Returns an instance or subclass instance of 
+    #                           Exception when successful, and nil when 
+    #                           there is no exception available.
+    # @since 1.5
+    def exception()
+      @write.close()
+      if @read.ready?()
+        ret = Marshal.load(@read.gets())
+      else
+        ret = nil
+      end
+      @read.close()
+      initialize_streams()
+      ret
+    end
+
     # The run method will spawn a child process and run the application _or_
     # block supplied to the constructer under a sandbox.  
     # This method will not block.
@@ -73,22 +102,33 @@ module Dia
     # @return [Fixnum]                The Process ID(PID) that the sandboxed 
     #                                 application is being run under.
     def run(*args)
+      initialize_streams()      
       @pid = fork do
-        if sandbox_init(FFI::MemoryPointer.from_string(@profile), 
-                        0x0001, 
-                        err = FFI::MemoryPointer.new(:pointer)) == -1
+        begin
+          if sandbox_init(FFI::MemoryPointer.from_string(@profile), 
+                          0x0001, 
+                          err = FFI::MemoryPointer.new(:pointer)) == -1
 
-          raise(Dia::SandboxException, "Failed to initialize sandbox" /
-                                       "(#{err.read_pointer.read_string})")
-        end
-        
-        if @app
-          exec(@app)
-        else
-          @blk.call(*args)
+            raise(Dia::SandboxException, "Failed to initialize sandbox" \
+                                         "(#{err.read_pointer.read_string})")
+          end
+          
+          if @app
+            exec(@app)
+          else
+            @blk.call(*args)
+          end
+
+        rescue SystemExit, Interrupt => e 
+          raise(e)
+        rescue Exception => e        
+          @write.write(Marshal.dump(e))
+        ensure
+          @write.close()
+          @read.close()
         end
       end
-      
+
       # parent ..
       @thr = Process.detach(@pid)
       @pid
@@ -102,7 +142,8 @@ module Dia
     #                       under a sandbox.
     #                       Returns nil if Dia::Sandbox#run has not 
     #                       been called yet, or if the process stopped
-    #                       abnormally(ie: through SIGKILL, or #terminate). 
+    #                       abnormally(ie: through SIGKILL, or #terminate).
+    # @since 1.5
     def exit_status()
       @thr.value().exitstatus() unless @thr.nil?
     end
@@ -143,7 +184,13 @@ module Dia
         end
       end
     end
+   
+    private
     
+    def initialize_streams()
+      @read, @write = IO.pipe()
+    end
+ 
   end
   
 end

data/test/suite/exceptions_text.rb

@@ -0,0 +1,41 @@
+BareTest.suite('Exceptions', :tags => [ :exception ]) do
+  assert('Dia::SandboxException is raised if a call to sandbox_init() fails') do
+    sandbox = Dia::Sandbox.new(Dia::Profiles::NO_OS_SERVICES) do 
+      # ...
+    end
+    sandbox.instance_variable_set("@profile", "i am going to break")
+    sandbox.run
+    sleep(0.1)
+    equal(Dia::SandboxException, sandbox.exception().class)
+  end
+
+  assert('Dia::Sandbox#exception() will return an exception raised in the sandbox') do
+    sandbox = Dia::Sandbox.new(Dia::Profiles::NO_OS_SERVICES) do
+      raise()
+    end
+  
+    sandbox.run()
+    sleep(0.1)
+    equal(RuntimeError, sandbox.exception.class())
+  end
+
+  assert('Dia::Sandbox#exception() returns nil if called before ' \
+         'Dia::Sandbox#run()') do
+    sandbox = Dia::Sandbox.new(Dia::Profiles::NO_OS_SERVICES) do
+                # ...
+              end
+    equal(nil, sandbox.exception())
+  end
+
+  assert('Dia::Sandbox#exception() returns nil after a second call') do
+    sandbox = Dia::Sandbox.new(Dia::Profiles::NO_OS_SERVICES) do 
+      raise()
+    end
+  
+    sandbox.run()
+    sleep(0.1)
+    equal(RuntimeError, sandbox.exception().class)
+    equal(nil, sandbox.exception())
+  end
+
+end

metadata

@@ -6,7 +6,8 @@ version: !ruby/object:Gem::Version
   - 1
   - 5
   - pre
-  version: 1.5.pre
+  - 2
+  version: 1.5.pre.2
 platform: ruby
 authors: 
 - Robert Gleeson
@@ -14,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-05-03 00:00:00 +01:00
+date: 2010-05-07 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -83,7 +84,7 @@ has_rdoc: yard
 homepage: 
 licenses: []
 
-post_install_message: "  ********************************************************************\n  Dia (1.5.pre)\n  \n  Thanks for installing Dia, 1.5.pre! \n  \n  Keep up with the latest @ GitHub:\n  http://github.com/robgleeson/dia\n  ********************************************************************\n"
+post_install_message: "  ********************************************************************\n  Dia (1.5.pre.2)\n  \n  Thanks for installing Dia, 1.5.pre.2! \n  \n  Keep up with the latest @ GitHub:\n  http://github.com/robgleeson/dia\n  ********************************************************************\n"
 rdoc_options: []
 
 require_paths: 
@@ -114,6 +115,7 @@ summary: Dia allows you to sandbox application(s) or block(s) of rubyon the OSX
 test_files: 
 - test/setup.rb
 - test/suite/check_if_sandbox_is_alive_test.rb
+- test/suite/exceptions_text.rb
 - test/suite/exit_status_test.rb
 - test/suite/passing_parameters_to_constructer_test.rb
 - test/suite/run_block_in_sandbox_test.rb