No::Worries::Proc(3pm)

1No::Worries::Proc(3)  User Contributed Perl Documentation No::Worries::Proc(3)
2
3
4

NAME

6       No::Worries::Proc - process handling without worries
7

SYNOPSIS

9         use No::Worries::Proc qw(proc_run proc_create proc_monitor proc_detach);
10
11         # simple interface to execute a command
12         $status = proc_run(command => [ "foo", "-x", 7 ]);
13         printf("foo exited with %d\n", $status);
14
15         # idem but with output redirection and more information
16         %proc = proc_run(command => [ qw(uname -a) ], stdout => \$output);
17         printf("process %d output is %s\n", $proc->{pid}, $output);
18
19         # start two process and wait for them to finish
20         $p1 = proc_create(
21             command => \@cmd1,
22             timeout => 5,           # to be killed if still running after 5s
23             stderr  => "/dev/null", # discard stderr
24         );
25         $p2 = proc_create(
26             command => \@cmd2,
27             stdout  => \$output,    # get stdout+stderr in $output
28             stderr  => "",          # merge stderr with stdout
29         );
30         proc_monitor([ $p1, $p2 ], timeout => 10);
31         printf("%d finished\n", $p1->{pid}) if $p1->{stop};
32         printf("%d finished\n", $p2->{pid}) if $p2->{stop};
33
34         # detach ourself to run as a daemon
35         proc_detach(callback => sub { print("started with pid $_[0]\n")});
36

DESCRIPTION

38       This module eases process handling by providing high level functions to
39       start, monitor and stop processes. All the functions die() on error.
40
41       It also provides the $No::Worries::Proc::Transient variable that
42       indicates, after a fork(), which process is transient and is about to
43       exec() or exit().  This is useful for instance in an END block:
44
45         END {
46             # remove our pid file unless we are transient
47             pf_unset($pidfile) unless $No::Worries::Proc::Transient;
48         }
49

FUNCTIONS

51       This module provides the following functions (none of them being
52       exported by default):
53
54       proc_output(COMMAND...)
55           execute the given command, capture its output (stdout only), check
56           its exit code (report an error if it is not zero) and return the
57           captured output; this is similar to Perl's qx() operator but
58           bypassing the shell and always checking the exit code
59
60       proc_create(OPTIONS)
61           create a new process that will execute the given command and return
62           a hash reference representing this process (see the "PROCESS
63           STRUCTURE" sections for more information), to be given to
64           proc_monitor() or proc_terminate() afterwards; supported options:
65
66           •   "command": the command to execute, it must be an array
67               reference
68
69           •   "cwd": the current working directory of the new process
70
71           •   "timeout": the maximum number of seconds that the process is
72               allowed to take to run (can be fractional); after this, it may
73               be killed by proc_monitor()
74
75           •   "kill": how to "gently" kill the process, see below
76
77           •   "stdin": what to do with stdin, see below
78
79           •   "stdout": what to do with stdout, see below
80
81           •   "stderr": what to do with stderr, see below
82
83       proc_terminate(PROC[, OPTIONS])
84           terminate the given process (PROC can be either a process structure
85           or simply a process id) by sending signals and waiting for the
86           process to finish; supported options:
87
88           •   "kill": how to "gently" kill the process, see below
89
90       proc_monitor(PROCS[, OPTIONS])
91           monitor the given process(es) (as created by proc_create()); PROCS
92           can be either a single process or a reference to a list of
93           processes; supported options:
94
95           •   "timeout": the maximum number of seconds that proc_monitor()
96               should take, can be fractional
97
98           •   "bufsize": the buffer size to use for I/O operations (default:
99               8192)
100
101           •   "deaths": the minimum number of process deaths that
102               proc_monitor() will wait for before returning
103
104       proc_run(OPTIONS)
105           execute the given process (i.e. create and monitor it until
106           termination) and return its status (i.e. $?) in scalar context or
107           the whole process structure in list context; supported options: the
108           ones of proc_create()
109
110       proc_detach([OPTIONS])
111           detach the current process so that it becomes a daemon running in
112           the background (this implies forking and re-opening std*);
113           supported options:
114
115       proc_status(STATUS)
116           return a string representation of the given process status (i.e.
117           $?)
118
119           •   "callback": code reference that will be executed by the parent
120               process just before exiting and will be given the child pid
121

PROCESS STRUCTURE

123       The process structure (hash) used in this module has the following
124       fields:
125
126       •   "command": the command being executed, as an array reference
127
128       •   "pid": the process id
129
130       •   "start": the start time, in fractional seconds
131
132       •   "stop": the stop time, in fractional seconds
133
134       •   "status": the status (i.e. $?)
135
136       •   "timeout": true if the process has been killed because of timeout
137

FILE DESCRIPTOR REDIRECTION

139       When using the "stdin" option of proc_create(), the value can be:
140
141       •   a string: input will be read from the given file name
142
143       •   a scalar reference: input will be the scalar itself
144
145       When using the "stdout" and "stderr" options of proc_create(), the
146       value can be:
147
148       •   a string: output will be written to the given file name
149
150       •   a scalar reference: output will be stored in the scalar
151
152       •   a code reference: each time new output is available, the code will
153           be called with two parameters: the process structure and the new
154           output
155
156       In addition, "stderr" can also be given an empty string that means that
157       stderr should be merged with stdout.
158

KILL SPECIFICATION

160       Both proc_create() and proc_terminate() can be given a "kill" option
161       that specifies how the process should be killed.
162
163       The specification is a string containing a space separated list of
164       signal/grace couples, meaning: send the given signal and wait a bit for
165       the process to finish.
166
167       If not specified, the default is "TERM/1 INT/1 QUIT/1", meaning:
168
169       •   send SIGTERM and wait up to 1 second for the process to finish
170
171       •   if the process is still alive, send SIGINT and wait up to 1 second
172
173       •   if the process is still alive, send SIGQUIT and wait up to 1 second
174
175       •   if the process is still alive, send SIGKILL (implicit)
176

GLOBAL VARIABLES

178       This module uses the following global variables (none of them being
179       exported):
180
181       $Transient
182           true if the process is about to exec() or exit(), there is usually
183           no need to perform any cleanup (e.g. in an END block) for this kind
184           of process
185

AUTHOR

190       Lionel Cons <http://cern.ch/lionel.cons>
191
192       Copyright (C) CERN 2012-2019
193
194
195
196perl v5.36.0                      2023-01-20              No::Worries::Proc(3)