File: README

package info (click to toggle)
ruby-open4 1.3.4-1
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, buster, jessie, jessie-kfreebsd, sid, stretch
  • size: 188 kB
  • ctags: 69
  • sloc: ruby: 816; makefile: 2
file content (403 lines) | stat: -rw-r--r-- 11,331 bytes parent folder | download | duplicates (4)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
URIS

  http://rubyforge.org/projects/codeforpeople/
  http://www.codeforpeople.com/lib/ruby/

SYNOPSIS

  open child process with handles on pid, stdin, stdout, and stderr: manage
  child processes and their io handles easily.

INSTALL

  ~> gem install open4

SAMPLES

  ----------------------------------------------------------------------------
  simple usage
  ----------------------------------------------------------------------------

    harp: > cat sample/simple.rb
    require "open4"

    pid, stdin, stdout, stderr = Open4::popen4 "sh"

    stdin.puts "echo 42.out"
    stdin.puts "echo 42.err 1>&2"
    stdin.close

    ignored, status = Process::waitpid2 pid

    puts "pid        : #{ pid }"
    puts "stdout     : #{ stdout.read.strip }"
    puts "stderr     : #{ stderr.read.strip }"
    puts "status     : #{ status.inspect }"
    puts "exitstatus : #{ status.exitstatus }"


    harp: > ruby sample/simple.rb
    pid        : 17273
    stdout     : 42.out
    stderr     : 42.err
    status     : #<Process::Status: pid=17273,exited(0)>
    exitstatus : 0


  ----------------------------------------------------------------------------
  in block form - the child process is automatically waited for
  ----------------------------------------------------------------------------

    harp: > cat sample/block.rb
    require 'open4'

    status =
      Open4::popen4("sh") do |pid, stdin, stdout, stderr|
        stdin.puts "echo 42.out"
        stdin.puts "echo 42.err 1>&2"
        stdin.close

        puts "pid        : #{ pid }"
        puts "stdout     : #{ stdout.read.strip }"
        puts "stderr     : #{ stderr.read.strip }"
      end

        puts "status     : #{ status.inspect }"
        puts "exitstatus : #{ status.exitstatus }"


    harp: > ruby sample/block.rb
    pid        : 17295
    stdout     : 42.out
    stderr     : 42.err
    status     : #<Process::Status: pid=17295,exited(0)>
    exitstatus : 0

  ----------------------------------------------------------------------------
  exceptions are marshaled from child to parent if fork/exec fails
  ----------------------------------------------------------------------------

    harp: > cat sample/exception.rb
    require "open4"
    Open4::popen4 "noexist"


    harp: > ruby sample/exception.rb
    /dmsp/reference/ruby-1.8.1//lib/ruby/site_ruby/open4.rb:100:in `popen4': No such file or directory - noexist (Errno::ENOENT)
            from sample/exception.rb:3

  ----------------------------------------------------------------------------
  the spawn method provides and even more convenient method of running a
  process, allowing any object that supports 'each', 'read', or 'to_s' to be
  given as stdin and any objects that support '<<' to be given as
  stdout/stderr.  an exception is thrown if the exec'd cmd fails (nonzero
  exitstatus) unless the option 'raise'=>false is given
  ----------------------------------------------------------------------------
  
    harp: > cat sample/spawn.rb
    require 'open4'
    include Open4

    cat = '  ruby -e"  ARGF.each{|line| STDOUT << line}  "  '

    stdout, stderr = '', ''
    status = spawn cat, 'stdin' => '42', 'stdout' => stdout, 'stderr' => stderr
    p status
    p stdout
    p stderr

    stdout, stderr = '', ''
    status = spawn cat, 0=>'42', 1=>stdout, 2=>stderr
    p status
    p stdout
    p stderr


    harp: > RUBYLIB=lib ruby sample/spawn.rb
    0
    "42"
    ""
    0
    "42"
    ""


  ----------------------------------------------------------------------------
  the bg/background method is similar to spawn, but the process is
  automatically set running in a thread.  the returned thread has several
  methods added dynamically which return the pid and blocking calls to the
  exitstatus.
  ----------------------------------------------------------------------------

    harp: > cat sample/bg.rb
    require 'yaml'
    require 'open4'
    include Open4

    stdin = '42'
    stdout = ''
    stderr = ''

    t = bg 'ruby -e"sleep 4; puts ARGF.read"', 0=>stdin, 1=>stdout, 2=>stderr

    waiter = Thread.new{ y t.pid => t.exitstatus } # t.exitstatus is a blocking call!

    while((status = t.status))
      y "status" => status
      sleep 1
    end

    waiter.join

    y "stdout" => stdout


    harp: > ruby sample/bg.rb
    ---
    status: run
    ---
    status: sleep
    ---
    status: sleep
    ---
    status: sleep
    ---
    21357: 0
    ---
    stdout: "42\n"

  ----------------------------------------------------------------------------
  the timeout methods can be used to ensure execution is preceding at the
  desired interval.  note also how to setup a 'pipeline'
  ----------------------------------------------------------------------------

    harp: > cat sample/stdin_timeout.rb
    require 'open4'

    producer = 'ruby -e" STDOUT.sync = true; loop{sleep(rand+rand) and puts 42} "'

    consumer = 'ruby -e" STDOUT.sync = true; STDIN.each{|line| puts line} "'

    open4(producer) do |pid, i, o, e|

      open4.spawn consumer, :stdin=>o, :stdout=>STDOUT, :stdin_timeout => 1.4

    end


    harp: > ruby sample/stdin_timeout.rb
    42
    42
    42
    42
    42
    /dmsp/reference/ruby-1.8.1//lib/ruby/1.8/timeout.rb:42:in `relay': execution expired (Timeout::Error)

  ----------------------------------------------------------------------------
  pfork4 is similar to popen4, but instead of executing a command, it runs
  ruby code in a child process. if the child process raises an exception, it
  propagates to the parent.
  ----------------------------------------------------------------------------

    harp: > cat sample/pfork4.rb
    require 'open4'

    echo = lambda do
      $stdout.write $stdin.read
      raise 'finish implementing me'
    end

    org_message = "hello, world!"
    got_message = nil
    exception   = nil

    begin
      Open4.pfork4(echo) do |cid, stdin, stdout, stderr|
        stdin.write org_message
        stdin.close
        got_message = stdout.read
      end
    rescue RuntimeError => e
      exception = e.to_s
    end

    puts "org_message: #{org_message}"
    puts "got_message: #{got_message}"
    puts "exception  : #{exception}"


    harp: > ruby sample/pfork4.rb
    org_message: hello, world!
    got_message: hello, world!
    exception  : finish implementing me

