module ProcessExecuter

def self.run(*command, **options_hash)

Returns:
  • (ProcessExecuter::Result) - The result of the completed subprocess

Raises:
  • (ProcessExecuter::Error) - if the command could not be executed or failed

Options Hash: (**options_hash)
  • :logger (Logger) -- The logger to use
  • :chdir (String) -- The directory to run the command in
  • :close_others (Boolean) -- If true, close non-standard file descriptors
  • :umask (Integer) -- Set the umask (see File.umask)
  • :rlimit_resource_name (Integer) -- Set resource limits (see Process.setrlimit)
  • :new_pgroup (Boolean) -- Create a new process group (Windows only)
  • :pgroup (true, Integer, nil) -- true or 0: new process group; non-zero: join
  • :unsetenv_others (Boolean) -- If true, unset all environment variables before
  • :raise_errors (Boolean) -- Raise an exception if the command fails
  • :err (#write) -- The object to write stderr to
  • :out (#write) -- The object to write stdout to
  • :timeout_after (Numeric) -- The maximum seconds to wait for the

Parameters:
  • options_hash (Hash) -- Additional options
  • command (Array) -- The command to run

Other tags:
    Example: Capture to multiple destinations (e.g. files, buffers, STDOUT, etc.) -
    Example: Capture to a file -
    Example: Capture to an explicit buffer -
    Example: Capture stdout and stderr into a single buffer -
    Example: Run command in a different directory -
    Example: Reset existing environment variables and add new ones -
    Example: Unset environment variables -
    Example: Set environment variables when using a command array -
    Example: Set environment variables -
    Example: Do not raise an error when the command fails -
    Example: Run a command which exits due to an unhandled signal -
    Example: Run a command which fails -
    Example: Run a command with a timeout -
    Example: Run a command given as an array of strings (does not use shell) -
    Example: Run a command given as a single string (uses shell) - 
def self.run(*command, **options_hash)
  options = ProcessExecuter.run_options(options_hash)
  run_with_options(command, options)
end

def self.run_options(obj)

Other tags:
    Api: - public

Raises:
  • (ArgumentError) - if obj is not a Hash or SpawnOptions

Returns:
  • (RunOptions) -

Parameters:
  • obj (Hash, RunOptions) -- the object to be converted 
def self.run_options(obj)
  case obj
  when ProcessExecuter::Options::RunOptions
    obj
  when Hash
    ProcessExecuter::Options::RunOptions.new(**obj)
  else
    raise ArgumentError, "Expected a Hash or ProcessExecuter::Options::RunOptions but got a #{obj.class}"
  end
end

def self.run_with_options(command, options)

Other tags:
    Api: - private

Returns:
  • (ProcessExecuter::Result) - The result of the completed subprocess

Parameters:
  • options (ProcessExecuter::Options::RunOptions) -- The options to use when running the command
  • command (Array) -- The command to run

Other tags:
    See: ProcessExecuter.run - for full documentation 
def self.run_with_options(command, options)
  ProcessExecuter::Runner.new.call(command, options)
end

def self.spawn_and_wait(*command, **options_hash)

Returns:
  • (ProcessExecuter::Result) - The result of the completed subprocess

Parameters:
  • options_hash (Hash) -- The options to use when executing the command
  • command (Array) -- The command to execute

Other tags:
    See: ProcessExecuter::Options#initialize - ProcessExecuter::Options#initialize for
    See: https://ruby-doc.org/core-3.1.2/Kernel.html#method-i-spawn - Kernel.spawn

Other tags:
    Example: capturing stdout to a string -
    Example: with a timeout - 
def self.spawn_and_wait(*command, **options_hash)
  options = ProcessExecuter.spawn_and_wait_options(options_hash)
  spawn_and_wait_with_options(command, options)
end

def self.spawn_and_wait_options(obj)

Other tags:
    Api: - public

Raises:
  • (ArgumentError) - if obj is not a Hash or SpawnOptions

Returns:
  • (SpawnAndWaitOptions) -

Parameters:
  • obj (Hash, SpawnAndWaitOptions) -- the object to be converted 
def self.spawn_and_wait_options(obj)
  case obj
  when ProcessExecuter::Options::SpawnAndWaitOptions
    obj
  when Hash
    ProcessExecuter::Options::SpawnAndWaitOptions.new(**obj)
  else
    raise ArgumentError, "Expected a Hash or ProcessExecuter::Options::SpawnAndWaitOptions but got a #{obj.class}"
  end
end

def self.spawn_and_wait_with_options(command, options)

Other tags:
    Api: - private

Returns:
  • (ProcessExecuter::Result) - The result of the completed subprocess

Parameters:
  • options (ProcessExecuter::Options::SpawnAndWaitOptions) -- The options to use when running the command
  • command (Array) -- The command to run

Other tags:
    See: ProcessExecuter.spawn_and_wait - for full documentation 
def self.spawn_and_wait_with_options(command, options)
  begin
    pid = Process.spawn(*command, **options.spawn_options)
  rescue StandardError => e
    raise ProcessExecuter::SpawnError, "Failed to spawn process: #{e.message}"
  end
  wait_for_process(pid, command, options)
end

def self.spawn_options(obj)

Other tags:
    Api: - public

Raises:
  • (ArgumentError) - if obj is not a Hash or SpawnOptions

Returns:
  • (SpawnOptions) -

Parameters:
  • obj (Hash, SpawnOptions) -- the object to be converted 
def self.spawn_options(obj)
  case obj
  when ProcessExecuter::Options::SpawnOptions
    obj
  when Hash
    ProcessExecuter::Options::SpawnOptions.new(**obj)
  else
    raise ArgumentError, "Expected a Hash or ProcessExecuter::Options::SpawnOptions but got a #{obj.class}"
  end
end

def self.wait_for_process(pid, command, options)

Other tags:
    Api: - private

Returns:
  • (ProcessExecuter::Result) - The result of the completed subprocess

Parameters:
  • options (ProcessExecuter::Options) -- the options used
  • pid (Integer) -- the process ID 
def self.wait_for_process(pid, command, options)
s.clock_gettime(Process::CLOCK_MONOTONIC)
ed_out = wait_for_process_raw(pid, options.timeout_after)
ess.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
sult.new(process_status, command:, options:, timed_out:, elapsed_time:)

def self.wait_for_process_raw(pid, timeout_after)

Other tags:
    Api: - private

Returns:
  • (Array) - an array containing the process status and a boolean

Parameters:
  • timeout_after (Numeric, nil) -- the number of seconds to wait for the process to terminate
  • pid (Integer) -- the process ID 
def self.wait_for_process_raw(pid, timeout_after)
(timeout_after) { Process.wait2(pid).last }
rror
ILL', pid)
e
id).last
med_out]