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 successfully 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 For an external program to be started, call
112 $status = $proc->start("program-name");
114 If you want to pass a couple of parameters to the launched program,
116 there's two options: You can either pass them in one argument like
117 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
126 between the two methods: If you provide one argument containing a
127 blank-separated command line, your shell is going to process any
128 meta-characters (if you choose to use some) before the process is
129 actually 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
139 the literal name "*" (which is unlikely to exist on your system
140 unless you deliberately create confusingly named files :). For more
141 info on this, look up "perldoc -f exec".
142 If, on the other hand, you want to start a Perl subroutine in the
144 background, simply provide the function reference like
145 $status = $proc->start(\&your_function);
147 or supply an unnamed subroutine:
149 $status = $proc->start( sub { sleep(1) } );
151 You can also provide additional parameters to be passed to the
153 function:
154 $status = $proc->start(\&printme, "hello", "world");
156 The start Method returns immediately after starting the specified
158 process in background, i.e. non-blocking mode. It returns 1 if the
159 process has been launched successfully and 0 if not.
160 poll
162 The poll method checks if the process is still running
163 $running = $myproc->poll();
165 and returns 1 if it is, 0 if it's not.
167 kill
169 The kill() method:
170 $myproc->kill();
172 terminates the process by sending it the SIGTERM signal. As an
174 option, another signal can be specified.
175 $myproc->kill("SIGUSR1");
177 sends the SIGUSR1 signal to the running process. kill returns 1 if
179 it succeeds in sending the signal, 0 if it doesn't.
180 kill_on_destroy
182 Set a flag to determine whether the process attached to this object
183 should be killed when the object is destroyed. By default, this
184 flag is set to false. The current value is returned.
185 $current = $proc->kill_on_destroy;
187 $proc->kill_on_destroy(1); # Set flag to true
188 $proc->kill_on_destroy(0); # Set flag to false
189 signal_on_destroy
191 Method to set the signal that will be sent to the process when the
192 object is destroyed (Assuming kill_on_destroy is true). Returns the
193 current setting.
194 $current = $proc->signal_on_destroy;
196 $proc->signal_on_destroy("KILL");
197 redirect_output
199 Redirects stdout and/or stderr output to a file. Specify undef to
200 leave the stderr/stdout handles of the process alone.
201 # stdout to a file, left stderr unchanged
203 $proc->redirect_output ("/tmp/someapp.stdout", undef);
204 # stderr to a file, left stdout unchanged
206 $proc->redirect_output (undef, "/tmp/someapp.stderr");
207 # stdout and stderr to a separate file
209 $proc->redirect_output ("/tmp/someapp.stdout", "/tmp/someapp.stderr");
210 Call this method before running the start method.
212 pid Returns the pid of the forked process associated with this object
214 $pid = $proc->pid;
216 t0 Returns the start time() of the forked process associated with this
218 object
219 $t0 = $proc->t0();
221 t1 Returns the stop time() of the forked process associated with this
223 object
224 $t1 = $proc->t1();
226 DESTROY (Destructor)
228 Object destructor. This method is called when the object is
229 destroyed (eg with "undef" or on exiting perl). If kill_on_destroy
230 is true the process associated with the object is sent the
231 signal_on_destroy signal (SIGTERM if undefined).
232 exit_status
234 Returns the exit status of the process as the $! variable
235 indicates. If the process is still running, "undef" is returned.
236 wait
238 The wait method:
239 $exit_status = $myproc->wait();
241 waits until the process is done and returns its exit status.
243 debug
245 Switches debug messages on and off -- Proc::Simple::debug(1)
246 switches them on, Proc::Simple::debug(0) keeps Proc::Simple quiet.
247 cleanup
249 Proc::Simple keeps around data of terminated processes, e.g. you
250 can check via "t0()" and "t1()" how long a process ran, even if
251 it's long gone. Over time, this data keeps occupying more and more
252 memory and if you have a long-running program, you might want to
253 run "Proc::Simple->cleanup()" every once in a while to get rid of
254 data pertaining to processes no longer in use.
255
257 Please keep in mind that there is no guarantee that the SIGTERM signal
258 really terminates a process. Processes can have signal handlers defined
259 that avoid the shutdown. If in doubt, whether a process still exists,
260 check it repeatedly with the poll routine after sending the signal.
261
263 If you pass a shell program to Proc::Simple, it'll use "exec()" to
264 launch it. As noted in Perl's "exec()" manpage, simple commands for the
265 one-argument version of "exec()" will be passed to "execvp()" directly,
266 while commands containing characters like ";" or "*" will be passed to
267 a shell to make sure those get the shell expansion treatment.
268 This has the interesting side effect that if you launch something like
270 $p->start("./womper *");
272 then you'll see two processes in your process list:
274 $ ps auxww | grep womper
276 mschilli 9126 11:21 0:00 sh -c ./womper *
277 mschilli 9127 11:21 0:00 /usr/local/bin/perl -w ./womper ...
278 A regular "kill()" on the process PID would only kill the first
280 process, but Proc::Simple's "kill()" will use a negative signal and
281 send it to the first process (9126). Since it has marked the process as
282 a process group leader when it created it previously (via setsid()),
283 this will cause both processes above to receive the signal sent by
284 "kill()".
285
287 Tim Jenness <t.jenness@jach.hawaii.edu>
288 did kill_on_destroy/signal_on_destroy/pid
289 Mark R. Southern <mark_southern@merck.com>
291 worked on EXIT_STATUS tracking
292 Tobias Jahn <tjahn@users.sourceforge.net>
294 added redirection to stdout/stderr
295 Clauss Strauch <Clauss_Strauch@aquila.fac.cs.cmu.edu> suggested the
297 multi-arg start()-methods.
298 Chip Capelik contributed a patch with the wait() method.
300 Jeff Holt provided a patch for time tracking with t0() and t1().
302 Brad Cavanagh fixed RT33440 (unreliable $?)
304
306 1996, Mike Schilli <cpan@perlmeister.com>
307
309 Copyright 1996-2011 by Mike Schilli, all rights reserved. This program
310 is free software, you can redistribute it and/or modify it under the
311 same terms as Perl itself.
312perl v5.34.0 2021-07-22 Simple(3)