Class: Toys::Utils::Exec::Controller

Inherits:
Object
  • Object
show all
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

Instance Method Summary collapse

Instance Attribute Details

#err ⇒ IO? (readonly)

The subcommand's standard error stream (which can be read from).

Returns:

  • (IO) —

    if the command was configured with err: :controller

  • (nil) —

    if the command was not configured with err: :controller



469
470
471
 
# File 'lib/toys/utils/exec.rb', line 469

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.

Returns:

  • (Exception) —

    if the process failed to start.

  • (nil) —

    if the process start was successful.



489
490
491
 
# File 'lib/toys/utils/exec.rb', line 489

def exception
  @exception
end

#in ⇒ IO? (readonly)

The subcommand's standard input stream (which can be written to).

Returns:

  • (IO) —

    if the command was configured with in: :controller

  • (nil) —

    if the command was not configured with in: :controller



451
452
453
 
# File 'lib/toys/utils/exec.rb', line 451

def in
  @in
end

#name ⇒ Object (readonly)

The subcommand's name.

Returns:

  • (Object) 


442
443
444
 
# File 'lib/toys/utils/exec.rb', line 442

def name
  @name
end

#out ⇒ IO? (readonly)

The subcommand's standard output stream (which can be read from).

Returns:

  • (IO) —

    if the command was configured with out: :controller

  • (nil) —

    if the command was not configured with out: :controller



460
461
462
 
# File 'lib/toys/utils/exec.rb', line 460

def out
  @out
end

#pid ⇒ Integer? (readonly)

The process ID.

Exactly one of exception and pid will be non-nil.

Returns:

  • (Integer) —

    if the process start was successful

  • (nil) —

    if the process could not be started.



479
480
481
 
# File 'lib/toys/utils/exec.rb', line 479

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.

Parameters:

  • which (:out, :err) —

    Which stream to capture

Returns:

  • (self) 


498
499
500
501
502
503
504
505
506
507
508
 
# File 'lib/toys/utils/exec.rb', line 498

def capture(which)
  stream = stream_for(which)
  @join_threads << ::Thread.new do
    begin
      @captures[which] = stream.read
    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.

Returns:

  • (self) 


526
527
528
 
# File 'lib/toys/utils/exec.rb', line 526

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.

Returns:

  • (self) 


516
517
518
 
# File 'lib/toys/utils/exec.rb', line 516

def capture_out
  capture(:out)
end

#executing? ⇒ Boolean

Determine whether the subcommand is still executing

Returns:

  • (Boolean) 


642
643
644
 
# File 'lib/toys/utils/exec.rb', line 642

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.

Parameters:

  • sig (Integer, String) —

    The signal to send.

Returns:

  • (self) 


631
632
633
634
 
# File 'lib/toys/utils/exec.rb', line 631

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.

Parameters:

  • which (:in, :out, :err) —

    Which stream to redirect

  • io (IO, StringIO, String, :null) —

    Where to redirect the stream

  • io_args (Object...) —

    The mode and permissions for opening the file, if redirecting to/from a file.

Returns:

  • (self) 


546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
 
# File 'lib/toys/utils/exec.rb', line 546

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.

Parameters:

  • io (IO, StringIO, String) —

    Where to redirect the stream

  • io_args (Object...) —

    The mode and permissions for opening the file, if redirecting to a file.

Returns:

  • (self) 


620
621
622
 
# File 'lib/toys/utils/exec.rb', line 620

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.

Parameters:

  • io (IO, StringIO, String, :null) —

    Where to redirect the stream

  • io_args (Object...) —

    The mode and permissions for opening the file, if redirecting from a file.

Returns:

  • (self) 


583
584
585
 
# File 'lib/toys/utils/exec.rb', line 583

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.

Parameters:

  • io (IO, StringIO, String, :null) —

    Where to redirect the stream

  • io_args (Object...) —

    The mode and permissions for opening the file, if redirecting to a file.

Returns:

  • (self) 


602
603
604
 
# File 'lib/toys/utils/exec.rb', line 602

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.

Parameters:

  • timeout (Numeric, nil) —

    The timeout in seconds, or nil to wait indefinitely.

Returns:



654
655
656
657
658
659
660
661
662
 
# File 'lib/toys/utils/exec.rb', line 654

def result(timeout: nil)
  return nil if @wait_thread && !@wait_thread.join(timeout)
  @result ||= begin
    close_streams
    @join_threads.each(&:join)
    Result.new(name, @captures[:out], @captures[:err], @wait_thread&.value, @exception)
          .tap { |result| @result_callback&.call(result) }
  end
end