HISTORY
  1.0.0
    - added ability for spawn to take a proc (respond_to?(:call))

      cmd = ' ruby -e" 42.times{ puts 0b101010 } " '
      include Open4
      spawn cmd, :stdout => lambda{|buf| puts buf} 


  0.9.5:
    - another patch from Corey Jewett, this time dealing with ruby's handling
      of chdir and threads.  basically the 'cwd' keyword to open4 cannot work
      with multiple threads (aka background) because ruby cannot cause green
      threads to have an actuall different working dir.  the moral is that the
      :cwd/'cwd' keyword to spawn will work with 0 or 1 threads in effect.
  
  0.9.4:
    - patch to #background from Corey Jewett


  0.9.3:
    - removed some debugging output accidentally left in 0.9.2.  arggh!

  0.9.2:
    - fixed a descriptor leak.  thanks Andre Nathan.

  0.9.1:
    - fixed warning with '-w' : @cid not initialized.  thanks blaise tarr.

  0.9.0:
    - added the ability for open4.spawn to take either an array of arguments
      or multiple arguments in order to specify the argv for the command run.
      for example

        open4.spawn ['touch', 'difficult to "quote"'], :stdout=>STDOUT

      same thing

        open4.spawn 'touch', 'difficult to "quote"', :stdout=>STDOUT

      thanks to jordan breeding for this suggestion


    - added 'cwd'/:cwd keyword.  usage is pretty obivous

        open4.spawn 'pwd', 1=>STDOUT, :cwd=>'/tmp'   #=> /tmp

      this one also from jordan

  0.8.0:

    - fixed a critical bug whereby a process producing tons of stdout, but for
      which the stdout was not handled, would cause the child process to
      become blocked/hung writing to the pipe.  eg, this command would cause a
      hang

        include Open4

        spawn 'ruby -e"  puts Array.new(65536){ 42 }  "'

      whereas this one would not

        include Open4

        spawn 'ruby -e"  puts Array.new(65536){ 42 }  "', :stdout=>StringIO.new

      this version handles the former by spawning a 'null' thread which reads,
      but does not process stdout/stderr.  that way commands which generate
      tons of output will never become blocked.

  0.7.0:
    - merged functionality of exitstatus/status keywords:

        include Open4

        spawn 'ruby -e "exit 42"'                 # raises 
        spawn 'ruby -e "exit 42"', :status=>true  # ok, returns status
        spawn 'ruby -e "exit 42"', :status=>42    # raises if status != 42
        spawn 'ruby -e "exit 42"', :status=>0,42  # raises if status != 0||42

    - the 0.6.0 was broken on rubyforge... this release fixes that (somehow!?)

  0.6.0:
    - added feature for exitstatus to be list of acceptable exit statuses

        Open4.spawn 'ruby -e "exit 42"'                      # raises
        Open4.spawn 'ruby -e "exit 42"', :exitstatus=>[0,42] # ok

    - added :status switch, which will always simply return the status (no
      error thrown for failure)

        Open4.spawn 'ruby -e "exit 42"'                          # raises 
        status = Open4.spawn 'ruby -e "exit 42"', :status=>true  # ok 

      note, however, that any SpawnError does in fact contain the failed
      status so, even when they are thrown, error status can be retrieved:

        include Open4

        status =
          begin
            spawn 'ruby -e "exit 42"'
          rescue SpawnError => e
            warn{ e }
            e.status
          end

  0.5.1:
    - fixes a __critical__ but in ThreadEnsemble class that had a race
      condition that could cause thread deadlock.  sorry bout that folks.

  0.5.0:
    - on the suggestion of tim pease (thanks tim!), i added timeout features
      to open4.  the command run may have an overall timeout and individual
      timeouts set for each of the io handles.  for example

        cmd = 'command_that_produce_out_at_one_second_intervals'

        open4.spawn cmd, :stdout_timeout => 2 

      or 

        cmd = 'command_that_should_complete_in_about_one_minute'

        open4.spawn cmd, :timeout => 60

      or

        cmd = 'consumes_input_at_one_line_per_second_rate'

        input = %w( 42 forty-two 42.0 )

        open4.spawn cmd, :stdin=>input, :stdin_timeout=>1

    - added 'open4' alias so one can write

        open4.spawn  vs Open4.spawn

      or even

        open4(cmd) do |pid,i,o,e|
        end

    - added signal info to SpawnError

  0.4.0:
    - improved error handling contributed by jordan breeding.
    - introduction of background/bg method

  0.3.0 :
    - bug fix from jordan breeding.  general clean up.  added spawn method.

  0.2.0 :
    - added exception marshaled from child -> parent when exec fails.  thanks
      to jordan breeding for a patch (yay!) and paul brannan for this most
      excellent idea.

  0.1.0 :
    - fixed docs to correctly show return value of popen4 (pid first not last).
      thanks Stefanie Tellex <stefie10@alum.mit.edu> for catching this. 
  0.0.0 :
    - initial version

AUTHOR

  ara.t.howard@gmail.com

LICENSE

  ruby's