Class: Toys::Utils::Exec::Controller
- Inherits:
-
Object
- Object
- Toys::Utils::Exec::Controller
- Defined in:
- toys-core/lib/toys/utils/exec.rb
Overview
Defined in the toys-core gem
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).
552 553 554 |
# File 'toys-core/lib/toys/utils/exec.rb', line 552 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.
572 573 574 |
# File 'toys-core/lib/toys/utils/exec.rb', line 572 def exception @exception end |
#in ⇒ IO? (readonly)
The subcommand's standard input stream (which can be written to).
534 535 536 |
# File 'toys-core/lib/toys/utils/exec.rb', line 534 def in @in end |
#name ⇒ Object (readonly)
The subcommand's name.
525 526 527 |
# File 'toys-core/lib/toys/utils/exec.rb', line 525 def name @name end |
#out ⇒ IO? (readonly)
The subcommand's standard output stream (which can be read from).
543 544 545 |
# File 'toys-core/lib/toys/utils/exec.rb', line 543 def out @out end |
#pid ⇒ Integer? (readonly)
The process ID.
Exactly one of #exception and #pid will be non-nil.
562 563 564 |
# File 'toys-core/lib/toys/utils/exec.rb', line 562 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.
581 582 583 584 585 586 587 588 589 590 591 592 593 594 |
# File 'toys-core/lib/toys/utils/exec.rb', line 581 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.
612 613 614 |
# File 'toys-core/lib/toys/utils/exec.rb', line 612 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.
602 603 604 |
# File 'toys-core/lib/toys/utils/exec.rb', line 602 def capture_out capture(:out) end |
#executing? ⇒ Boolean
Determine whether the subcommand is still executing
728 729 730 |
# File 'toys-core/lib/toys/utils/exec.rb', line 728 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.
717 718 719 720 |
# File 'toys-core/lib/toys/utils/exec.rb', line 717 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.
632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 |
# File 'toys-core/lib/toys/utils/exec.rb', line 632 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.
706 707 708 |
# File 'toys-core/lib/toys/utils/exec.rb', line 706 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.
669 670 671 |
# File 'toys-core/lib/toys/utils/exec.rb', line 669 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.
688 689 690 |
# File 'toys-core/lib/toys/utils/exec.rb', line 688 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.
744 745 746 747 748 749 750 751 752 753 |
# File 'toys-core/lib/toys/utils/exec.rb', line 744 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 |