Class: ProcessBuilder

Inherits:
Object
  • Object
show all
Defined in:
lib/process_builder.rb

Overview

Object-oriented wrapper around Process.spawn and the Open3 library. ProcessBuilder is an immutable description of a process and its various attributes. ProcessBuilder objects are created with the ProcessBuilder.build method, and after having been created can be used to spawn the process in various ways, such as #spawn or #popen3.

See the descriptions of the methods of this class for further details, and the documentation for Process.spawn and Open3 for full details of the arguments that each understands.

Direct Known Subclasses

Builder

Defined Under Namespace

Classes: Builder

Constant Summary collapse

VERSION = 
'1.1.0'

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(*args) ⇒ ProcessBuilder

Returns a new instance of ProcessBuilder.



81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
 
# File 'lib/process_builder.rb', line 81

def initialize(*args)
  if args.size == 1 && args.first.is_a?(ProcessBuilder)
    self.copy_fields(args.first)
  else
    @command_line = array_copy(args)
    @environment = Hash.new
    @redirection = Hash.new
    @rlimit = Hash.new
    if block_given?
      builder = Builder.new(self)
      yield builder
      self.copy_fields(builder)
    end
  end
  self.freeze
end

Instance Attribute Details

#close_others ⇒ Object (readonly)

File descriptor inheritance, corresponding to the :close_others option of Process.spawn.



42
43
44
 
# File 'lib/process_builder.rb', line 42

def close_others
  @close_others
end

#command_line ⇒ Object (readonly)

The command and arguments passed to Process.spawn



17
18
19
 
# File 'lib/process_builder.rb', line 17

def command_line
  @command_line
end

#directory ⇒ Object (readonly)

Working directory for the process. Corresponds to the :chdir option of Process.spawn



21
22
23
 
# File 'lib/process_builder.rb', line 21

def directory
  @directory
end

#environment ⇒ Object (readonly)

Hash representing environment variables for the process. Passed as the optional [env] argument of Process.spawn.



25
26
27
 
# File 'lib/process_builder.rb', line 25

def environment
  @environment
end

#pgroup ⇒ Object (readonly)

Process group, corresponding to the :pgroup option of Process.spawn.



33
34
35
 
# File 'lib/process_builder.rb', line 33

def pgroup
  @pgroup
end

#redirection ⇒ Object (readonly)

Hash specifying IO redirection for the child process, corresponding to the redirection options of Process.spawn. Generally not used if using any of the Open3 mechanisms for spawning the process.



38
39
40
 
# File 'lib/process_builder.rb', line 38

def redirection
  @redirection
end

#rlimit ⇒ Object (readonly)

Hash specifying resource limits. Process.spawn expects resource limits to be specified as options in the form :rlimit_resourcename, where resourcename is one of the resources understood by Process.setrlimit, such as :rlimit_core for example. The keys of this Hash will be used to construct the options, so setting rlimit would result in an option named :rlimit_core.



54
55
56
 
# File 'lib/process_builder.rb', line 54

def rlimit
  @rlimit
end

#umask ⇒ Object (readonly)

umask for the child process, corresponding to the :umask option of Process.spawn.



46
47
48
 
# File 'lib/process_builder.rb', line 46

def umask
  @umask
end

#unsetenv_others ⇒ Object (readonly) Also known as: unsetenv_others?

If true, clear environment variables, other than specified explicitly in environment.



29
30
31
 
# File 'lib/process_builder.rb', line 29

def unsetenv_others
  @unsetenv_others
end

Class Method Details

.build(*args, &block) ⇒ Object

Build a new process description using the given args as the process command line. If a block is given, this method will yield a mutable ProcessBuilder::Builder object to it so that the block can specify the attributes of the process. The object returned by this method, however, is an immutable (and frozen) instance of ProcessBuilder.



61
62
63
 
# File 'lib/process_builder.rb', line 61

def self.build(*args, &block)
  new(*args, &block)
end

.copy(other) ⇒ Object

Build a new process description copied from the given other ProcessBuilder. Like the build method, this method yields to the given block to allow for customization of the process attributes.

Raises:

  • (ArgumentError) 


68
69
70
71
72
73
74
75
76
77
78
79
 
# File 'lib/process_builder.rb', line 68

def self.copy(other)
  raise ArgumentError unless other.is_a?(ProcessBuilder)
  if block_given?
    builder = Builder.new(other)
    if block_given?
      yield builder
    end
    new(builder)
  else
    new(other)
  end
end

Instance Method Details

#capture2(stdin_data, &block) ⇒ Object

Execute the process described by this ProcessBuilder using Open3.capture2. The argument to this method is used as the :stdin_data argument of Open3.capture2.



127
128
129
130
131
 
# File 'lib/process_builder.rb', line 127

def capture2(stdin_data, &block)
  args = self.spawn_args
  args.last[:stdin_data] = stdin_data.to_s.dup
  Open3.capture2(*args, &block)
end

#capture3(stdin_data, &block) ⇒ Object

Execute the process described by this ProcessBuilder using Open3.capture3. The argument to this method is used as the :stdin_data argument of Open3.capture3.



136
137
138
139
140
 
# File 'lib/process_builder.rb', line 136

def capture3(stdin_data, &block)
  args = self.spawn_args
  args.last[:stdin_data] = stdin_data.to_s.dup
  Open3.capture3(*args, &block)
end

#initialize_copy(other) ⇒ Object 



98
99
100
101
 
# File 'lib/process_builder.rb', line 98

def initialize_copy(other)
  super
  self.copy_fields(other)
end

#popen2(&block) ⇒ Object

Spawn the process described by this ProcessBuilder using Open3.popen2.



110
111
112
 
# File 'lib/process_builder.rb', line 110

def popen2(&block)
  Open3.popen2(*spawn_args, &block)
end

#popen2e(&block) ⇒ Object

Spawn the process described by this ProcessBuilder using Open3.popen2e.



115
116
117
 
# File 'lib/process_builder.rb', line 115

def popen2e(&block)
  Open3.popen2e(*spawn_args, &block)
end

#popen3(&block) ⇒ Object

Spawn the process described by this ProcessBuilder using Open3.popen3.



120
121
122
 
# File 'lib/process_builder.rb', line 120

def popen3(&block)
  Open3.popen3(*spawn_args, &block)
end

#spawn ⇒ Object

Spawn the process described by this ProcessBuilder using Process.spawn. Returns the PID of the spawned process.



105
106
107
 
# File 'lib/process_builder.rb', line 105

def spawn
  Process.spawn(*spawn_args)
end

#spawn_args ⇒ Object

Returns an array of arguments as understood by Process.spawn.



143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
 
# File 'lib/process_builder.rb', line 143

def spawn_args
  result = Array.new
  unless environment.empty?
    result << environment
  end
  result.concat(command_line)
  opts = Hash.new
  opts[:chdir] = directory.to_s unless directory.nil?
  opts[:pgroup] = pgroup unless pgroup.nil?
  opts[:umask] = umask unless umask.nil?
  opts[:unsetenv_others] = unsetenv_others unless unsetenv_others.nil?
  opts[:close_others] = close_others unless close_others.nil?
  rlimit.each do |key, value|
    opts["rlimit_#{key}".to_sym] = value
  end
  redirection.each do |key, value|
    opts[key] = value
  end
  result << opts
  result
end