Updated mcollective.init according to OSCI-658

[packages/precise/mcollective.git] / lib / mcollective / vendor / systemu / README

diff --git a/lib/mcollective/vendor/systemu/README b/lib/mcollective/vendor/systemu/README
new file mode 100644 (file)
index 0000000..978f24f
--- /dev/null
+++ b/lib/mcollective/vendor/systemu/README
@@ -0,0 +1,170 @@
+NAME
+
+  systemu
+
+SYNOPSIS
+
+  universal capture of stdout and stderr and handling of child process pid for
+  windows, *nix, etc.
+
+URIS
+
+  http://github.com/ahoward/systemu
+  http://rubyforge.org/projects/codeforpeople/
+
+INSTALL
+
+  gem install systemu
+
+HISTORY
+  2.0.0
+    - versioning issue.  new gem release.
+
+  1.3.1
+    - updates for ruby 1.9.1
+
+  1.3.0
+    - move to github
+
+  1.2.0
+
+    - fixed handling of background thread management - needed
+      Thread.current.abort_on_exception = true
+
+    - fixed reporting of child pid, it was reported as the parent's pid before
+
+SAMPLES
+
+
+  <========< samples/a.rb >========>
+
+  ~ > cat samples/a.rb
+
+    #
+    # systemu can be used on any platform to return status, stdout, and stderr of
+    # any command.  unlike other methods like open3/popen4 there is zero danger of
+    # full pipes or threading issues hanging your process or subprocess.
+    #
+      require 'systemu'
+    
+      date = %q( ruby -e"  t = Time.now; STDOUT.puts t; STDERR.puts t  " )
+    
+      status, stdout, stderr = systemu date
+      p [ status, stdout, stderr ]
+
+  ~ > ruby samples/a.rb
+
+    [#<Process::Status: pid 50931 exit 0>, "2011-12-11 22:07:30 -0700\n", "2011-12-11 22:07:30 -0700\n"]
+
+
+  <========< samples/b.rb >========>
+
+  ~ > cat samples/b.rb
+
+    #
+    # quite a few keys can be passed to the command to alter it's behaviour.  if
+    # either stdout or stderr is supplied those objects should respond_to? '<<'
+    # and only status will be returned
+    #
+      require 'systemu'
+    
+      date = %q( ruby -e"  t = Time.now; STDOUT.puts t; STDERR.puts t  " )
+    
+      stdout, stderr = '', ''
+      status = systemu date, 'stdout' => stdout, 'stderr' => stderr
+      p [ status, stdout, stderr ]
+
+  ~ > ruby samples/b.rb
+
+    [#<Process::Status: pid 50936 exit 0>, "2011-12-11 22:07:30 -0700\n", "2011-12-11 22:07:30 -0700\n"]
+
+
+  <========< samples/c.rb >========>
+
+  ~ > cat samples/c.rb
+
+    #
+    # of course stdin can be supplied too.  synonyms for 'stdin' include '0' and
+    # 0.  the other stdio streams have similar shortcuts
+    #
+      require 'systemu'
+    
+      cat = %q( ruby -e"  ARGF.each{|line| puts line}  " )
+    
+      status = systemu cat, 0=>'the stdin for cat', 1=>stdout=''
+      puts stdout
+
+  ~ > ruby samples/c.rb
+
+    the stdin for cat
+
+
+  <========< samples/d.rb >========>
+
+  ~ > cat samples/d.rb
+
+    #
+    # the cwd can be supplied
+    #
+      require 'systemu'
+      require 'tmpdir'
+    
+      pwd = %q( ruby -e"  STDERR.puts Dir.pwd  " )
+    
+      status = systemu pwd, 2=>(stderr=''), :cwd=>Dir.tmpdir
+      puts stderr
+    
+
+  ~ > ruby samples/d.rb
+
+    /private/var/folders/sp/nwtflj890qnb6z4b53dqxvlw0000gp/T
+
+
+  <========< samples/e.rb >========>
+
+  ~ > cat samples/e.rb
+
+    #
+    # any environment vars specified are merged into the child's environment
+    #
+      require 'systemu'
+    
+      env = %q( ruby -r yaml -e"  puts ENV[ 'answer' ] " )
+    
+      status = systemu env, 1=>stdout='', 'env'=>{ 'answer' => 0b101010 }
+      puts stdout
+
+  ~ > ruby samples/e.rb
+
+    42
+
+
+  <========< samples/f.rb >========>
+
+  ~ > cat samples/f.rb
+
+    #
+    # if a block is specified then it is passed the child pid and run in a
+    # background thread.  note that this thread will __not__ be blocked during the
+    # execution of the command so it may do useful work such as killing the child
+    # if execution time passes a certain threshold
+    #
+      require 'systemu'
+    
+      looper = %q( ruby -e" loop{ STDERR.puts Time.now.to_i; sleep 1 } " )
+    
+      status, stdout, stderr =
+        systemu looper do |cid|
+          sleep 3
+          Process.kill 9, cid
+        end
+    
+      p status
+      p stderr
+
+  ~ > ruby samples/f.rb
+
+    #<Process::Status: pid 50956 SIGKILL (signal 9)>
+    "1323666451\n1323666452\n1323666453\n"
+
+