blib/lib/POE/Quickie.pm

filter: Statementstmt 86.3% 165 / 191 Branchbran 76.7% 66 / 86 Conditioncond 50.0% 12 / 24 MC/DCmcdc 21.4% 3 / 14 Subroutinesub 90.3% 28 / 31 Podpod 100% 9 / 9 totaltotal 79.7% 283 / 355 CC 56 SCAR 18.7
CC
56
Cov
81%
run
11.4
_child_signal
10.5
_create_wheel
9.2
CRAP 6.5
↑ Summary
1 package POE::Quickie;
2 10 ▶BEGIN {
Subroutine BEGIN: called CC=1 SCAR=0.0
3 10 $POE::Quickie::AUTHORITY = 'cpan:HINRIK';
4 }
5 10 ▶BEGIN {
Subroutine BEGIN: called CC=1 SCAR=0.0
6 10 $POE::Quickie::VERSION = '0.18';
7 }
8  
9 10 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
10 10 ▶use warnings FATAL => 'all';
Subroutine BEGIN: called CC=1 SCAR=0.0
11 10 ▶use Carp 'croak';
Subroutine BEGIN: called CC=1 SCAR=0.0
12 10 ▶use POE;
Subroutine BEGIN: called CC=1 SCAR=0.0
13 10 ▶use POE::Filter::Stream;
Subroutine BEGIN: called CC=1 SCAR=0.0
14 10 ▶use POE::Wheel::Run;
Subroutine BEGIN: called CC=1 SCAR=0.0
15  
16 10 require Exporter;
17 10 ▶use base 'Exporter';
Subroutine BEGIN: called CC=1 SCAR=0.0
18 10 our @EXPORT = qw(quickie_run quickie quickie_merged quickie_tee quickie_tee_merged);
19 10 our @EXPORT_OK = @EXPORT;
20 10 our %EXPORT_TAGS = (ALL => [@EXPORT]);
21  
22 10 our %OBJECTS;
23  
24 15 ▶sub new {
Subroutine new: called CC=2 SCAR=6.9
Pod documented
25 15 my ($package, %args) = @_;
26  
27 15 my $parent_id = $poe_kernel->get_active_session->ID;
28 15 ▶ if (my $self = $OBJECTS{$parent_id}) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $self = $POE::Quickie::OBJECTS{$parent_id}) 6 9 15
29 6 return $self;
30 }
31  
32 9 my $self = bless \%args, $package;
33 9 $self->{parent_id} = $parent_id;
34 9 $OBJECTS{$parent_id} = $self;
35  
36 9 return $self;
37 }
38  
39 13 ▶sub _create_session {
Subroutine _create_session: called CC=4 SCAR=15.2
40 13 my ($self) = @_;
41  
42 POE::Session->create(
43 object_states => [
44 $self => [qw(
45 _start
46 _stop
47 _exception
48 _create_wheel
49 _child_signal
50 _child_timeout
51 _child_stdin
52 _child_stdout
53 _child_stderr
54 _killall
55 )],
56 ],
57 options => {
58 ($self->{debug} ? (debug => 1) : ()),
59 ($self->{default} ? (default => 1) : ()),
60 13 ▶ ($self->{trace} ? (trace => 1) : ()),
Branch: 3 branches
BranchTrueFalseTotal
$self->{'debug'} ? : 0 13 13
$self->{'default'} ? : 0 13 13
$self->{'trace'} ? : 0 13 13
61 },
62 );
63  
64 13 return;
65 }
66  
67 13 ▶sub _start {
Subroutine _start: called CC=1 SCAR=0.0
68 13 my ($kernel, $session, $self) = @_[KERNEL, SESSION, OBJECT];
69  
70 13 my $session_id = $session->ID;
71 13 $self->{session_id} = $session_id;
72 13 $kernel->sig(DIE => '_exception');
73 13 return;
74 }
75  
76 13 ▶sub _stop {
Subroutine _stop: called CC=1 SCAR=0.0
77 13 my $self = $_[OBJECT];
78 13 delete $self->{session_id};
79 13 return;
80 }
81  
82 14 ▶sub run {
Subroutine run: called CC=9 SCAR=24.4
Pod documented
83 14 my ($self, %args) = @_;
84 14 ▶ $self = POE::Quickie->new() if ref $self ne 'POE::Quickie';
Branch: 1 branch
BranchTrueFalseTotal
if ref $self ne "POE::Quickie" 2 12 14
85  
86 14 ▶ croak 'Program parameter not supplied' if !defined $args{Program};
Branch: 1 branch
BranchTrueFalseTotal
unless defined $args{"Program"} 0 14 14
87  
88 14 ▶ if ($args{AltFork} && ref $args{Program}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($args{"AltFork"} and ref $args{"Program"}) 0 14 14
Condition33%1/3
$args{"AltFork"} and ref $args{"Program"}
!ll&&!rl&&r
1400
MC/DC0%0/2
$args{"AltFork"} and ref $args{"Program"}
$args{"AltFork"} ref $args{"Program"}
Truth table33%1/3
A and B
A= $args{"AltFork"}B= ref $args{"Program"}
ABresult
0X0
100
111
89 0 croak 'Program must be a string when AltFork is enabled';
90 }
91  
92 14 ▶ if ($args{AltFork} && $^O eq 'Win32') {
Branch: 1 branch
BranchTrueFalseTotal
if ($args{"AltFork"} and $^O eq "Win32") 0 14 14
Condition33%1/3
$args{"AltFork"} and $^O eq "Win32"
!ll&&!rl&&r
1400
MC/DC0%0/2
$args{"AltFork"} and $^O eq "Win32"
$args{"AltFork"} $^O eq "Win32"
Truth table33%1/3
A and B
A= $args{"AltFork"}B= $^O eq "Win32"
ABresult
0X0
100
111
93 0 croak 'AltFork does not currently work on Win32';
94 }
95  
96 14 ▶ $self->_create_session() if !defined $self->{session_id};
Branch: 1 branch
BranchTrueFalseTotal
unless defined $self->{"session_id"} 13 1 14
97  
98 my ($exception, $wheel)
99 14 = $poe_kernel->call($self->{session_id}, '_create_wheel', \%args);
100  
101 # propagate possible exception from POE::Wheel::Run->new()
102 14 ▶ croak $exception if $exception;
Branch: 1 branch
BranchTrueFalseTotal
if $exception 1 13 14
103  
104 13 return $wheel->PID;
105 }
106  
107 14 ▶sub _create_wheel {
Subroutine _create_wheel: called CC=9 SCAR=22.2
108 14 my ($kernel, $self, $args) = @_[KERNEL, OBJECT, ARG0];
109  
110 14 my %data;
111 14 for my $arg (qw(AltFork Timeout Input Program Context ProgramArgs
112 StdoutEvent StderrEvent ExitEvent ResultEvent Tee Merged)) {
113 168 ▶ next if !exists $args->{$arg};
Branch: 1 branch
BranchTrueFalseTotal
unless exists $args->{$arg} 125 43 168
114 43 $data{$arg} = delete $args->{$arg};
115 }
116  
117 14 ▶ if ($data{AltFork}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($data{"AltFork"}) 0 14 14
118 0 my @inc = map { +'-I' => $_ } @INC;
119 0 $data{Program} = [$^X, @inc, '-e', $data{Program}];
120 }
121  
122 14 my $wheel;
123 14 eval {
124 $wheel = POE::Wheel::Run->new(
125 StdinFilter => POE::Filter::Stream->new(),
126 StdinEvent => '_child_stdin',
127 StdoutEvent => '_child_stdout',
128 StderrEvent => '_child_stderr',
129 Program => $data{Program},
130 (defined $data{ProgramArgs}
131 ? (ProgramArgs => $data{ProgramArgs})
132 14 ▶ : ()
Branch: 2 branches
BranchTrueFalseTotal
defined $data{'ProgramArgs'} ? : 1 13 14
$^O ne 'Win32' ? : 14 0 14
133 ),
134 ($^O ne 'Win32'
135 ? (CloseOnCall => 1)
136 : ()
137 ),
138 %$args,
139 );
140 };
141  
142 14 ▶ if ($@) {
Branch: 1 branch
BranchTrueFalseTotal
if ($@) 1 13 14
143 1 chomp $@;
144 1 return $@;
145 }
146  
147 13 $data{obj} = $wheel;
148 13 $data{extra_args} = $args;
149 13 $self->{wheels}{$wheel->ID} = \%data;
150  
151 13 ▶ if (defined $data{Input}) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $data{'Input'}) { } 1 12 13
152 1 $wheel->put($data{Input});
153 }
154 else {
155 12 $wheel->shutdown_stdin();
156 }
157  
158 13 ▶ if ($data{Timeout}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($data{"Timeout"}) 1 12 13
159 $data{alrm} =
160 1 $kernel->delay_set('_child_timeout', $data{Timeout}, $wheel->ID);
161 }
162  
163 13 $kernel->sig_child($wheel->PID, '_child_signal');
164  
165 13 return (undef, $wheel);
166 }
167  
168 0 ▶sub _exception {
Subroutine _exception: not called CC=1 SCAR=6.9
169 0 my ($kernel, $self, $ex) = @_[KERNEL, OBJECT, ARG1];
170 0 chomp $ex->{error_str};
171 warn __PACKAGE__.": Event $ex->{event} in session "
172 0 .$ex->{dest_session}->ID." raised exception:\n $ex->{error_str}\n";
173 0 $kernel->sig_handled();
174 0 return;
175 }
176  
177 13 ▶sub _child_signal {
Subroutine _child_signal: called CC=10 SCAR=23.5
178 13 my ($kernel, $self, $pid, $status) = @_[KERNEL, OBJECT, ARG1, ARG2];
179 13 my $id = $self->_pid_to_id($pid);
180  
181 13 my $data = $self->{wheels}{$id};
182  
183 13 my $s = $status >> 8;
184 13 ▶ if ($s != 0 && !exists $data->{ExitEvent}
Branch: 1 branch
BranchTrueFalseTotal
if ($s != 0 and not exists $data->{"ExitEvent"} and not exists $data->{"ResultEvent"}) 0 13 13
Condition50%3/6
$s != 0 and not exists $data->{"ExitEvent"} and not exists $data->{"ResultEvent"}
!ll&&!rl&&r
1300
$s != 0 and not exists $data->{"ExitEvent"}
!ll&&!rl&&r
1210
MC/DC0%0/3
$s != 0 and not exists $data->{"ExitEvent"} and not exists $data->{"ResultEvent"}
$s != 0 not exists $data->{"ExitEvent"} not exists $data->{"ResultEvent"}
Truth table50%2/4
A and not(B) and not(C)
A= $s != 0B= not exists $data->{"ExitEvent"}C= not exists $data->{"ResultEvent"}
ABCresult
0XX0
10X0
1100
1111
185 && !exists $data->{ResultEvent}) {
186 0 warn "Child $pid exited with nonzero status $s\n";
187 }
188  
189 13 ▶ $kernel->alarm_remove($data->{alrm}) if $data->{Timeout};
Branch: 1 branch
BranchTrueFalseTotal
if $data->{"Timeout"} 1 12 13
190 13 ▶ if ($data->{lazy}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($data->{"lazy"}) 8 5 13
191 $self->{lazy}{$id} = {
192 merged => $data->{merged},
193 stdout => $data->{stdout},
194 stderr => $data->{stderr},
195 8 status => $status,
196 }
197 }
198 13 delete $self->{wheels}{$id};
199  
200 13 ▶ if (defined $data->{ExitEvent}) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $data->{"ExitEvent"}) 2 11 13
201 $kernel->call(
202 $self->{parent_id},
203 $data->{ExitEvent},
204 $status,
205 $pid,
206 (defined $data->{Context}
207 ? $data->{Context}
208 2 ▶ : ()),
Branch: 1 branch
BranchTrueFalseTotal
defined $data->{'Context'} ? : 0 2 2
209 );
210 }
211  
212 13 ▶ if (defined $data->{ResultEvent}) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $data->{"ResultEvent"}) 2 11 13
213 $kernel->call(
214 $self->{parent_id},
215 $data->{ResultEvent},
216 $pid,
217 $data->{stdout},
218 $data->{stderr},
219 $data->{merged},
220 $status,
221 (defined $data->{Context}
222 ? $data->{Context}
223 2 ▶ : ()),
Branch: 1 branch
BranchTrueFalseTotal
defined $data->{'Context'} ? : 1 1 2
224 );
225 }
226  
227 13 return;
228 }
229  
230 1 ▶sub _child_timeout {
Subroutine _child_timeout: called CC=1 SCAR=0.0
231 1 my ($self, $id) = @_[OBJECT, ARG0];
232 1 $self->{wheels}{$id}{obj}->kill();
233 1 return;
234 }
235  
236 1 ▶sub _child_stdin {
Subroutine _child_stdin: called CC=1 SCAR=0.0
237 1 my ($self, $id) = @_[OBJECT, ARG0];
238 1 $self->{wheels}{$id}{obj}->shutdown_stdin();
239 1 return;
240 }
241  
242 10 ▶sub _child_stdout {
Subroutine _child_stdout: called CC=7 SCAR=19.7
243 10 my ($kernel, $self, $output, $id) = @_[KERNEL, OBJECT, ARG0, ARG1];
244  
245 10 my $data = $self->{wheels}{$id};
246  
247 10 ▶ if ($data->{lazy} || defined $data->{ResultEvent}) {
Branch: 3 branches
BranchTrueFalseTotal
if ($data->{'lazy'} or defined $data->{'ResultEvent'}) { } 8 2 10
elsif (not exists $data->{'StdoutEvent'}) { } 0 2 2
elsif (defined(my $event = $data->{'StdoutEvent'})) { } 2 0 2
Condition100%3/3
$data->{"lazy"} or defined $data->{"ResultEvent"}
l!l&&r!l&&!r
622
MC/DC100%2/2
$data->{"lazy"} or defined $data->{"ResultEvent"}
$data->{"lazy"} defined $data->{"ResultEvent"}
Truth table100%3/3
A or B
A= $data->{"lazy"}B= defined $data->{"ResultEvent"}
ABresult
1X1
011
000
248 8 push @{ $data->{merged} }, $output;
249 8 push @{ $data->{stdout} }, $output;
250  
251 8 ▶ if ($data->{lazy}{Tee}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($data->{"lazy"}{"Tee"}) 2 6 8
252 2 print $output, "\n";
253 }
254 }
255 elsif (!exists $data->{StdoutEvent}) {
256 0 print "$output\n";
257 }
258 elsif (defined (my $event = $data->{StdoutEvent})) {
259 2 my $context = $data->{Context};
260 $kernel->call(
261 $self->{parent_id},
262 $event,
263 $output,
264 $data->{obj}->PID,
265 2 ▶ (defined $context ? $context : ()),
Branch: 1 branch
BranchTrueFalseTotal
defined $context ? : 2 0 2
266 );
267 }
268  
269 10 return;
270 }
271  
272 6 ▶sub _child_stderr {
Subroutine _child_stderr: called CC=8 SCAR=21.0
273 6 my ($kernel, $self, $error, $id) = @_[KERNEL, OBJECT, ARG0, ARG1];
274  
275 6 my $data = $self->{wheels}{$id};
276  
277 6 ▶ if ($data->{lazy} || defined $data->{ResultEvent}) {
Branch: 3 branches
BranchTrueFalseTotal
if ($data->{'lazy'} or defined $data->{'ResultEvent'}) { } 4 2 6
elsif (not exists $data->{'StderrEvent'}) { } 0 2 2
elsif (defined(my $event = $data->{'StderrEvent'})) { } 1 1 2
Condition66%2/3
$data->{"lazy"} or defined $data->{"ResultEvent"}
l!l&&r!l&&!r
402
MC/DC50%1/2
$data->{"lazy"} or defined $data->{"ResultEvent"}
$data->{"lazy"} defined $data->{"ResultEvent"}
Truth table66%2/3
A or B
A= $data->{"lazy"}B= defined $data->{"ResultEvent"}
ABresult
1X1
011
000
278 4 push @{ $data->{merged} }, $error;
279 4 push @{ $data->{stderr} }, $error;
280  
281 4 ▶ if ($data->{lazy}{Tee}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($data->{"lazy"}{"Tee"}) 2 2 4
282 $data->{lazy}{Merged}
283 2 ▶ ? print $error, "\n"
Branch: 1 branch
BranchTrueFalseTotal
$data->{'lazy'}{'Merged'} ? : 1 1 2
284 : warn $error, "\n";
285 }
286 }
287 elsif (!exists $data->{StderrEvent}) {
288 0 warn "$error\n";
289 }
290 elsif (defined (my $event = $data->{StderrEvent})) {
291 1 my $context = $data->{Context};
292 $kernel->call(
293 $self->{parent_id},
294 $event,
295 $error,
296 $data->{obj}->PID,
297 1 ▶ (defined $context ? $context : ()),
Branch: 1 branch
BranchTrueFalseTotal
defined $context ? : 1 0 1
298 );
299 }
300  
301 6 return;
302 }
303  
304 19 ▶sub _pid_to_id {
Subroutine _pid_to_id: called CC=3 SCAR=11.7
305 19 my ($self, $pid) = @_;
306  
307 19 for my $id (keys %{ $self->{wheels} }) {
308 19 ▶ return $id if $self->{wheels}{$id}{obj}->PID == $pid;
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"wheels"}{$id}{"obj"}->PID == $pid 19 0 19
309 }
310  
311 0 return;
312 }
313  
314 0 ▶sub killall {
Subroutine killall: not called CC=2 SCAR=17.9
Pod documented
315 0 my $self = shift;
316 0 ▶ $self = POE::Quickie->new() if ref $self ne 'POE::Quickie';
Branch: 1 branch
BranchTrueFalseTotal
if ref $self ne "POE::Quickie" 0 0 0
317 0 $poe_kernel->call($self->{session_id}, '_killall', @_);
318 0 return;
319 }
320  
321 0 ▶sub _killall {
Subroutine _killall: not called CC=2 SCAR=17.9
322 0 my ($kernel, $self, $signal) = @_[KERNEL, OBJECT, ARG0];
323  
324 0 $kernel->alarm_remove_all();
325  
326 0 for my $id (keys %{ $self->{wheels}}) {
327 0 $self->{wheels}{$id}{obj}->kill($signal);
328 }
329  
330 0 return;
331 }
332  
333 1 ▶sub processes {
Subroutine processes: called CC=3 SCAR=11.0
Pod documented
334 1 my ($self) = @_;
335 1 ▶ $self = POE::Quickie->new() if ref $self ne 'POE::Quickie';
Branch: 1 branch
BranchTrueFalseTotal
if ref $self ne "POE::Quickie" 1 0 1
336  
337 1 my %wheels;
338 1 for my $id (keys %{ $self->{wheels} }) {
339 1 my $pid = $self->{wheels}{$id}{obj}->PID;
340 1 $wheels{$pid} = $self->{wheels}{$id}{Context};
341 }
342  
343 1 return \%wheels;
344 }
345  
346 6 ▶sub _lazy_run {
Subroutine _lazy_run: called CC=8 SCAR=21.5
347 6 my ($self, %args) = @_;
348  
349 6 my %run_args;
350 6 ▶ if (@{ $args{RunArgs} } == 1 &&
Branch: 1 branch
BranchTrueFalseTotal
if (@{$args{'RunArgs'};} == 1 and !ref($args{'RunArgs'}[0]) || ref($args{'RunArgs'}[0]) =~ /^(?:ARRAY|CODE)$/) { } 6 0 6
Condition33%2/6
@{$args{"RunArgs"};} == 1 and !ref($args{"RunArgs"}[0]) || ref($args{"RunArgs"}[0]) =~ /^(?:ARRAY|CODE)$/
!ll&&!rl&&r
006
not ref $args{"RunArgs"}[0] or ref($args{"RunArgs"}[0]) =~ /^(?:ARRAY|CODE)$/
l!l&&r!l&&!r
060
MC/DC0%0/3
@{$args{"RunArgs"};} == 1 and !ref($args{"RunArgs"}[0]) || ref($args{"RunArgs"}[0]) =~ /^(?:ARRAY|CODE)$/
@{$args{"RunArgs"};} == 1 not ref $args{"RunArgs"}[0] ref($args{"RunArgs"}[0]) =~ /^(?:ARRAY|CODE)$/
Truth table25%1/4
A and not(B) or C
A= @{$args{"RunArgs"};} == 1B= not ref $args{"RunArgs"}[0]C= ref($args{"RunArgs"}[0]) =~ /^(?:ARRAY|CODE)$/
ABCresult
0XX0
1000
11X1
1011
351 (!ref $args{RunArgs}[0] || ref ($args{RunArgs}[0]) =~ /^(?:ARRAY|CODE)$/)) {
352 6 $run_args{Program} = $args{RunArgs}[0];
353 }
354 else {
355 0 %run_args = @{ $args{RunArgs} };
356 }
357  
358 my $pid = $self->run(
359 %run_args,
360 ExitEvent => undef,
361 ($args{Tee} ? () : (StderrEvent => undef)),
362 6 ▶ ($args{Tee} ? () : (StdoutEvent => undef)),
Branch: 2 branches
BranchTrueFalseTotal
$args{'Tee'} ? : 2 4 6
$args{'Tee'} ? : 2 4 6
363 );
364  
365 6 my $id = $self->_pid_to_id($pid);
366 $self->{wheels}{$id}{lazy} = {
367 Tee => $args{Tee},
368 Merged => $args{Merged},
369 6 };
370  
371 6 my $parent_id = $poe_kernel->get_active_session->ID;
372 6 $poe_kernel->refcount_increment($parent_id, __PACKAGE__);
373 6 ▶ $poe_kernel->run_one_timeslice() while $self->{wheels}{$id};
Branch: 1 branch
BranchTrueFalseTotal
$self->{"wheels"}{$id} and do { $POE::Quickie::poe_kernel->run_one_timeslice } 36 6 42
374 6 $poe_kernel->refcount_decrement($parent_id, __PACKAGE__);
375  
376 6 my $data = delete $self->{lazy}{$id};
377 6 ▶ return $data->{merged}, $data->{status} if $args{Merged};
Branch: 1 branch
BranchTrueFalseTotal
if $args{"Merged"} 2 4 6
378 4 return $data->{stdout}, $data->{stderr}, $data->{status};
379 }
380  
381 2 ▶sub quickie_run {
Subroutine quickie_run: called CC=1 SCAR=0.0
Pod documented
382 2 my %args = @_;
383 2 my $self = POE::Quickie->new();
384 2 return $self->run(%args);
385 }
386  
387 3 ▶sub quickie {
Subroutine quickie: called CC=1 SCAR=0.0
Pod documented
388 3 my @args = @_;
389 3 my $self = POE::Quickie->new();
390  
391 3 return $self->_lazy_run(
392 RunArgs => \@args
393 );
394 }
395  
396 1 ▶sub quickie_tee {
Subroutine quickie_tee: called CC=1 SCAR=0.0
Pod documented
397 1 my @args = @_;
398 1 my $self = POE::Quickie->new();
399 1 return $self->_lazy_run(
400 RunArgs => \@args,
401 Tee => 1,
402 );
403 }
404  
405 1 ▶sub quickie_merged {
Subroutine quickie_merged: called CC=1 SCAR=0.0
Pod documented
406 1 my @args = @_;
407 1 my $self = POE::Quickie->new();
408  
409 1 return $self->_lazy_run(
410 RunArgs => \@args,
411 Merged => 1,
412 );
413 }
414  
415 1 ▶sub quickie_tee_merged {
Subroutine quickie_tee_merged: called CC=1 SCAR=0.0
Pod documented
416 1 my @args = @_;
417 1 my $self = POE::Quickie->new();
418  
419 1 return $self->_lazy_run(
420 RunArgs => \@args,
421 Tee => 1,
422 Merged => 1,
423 );
424 }
425  
426 10 1;
427  
428 =encoding utf8
429  
430 =head1 NAME
431  
432 POE::Quickie - A lazy way to wrap blocking code and programs
433  
434 =head1 SYNOPSIS
435  
436 use POE::Quickie;
437  
438 sub event_handler {
439 # the "I'll wait until it's finished" approach, which will block your
440 # session until the command has finished
441 my ($stdout, $stderr, $exit_status) = quickie('foo.pl');
442 print $stdout;
443  
444 # the "keep me posted" approach, which will give you each line of output
445 # as it is appears
446 quickie_run(
447 Program => ['foo.pl', 'bar'],
448 StdoutEvent => 'stdout',
449 Context => 'remember this',
450 );
451  
452 # the "get back to me when it's done" approach, which will notify you
453 # of the entire output when the command has finished
454 quickie_run(
455 Program => ['foo.pl', 'bar'],
456 Context => 'remember this',
457 ResultEvent => 'result',
458 );
459 }
460  
461 sub stdout {
462 my ($output, $context) = @_[ARG0, ARG1];
463 print "got output: '$output' in the context of '$context'\n";
464 }
465  
466 sub result {
467 my ($pid, $stdout, $stderr, $merged, $status, $context) = @_[ARG0..$#_];
468 print "got all this output in the context of '$context':\n";
469 print "$_\n" for @$stdout;
470 }
471  
472 =head1 DESCRIPTION
473  
474 If you need nonblocking access to an external program, or want to execute
475 some blocking code in a separate process, but you don't want to write a
476 wrapper module or some L<POE::Wheel::Run|POE::Wheel::Run> boilerplate code,
477 then POE::Quickie can help. You just specify what you're interested in
478 (stdout, stderr, and/or exit code), and POE::Quickie will handle the rest in
479 a sensible way.
480  
481 It has some convenience features, such as killing processes after a timeout,
482 and storing process-specific context information which will be delivered with
483 every event.
484  
485 There is also an even lazier API which suspends the execution of your event
486 handler and gives control back to POE while your task is running, the same
487 way L<LWP::UserAgent::POE|LWP::UserAgent::POE> does. This is provided by the
488 L<C<quickie_*>|/FUNCTIONS> functions which are exported by default.
489  
490 =head1 METHODS
491  
492 =head2 C<new>
493  
494 Constructs a POE::Quickie object. You only need to do this if you want to
495 specify any of the parameters below, since a POE::Quickie object will be
496 constructed automatically when it is needed. The rest of the methods can
497 be called on the object (C<< $object->run() >>) or as class methods
498 (C<< POE::Quickie->run() >>). You can safely let the object go out of scope;
499 POE::Quickie will continue to run your processes until they finish.
500  
501 Takes 3 optional parameters: B<'debug'>, B<'default'>, and B<'trace'>. These
502 will be passed to the object's L<POE::Session|POE::Session> constructor. See
503 its documentation for details.
504  
505 =head2 C<run>
506  
507 This method spawns a new child process. It returns its process id.
508  
509 You can either call it with a single argument (string, arrayref, or coderef),
510 which will used as the B<'Program'> argument, or you can supply the following
511 key-value pairs:
512  
513 B<'Program'> (required), will be passed to directly to
514 L<POE::Wheel::Run|POE::Wheel::Run/new>'s constructor.
515  
516 B<'ProgramArgs'> (optional), will be passed directly to
517 L<POE::Wheel::Run|POE::Wheel::Run/new>'s constructor.
518  
519 B<'Input'> (optional), a string containing the input to the process. This
520 string, if provided, will be sent immediately to the child, and its stdin
521 will then be shut down. B<Note:> no processing will be done on the data
522 before it is sent. For instance, if you are executing a program which expects
523 line-based input, be sure to end your input with a newline.
524  
525 B<'StdoutEvent'> (optional), the event for delivering lines from the
526 process' STDOUT. If you don't supply this, they will be printed to the main
527 process's STDOUT. To explicitly ignore them, set this to C<undef>.
528  
529 B<'StderrEvent'> (optional), the event for delivering lines from the
530 process' STDERR. If you don't supply this, they will be printed to the main
531 process' STDERR. To explicitly ignore them, set this to C<undef>.
532  
533 B<'ExitEvent'> (optional), the event to be called when the process has exited.
534 If you don't supply this, a warning indicating the exit code will be printed
535 if it is nonzero. To explicitly ignore it, set this to C<undef>.
536  
537 B<'ResultEvent'> (optional), like 'ExitEvent', but it will also contain all
538 the stdout/stderr generated by the child process.
539  
540 B<'Context'> (optional), a variable which will be sent back to you with every
541 event. If you pass a reference, that same reference will be delivered back
542 to you later (not a copy), so you can update it as you see fit.
543  
544 B<'Timeout'> (optional), a timeout in seconds after which the process will
545 be forcibly L<killed|POE::Wheel::Run/kill> if it is still running. There is
546 no timeout by default.
547  
548 B<'AltFork'> (optional), if true, a new instance of the active Perl
549 interpreter (L<C<$^X>|perlvar>) will be launched with B<'Program'> (which
550 must be a string) as the code argument (L<I<-e>|perlrun>), and the current
551 L<C<@INC>|perlvar> passed as include arguments (L<I<-I>|perlrun>). Default
552 is false.
553  
554 All other arguments will be passed to POE::Wheel::Run's
555 L<C<new>|POE::Wheel::Run/new> method. Useful if you want to specify the
556 input/output filters and such.
557  
558 =head2 C<killall>
559  
560 This L<kills|POE::Wheel::Run/kill> all processes which POE::Quickie is
561 managing for your session. Takes one optional argument, a signal name (e.g.
562 B<'SIGTERM'>).
563  
564 =head2 C<processes>
565  
566 Returns a hash reference of all the currently running processes. The key
567 is the process id, and the value is the context variable, if any.
568  
569 =head1 OUTPUT
570  
571 The following events might get sent to your session. The names correspond
572 to the options to L<C<run>|/run>.
573  
574 =head2 StdoutEvent
575  
576 =over 4
577  
578 =item C<ARG0>: the chunk of STDOUT generated by the process
579  
580 =item C<ARG1>: the process id of the child process
581  
582 =item C<ARG2>: the context variable, if any
583  
584 =back
585  
586 =head2 StderrEvent
587  
588 =over 4
589  
590 =item C<ARG0>: the chunk of STDERR generated by the process
591  
592 =item C<ARG1>: the process id of the child process
593  
594 =item C<ARG2>: the context variable, if any
595  
596 =back
597  
598 =head2 ExitEvent
599  
600 =over 4
601  
602 =item C<ARG0>: the exit code (L<C<$?>|perlvar>) of the child process
603  
604 =item C<ARG1>: the process id of the child process
605  
606 =item C<ARG2>: the context variable, if any
607  
608 =head2 ResultEvent
609  
610 =over 4
611  
612 =item C<ARG0>: the process id of the child process
613  
614 =item C<ARG1>: an array of every chunk of stdout generated by the child process
615  
616 =item C<ARG2>: an array of every chunk of stderr generated by the child process
617  
618 =item C<ARG3>: an array of the interleaved stdout and stderr chunks
619  
620 =item C<ARG4>: the exit code (L<C<$?>|perlvar>) of the child process
621  
622 =item C<ARG5>: the context variable, if any
623  
624 =back
625  
626 =back
627  
628 =head1 FUNCTIONS
629  
630 =head2 C<quickie_run>
631  
632 Equivalent to C<< POE::Quickie->run() >>, provided as a convenience.
633  
634 =head2 Blocking functions
635  
636 The following functions are modeled after the ones provided by
637 L<Capture::Tiny|Capture::Tiny>. They will not return until the executed
638 process has exited. However,
639 L<C<run_one_timeslice>|POE::Kernel/run_one_timeslice> in POE::Kernel will be
640 called in the meantime, so the rest of your application will continue to run.
641  
642 They all take the same arguments as the L<C<run>|/run> method, except for the
643 B<'*Event'> and B<'Context'> arguments.
644  
645 B<Note:> Since these functions block, you must be careful not to call them in
646 event handlers which were executed with C<< $poe_kernel->call() >> by other
647 sessions, so you don't hold them up. A simple way to avoid that is to
648 C<yield()> or C<post()> a new event to your session and do it from there.
649  
650 =head3 C<quickie>
651  
652 Returns 3 values: the stdout, stderr, and exit code (L<C<$?>|perlvar>) of the
653 child process.
654  
655 =head3 C<quickie_tee>
656  
657 Returns 3 values: an array of all stdout chunks, an array of all stderr
658 chunks, and the exit code (L<C<$?>|perlvar>) of the child process. In addition,
659 it will echo the stdout/stderr to your process' stdout/stderr.
660  
661 =head3 C<quickie_merged>
662  
663 Returns 2 values: an array of interleaved stdout and stderr chunks, and the
664 exit code (L<C<$?>|perlvar>) of the child process. Beware that stdout and
665 stderr in the merged result are not guaranteed to be properly ordered due to
666 buffering.
667  
668 =head3 C<quickie_tee_merged>
669  
670 Returns 2 values: an array of interleaved stdout and stderr chunks, and the
671 exit code (L<C<$?>|perlvar>) of the child process. In addition, it will echo
672 the merged stdout & stderr to your process' stdout. Beware that stdout and
673 stderr in the merged result are not guaranteed to be properly ordered due to
674 buffering.
675  
676 =head1 AUTHOR
677  
678 Hinrik E<Ouml>rn SigurE<eth>sson, hinrik.sig@gmail.com
679  
680 =head1 LICENSE AND COPYRIGHT
681  
682 Copyright 2010-2011 Hinrik E<Ouml>rn SigurE<eth>sson
683  
684 This program is free software, you can redistribute it and/or modify
685 it under the same terms as Perl itself.
686  
687 =cut
↑ Summary