Class: Microsandbox::ExecHandle

Inherits:
Object
  • Object
show all
Includes:
Enumerable
Defined in:
lib/microsandbox/exec_handle.rb

Overview

Note:

Single-pass, forward-only, single-consumer. each/collect drain a one-shot native event channel, so the handle is not rewindable: a second each, or collect after a partial each (and vice versa), yields only what is left. Consume it once, from one thread. (An out-of-band #kill/#signal via the control channel is the exception — it can unblock a parked each from another thread.)

A live, streaming command execution, returned by Sandbox#exec_stream and Sandbox#shell_stream.

Iterate it (it is Enumerable) to consume ExecEvents as they arrive, or call #collect to drain it into an ExecOutput.

Examples:

handle = sb.exec_stream("python", ["-u", "script.py"])
handle.each do |event|
  print event.text if event.stdout? || event.stderr?
end

Instance Method Summary collapse

Constructor Details

#initialize(native) ⇒ ExecHandle

Returns a new instance of ExecHandle.



104
105
106
 
# File 'lib/microsandbox/exec_handle.rb', line 104

def initialize(native)
  @native = native
end

Instance Method Details

#collect ⇒ ExecOutput

Drain the stream and collect all output.

Returns:



134
135
136
 
# File 'lib/microsandbox/exec_handle.rb', line 134

def collect
  ExecOutput.new(@native.collect)
end

#each {|event| ... } ⇒ self, Enumerator

Yield each Microsandbox::ExecEvent until the stream ends. Returns an Enumerator when called without a block.

Yield Parameters:

Returns:

  • (self, Enumerator) 


117
118
119
120
121
122
123
124
 
# File 'lib/microsandbox/exec_handle.rb', line 117

def each
  return enum_for(:each) unless block_given?

  while (event = @native.recv)
    yield ExecEvent.new(event)
  end
  self
end

#id ⇒ String

Returns the correlation id for this execution.

Returns:

  • (String) —

    the correlation id for this execution



109
110
111
 
# File 'lib/microsandbox/exec_handle.rb', line 109

def id
  @native.id
end

#kill ⇒ nil

Kill the running process (SIGKILL).

Returns:

  • (nil) 


147
148
149
150
 
# File 'lib/microsandbox/exec_handle.rb', line 147

def kill
  @native.kill
  nil
end

#resize(rows, cols) ⇒ nil

Resize the pseudo-terminal (only meaningful when started with tty: true).

Returns:

  • (nil) 


154
155
156
157
 
# File 'lib/microsandbox/exec_handle.rb', line 154

def resize(rows, cols)
  @native.resize(Integer(rows), Integer(cols))
  nil
end

#signal(sig) ⇒ nil

Send a signal (integer) to the running process.

Returns:

  • (nil) 


140
141
142
143
 
# File 'lib/microsandbox/exec_handle.rb', line 140

def signal(sig)
  @native.signal(Integer(sig))
  nil
end

#stdin ⇒ ExecStdin?

The stdin writer, or nil if stdin was not piped. Returned only once.

Returns:



161
162
163
164
165
166
 
# File 'lib/microsandbox/exec_handle.rb', line 161

def stdin
  return @stdin if defined?(@stdin)

  native_sink = @native.take_stdin
  @stdin = native_sink && ExecStdin.new(native_sink)
end

#wait ⇒ ExitStatus

Block until the process exits.

Returns:



128
129
130
 
# File 'lib/microsandbox/exec_handle.rb', line 128

def wait
  ExitStatus.new(@native.wait)
end