1Simple(3) User Contributed Perl Documentation Simple(3)
2
6 Proc::Simple -- launch and control background processes
7
9 use Proc::Simple;
10 $myproc = Proc::Simple->new(); # Create a new process object
12 $myproc->start("shell-command-line"); # Launch an external program
14 $myproc->start("command", # Launch an external program
15 "param", ...); # with parameters
16 $myproc->start(sub { ... }); # Launch a perl subroutine
18 $myproc->start(\&subroutine); # Launch a perl subroutine
19 $myproc->start(\&subroutine, # Launch a perl subroutine
20 $param, ...); # with parameters
21 $running = $myproc->poll(); # Poll Running Process
23 $exit_status = $myproc->wait(); # Wait until process is done
25 $proc->kill_on_destroy(1); # Set kill on destroy
27 $proc->signal_on_destroy("KILL"); # Specify signal to be sent
28 # on destroy
29 $myproc->kill(); # Kill Process (SIGTERM)
31 $myproc->kill("SIGUSR1"); # Send specified signal
35 $myproc->exit_status(); # Return exit status of process
37 Proc::Simple::debug($level); # Turn debug on
40
42 The Proc::Simple package provides objects mimicing real-life processes
43 from a user's point of view. A new process object is created by
44 $myproc = Proc::Simple->new();
46 Either external programs or perl subroutines can be launched and
48 controlled as processes in the background.
49 A 10-second sleep process, for example, can be launched as an external
51 program as in
52 $myproc->start("/bin/sleep 10"); # or
54 $myproc->start("/bin/sleep", "10");
55 or as a perl subroutine, as in
57 sub mysleep { sleep(shift); } # Define mysleep()
59 $myproc->start(\&mysleep, 10); # Launch it.
60 or even as
62 $myproc->start(sub { sleep(10); });
64 The start Method returns immediately after starting the specified
66 process in background, i.e. there's no blocking. It returns 1 if the
67 process has been launched sucessfully and 0 if not.
68 The poll method checks if the process is still running
70 $running = $myproc->poll();
72 and returns 1 if it is, 0 if it's not. Finally,
74 $myproc->kill();
76 terminates the process by sending it the SIGTERM signal. As an option,
78 another signal can be specified.
79 $myproc->kill("SIGUSR1");
81 sends the SIGUSR1 signal to the running process. kill returns 1 if it
83 succeeds in sending the signal, 0 if it doesn't.
84 The methods are discussed in more detail in the next section.
86 A destructor is provided so that a signal can be sent to the forked
88 processes automatically should the process object be destroyed or if
89 the process exits. By default this behaviour is turned off (see the
90 kill_on_destroy and signal_on_destroy methods).
91
93 The following methods are available:
94 new (Constructor)
96 Create a new instance of this class by writing
97 $proc = new Proc::Simple;
99 or
101 $proc = Proc::Simple->new();
103 It takes no arguments.
105 start
107 Launches a new process. The "start()" method can be used to launch
108 both external programs (like "/bin/echo") or one of your self-
109 defined subroutines (like "foo()") in a new process.
110 Starting External Programs
112 For an external program to be started, call
113 $status = $proc->start("program-name");
115 If you want to pass a couple of parameters to the launched program,
117 there's two options: You can either pass them in one argument like in
118 $status = $proc->start("/bin/echo hello world");
120 or in several arguments like in
122 $status = $proc->start("/bin/echo", "hello", "world");
124 Just as in Perl's function "system()", there's a big difference between
126 the two methods: If you provide one argument containing a blank-
127 separated command line, your shell is going to process any meta-
128 characters (if you choose to use some) before the process is actually
129 launched:
130 $status = $proc->start("/bin/ls -l /etc/initt*");
132 will expand "/etc/initt*" to "/etc/inittab" before running the "ls"
134 command. If, on the other hand, you say
135 $status = $proc->start("/bin/ls", "-l", "*");
137 the "*" will stay unexpanded, meaning you'll look for a file with the
139 literal name "*" (which is unlikely to exist on your system unless you
140 deliberately create confusingly named files :). For more info on this,
141 look up "perldoc -f exec".
142 Starting Subroutines
144 If, on the other hand, you want to start a Perl subroutine in the
145 background, simply provide the function reference like
146 $status = $proc->start(\&your_function);
148 or supply an unnamed subroutine:
150 $status = $proc->start( sub { sleep(1) } );
152 You can also provide additional parameters to be passed to the
154 function:
155 $status = $proc->start(\&printme, "hello", "world");
157 The start Method returns immediately after starting the specified
159 process in background, i.e. non-blocking mode. It returns 1 if the
160 process has been launched sucessfully and 0 if not.
161 poll
163 The poll method checks if the process is still running
164 $running = $myproc->poll();
166 and returns 1 if it is, 0 if it's not.
168 kill
170 The kill() method:
171 $myproc->kill();
173 terminates the process by sending it the SIGTERM signal. As an
175 option, another signal can be specified.
176 $myproc->kill("SIGUSR1");
178 sends the SIGUSR1 signal to the running process. kill returns 1 if
180 it succeeds in sending the signal, 0 if it doesn't.
181 kill_on_destroy
183 Set a flag to determine whether the process attached to this object
184 should be killed when the object is destroyed. By default, this
185 flag is set to false. The current value is returned.
186 $current = $proc->kill_on_destroy;
188 $proc->kill_on_destroy(1); # Set flag to true
189 $proc->kill_on_destroy(0); # Set flag to false
190 signal_on_destroy
192 Method to set the signal that will be sent to the process when the
193 object is destroyed (Assuming kill_on_destroy is true). Returns the
194 current setting.
195 $current = $proc->signal_on_destroy;
197 $proc->signal_on_destroy("KILL");
198 redirect_output
200 This allows to redirect the stdout and/or stderr output to a file.
201 Specify undef to leave th
202 # stdout to a file, left stderr unchanged
204 $proc->redirect_output ("/tmp/someapp.stdout", undef);
205 # stderr to a file, left stdout unchanged
207 $proc->redirect_output (undef, "/tmp/someapp.stderr");
208 # stdout and stderr to a separate file
210 $proc->redirect_output ("/tmp/someapp.stdout", "/tmp/someapp.stderr");
211 Call this method before running the start method.
213 pid Returns the pid of the forked process associated with this object
215 $pid = $proc->pid;
217 t0 Returns the start time() of the forked process associated with this
219 object
220 $t0 = $proc->t0();
222 t1 Returns the stop time() of the forked process associated with this
224 object
225 $t1 = $proc->t1();
227 DESTROY (Destructor)
229 Object destructor. This method is called when the object is
230 destroyed (eg with "undef" or on exiting perl). If kill_on_destroy
231 is true the process associated with the object is sent the
232 signal_on_destroy signal (SIGTERM if undefined).
233 exit_status
235 Returns the exit status of the process as the $! variable
236 indicates. If the process is still running, "undef" is returned.
237 wait
239 The wait method:
240 $exit_status = $myproc->wait();
242 waits until the process is done and returns its exit status.
244 debug
246 Switches debug messages on and off -- Proc::Simple::debug(1)
247 switches them on, Proc::Simple::debug(0) keeps Proc::Simple quiet.
248
250 Please keep in mind that there is no guarantee that the SIGTERM signal
251 really terminates a process. Processes can have signal handlers defined
252 that avoid the shutdown. If in doubt, whether a process still exists,
253 check it repeatedly with the poll routine after sending the signal.
254
256 I'd recommend using perl 5.6.0 although it might also run with 5.003 --
257 if you don't have it, this is the time to upgrade!
258 LEGALESE Copyright 1996 by Mike Schilli, all rights reserved. This
260 program is free software, you can redistribute it and/or modify it
261 under the same terms as Perl itself.
262
264 Michael Schilli <michael@perlmeister.com>
265 Contributors:
267 Tim Jenness <t.jenness@jach.hawaii.edu>
269 did kill_on_destroy/signal_on_destroy/pid
270 Mark R. Southern <mark_southern@merck.com>
272 worked on EXIT_STATUS tracking
273 Tobias Jahn <tjahn@users.sourceforge.net>
275 added redirection to stdout/stderr
276 Clauss Strauch <Clauss_Strauch@aquila.fac.cs.cmu.edu> suggested the
278 multi-arg start()-methods.
279 Chip Capelik contributed a patch with the wait() method.
281 Jeff Holt provided a patch for time tracking with t0() and t1().
283 Brad Cavanagh fixed RT33440 (unreliable $?)
285
287 Hey! The above document had some coding errors, which are explained
288 below:
289 Around line 178:
291 You forgot a '=back' before '=head2'
292 Around line 282:
294 '=item' outside of any '=over'
295 Around line 720:
297 You forgot a '=back' before '=head1'
298perl v5.12.0 2009-07-09 Simple(3)