Class: Toys::Utils::Exec::Controller
- Inherits:
-
Object
- Object
- Toys::Utils::Exec::Controller
- Defined in:
- lib/toys/utils/exec.rb
Overview
An object that controls a subprocess. This object is returned from an execution running in the background, or is yielded to a control block for an execution running in the foreground. You may use this object to interact with the subcommand's streams, send signals to the process, and get its result.
Instance Attribute Summary collapse
-
#err ⇒ IO?
readonly
The subcommand's standard error stream (which can be read from).
-
#exception ⇒ Exception?
readonly
The exception raised when the process failed to start.
-
#in ⇒ IO?
readonly
The subcommand's standard input stream (which can be written to).
-
#name ⇒ Object
readonly
The subcommand's name.
-
#out ⇒ IO?
readonly
The subcommand's standard output stream (which can be read from).
-
#pid ⇒ Integer?
readonly
The process ID.
Instance Method Summary collapse
-
#capture(which) ⇒ self
Captures the remaining data in the given stream.
-
#capture_err ⇒ self
Captures the remaining data in the standard error stream.
-
#capture_out ⇒ self
Captures the remaining data in the standard output stream.
-
#executing? ⇒ Boolean
Determine whether the subcommand is still executing.
-
#kill(sig) ⇒ self
(also: #signal)
Send the given signal to the process.
-
#redirect(which, io, *io_args) ⇒ self
Redirects the remainder of the given stream.
-
#redirect_err(io, *io_args) ⇒ self
Redirects the remainder of the standard error stream.
-
#redirect_in(io, *io_args) ⇒ self
Redirects the remainder of the standard input stream.
-
#redirect_out(io, *io_args) ⇒ self
Redirects the remainder of the standard output stream.
-
#result(timeout: nil) ⇒ Toys::Utils::Exec::Result?
Wait for the subcommand to complete, and return a result object.
Instance Attribute Details
#err ⇒ IO? (readonly)
The subcommand's standard error stream (which can be read from).
548 549 550 |
# File 'lib/toys/utils/exec.rb', line 548 def err @err end |
#exception ⇒ Exception? (readonly)
The exception raised when the process failed to start.
Exactly one of #exception and #pid will be non-nil.
568 569 570 |
# File 'lib/toys/utils/exec.rb', line 568 def exception @exception end |
#in ⇒ IO? (readonly)
The subcommand's standard input stream (which can be written to).
530 531 532 |
# File 'lib/toys/utils/exec.rb', line 530 def in @in end |
#name ⇒ Object (readonly)
The subcommand's name.
521 522 523 |
# File 'lib/toys/utils/exec.rb', line 521 def name @name end |
#out ⇒ IO? (readonly)
The subcommand's standard output stream (which can be read from).
539 540 541 |
# File 'lib/toys/utils/exec.rb', line 539 def out @out end |
#pid ⇒ Integer? (readonly)
The process ID.
Exactly one of #exception and #pid will be non-nil.
558 559 560 |
# File 'lib/toys/utils/exec.rb', line 558 def pid @pid end |
Instance Method Details
#capture(which) ⇒ self
Captures the remaining data in the given stream. After calling this, do not read directly from the stream.
577 578 579 580 581 582 583 584 585 586 587 588 589 590 |
# File 'lib/toys/utils/exec.rb', line 577 def capture(which) stream = stream_for(which) @join_threads << ::Thread.new do begin data = stream.read @mutex.synchronize do @captures[which] = data end ensure stream.close end end self end |
#capture_err ⇒ self
Captures the remaining data in the standard error stream. After calling this, do not read directly from the stream.
608 609 610 |
# File 'lib/toys/utils/exec.rb', line 608 def capture_err capture(:err) end |
#capture_out ⇒ self
Captures the remaining data in the standard output stream. After calling this, do not read directly from the stream.
598 599 600 |
# File 'lib/toys/utils/exec.rb', line 598 def capture_out capture(:out) end |
#executing? ⇒ Boolean
Determine whether the subcommand is still executing
724 725 726 |
# File 'lib/toys/utils/exec.rb', line 724 def executing? @wait_thread&.status ? true : false end |
#kill(sig) ⇒ self Also known as: signal
Send the given signal to the process. The signal may be specified by name or number.
713 714 715 716 |
# File 'lib/toys/utils/exec.rb', line 713 def kill(sig) ::Process.kill(sig, pid) if pid self end |
#redirect(which, io, *io_args) ⇒ self
Redirects the remainder of the given stream.
You may specify the stream as an IO or IO-like object, or as a file
specified by its path. If specifying a file, you may optionally
provide the mode and permissions for the call to File#open
. You can
also specify the value :null
to indicate the null file.
After calling this, do not interact directly with the stream.
628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 |
# File 'lib/toys/utils/exec.rb', line 628 def redirect(which, io, *io_args) io = ::File::NULL if io == :null if io.is_a?(::String) io_args = which == :in ? ["r"] : ["w"] if io_args.empty? io = ::File.open(io, *io_args) end stream = stream_for(which, allow_in: true) @join_threads << ::Thread.new do begin if which == :in ::IO.copy_stream(io, stream) else ::IO.copy_stream(stream, io) end ensure stream.close io.close end end self end |
#redirect_err(io, *io_args) ⇒ self
Redirects the remainder of the standard error stream.
You may specify the stream as an IO or IO-like object, or as a file
specified by its path. If specifying a file, you may optionally
provide the mode and permissions for the call to File#open
.
After calling this, do not interact directly with the stream.
702 703 704 |
# File 'lib/toys/utils/exec.rb', line 702 def redirect_err(io, *io_args) redirect(:err, io, *io_args) end |
#redirect_in(io, *io_args) ⇒ self
Redirects the remainder of the standard input stream.
You may specify the stream as an IO or IO-like object, or as a file
specified by its path. If specifying a file, you may optionally
provide the mode and permissions for the call to File#open
. You can
also specify the value :null
to indicate the null file.
After calling this, do not interact directly with the stream.
665 666 667 |
# File 'lib/toys/utils/exec.rb', line 665 def redirect_in(io, *io_args) redirect(:in, io, *io_args) end |
#redirect_out(io, *io_args) ⇒ self
Redirects the remainder of the standard output stream.
You may specify the stream as an IO or IO-like object, or as a file
specified by its path. If specifying a file, you may optionally
provide the mode and permissions for the call to File#open
. You can
also specify the value :null
to indicate the null file.
After calling this, do not interact directly with the stream.
684 685 686 |
# File 'lib/toys/utils/exec.rb', line 684 def redirect_out(io, *io_args) redirect(:out, io, *io_args) end |
#result(timeout: nil) ⇒ Toys::Utils::Exec::Result?
Wait for the subcommand to complete, and return a result object.
Closes the control streams if present. The stdin stream is always closed, even if the call times out. The stdout and stderr streams are closed only after the command terminates.
740 741 742 743 744 745 746 747 748 749 |
# File 'lib/toys/utils/exec.rb', line 740 def result(timeout: nil) close_streams(:in) return nil if @wait_thread && !@wait_thread.join(timeout) @result ||= begin close_streams(:out) @join_threads.each(&:join) Result.new(name, @captures[:out], @captures[:err], @wait_thread&.value, @exception) .tap { |result| @result_callback&.call(result) } end end |