blib/lib/Venus/Process.pm

filter: Statementstmt 89.9% 583 / 648 Branchbran 80.8% 199 / 246 Conditioncond 61.9% 26 / 42 MC/DCmcdc 25.0% 6 / 24 Subroutinesub 83.1% 94 / 113 Podpod 79.5% 66 / 83 totaltotal 84.2% 974 / 1156 CC 149 SCAR 13.3
CC
149
Cov
86%
__ANON__
12.7
fork
8.0
poll
7.3
CRAP 3.8
« blib/lib/Venus/String.pm ↑ Summary blib/lib/Venus/Role/Coercible.pm »
1 package Venus::Process;
2  
3 2 ▶use 5.018;
Subroutine BEGIN: called CC=1 SCAR=0.0
4  
5 2 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
6 2 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
7  
8 # IMPORTS
9  
10 2 ▶use Venus::Class 'attr', 'base', 'with';
Subroutine BEGIN: called CC=1 SCAR=0.0
11  
12 # INHERITS
13  
14 2 base 'Venus::Kind::Utility';
15  
16 # INTEGRATES
17  
18 2 with 'Venus::Role::Valuable';
19 2 with 'Venus::Role::Buildable';
20 2 with 'Venus::Role::Accessible';
21 2 with 'Venus::Role::Explainable';
22  
23 # STATE
24  
25 2 require Config;
26 2 require Cwd;
27 2 require File::Spec;
28 2 require POSIX;
29  
30 2 our $CWD = Cwd->getcwd;
31 2 our $ERROR;
32 2 our $MAPSIG = {%SIG};
33 2 our $PATH = $CWD;
34 2 our $PID = $$;
35 2 our $PPID;
36  
37 # OVERLOADS
38  
39 2 ▶use overload (
Subroutine BEGIN: called CC=1 SCAR=0.0
40 2 '""' => 'explain',
41 '~~' => 'explain',
42 fallback => 1,
43 2 );
44  
45 # ATTRIBUTES
46  
47 2 attr 'alarm';
48  
49 # BUILDERS
50  
51 364 ▶sub build_self {
Subroutine build_self: called CC=2 SCAR=7.1
Pod undocumented
52 364 my ($self, $data) = @_;
53  
54 364 ▶ $PID = $self->value if $self->value;
Branch: 1 branch
BranchTrueFalseTotal
if $self->value 364 0 364
55  
56 364 return $self;
57 }
58  
59 # HOOKS
60  
61 0 ▶sub _alarm {
Subroutine _alarm: not called CC=1 SCAR=6.9
62 0 CORE::alarm(shift);
63 }
64  
65 0 ▶sub _chdir {
Subroutine _chdir: not called CC=1 SCAR=6.9
66 0 CORE::chdir(shift);
67 }
68  
69 0 ▶sub _exit {
Subroutine _exit: not called CC=1 SCAR=6.9
70 0 POSIX::_exit(shift);
71 }
72  
73 0 ▶sub _exitcode {
Subroutine _exitcode: not called CC=1 SCAR=6.9
74 0 $? >> 8;
75 }
76  
77 0 ▶sub _fork {
Subroutine _fork: not called CC=1 SCAR=6.9
78 0 CORE::fork();
79 }
80  
81 0 ▶sub _forkable {
Subroutine _forkable: not called CC=2 SCAR=17.9
82 0 ▶ $Config::Config{d_pseudofork} ? 0 : 1;
Branch: 1 branch
BranchTrueFalseTotal
$Config::Config{'d_pseudofork'} ? : 0 0 0
83 }
84  
85 0 ▶sub _serve {
Subroutine _serve: not called CC=1 SCAR=6.9
86 0 true;
87 }
88  
89 0 ▶sub _kill {
Subroutine _kill: not called CC=1 SCAR=6.9
90 0 CORE::kill(@_);
91 }
92  
93 0 ▶sub _open {
Subroutine _open: not called CC=1 SCAR=6.9
94 0 CORE::open(shift, shift, shift);
95 }
96  
97 0 ▶sub _ping {
Subroutine _ping: not called CC=1 SCAR=6.9
98 0 _kill(0, @_);
99 }
100  
101 0 ▶sub _setsid {
Subroutine _setsid: not called CC=1 SCAR=6.9
102 0 POSIX::setsid();
103 }
104  
105 0 ▶sub _time {
Subroutine _time: not called CC=1 SCAR=6.9
106 0 CORE::time();
107 }
108  
109 0 ▶sub _waitpid {
Subroutine _waitpid: not called CC=1 SCAR=6.9
110 0 CORE::waitpid(shift, shift);
111 }
112  
113 # METHODS
114  
115 14 ▶sub async {
Subroutine async: called CC=1 SCAR=0.2
Pod documented
116 14 my ($self, $code, @args) = @_;
117  
118 14 require Venus::Path;
119  
120 14 my $path = $PATH;
121  
122 14 $PATH = Venus::Path->mktemp_dir->absolute->value;
123  
124 14 my $parent = $self->class->new;
125  
126 14 $parent->{directory} = $PATH;
127  
128 14 $parent->register;
129  
130 13 ▶ my $pid = $parent->work(sub{
Subroutine __ANON__: called CC=4 SCAR=15.2
131 13 my ($process) = @_;
132  
133 13 $process->untrap;
134  
135 13 $process->{directory} = $PATH;
136  
137 13 $process->register;
138  
139 13 $process->watch($process->ppid);
140  
141 13 $process->ppid(undef);
142  
143 13 my $error;
144  
145 13 my $result = $process->try($code, @args)->error(\$error)->result;
146  
147 13 ▶ if (defined $error) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $error) 0 13 13
148 0 require Scalar::Util;
149 0 require Venus::Error;
150 0 ▶ $error = Venus::Error->new($error) if !Scalar::Util::blessed($error);
Branch: 1 branch
BranchTrueFalseTotal
unless builtin::blessed($error) 0 0 0
151 0 $result = $error;
152 }
153  
154 13 ▶ $process->sendall($result) if defined $result;
Branch: 1 branch
BranchTrueFalseTotal
if defined $result 11 2 13
155  
156 13 return;
157 14 });
158  
159 14 $parent->watch($pid);
160  
161 0 ▶ $parent->trap(int => sub {
Subroutine __ANON__: not called CC=1 SCAR=6.9
162 0 $parent->killall;
163 14 });
164  
165 0 ▶ $parent->trap(term => sub {
Subroutine __ANON__: not called CC=1 SCAR=6.9
166 0 $parent->killall;
167 14 });
168  
169 14 $PATH = $path;
170  
171 14 return $parent;
172 }
173  
174 14 ▶sub await {
Subroutine await: called CC=6 SCAR=18.1
Pod documented
175 14 my ($self, $timeout) = @_;
176  
177 14 my $path = $PATH;
178  
179 14 $PATH = $self->{directory};
180  
181 14 my $result = [];
182  
183 14 ▶ if (defined $timeout) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $timeout) { } 7 7 14
184 7 ▶ if ($timeout == 0) {
Branch: 1 branch
BranchTrueFalseTotal
if ($timeout == 0) { } 7 0 7
185 7 (my $error, @{$result}) = $self->catch('recvall');
186 }
187 else {
188 0 (my $error, @{$result}) = $self->catch('poll', $timeout, 'recvall');
189 }
190 }
191 else {
192 7 ▶ do{@{$result} = $self->recvall} while !@{$result};
Branch: 1 branch
BranchTrueFalseTotal
@{$result;} or do { do { @{$result;} = $self->recvall } } 7 0 7
193 }
194  
195 14 $self->check($_) for ($self->watchlist);
196  
197 14 $PATH = $path;
198  
199 14 ▶ return wantarray ? (@{$result}) : $result;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 12 2 14
200 }
201  
202 7 ▶sub chdir {
Subroutine chdir: called CC=3 SCAR=11.0
Pod documented
203 7 my ($self, $path) = @_;
204  
205 7 ▶ $path ||= $CWD;
Condition66%2/3
$path ||= $Venus::Process::CWD
l!l&&r!l&&!r
520
MC/DC0%0/2
$path ||= $Venus::Process::CWD
$path $Venus::Process::CWD
Truth table66%2/3
A ||= B
A= $pathB= $Venus::Process::CWD
ABresult
1X1
011
000
206  
207 7 ▶ _chdir($path) or do {
Branch: 1 branch
BranchTrueFalseTotal
_chdir($path) or do { my $error = $!; $self->error_on_chdir({"path", $path, "pid", $Venus::Process::PID, "error", $error})->input($self, $path)->output($error)->throw } 6 1 7
208 1 my $error = $!;
209 1 $self->error_on_chdir({path => $path, pid => $PID, error => $error})
210 ->input($self, $path)
211 ->output($error)
212 ->throw;
213 };
214  
215 6 return $self;
216 }
217  
218 42 ▶sub check {
Subroutine check: called CC=2 SCAR=6.9
Pod documented
219 42 my ($self, $pid) = @_;
220  
221 42 my $result = _waitpid($pid, POSIX::WNOHANG());
222  
223 42 ▶ return wantarray ? ($result, _exitcode) : $result;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 27 15 42
224 }
225  
226 52 ▶sub count {
Subroutine count: called CC=4 SCAR=14.3
Pod documented
227 52 my ($self, $code, @args) = @_;
228  
229 52 ▶ $code ||= 'watchlist';
Condition100%2/2
$code ||= "watchlist"
l!l
151
MC/DC100%1/1
$code ||= "watchlist"
$code
Truth table100%2/2
A
A= $code
Aresult
11
00
230  
231 52 my @result = $self->$code(@args);
232  
233 0 ▶ my $count = (@result == 1 && ref $result[0] eq 'ARRAY') ? @{$result[0]} : @result;
Branch: 1 branch
BranchTrueFalseTotal
@result == 1 && ref $result[0] eq 'ARRAY' ? : 0 52 52
Condition66%2/3
@result == 1 and ref $result[0] eq "ARRAY"
!ll&&!rl&&r
20320
MC/DC0%0/2
@result == 1 and ref $result[0] eq "ARRAY"
@result == 1 ref $result[0] eq "ARRAY"
Truth table66%2/3
A and B
A= @result == 1B= ref $result[0] eq "ARRAY"
ABresult
0X0
100
111
234  
235 52 return $count;
236 }
237  
238 1 ▶sub daemon {
Subroutine daemon: called CC=2 SCAR=7.6
Pod documented
239 1 my ($self) = @_;
240  
241 1 ▶ if (my $process = $self->fork) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $process = $self->fork) { } 1 0 1
242 1 return $process->disengage->do('setsid');
243 }
244 else {
245 0 return $self->exit;
246 }
247 }
248  
249 12 ▶sub data {
Subroutine data: called CC=7 SCAR=19.5
Pod documented
250 12 my ($self, @args) = @_;
251  
252 12 ▶ my @pids = @args ? @args : ($self->watchlist);
Branch: 1 branch
BranchTrueFalseTotal
@args ? : 3 9 12
253  
254 12 ▶ return 0 if !@pids;
Branch: 1 branch
BranchTrueFalseTotal
unless @pids 0 12 12
255  
256 12 my $result = 0;
257  
258 12 require Venus::Path;
259  
260 12 my $path = Venus::Path->new($PATH);
261  
262 12 ▶ $path = $path->child($self->exchange) if $self->exchange;
Branch: 1 branch
BranchTrueFalseTotal
if $self->exchange 8 4 12
263  
264 12 for my $pid (@pids) {
265 20 ▶ next if !(my $pdir = $path->child($self->recv_key($pid)))->exists;
Branch: 1 branch
BranchTrueFalseTotal
unless (my $pdir = $path->child($self->recv_key($pid)))->exists 1 19 20
266  
267 2 ▶ $result += 1 for CORE::glob($pdir->child('*.data')->absolute);
Subroutine BEGIN: called CC=1 SCAR=0.0
268 }
269  
270 12 return $result;
271 }
272  
273 39 ▶sub decode {
Subroutine decode: called CC=1 SCAR=0.0
Pod documented
274 39 my ($self, $data) = @_;
275  
276 39 require Venus::Dump;
277  
278 39 return Venus::Dump->new->decode($data);
279 }
280  
281 0 ▶sub default {
Subroutine default: not called CC=1 SCAR=6.9
282 0 return $PID;
283 }
284  
285 2 ▶sub disengage {
Subroutine disengage: called CC=2 SCAR=6.9
Pod documented
286 2 my ($self) = @_;
287  
288 2 $self->chdir(File::Spec->rootdir);
289  
290 2 $self->$_(File::Spec->devnull) for qw(stdin stdout stderr);
291  
292 2 return $self;
293 }
294  
295 47 ▶sub encode {
Subroutine encode: called CC=1 SCAR=0.0
Pod documented
296 47 my ($self, $data) = @_;
297  
298 47 require Venus::Dump;
299  
300 47 return Venus::Dump->new($data)->encode;
301 }
302  
303 1 ▶sub engage {
Subroutine engage: called CC=2 SCAR=6.9
Pod documented
304 1 my ($self) = @_;
305  
306 1 $self->chdir;
307  
308 1 $self->$_ for qw(stdin stdout stderr);
309  
310 1 return $self;
311 }
312  
313 466 ▶sub exchange {
Subroutine exchange: called CC=2 SCAR=6.9
Pod documented
314 466 my ($self, $name) = @_;
315  
316 466 ▶ return $name ? ($self->{exchange} = $name) : $self->{exchange};
Branch: 1 branch
BranchTrueFalseTotal
$name ? : 15 451 466
317 }
318  
319 57 ▶sub exit {
Subroutine exit: called CC=2 SCAR=6.9
Pod documented
320 57 my ($self, $code) = @_;
321  
322 57 ▶ return _exit($code // 0);
Condition100%2/2
$code // 0
l!l
156
MC/DC100%1/1
$code // 0
$code
Truth table100%2/2
A
A= $code
Aresult
11
00
323 }
324  
325 102 ▶sub explain {
Subroutine explain: called CC=1 SCAR=0.0
Pod undocumented
326 102 my ($self) = @_;
327  
328 102 return $self->get;
329 }
330  
331 2 ▶sub followers {
Subroutine followers: called CC=2 SCAR=7.2
Pod documented
332 2 my ($self) = @_;
333  
334 2 my $leader = $self->leader;
335  
336 2 my $result = [sort grep {$_ != $leader} $self->others_active, $self->pid];
337  
338 0 ▶ return wantarray ? @{$result} : $result;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 0 2 2
339 }
340  
341 160 ▶sub fork {
Subroutine fork: called CC=8 SCAR=20.8
Pod documented
342 160 my ($self, $code, @args) = @_;
343  
344 160 ▶ if (not(_forkable())) {
Branch: 1 branch
BranchTrueFalseTotal
unless (_forkable()) 1 159 160
345 1 $self->error_on_fork_support({pid => $PID})->throw;
346 }
347 159 ▶ if (defined(my $pid = _fork())) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined(my $pid = _fork())) { } 159 0 159
348 159 ▶ if ($pid) {
Branch: 1 branch
BranchTrueFalseTotal
if ($pid) 106 53 159
349 106 $self->watch($pid);
350 106 ▶ return wantarray ? (undef, $pid) : undef;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 29 77 106
351 }
352  
353 53 $PPID = $PID;
354 53 $PID = $$;
355 53 my $process = $self->class->new;
356 53 my $orig_seed = srand;
357 53 my $self_seed = substr(((time ^ $$) ** 2), 0, length($orig_seed));
358 53 srand $self_seed;
359  
360 53 ▶ _alarm($self->alarm) if defined $self->alarm;
Branch: 1 branch
BranchTrueFalseTotal
if defined $self->alarm 1 52 53
361  
362 53 ▶ if ($code) {
Branch: 1 branch
BranchTrueFalseTotal
if ($code) 22 31 53
363 22 local $_ = $process;
364 22 $process->$code(@args);
365 }
366  
367 53 ▶ return wantarray ? ($process, $PID) : $process;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 24 29 53
368 }
369 else {
370 0 my $error = $!;
371 0 $self->error_on_fork_process({error => $error, pid => $PID})->throw;
372 }
373 }
374  
375 3 ▶sub forks {
Subroutine forks: called CC=7 SCAR=19.5
Pod documented
376 3 my ($self, $count, $code, @args) = @_;
377  
378 3 my $pid;
379 my @pids;
380 3 my $process;
381  
382 3 ▶ for (my $i = 1; $i <= ($count || 0); $i++) {
Branch: 1 branch
BranchTrueFalseTotal
if ($i <= ($count || 0)) 7 1 8
Condition50%1/2
$count || 0
l!l
80
MC/DC0%0/1
$count || 0
$count
Truth table50%1/2
A
A= $count
Aresult
11
00
383 7 ($process, $pid) = $self->fork($code, @args, $i);
384 7 ▶ if (!$process) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($process) 5 2 7
385 5 push @pids, $pid;
386 }
387 7 ▶ if ($process) {
Branch: 1 branch
BranchTrueFalseTotal
if ($process) 2 5 7
388 2 last;
389 }
390 }
391  
392 3 ▶ return wantarray ? ($process ? ($process, []) : ($process, [@pids]) ) : $process;
Branch: 2 branches
BranchTrueFalseTotal
wantarray ? : 2 1 3
$process ? : 1 1 2
393 }
394  
395 7 ▶sub future {
Subroutine future: called CC=1 SCAR=0.8
Pod documented
396 7 my ($self, $code, @args) = @_;
397  
398 7 my $async = $self->async($code, @args);
399  
400 7 require Venus::Future;
401  
402 7 my $retry = 0;
403  
404 7 ▶ my $future = Venus::Future->new(sub{
Subroutine __ANON__: called CC=6 SCAR=25.4
405 7 my ($resolve, $reject) = @_;
406 7 my ($result) = $async->try('await', 0)->error(\my $error)->result;
407 7 ▶ if (defined $error) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $error) 0 7 7
408 0 return $reject->result($error);
409 }
410 7 ▶ if (defined $result) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $result) 7 0 7
411 7 ▶ if (UNIVERSAL::isa($result, 'Venus::Error')) {
Branch: 1 branch
BranchTrueFalseTotal
if (UNIVERSAL::isa($result, 'Venus::Error')) { } 0 7 7
412 0 return $reject->result($result);
413 }
414 else {
415 7 return $resolve->result($result);
416 }
417 }
418 0 ▶ if ($retry++ > 1 && !$async->ping($async->watchlist)) {
Branch: 1 branch
BranchTrueFalseTotal
if ($retry++ > 1 and not $async->ping($async->watchlist)) 0 0 0
Condition0%0/3
$retry++ > 1 and not $async->ping($async->watchlist)
!ll&&!rl&&r
000
MC/DC0%0/2
$retry++ > 1 and not $async->ping($async->watchlist)
$retry++ > 1 not $async->ping($async->watchlist)
Truth table0%0/3
A and not(B)
A= $retry++ > 1B= not $async->ping($async->watchlist)
ABresult
0X0
100
111
419 0 return $reject->result($async->error_on_ping({pid => ($async->watchlist)[0]}));
420 }
421 7 });
422  
423 7 return $future;
424 }
425  
426 365 ▶sub is_dyadic {
Subroutine is_dyadic: called CC=6 SCAR=18.1
Pod documented
427 365 my ($self) = @_;
428  
429 365 my $directory = $self->{directory};
430  
431 365 my $path = $PATH;
432  
433 365 ▶ my $temporary = $PATH = $directory if $directory;
Branch: 1 branch
BranchTrueFalseTotal
if $directory 27 338 365
434  
435 365 ▶ my $is_dyadic = $directory && ($temporary) && $self->is_registered && ($self->count == 1) ? true : false;
Branch: 1 branch
BranchTrueFalseTotal
$directory && $temporary && $self->is_registered && $self->count == 1 ? : 27 338 365
Condition66%6/9
$directory and $temporary and $self->is_registered and $self->count == 1
!ll&&!rl&&r
338027
$directory and $temporary and $self->is_registered
!ll&&!rl&&r
338027
$directory and $temporary
!ll&&!rl&&r
338027
MC/DC25%1/4
$directory and $temporary and $self->is_registered and $self->count == 1
$directory $temporary $self->is_registered $self->count == 1
Truth table40%2/5
A and B and C and D
A= $directoryB= $temporaryC= $self->is_registeredD= $self->count == 1
ABCDresult
0XXX0
10XX0
110X0
11100
11111
436  
437 365 $PATH = $path;
438  
439 365 return $is_dyadic;
440 }
441  
442 6 ▶sub is_leader {
Subroutine is_leader: called CC=2 SCAR=6.9
Pod documented
443 6 my ($self) = @_;
444  
445 6 ▶ return $self->leader == $self->pid ? true : false;
Branch: 1 branch
BranchTrueFalseTotal
$self->leader == $self->pid ? : 4 2 6
446 }
447  
448 3 ▶sub is_follower {
Subroutine is_follower: called CC=2 SCAR=6.9
Pod documented
449 3 my ($self) = @_;
450  
451 3 ▶ return $self->is_leader ? false : true;
Branch: 1 branch
BranchTrueFalseTotal
$self->is_leader ? : 2 1 3
452 }
453  
454 36 ▶sub is_registered {
Subroutine is_registered: called CC=2 SCAR=6.9
Pod documented
455 36 my ($self) = @_;
456  
457 36 ▶ return (grep {$_ == $self->pid} $self->registrants) ? true : false;
Branch: 1 branch
BranchTrueFalseTotal
grep({$_ == $self->pid;} $self->registrants) ? : 30 6 36
458 }
459  
460 5 ▶sub is_unregistered {
Subroutine is_unregistered: called CC=2 SCAR=6.9
Pod documented
461 5 my ($self) = @_;
462  
463 5 ▶ return $self->is_registered ? false : true;
Branch: 1 branch
BranchTrueFalseTotal
$self->is_registered ? : 1 4 5
464 }
465  
466 14 ▶sub join {
Subroutine join: called CC=2 SCAR=6.9
Pod documented
467 14 my ($self, $name) = @_;
468  
469 14 ▶ $self->exchange($name) if $name;
Branch: 1 branch
BranchTrueFalseTotal
if $name 13 1 14
470  
471 14 $self->register;
472  
473 14 @{$self->watchlist} = ();
474  
475 14 return $self;
476 }
477  
478 6 ▶sub kill {
Subroutine kill: called CC=1 SCAR=0.0
Pod documented
479 6 my ($self, $name, @pids) = @_;
480  
481 6 return _kill(uc($name), @pids);
482 }
483  
484 2 ▶sub killall {
Subroutine killall: called CC=4 SCAR=14.6
Pod documented
485 2 my ($self, $name, @pids) = @_;
486  
487 2 ▶ $name ||= 'INT';
Condition50%1/2
$name ||= "INT"
l!l
20
MC/DC0%0/1
$name ||= "INT"
$name
Truth table50%1/2
A
A= $name
Aresult
11
00
488  
489 2 ▶ my $result = [map $self->kill($name, $_), (@pids ? @pids : $self->watchlist)];
Branch: 1 branch
BranchTrueFalseTotal
@pids ? : 1 1 2
490  
491 0 ▶ return wantarray ? @{$result} : $result;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 0 2 2
492 }
493  
494 11 ▶sub leader {
Subroutine leader: called CC=1 SCAR=0.0
Pod documented
495 11 my ($self) = @_;
496  
497 11 my $leader = (sort $self->others_active, $self->pid)[0];
498  
499 11 return $leader;
500 }
501  
502 2 ▶sub leave {
Subroutine leave: called CC=1 SCAR=0.0
Pod documented
503 2 my ($self, $name) = @_;
504  
505 2 $self->unregister;
506  
507 2 delete $self->{exchange};
508 2 delete $self->{watchlist};
509  
510 2 return $self;
511 }
512  
513 16 ▶sub limit {
Subroutine limit: called CC=3 SCAR=11.0
Pod documented
514 16 my ($self, $count) = @_;
515  
516 16 ▶ if ($self->count >= $count) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->count >= $count) { } 3 13 16
517 3 ▶ $self->prune while $self->count >= $count;
Branch: 1 branch
BranchTrueFalseTotal
$self->count >= $count and do { $self->prune } 3 3 6
518 3 return true;
519 }
520 else {
521 13 return false;
522 }
523 }
524  
525 65 ▶sub others {
Subroutine others: called CC=2 SCAR=6.9
Pod documented
526 65 my ($self) = @_;
527  
528 65 my $pid = $self->pid;
529  
530 65 my $result = [grep {$_ != $pid} $self->registrants];
531  
532 65 ▶ return wantarray ? @{$result} : $result;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 37 28 65
533 }
534  
535 33 ▶sub others_active {
Subroutine others_active: called CC=2 SCAR=6.9
Pod documented
536 33 my ($self) = @_;
537  
538 33 my $pid = $self->pid;
539  
540 33 my $result = [grep $self->ping($_), $self->others];
541  
542 33 ▶ return wantarray ? @{$result} : $result;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 32 1 33
543 }
544  
545 4 ▶sub others_inactive {
Subroutine others_inactive: called CC=2 SCAR=6.9
Pod documented
546 4 my ($self) = @_;
547  
548 4 my $pid = $self->pid;
549  
550 4 my $result = [grep !$self->ping($_), $self->others];
551  
552 4 ▶ return wantarray ? @{$result} : $result;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 3 1 4
553 }
554  
555 666 ▶sub pid {
Subroutine pid: called CC=2 SCAR=8.1
Pod documented
556 666 my ($self, @data) = @_;
557  
558 666 ▶ return $self->value if !@data;
Branch: 1 branch
BranchTrueFalseTotal
unless @data 666 0 666
559  
560 0 return $self->value((($PID) = @data));
561 }
562  
563 2 ▶sub pids {
Subroutine pids: called CC=2 SCAR=7.6
Pod documented
564 2 my ($self) = @_;
565  
566 2 my $result = [$self->pid, $self->watchlist];
567  
568 0 ▶ return wantarray ? @{$result} : $result;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 0 2 2
569 }
570  
571 77 ▶sub ppid {
Subroutine ppid: called CC=2 SCAR=6.9
Pod documented
572 77 my ($self, @data) = @_;
573  
574 77 ▶ my $pid = @data ? (($PPID) = @data) : $PPID;
Branch: 1 branch
BranchTrueFalseTotal
@data ? : 13 64 77
575  
576 77 return $pid;
577 }
578  
579 62 ▶sub ping {
Subroutine ping: called CC=1 SCAR=0.0
Pod documented
580 62 my ($self, @pids) = @_;
581  
582 62 return _ping(@pids);
583 }
584  
585 4 ▶sub poll {
Subroutine poll: called CC=7 SCAR=19.8
Pod documented
586 4 my ($self, $timeout, $code, @args) = @_;
587  
588 4 ▶ if (!$code) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($code) 0 4 4
589 0 $code = 'recvall';
590 }
591  
592 4 ▶ if (!$timeout) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($timeout) 2 2 4
593 2 $timeout = 0;
594 }
595  
596 4 my $result = [];
597  
598 4 my $time = _time();
599 4 my $then = $time + $timeout;
600 4 my $seen = 0;
601  
602 4 ▶ while (time <= $then) {
Branch: 1 branch
BranchTrueFalseTotal
if (time <= $then) 3 1 4
603 3 ▶ last if $seen = (@{$result} = grep defined, $self->$code(@args));
Branch: 1 branch
BranchTrueFalseTotal
if $seen = @{$result;} = grep(defined($_), $self->$code(@args)) 3 0 3
604 }
605  
606 4 ▶ if (!$seen) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($seen) 1 3 4
607 1 $self->error_on_timeout_poll({timeout => $timeout, code => $code})
608 ->input($self, $timeout)
609 ->throw;
610 }
611  
612 0 ▶ return wantarray ? @{$result} : $result;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 0 3 3
613 }
614  
615 20 ▶sub pool {
Subroutine pool: called CC=6 SCAR=17.9
Pod documented
616 20 my ($self, $count, $timeout) = @_;
617  
618 20 ▶ if (!$count) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($count) 3 17 20
619 3 $count = 1;
620 }
621  
622 20 ▶ if (!$timeout) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($timeout) 20 0 20
623 20 $timeout = 0;
624 }
625  
626 20 my @pids;
627 20 my $time = _time();
628 20 my $then = $time + $timeout;
629 20 my $seen = 0;
630  
631 20 ▶ while (time <= $then) {
Branch: 1 branch
BranchTrueFalseTotal
if (time <= $then) 19 1 20
632 19 ▶ last if ($seen = (@pids = $self->others_active)) >= $count;
Branch: 1 branch
BranchTrueFalseTotal
if ($seen = @pids = $self->others_active) >= $count 19 0 19
633 }
634  
635 20 ▶ if ($seen < $count) {
Branch: 1 branch
BranchTrueFalseTotal
if ($seen < $count) 1 19 20
636 1 $self->error_on_timeout_pool({timeout => $timeout, pool_size => $count})
637 ->input($self, $count, $timeout)
638 ->throw;
639 }
640  
641 19 @{$self->watchlist} = @pids;
642  
643 19 return $self;
644 }
645  
646 6 ▶sub prune {
Subroutine prune: called CC=1 SCAR=0.0
Pod documented
647 6 my ($self) = @_;
648  
649 6 $self->unwatch($self->stopped);
650  
651 6 return $self;
652 }
653  
654 46 ▶sub read {
Subroutine read: called CC=4 SCAR=13.9
Pod undocumented
655 46 my ($self, $key) = @_;
656  
657 46 require Venus::Path;
658  
659 46 my $path = Venus::Path->new($PATH);
660  
661 46 ▶ $path = $path->child($self->exchange) if $self->exchange;
Branch: 1 branch
BranchTrueFalseTotal
if $self->exchange 14 32 46
662  
663 46 $path = $path->child($key);
664  
665 46 ▶ $path->catch('mkdirs') if !$path->exists;
Branch: 1 branch
BranchTrueFalseTotal
unless $path->exists 1 45 46
666  
667 46 my $file = (CORE::glob($path->child('*.data')->absolute))[0];
668  
669 46 ▶ return undef if !$file;
Branch: 1 branch
BranchTrueFalseTotal
unless $file 8 38 46
670  
671 38 $path = Venus::Path->new($file);
672  
673 38 my $data = $path->read;
674  
675 38 $path->unlink;
676  
677 38 return $data;
678 }
679  
680 3 ▶sub recall {
Subroutine recall: called CC=4 SCAR=14.2
Pod documented
681 3 my ($self, $pid) = @_;
682  
683 3 ▶ ($pid) = grep {$_ == $pid} $self->others_inactive if $pid;
Branch: 1 branch
BranchTrueFalseTotal
if $pid 3 0 3
684  
685 3 ▶ return undef if !$pid;
Branch: 1 branch
BranchTrueFalseTotal
unless $pid 0 3 3
686  
687 3 my $key = $self->send_key($pid);
688  
689 3 my $string = $self->read($key);
690  
691 3 ▶ return undef if !defined $string;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $string 0 3 3
692  
693 3 my $data = $self->decode($string);
694  
695 3 return $data;
696 }
697  
698 1 ▶sub recallall {
Subroutine recallall: called CC=4 SCAR=14.5
Pod documented
699 1 my ($self) = @_;
700  
701 1 my $result = [];
702  
703 1 for my $pid (grep defined, $self->ppid, $self->watchlist) {
704 2 my $data = $self->recall($pid);
705 2 ▶ push @{$result}, $data if defined $data;
Branch: 1 branch
BranchTrueFalseTotal
if defined $data 2 0 2
706 }
707  
708 0 ▶ return wantarray ? @{$result} : $result;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 0 1 1
709 }
710  
711 44 ▶sub recv {
Subroutine recv: called CC=3 SCAR=11.0
Pod documented
712 44 my ($self, $pid) = @_;
713  
714 44 ▶ return undef if !$pid;
Branch: 1 branch
BranchTrueFalseTotal
unless $pid 1 43 44
715  
716 43 my $key = $self->recv_key($pid);
717  
718 43 my $string = $self->read($key);
719  
720 43 ▶ return undef if !defined $string;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $string 8 35 43
721  
722 35 my $data = $self->decode($string);
723  
724 35 return $data;
725 }
726  
727 24 ▶sub recvall {
Subroutine recvall: called CC=4 SCAR=13.9
Pod documented
728 24 my ($self) = @_;
729  
730 24 my $result = [];
731  
732 24 for my $pid (grep defined, $self->ppid, $self->watchlist) {
733 37 my $data = $self->recv($pid);
734 37 ▶ push @{$result}, $data if defined $data;
Branch: 1 branch
BranchTrueFalseTotal
if defined $data 31 6 37
735 }
736  
737 24 ▶ return wantarray ? @{$result} : $result;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 14 10 24
738 }
739  
740 134 ▶sub recv_key {
Subroutine recv_key: called CC=1 SCAR=0.0
Pod undocumented
741 134 my ($self, $pid) = @_;
742  
743 134 return CORE::join '.', $pid, $self->pid;
744 }
745  
746 105 ▶sub register {
Subroutine register: called CC=3 SCAR=11.0
Pod documented
747 105 my ($self) = @_;
748  
749 105 require Venus::Path;
750  
751 105 my $path = Venus::Path->new($PATH);
752  
753 105 ▶ $path = $path->child($self->exchange) if $self->exchange;
Branch: 1 branch
BranchTrueFalseTotal
if $self->exchange 13 92 105
754  
755 105 my $key = $self->send_key($self->pid);
756  
757 105 $path = $path->child($key);
758  
759 105 ▶ $path->catch('mkdirs') if !$path->exists;
Branch: 1 branch
BranchTrueFalseTotal
unless $path->exists 78 27 105
760  
761 105 return $self;
762 }
763  
764 102 ▶sub registrants {
Subroutine registrants: called CC=3 SCAR=11.0
Pod documented
765 102 my ($self) = @_;
766  
767 102 require Venus::Path;
768  
769 102 my $path = Venus::Path->new($PATH);
770  
771 102 ▶ $path = $path->child($self->exchange) if $self->exchange;
Branch: 1 branch
BranchTrueFalseTotal
if $self->exchange 12 90 102
772  
773 102 my $result = [
774 map /(\d+)$/, grep /(\d+)\.\1$/, CORE::glob($path->child('*.*')->absolute)
775 ];
776  
777 102 ▶ return wantarray ? @{$result} : $result;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 101 1 102
778 }
779  
780 1 ▶sub restart {
Subroutine restart: called CC=2 SCAR=7.8
Pod documented
781 1 my ($self, $code) = @_;
782  
783 1 my $result = [];
784  
785 1 ▶ $self->status(sub {
Subroutine __ANON__: called CC=3 SCAR=13.1
786 1 ▶ push @{$result}, $code->(@_) if ($_[1] == -1) || ($_[1] == $_[0])
Branch: 1 branch
BranchTrueFalseTotal
if $_[1] == -1 or $_[1] == $_[0] 1 0 1
Condition33%1/3
$_[1] == -1 or $_[1] == $_[0]
l!l&&r!l&&!r
010
MC/DC0%0/2
$_[1] == -1 or $_[1] == $_[0]
$_[1] == -1 $_[1] == $_[0]
Truth table33%1/3
A or B
A= $_[1] == -1B= $_[1] == $_[0]
ABresult
1X1
011
000
787 1 });
788  
789 0 ▶ return wantarray ? @{$result} : $result;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 0 1 1
790 }
791  
792 47 ▶sub send {
Subroutine send: called CC=2 SCAR=6.9
Pod documented
793 47 my ($self, $pid, $data) = @_;
794  
795 47 ▶ return $self if !$pid;
Branch: 1 branch
BranchTrueFalseTotal
unless $pid 1 46 47
796  
797 46 my $string = $self->encode($data);
798  
799 46 my $key = $self->send_key($pid);
800  
801 46 $self->write($key, $string);
802  
803 46 return $self;
804 }
805  
806 24 ▶sub sendall {
Subroutine sendall: called CC=2 SCAR=6.9
Pod documented
807 24 my ($self, $data) = @_;
808  
809 24 for my $pid (grep defined, $self->ppid, $self->watchlist) {
810 31 $self->send($pid, $data);
811 }
812  
813 24 return $self;
814 }
815  
816 154 ▶sub send_key {
Subroutine send_key: called CC=1 SCAR=0.0
Pod undocumented
817 154 my ($self, $pid) = @_;
818  
819 154 return CORE::join '.', $self->pid, $pid;
820 }
821  
822 2 ▶sub serve {
Subroutine serve: called CC=3 SCAR=11.0
Pod documented
823 2 my ($self, $count, $code) = @_;
824  
825 2 ▶ do {$self->work($code) until $self->limit($count)} while _serve;
Branch: 2 branches
BranchTrueFalseTotal
_serve() and do { do { $self->work($code) until $self->limit($count) } } 0 2 2
$self->limit($count) or do { $self->work($code) } 2 12 14
826  
827 2 return $self;
828 }
829  
830 3 ▶sub setsid {
Subroutine setsid: called CC=2 SCAR=6.9
Pod documented
831 3 my ($self) = @_;
832  
833 3 my $result = _setsid != -1;
834  
835 3 ▶ if (!$result) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($result) 1 2 3
836 1 my $error = $!;
837 1 $self->error_on_setid({pid => $PID, error => $error})->throw;
838 }
839  
840 2 return $result;
841 }
842  
843 2 ▶sub started {
Subroutine started: called CC=2 SCAR=7.1
Pod documented
844 2 my ($self) = @_;
845  
846 2 my $result = [];
847  
848 2 ▶ $self->status(sub {
Subroutine __ANON__: called CC=3 SCAR=11.1
849 2 ▶ push @{$result}, $_[0] if $_[1] > -1 && $_[1] != $_[0]
Branch: 1 branch
BranchTrueFalseTotal
if $_[1] > -1 and $_[1] != $_[0] 1 1 2
Condition66%2/3
$_[1] > -1 and $_[1] != $_[0]
!ll&&!rl&&r
101
MC/DC50%1/2
$_[1] > -1 and $_[1] != $_[0]
$_[1] > -1 $_[1] != $_[0]
Truth table66%2/3
A and B
A= $_[1] > -1B= $_[1] != $_[0]
ABresult
0X0
100
111
850 2 });
851  
852 0 ▶ return wantarray ? @{$result} : $result;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 0 2 2
853 }
854  
855 14 ▶sub status {
Subroutine status: called CC=3 SCAR=11.0
Pod documented
856 14 my ($self, $code) = @_;
857  
858 14 my $result = [];
859 14 my $watchlist = $self->watchlist;
860  
861 14 for my $pid (@{$watchlist}) {
862 25 local $_ = $pid;
863 25 push @{$result}, $code->($pid, $self->check($pid));
864 }
865  
866 14 ▶ return wantarray ? @{$result} : $result;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 1 13 14
867 }
868  
869 6 ▶sub stderr {
Subroutine stderr: called CC=5 SCAR=16.1
Pod documented
870 6 my ($self, $path) = @_;
871  
872 6 state $STDERR;
873  
874 6 ▶ if (!$STDERR) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($STDERR) 6 0 6
875 6 _open($STDERR, '>&', \*STDERR);
876 }
877 6 ▶ if (!$path) {
Branch: 1 branch
BranchTrueFalseTotal
if (not $path) { } 2 4 6
878 2 _open(\*STDERR, '>&', $STDERR);
879 }
880 else {
881 4 ▶ _open(\*STDERR, '>&', IO::File->new($path, 'w')) or my $error = $!;
Branch: 1 branch
BranchTrueFalseTotal
_open(\*STDERR, ">&", "IO::File"->new($path, "w")) or my $error = $! 3 1 4
882 4 ▶ if ($error) {
Branch: 1 branch
BranchTrueFalseTotal
if ($error) 1 3 4
883 1 $self->error_on_stderr({path => $path, pid => $PID, error => $error})
884 ->input($self, $path)
885 ->output($error)
886 ->throw;
887 }
888 }
889  
890 5 return $self;
891 }
892  
893 6 ▶sub stdin {
Subroutine stdin: called CC=4 SCAR=13.9
Pod documented
894 6 my ($self, $path) = @_;
895  
896 6 state $STDIN;
897  
898 6 ▶ if (!$STDIN) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($STDIN) 6 0 6
899 6 _open($STDIN, '<&', \*STDIN);
900 }
901 6 ▶ if (!$path) {
Branch: 1 branch
BranchTrueFalseTotal
if (not $path) { } 2 4 6
902 2 _open(\*STDIN, '<&', $STDIN);
903 }
904 else {
905 4 ▶ _open(\*STDIN, '<&', IO::File->new($path, 'r')) or do {
Branch: 1 branch
BranchTrueFalseTotal
_open(\*STDIN, "<&", "IO::File"->new($path, "r")) or do { my $error = $!; $self->error_on_stdin({"path", $path, "pid", $Venus::Process::PID, "error", $error})->input($self, $path)->output($error)->throw } 3 1 4
906 1 my $error = $!;
907 1 $self->error_on_stdin({path => $path, pid => $PID, error => $error})
908 ->input($self, $path)
909 ->output($error)
910 ->throw;
911 };
912 }
913  
914 5 return $self;
915 }
916  
917 6 ▶sub stdout {
Subroutine stdout: called CC=4 SCAR=13.9
Pod documented
918 6 my ($self, $path) = @_;
919  
920 6 state $STDOUT;
921  
922 6 ▶ if (!$STDOUT) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($STDOUT) 6 0 6
923 6 _open($STDOUT, '>&', \*STDOUT);
924 }
925 6 ▶ if (!$path) {
Branch: 1 branch
BranchTrueFalseTotal
if (not $path) { } 2 4 6
926 2 _open(\*STDOUT, '>&', $STDOUT);
927 }
928 else {
929 4 ▶ _open(\*STDOUT, '>&', IO::File->new($path, 'w')) or do {
Branch: 1 branch
BranchTrueFalseTotal
_open(\*STDOUT, ">&", "IO::File"->new($path, "w")) or do { my $error = $!; $self->error_on_stdout({"path", $path, "pid", $Venus::Process::PID, "error", $error})->input($self, $path)->output($error)->throw } 3 1 4
930 1 my $error = $!;
931 1 $self->error_on_stdout({path => $path, pid => $PID, error => $error})
932 ->input($self, $path)
933 ->output($error)
934 ->throw;
935 };
936 }
937  
938 5 return $self;
939 }
940  
941 8 ▶sub stopped {
Subroutine stopped: called CC=2 SCAR=6.9
Pod documented
942 8 my ($self) = @_;
943  
944 8 my $result = [];
945  
946 19 ▶ $self->status(sub {
Subroutine __ANON__: called CC=3 SCAR=11.1
947 19 ▶ push @{$result}, $_[0] if ($_[1] == -1) || ($_[1] == $_[0])
Branch: 1 branch
BranchTrueFalseTotal
if $_[1] == -1 or $_[1] == $_[0] 18 1 19
Condition66%2/3
$_[1] == -1 or $_[1] == $_[0]
l!l&&r!l&&!r
1801
MC/DC50%1/2
$_[1] == -1 or $_[1] == $_[0]
$_[1] == -1 $_[1] == $_[0]
Truth table66%2/3
A or B
A= $_[1] == -1B= $_[1] == $_[0]
ABresult
1X1
011
000
948 8 });
949  
950 8 ▶ return wantarray ? @{$result} : $result;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 6 2 8
951 }
952  
953 3 ▶sub sync {
Subroutine sync: called CC=6 SCAR=18.0
Pod documented
954 3 my ($self, $count, $timeout) = @_;
955  
956 3 ▶ if (!$count) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($count) 1 2 3
957 1 $count = 1;
958 }
959  
960 3 ▶ if (!$timeout) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($timeout) 3 0 3
961 3 $timeout = 0;
962 }
963  
964 3 my $time = _time();
965 3 my $then = $time + $timeout;
966 3 my $msgs = 0;
967  
968 3 ▶ while (time <= $then) {
Branch: 1 branch
BranchTrueFalseTotal
if (time <= $then) 2 1 3
969 2 ▶ last if ($msgs = (scalar grep $self->data($_), $self->pool->watchlist)) >= $count;
Branch: 1 branch
BranchTrueFalseTotal
if ($msgs = scalar grep($self->data($_), $self->pool->watchlist)) >= $count 2 0 2
970 }
971  
972 3 ▶ if ($msgs < $count) {
Branch: 1 branch
BranchTrueFalseTotal
if ($msgs < $count) 1 2 3
973 1 $self->error_on_timeout_sync({timeout => $timeout, pool_size => $count})
974 ->input($self, $count, $timeout)
975 ->throw;
976 }
977  
978 2 return $self;
979 }
980  
981 33 ▶sub trap {
Subroutine trap: called CC=2 SCAR=8.5
Pod documented
982 33 my ($self, $name, $expr) = @_;
983  
984 0 ▶ $SIG{uc($name)} = !ref($expr) ? uc($expr) : sub {
Subroutine __ANON__: not called CC=2 SCAR=17.9
985 0 local($!, $?);
986 0 ▶ return $self->$expr->(uc($name), @_) if ref $expr eq 'CODE';
Branch: 1 branch
BranchTrueFalseTotal
if ref $expr eq "CODE" 0 0 0
987 33 ▶ };
Branch: 1 branch
BranchTrueFalseTotal
!ref($expr) ? : 2 31 33
988  
989 33 return $self;
990 }
991  
992 79 ▶sub wait {
Subroutine wait: called CC=2 SCAR=6.9
Pod documented
993 79 my ($self, $pid) = @_;
994  
995 79 my $result = _waitpid($pid, 0);
996  
997 79 ▶ return wantarray ? ($result, _exitcode) : $result;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 5 74 79
998 }
999  
1000 3 ▶sub waitall {
Subroutine waitall: called CC=3 SCAR=11.4
Pod documented
1001 3 my ($self, @pids) = @_;
1002  
1003 3 ▶ my $result = [map [$self->wait($_)], @pids ? @pids : $self->watchlist];
Branch: 1 branch
BranchTrueFalseTotal
@pids ? : 1 2 3
1004  
1005 0 ▶ return wantarray ? @{$result} : $result;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 0 3 3
1006 }
1007  
1008 151 ▶sub watch {
Subroutine watch: called CC=2 SCAR=6.9
Pod documented
1009 151 my ($self, @args) = @_;
1010  
1011 151 my $watchlist = $self->watchlist;
1012  
1013 151 my %seen; @{$watchlist} = grep !$seen{$_}++, @{$watchlist}, @args;
1014  
1015 151 ▶ return wantarray ? @{$watchlist} : $watchlist;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 3 148 151
1016 }
1017  
1018 348 ▶sub watchlist {
Subroutine watchlist: called CC=3 SCAR=11.0
Pod documented
1019 348 my ($self) = @_;
1020  
1021 348 ▶ my $watchlist = $self->{watchlist} ||= [];
Condition100%2/2
$self->{"watchlist"} ||= []
l!l
190158
MC/DC100%1/1
$self->{"watchlist"} ||= []
$self->{"watchlist"}
Truth table100%2/2
A
A= $self->{"watchlist"}
Aresult
11
00
1022  
1023 348 ▶ return wantarray ? @{$watchlist} : $watchlist;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 139 209 348
1024 }
1025  
1026 37 ▶sub work {
Subroutine work: called CC=1 SCAR=0.0
Pod documented
1027 37 my ($self, $code, @args) = @_;
1028  
1029 20 ▶ my @returned = $self->fork(sub{
Subroutine __ANON__: called CC=1 SCAR=0.0
1030 20 my ($process) = @_;
1031 20 local $_ = $process;
1032 20 $process->$code(@args);
1033 20 $process->exit;
1034 37 });
1035  
1036 37 return $returned[-1];
1037 }
1038  
1039 2 ▶sub works {
Subroutine works: called CC=4 SCAR=14.3
Pod documented
1040 2 my ($self, $count, $code, @args) = @_;
1041  
1042 2 my $result = [];
1043  
1044 2 ▶ for (my $i = 1; $i <= ($count || 0); $i++) {
Branch: 1 branch
BranchTrueFalseTotal
if ($i <= ($count || 0)) 7 2 9
Condition50%1/2
$count || 0
l!l
90
MC/DC0%0/1
$count || 0
$count
Truth table50%1/2
A
A= $count
Aresult
11
00
1045 7 push @{$result}, scalar($self->work($code, @args));
1046 }
1047  
1048 0 ▶ return wantarray ? @{$result} : $result;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 0 2 2
1049 }
1050  
1051 46 ▶sub write {
Subroutine write: called CC=4 SCAR=13.9
Pod undocumented
1052 46 my ($self, $key, $data) = @_;
1053  
1054 46 require Venus::Path;
1055  
1056 46 my $path = Venus::Path->new($PATH);
1057  
1058 46 ▶ $path = $path->child($self->exchange) if $self->exchange;
Branch: 1 branch
BranchTrueFalseTotal
if $self->exchange 12 34 46
1059  
1060 46 $path = $path->child($key);
1061  
1062 46 ▶ $path->catch('mkdirs') if !$path->exists;
Branch: 1 branch
BranchTrueFalseTotal
unless $path->exists 9 37 46
1063  
1064 46 state $atom = 0;
1065 46 state $time = time;
1066  
1067 46 ▶ ($atom = ($time == time) ? $atom + 1 : 1);
Branch: 1 branch
BranchTrueFalseTotal
$time == time ? : 42 4 46
1068  
1069 46 $path = $path->child(CORE::join '.', time, $atom, 'data');
1070  
1071 46 $time = time;
1072  
1073 46 $path->write($data);
1074  
1075 46 return $self;
1076 }
1077  
1078 71 ▶sub unregister {
Subroutine unregister: called CC=3 SCAR=11.0
Pod documented
1079 71 my ($self) = @_;
1080  
1081 71 require Venus::Path;
1082  
1083 71 my $path = Venus::Path->new($PATH);
1084  
1085 71 ▶ $path = $path->child($self->exchange) if $self->exchange;
Branch: 1 branch
BranchTrueFalseTotal
if $self->exchange 1 70 71
1086  
1087 71 my $key = $self->recv_key($self->pid);
1088  
1089 71 $path = $path->child($key);
1090  
1091 71 ▶ $path->rmdirs if $path->exists;
Branch: 1 branch
BranchTrueFalseTotal
if $path->exists 62 9 71
1092  
1093 71 return $self;
1094 }
1095  
1096 15 ▶sub untrap {
Subroutine untrap: called CC=2 SCAR=6.9
Pod documented
1097 15 my ($self, $name) = @_;
1098  
1099 15 ▶ if ($name) {
Branch: 1 branch
BranchTrueFalseTotal
if ($name) { } 1 14 15
1100 1 $SIG{uc($name)} = $$MAPSIG{uc($name)};
1101 }
1102 else {
1103 14 %SIG = %$MAPSIG;
1104 }
1105  
1106 15 return $self;
1107 }
1108  
1109 9 ▶sub unwatch {
Subroutine unwatch: called CC=2 SCAR=7.1
Pod documented
1110 9 my ($self, @args) = @_;
1111  
1112 9 my $watchlist = $self->watchlist;
1113  
1114 9 my %seen = map +($_, 1), @args;
1115  
1116 9 @{$watchlist} = grep !$seen{$_}++, @{$watchlist}, @args;
1117  
1118 0 ▶ return wantarray ? @{$watchlist} : $watchlist;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 0 9 9
1119 }
1120  
1121 # ERRORS
1122  
1123 1 ▶sub error_on_chdir {
Subroutine error_on_chdir: called CC=1 SCAR=0.0
Pod undocumented
1124 1 my ($self, $data) = @_;
1125  
1126 1 my $error = $self->error->sysinfo;
1127  
1128 1 my $message = 'Can\'t chdir "{{path}}": {{error}}';
1129  
1130 1 $error->name('on.chdir');
1131 1 $error->message($message);
1132 1 $error->offset(1);
1133 1 $error->stash($data);
1134 1 $error->reset;
1135  
1136 1 return $error;
1137 }
1138  
1139 0 ▶sub error_on_fork_process {
Subroutine error_on_fork_process: not called CC=1 SCAR=6.9
Pod undocumented
1140 0 my ($self, $data) = @_;
1141  
1142 0 my $error = $self->error->sysinfo;
1143  
1144 0 my $message = 'Can\'t fork process {{pid}}: {{error}}';
1145  
1146 0 $error->name('on.fork.process');
1147 0 $error->message($message);
1148 0 $error->offset(1);
1149 0 $error->stash($data);
1150 0 $error->reset;
1151  
1152 0 return $error;
1153 }
1154  
1155 1 ▶sub error_on_fork_support {
Subroutine error_on_fork_support: called CC=1 SCAR=0.0
Pod undocumented
1156 1 my ($self, $data) = @_;
1157  
1158 1 my $error = $self->error->sysinfo;
1159  
1160 1 my $message = 'Can\'t fork process {{pid}}: Fork emulation not supported';
1161  
1162 1 $error->name('on.fork.support');
1163 1 $error->message($message);
1164 1 $error->offset(1);
1165 1 $error->stash($data);
1166 1 $error->reset;
1167  
1168 1 return $error;
1169 }
1170  
1171 0 ▶sub error_on_ping {
Subroutine error_on_ping: not called CC=1 SCAR=6.9
Pod undocumented
1172 0 my ($self, $data) = @_;
1173  
1174 0 my $error = $self->error->sysinfo;
1175  
1176 0 my $message = 'Process {{pid}} not responding to ping';
1177  
1178 0 $error->name('on.ping');
1179 0 $error->message($message);
1180 0 $error->offset(1);
1181 0 $error->stash($data);
1182 0 $error->reset;
1183  
1184 0 return $error;
1185 }
1186  
1187 1 ▶sub error_on_setid {
Subroutine error_on_setid: called CC=1 SCAR=0.0
Pod undocumented
1188 1 my ($self, $data) = @_;
1189  
1190 1 my $error = $self->error->sysinfo;
1191  
1192 1 my $message = 'Can\'t start a new session: {{error}}';
1193  
1194 1 $error->name('on.setid');
1195 1 $error->message($message);
1196 1 $error->offset(1);
1197 1 $error->stash($data);
1198 1 $error->reset;
1199  
1200 1 return $error;
1201 }
1202  
1203 1 ▶sub error_on_stderr {
Subroutine error_on_stderr: called CC=1 SCAR=0.0
Pod undocumented
1204 1 my ($self, $data) = @_;
1205  
1206 1 my $error = $self->error->sysinfo;
1207  
1208 1 my $message = 'Can\'t redirect STDERR to "{{path}}": {{error}}';
1209  
1210 1 $error->name('on.stderr');
1211 1 $error->message($message);
1212 1 $error->offset(1);
1213 1 $error->stash($data);
1214 1 $error->reset;
1215  
1216 1 return $error;
1217 }
1218  
1219 1 ▶sub error_on_stdin {
Subroutine error_on_stdin: called CC=1 SCAR=0.0
Pod undocumented
1220 1 my ($self, $data) = @_;
1221  
1222 1 my $error = $self->error->sysinfo;
1223  
1224 1 my $message = 'Can\'t redirect STDIN to "{{path}}": {{error}}';
1225  
1226 1 $error->name('on.stdin');
1227 1 $error->message($message);
1228 1 $error->offset(1);
1229 1 $error->stash($data);
1230 1 $error->reset;
1231  
1232 1 return $error;
1233 }
1234  
1235 1 ▶sub error_on_stdout {
Subroutine error_on_stdout: called CC=1 SCAR=0.0
Pod undocumented
1236 1 my ($self, $data) = @_;
1237  
1238 1 my $error = $self->error->sysinfo;
1239  
1240 1 my $message = 'Can\'t redirect STDOUT to "{{path}}": {{error}}';
1241  
1242 1 $error->name('on.stdout');
1243 1 $error->message($message);
1244 1 $error->offset(1);
1245 1 $error->stash($data);
1246 1 $error->reset;
1247  
1248 1 return $error;
1249 }
1250  
1251 1 ▶sub error_on_timeout_poll {
Subroutine error_on_timeout_poll: called CC=2 SCAR=6.9
Pod undocumented
1252 1 my ($self, $data) = @_;
1253  
1254 1 my $error = $self->error->sysinfo;
1255  
1256 1 my $message = CORE::join ' ', 'Timed out after {{timeout}} seconds',
1257 'in process {{pid}} while polling {{name}}';
1258  
1259 1 $data->{exchange} = $self->exchange;
1260 1 ▶ $data->{name} = (ref $data->{code} eq 'CODE' ? '__ANON__' : $data->{code});
Branch: 1 branch
BranchTrueFalseTotal
ref $data->{'code'} eq 'CODE' ? : 0 1 1
1261 1 $data->{pid} = $self->pid;
1262  
1263 1 $error->name('on.timeout.poll');
1264 1 $error->message($message);
1265 1 $error->offset(1);
1266 1 $error->stash($data);
1267 1 $error->reset;
1268  
1269 1 return $error;
1270 }
1271  
1272 1 ▶sub error_on_timeout_pool {
Subroutine error_on_timeout_pool: called CC=1 SCAR=0.0
Pod undocumented
1273 1 my ($self, $data) = @_;
1274  
1275 1 my $error = $self->error->sysinfo;
1276  
1277 1 my $message = CORE::join ' ', 'Timed out after {{timeout}} seconds',
1278 'in process {{pid}} while pooling';
1279  
1280  
1281 1 $data->{exchange} = $self->exchange;
1282 1 $data->{pid} = $self->pid;
1283  
1284 1 $error->name('on.timeout.pool');
1285 1 $error->message($message);
1286 1 $error->offset(1);
1287 1 $error->stash($data);
1288 1 $error->reset;
1289  
1290 1 return $error;
1291 }
1292  
1293 1 ▶sub error_on_timeout_sync {
Subroutine error_on_timeout_sync: called CC=1 SCAR=0.0
Pod undocumented
1294 1 my ($self, $data) = @_;
1295  
1296 1 my $error = $self->error->sysinfo;
1297  
1298 1 my $message = CORE::join ' ', 'Timed out after {{timeout}} seconds',
1299 'in process {{pid}} while syncing';
1300  
1301 1 $data->{exchange} = $self->exchange;
1302 1 $data->{pid} = $self->pid;
1303  
1304 1 $error->name('on.timeout.sync');
1305 1 $error->message($message);
1306 1 $error->offset(1);
1307 1 $error->stash($data);
1308 1 $error->reset;
1309  
1310 1 return $error;
1311 }
1312  
1313 # DESTROY
1314  
1315 363 ▶sub DESTROY {
Subroutine DESTROY: called CC=3 SCAR=13.0
1316 363 my ($self, @data) = @_;
1317  
1318 363 $self->SUPER::DESTROY(@data);
1319  
1320 363 ▶ if ($self->is_dyadic && !$self->others) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->is_dyadic and not $self->others) 0 363 363
Condition66%2/3
$self->is_dyadic and not $self->others
!ll&&!rl&&r
337260
MC/DC0%0/2
$self->is_dyadic and not $self->others
$self->is_dyadic not $self->others
Truth table66%2/3
A and not(B)
A= $self->is_dyadicB= not $self->others
ABresult
0X0
100
111
1321 0 $self->unregister;
1322 0 require Venus::Path; Venus::Path->new($self->{directory})->rmdirs;
1323 }
1324  
1325 363 return $self;
1326 }
1327  
1328 2 1;
1329  
1330  
1331  
1332 =head1 NAME
1333  
1334 Venus::Process - Process Class
1335  
1336 =cut
1337  
1338 =head1 ABSTRACT
1339  
1340 Process Class for Perl 5
1341  
1342 =cut
1343  
1344 =head1 SYNOPSIS
1345  
1346 package main;
1347  
1348 use Venus::Process;
1349  
1350 my $parent = Venus::Process->new;
1351  
1352 my $process = $parent->fork;
1353  
1354 if ($process) {
1355 # do something in child process ...
1356 $process->exit;
1357 }
1358 else {
1359 # do something in parent process ...
1360 $parent->wait(-1);
1361 }
1362  
1363 # $parent->exit;
1364  
1365 =cut
1366  
1367 =head1 DESCRIPTION
1368  
1369 This package provides methods for handling and forking processes.
1370  
1371 =cut
1372  
1373 =head1 ATTRIBUTES
1374  
1375 This package has the following attributes:
1376  
1377 =cut
1378  
1379 =head2 alarm
1380  
1381 alarm(number $seconds) (number)
1382  
1383 The alarm attribute is used in calls to L<alarm> when the process is forked,
1384 installing an alarm in the forked process if set.
1385  
1386 I<Since C<2.40>>
1387  
1388 =over 4
1389  
1390 =item alarm example 1
1391  
1392 # given: synopsis
1393  
1394 package main;
1395  
1396 my $alarm = $parent->alarm;
1397  
1398 # undef
1399  
1400 =back
1401  
1402 =over 4
1403  
1404 =item alarm example 2
1405  
1406 # given: synopsis
1407  
1408 package main;
1409  
1410 my $alarm = $parent->alarm(10);
1411  
1412 # 10
1413  
1414 =back
1415  
1416 =cut
1417  
1418 =head1 INHERITS
1419  
1420 This package inherits behaviors from:
1421  
1422 L<Venus::Kind::Utility>
1423  
1424 =cut
1425  
1426 =head1 INTEGRATES
1427  
1428 This package integrates behaviors from:
1429  
1430 L<Venus::Role::Accessible>
1431  
1432 L<Venus::Role::Buildable>
1433  
1434 L<Venus::Role::Explainable>
1435  
1436 L<Venus::Role::Valuable>
1437  
1438 =cut
1439  
1440 =head1 METHODS
1441  
1442 This package provides the following methods:
1443  
1444 =cut
1445  
1446 =head2 async
1447  
1448 async(coderef $code, any @args) (Venus::Process)
1449  
1450 The async method creates a new L<Venus::Process> object and asynchronously runs
1451 the callback provided via the L</work> method. Both process objects are
1452 configured to be are dyadic, i.e. representing an exclusing bi-directoral
1453 relationship. Additionally, the callback return value will be automatically
1454 made available via the L</await> method unless it's undefined. This method
1455 returns the newly created L<"dyadic"|/is_dyadic> process object.
1456  
1457 I<Since C<3.40>>
1458  
1459 =over 4
1460  
1461 =item async example 1
1462  
1463 # given: synopsis;
1464  
1465 my $async = $parent->async(sub{
1466 my ($process) = @_;
1467 # in forked process ...
1468 $process->exit;
1469 });
1470  
1471 # bless({...}, 'Venus::Process')
1472  
1473 =back
1474  
1475 =cut
1476  
1477 =head2 await
1478  
1479 await(number $timeout) (arrayref)
1480  
1481 The await method expects to operate on a L<"dyadic"|/is_dyadic> process object
1482 and blocks the execution of the current process until a value is received from
1483 its couterpart. If a timeout is provided, execution will be blocked until a
1484 value is received or the wait time expires. If a timeout of C<0> is provided,
1485 execution will not be blocked. If no timeout is provided at all, execution will
1486 block indefinitely.
1487  
1488 I<Since C<3.40>>
1489  
1490 =over 4
1491  
1492 =item await example 1
1493  
1494 # given: synopsis;
1495  
1496 my $async = $parent->async(sub{
1497 ($process) = @_;
1498 # in forked process ...
1499 return 'done';
1500 });
1501  
1502 my $await = $async->await;
1503  
1504 # ['done']
1505  
1506 =back
1507  
1508 =over 4
1509  
1510 =item await example 2
1511  
1512 # given: synopsis;
1513  
1514 my $async = $parent->async(sub{
1515 ($process) = @_;
1516 # in forked process ...
1517 return {status => 'done'};
1518 });
1519  
1520 my $await = $async->await;
1521  
1522 # [{status => 'done'}]
1523  
1524 =back
1525  
1526 =over 4
1527  
1528 =item await example 3
1529  
1530 # given: synopsis;
1531  
1532 my $async = $parent->async(sub{
1533 ($process) = @_;
1534 # in forked process ...
1535 return 'done';
1536 });
1537  
1538 my ($await) = $async->await;
1539  
1540 # 'done'
1541  
1542 =back
1543  
1544 =over 4
1545  
1546 =item await example 4
1547  
1548 # given: synopsis;
1549  
1550 my $async = $parent->async(sub{
1551 ($process) = @_;
1552 # in forked process ...
1553 return {status => 'done'};
1554 });
1555  
1556 my ($await) = $async->await;
1557  
1558 # {status => 'done'}
1559  
1560 =back
1561  
1562 =over 4
1563  
1564 =item await example 5
1565  
1566 # given: synopsis;
1567  
1568 my $async = $parent->async(sub{
1569 ($process) = @_;
1570 # in forked process ...
1571 $process->sendall('send 1');
1572 $process->sendall('send 2');
1573 $process->sendall('send 3');
1574 return;
1575 });
1576  
1577 my $await;
1578  
1579 my $results = [];
1580  
1581 push @$results, $async->await;
1582  
1583 # 'send 1'
1584  
1585 push @$results, $async->await;
1586  
1587 # 'send 2'
1588  
1589 push @$results, $async->await;
1590  
1591 # 'send 3'
1592  
1593 $results;
1594  
1595 # ['send 1', 'send 2', 'send 3']
1596  
1597 =back
1598  
1599 =cut
1600  
1601 =head2 chdir
1602  
1603 chdir(string $path) (Venus::Process)
1604  
1605 The chdir method changes the working directory the current process is operating
1606 within.
1607  
1608 I<Since C<0.06>>
1609  
1610 =over 4
1611  
1612 =item chdir example 1
1613  
1614 # given: synopsis;
1615  
1616 $parent = $parent->chdir;
1617  
1618 # bless({...}, 'Venus::Process')
1619  
1620 =back
1621  
1622 =over 4
1623  
1624 =item chdir example 2
1625  
1626 # given: synopsis;
1627  
1628 $parent = $parent->chdir('/tmp');
1629  
1630 # bless({...}, 'Venus::Process')
1631  
1632 =back
1633  
1634 =over 4
1635  
1636 =item chdir example 3
1637  
1638 # given: synopsis;
1639  
1640 $parent = $parent->chdir('/xyz');
1641  
1642 # Exception! (isa Venus::Process::Error) (see error_on_chdir)
1643  
1644 =back
1645  
1646 =over 4
1647  
1648 =item B<may raise> L<Venus::Process::Error> C<on.chdir>
1649  
1650 # given: synopsis;
1651  
1652 $parent->chdir('/path/to/nowhere');
1653  
1654 # Error! (on.chdir)
1655  
1656 =back
1657  
1658 =cut
1659  
1660 =head2 check
1661  
1662 check(number $pid) (number, number)
1663  
1664 The check method does a non-blocking L<perlfunc/waitpid> operation and returns
1665 the wait status. In list context, returns the specified process' exit code (if
1666 terminated).
1667  
1668 I<Since C<0.06>>
1669  
1670 =over 4
1671  
1672 =item check example 1
1673  
1674 package main;
1675  
1676 use Venus::Process;
1677  
1678 my $parent = Venus::Process->new;
1679  
1680 my ($process, $pid) = $parent->fork;
1681  
1682 if ($process) {
1683 # in forked process ...
1684 $process->exit;
1685 }
1686  
1687 my $check = $parent->check($pid);
1688  
1689 # 0
1690  
1691 =back
1692  
1693 =over 4
1694  
1695 =item check example 2
1696  
1697 package main;
1698  
1699 use Venus::Process;
1700  
1701 my $parent = Venus::Process->new;
1702  
1703 my ($process, $pid) = $parent->fork;
1704  
1705 if ($process) {
1706 # in forked process ...
1707 $process->exit;
1708 }
1709  
1710 my ($check, $status) = $parent->check('00000');
1711  
1712 # (-1, -1)
1713  
1714 =back
1715  
1716 =over 4
1717  
1718 =item check example 3
1719  
1720 package main;
1721  
1722 use Venus::Process;
1723  
1724 my $parent = Venus::Process->new;
1725  
1726 my ($process, $pid) = $parent->fork(sub{ $_->exit(1) });
1727  
1728 if ($process) {
1729 # in forked process ...
1730 $process->exit;
1731 }
1732  
1733 my ($check, $status) = $parent->check($pid);
1734  
1735 # ($pid, 1)
1736  
1737 =back
1738  
1739 =cut
1740  
1741 =head2 count
1742  
1743 count(string | coderef $code, any @args) (number)
1744  
1745 The count method dispatches to the method specified (or the L</watchlist> if
1746 not specified) and returns a count of the items returned from the dispatched
1747 call.
1748  
1749 I<Since C<2.40>>
1750  
1751 =over 4
1752  
1753 =item count example 1
1754  
1755 package main;
1756  
1757 use Venus::Process;
1758  
1759 my $parent = Venus::Process->new;
1760  
1761 my $count = $parent->count;
1762  
1763 # 0
1764  
1765 =back
1766  
1767 =over 4
1768  
1769 =item count example 2
1770  
1771 package main;
1772  
1773 use Venus::Process;
1774  
1775 my $parent = Venus::Process->new;
1776  
1777 my ($pid) = $parent->watch(1001);
1778  
1779 my $count = $parent->count;
1780  
1781 # 1
1782  
1783 =back
1784  
1785 =over 4
1786  
1787 =item count example 3
1788  
1789 package main;
1790  
1791 use Venus::Process;
1792  
1793 my $parent = Venus::Process->new;
1794  
1795 my ($pid) = $parent->watch(1001);
1796  
1797 my $count = $parent->count('watchlist');
1798  
1799 # 1
1800  
1801 =back
1802  
1803 =cut
1804  
1805 =head2 daemon
1806  
1807 daemon() (Venus::Process)
1808  
1809 The daemon method detaches the process from controlling terminal and runs it in
1810 the background as system daemon. This method internally calls L</disengage> and
1811 L</setsid> and attempts to change the working directory to the root directory.
1812  
1813 I<Since C<0.06>>
1814  
1815 =over 4
1816  
1817 =item daemon example 1
1818  
1819 # given: synopsis;
1820  
1821 my $daemon = $parent->daemon; # exits parent immediately
1822  
1823 # in forked process ...
1824  
1825 # $daemon->exit;
1826  
1827 =back
1828  
1829 =cut
1830  
1831 =head2 data
1832  
1833 data(number @pids) (number)
1834  
1835 The data method returns the number of messages sent to the current process,
1836 from the PID or PIDs provided (if any). If no PID list is provided, the count
1837 returned is based on the PIDs returned from L</watchlist>.
1838  
1839 I<Since C<2.91>>
1840  
1841 =over 4
1842  
1843 =item data example 1
1844  
1845 # given: synopsis
1846  
1847 package main;
1848  
1849 my $data = $parent->data;
1850  
1851 # 0
1852  
1853 =back
1854  
1855 =over 4
1856  
1857 =item data example 2
1858  
1859 # given: synopsis
1860  
1861 package main;
1862  
1863 # in process 1
1864  
1865 my $process_1 = Venus::Process->new(12345)->join('procs');
1866  
1867 # in process 2
1868  
1869 my $process_2 = Venus::Process->new(12346)->join('procs');
1870  
1871 # in process 3
1872  
1873 my $process_3 = Venus::Process->new(12347)->join('procs');
1874  
1875 # in process 1
1876  
1877 $process_1->pool(2)->sendall({
1878 from => $process_1->pid, said => 'hello',
1879 });
1880  
1881 # in process 2
1882  
1883 $process_2->pool(2)->sendall({
1884 from => $process_2->pid, said => 'hello',
1885 });
1886  
1887 # $process_2->data;
1888  
1889 # 2
1890  
1891 # in process 3
1892  
1893 $process_3->pool(2)->sendall({
1894 from => $process_3->pid, said => 'hello',
1895 });
1896  
1897 # $process_3->data;
1898  
1899 # 2
1900  
1901 # in process 1
1902  
1903 my $data = $process_1->data;
1904  
1905 # 2
1906  
1907 =back
1908  
1909 =over 4
1910  
1911 =item data example 3
1912  
1913 # given: synopsis
1914  
1915 package main;
1916  
1917 # in process 1
1918  
1919 my $process_1 = Venus::Process->new(12345)->join('procs');
1920  
1921 # in process 2
1922  
1923 my $process_2 = Venus::Process->new(12346)->join('procs');
1924  
1925 # in process 3
1926  
1927 my $process_3 = Venus::Process->new(12347)->join('procs');
1928  
1929 # in process 1
1930  
1931 $process_1->pool(2)->sendall({
1932 from => $process_1->pid, said => 'hello',
1933 });
1934  
1935 # in process 2
1936  
1937 $process_2->pool(2)->sendall({
1938 from => $process_2->pid, said => 'hello',
1939 });
1940  
1941 # $process_2->data;
1942  
1943 # 2
1944  
1945 # in process 3
1946  
1947 $process_3->pool(2)->sendall({
1948 from => $process_3->pid, said => 'hello',
1949 });
1950  
1951 # $process_3->data;
1952  
1953 # 2
1954  
1955 # in process 1
1956  
1957 $process_1->recvall;
1958  
1959 my $data = $process_1->data;
1960  
1961 # 0
1962  
1963 =back
1964  
1965 =cut
1966  
1967 =head2 decode
1968  
1969 decode(string $data) (any)
1970  
1971 The decode method accepts a string representation of a Perl value and returns
1972 the Perl value.
1973  
1974 I<Since C<2.91>>
1975  
1976 =over 4
1977  
1978 =item decode example 1
1979  
1980 # given: synopsis
1981  
1982 package main;
1983  
1984 my $decode = $parent->decode("{ok=>1}");
1985  
1986 # { ok => 1 }
1987  
1988 =back
1989  
1990 =cut
1991  
1992 =head2 disengage
1993  
1994 disengage() (Venus::Process)
1995  
1996 The disengage method limits the interactivity of the process by changing the
1997 working directory to the root directory and redirecting its standard file
1998 descriptors from and to C</dev/null>, or the OS' equivalent. These state
1999 changes can be undone by calling the L</engage> method.
2000  
2001 I<Since C<0.06>>
2002  
2003 =over 4
2004  
2005 =item disengage example 1
2006  
2007 # given: synopsis;
2008  
2009 $parent = $parent->disengage;
2010  
2011 # bless({...}, 'Venus::Process')
2012  
2013 =back
2014  
2015 =cut
2016  
2017 =head2 encode
2018  
2019 encode(any $data) (string)
2020  
2021 The encode method accepts a Perl value and returns a string representation of
2022 that Perl value.
2023  
2024 I<Since C<2.91>>
2025  
2026 =over 4
2027  
2028 =item encode example 1
2029  
2030 # given: synopsis
2031  
2032 package main;
2033  
2034 my $encode = $parent->encode({ok=>1});
2035  
2036 # "{ok=>1}"
2037  
2038 =back
2039  
2040 =cut
2041  
2042 =head2 engage
2043  
2044 engage() (Venus::Process)
2045  
2046 The engage method ensures the interactivity of the process by changing the
2047 working directory to the directory used to launch the process, and by
2048 redirecting/returning its standard file descriptors from and to their defaults.
2049 This method effectively does the opposite of the L</disengage> method.
2050  
2051 I<Since C<0.06>>
2052  
2053 =over 4
2054  
2055 =item engage example 1
2056  
2057 # given: synopsis;
2058  
2059 $parent = $parent->engage;
2060  
2061 # bless({...}, 'Venus::Process')
2062  
2063 =back
2064  
2065 =cut
2066  
2067 =head2 exchange
2068  
2069 exchange(string $name) (any)
2070  
2071 The exchange method gets and/or sets the name of the data exchange. The
2072 exchange is the ontext in which processes can register and cooperate. Process
2073 can cooperate in different exchanges (or contexts) and messages sent to a
2074 process in one context are not available to be retrieved will operating in
2075 another exchange (or context).
2076  
2077 I<Since C<2.91>>
2078  
2079 =over 4
2080  
2081 =item exchange example 1
2082  
2083 # given: synopsis
2084  
2085 package main;
2086  
2087 my $exchange = $parent->exchange;
2088  
2089 # undef
2090  
2091 =back
2092  
2093 =over 4
2094  
2095 =item exchange example 2
2096  
2097 # given: synopsis
2098  
2099 package main;
2100  
2101 my $exchange = $parent->exchange('procs');
2102  
2103 # "procs"
2104  
2105 =back
2106  
2107 =over 4
2108  
2109 =item exchange example 3
2110  
2111 # given: synopsis
2112  
2113 package main;
2114  
2115 my $exchange = $parent->exchange('procs');
2116  
2117 # "procs"
2118  
2119 $exchange = $parent->exchange;
2120  
2121 # "procs"
2122  
2123 =back
2124  
2125 =cut
2126  
2127 =head2 exit
2128  
2129 exit(number $status) (number)
2130  
2131 The exit method exits the program immediately.
2132  
2133 I<Since C<0.06>>
2134  
2135 =over 4
2136  
2137 =item exit example 1
2138  
2139 # given: synopsis;
2140  
2141 my $exit = $parent->exit;
2142  
2143 # 0
2144  
2145 =back
2146  
2147 =over 4
2148  
2149 =item exit example 2
2150  
2151 # given: synopsis;
2152  
2153 my $exit = $parent->exit(1);
2154  
2155 # 1
2156  
2157 =back
2158  
2159 =cut
2160  
2161 =head2 followers
2162  
2163 followers() (arrayref)
2164  
2165 The followers method returns the list of PIDs registered under the current
2166 L</exchange> who are not the L</leader>.
2167  
2168 I<Since C<2.91>>
2169  
2170 =over 4
2171  
2172 =item followers example 1
2173  
2174 # given: synopsis
2175  
2176 package main;
2177  
2178 my $followers = $parent->followers;
2179  
2180 # []
2181  
2182 =back
2183  
2184 =over 4
2185  
2186 =item followers example 2
2187  
2188 # given: synopsis
2189  
2190 package main;
2191  
2192 # in process 1
2193  
2194 my $process_1 = Venus::Process->new(12345)->register;
2195  
2196 # in process 2
2197  
2198 my $process_2 = Venus::Process->new(12346)->register;
2199  
2200 # in process 3
2201  
2202 my $process_3 = Venus::Process->new(12347)->register;
2203  
2204 # in process 1
2205  
2206 my $followers = $process_1->followers;
2207  
2208 # [12346, 12347]
2209  
2210 =back
2211  
2212 =cut
2213  
2214 =head2 fork
2215  
2216 fork(string | coderef $code, any @args) (Venus::Process, number)
2217  
2218 The fork method calls the system L<perlfunc/fork> function and creates a new
2219 process running the same program at the same point (or call site). This method
2220 returns a new L<Venus::Process> object representing the child process (from
2221 within the execution of the child process (or fork)), and returns C<undef> to
2222 the parent (or originating) process. In list context, this method returns both
2223 the process and I<PID> (or process ID) of the child process. If a callback or
2224 argument is provided it will be executed in the child process.
2225  
2226 I<Since C<0.06>>
2227  
2228 =over 4
2229  
2230 =item fork example 1
2231  
2232 # given: synopsis;
2233  
2234 $process = $parent->fork;
2235  
2236 # if ($process) {
2237 # # in forked process ...
2238 # $process->exit;
2239 # }
2240 # else {
2241 # # in parent process ...
2242 # $parent->wait(-1);
2243 # }
2244  
2245 # in child process
2246  
2247 # bless({...}, 'Venus::Process')
2248  
2249 =back
2250  
2251 =over 4
2252  
2253 =item fork example 2
2254  
2255 # given: synopsis;
2256  
2257 my $pid;
2258  
2259 ($process, $pid) = $parent->fork;
2260  
2261 # if ($process) {
2262 # # in forked process ...
2263 # $process->exit;
2264 # }
2265 # else {
2266 # # in parent process ...
2267 # $parent->wait($pid);
2268 # }
2269  
2270 # in parent process
2271  
2272 # (undef, $pid)
2273  
2274 =back
2275  
2276 =over 4
2277  
2278 =item fork example 3
2279  
2280 # given: synopsis;
2281  
2282 my $pid;
2283  
2284 ($process, $pid) = $parent->fork(sub{
2285 $$_{started} = time;
2286 });
2287  
2288 # if ($process) {
2289 # # in forked process ...
2290 # $process->exit;
2291 # }
2292 # else {
2293 # # in parent process ...
2294 # $parent->wait($pid);
2295 # }
2296  
2297 # in parent process
2298  
2299 # (undef, $pid)
2300  
2301 =back
2302  
2303 =over 4
2304  
2305 =item fork example 4
2306  
2307 # given: synopsis;
2308  
2309 $process = $parent->fork(sub{});
2310  
2311 # simulate fork failure
2312  
2313 # no forking attempted if NOT supported
2314  
2315 # Exception! (isa Venus::Process:Error) (see error_on_fork_support)
2316  
2317 =back
2318  
2319 =over 4
2320  
2321 =item fork example 5
2322  
2323 # given: synopsis
2324  
2325 $process = $parent->do('alarm', 10)->fork;
2326  
2327 # if ($process) {
2328 # # in forked process with alarm installed ...
2329 # $process->exit;
2330 # }
2331 # else {
2332 # # in parent process ...
2333 # $parent->wait(-1);
2334 # }
2335  
2336 # in child process
2337  
2338 # bless({...}, 'Venus::Process')
2339  
2340 =back
2341  
2342 =cut
2343  
2344 =head2 forks
2345  
2346 forks(string | coderef $code, any @args) (Venus::Process, within[arrayref, number])
2347  
2348 The forks method creates multiple forks by calling the L</fork> method C<n>
2349 times, based on the count specified. As with the L</fork> method, this method
2350 returns a new L<Venus::Process> object representing the child process (from
2351 within the execution of the child process (or fork)), and returns C<undef> to
2352 the parent (or originating) process. In list context, this method returns both
2353 the process and an arrayref of I<PID> values (or process IDs) for each of the
2354 child processes created. If a callback or argument is provided it will be
2355 executed in each child process.
2356  
2357 I<Since C<0.06>>
2358  
2359 =over 4
2360  
2361 =item forks example 1
2362  
2363 # given: synopsis;
2364  
2365 $process = $parent->forks(5);
2366  
2367 # if ($process) {
2368 # # do something in (each) forked process ...
2369 # $process->exit;
2370 # }
2371 # else {
2372 # # do something in parent process ...
2373 # $parent->wait(-1);
2374 # }
2375  
2376 # bless({...}, 'Venus::Process')
2377  
2378 =back
2379  
2380 =over 4
2381  
2382 =item forks example 2
2383  
2384 # given: synopsis;
2385  
2386 my $pids;
2387  
2388 ($process, $pids) = $parent->forks(5);
2389  
2390 # if ($process) {
2391 # # do something in (each) forked process ...
2392 # $process->exit;
2393 # }
2394 # else {
2395 # # do something in parent process ...
2396 # $parent->wait($_) for @$pids;
2397 # }
2398  
2399 # in parent process
2400  
2401 # (undef, $pids)
2402  
2403 =back
2404  
2405 =over 4
2406  
2407 =item forks example 3
2408  
2409 # given: synopsis;
2410  
2411 my $pids;
2412  
2413 ($process, $pids) = $parent->forks(5, sub{
2414 my ($fork, $pid, $iteration) = @_;
2415 # $iteration is the fork iteration index
2416 $fork->exit;
2417 });
2418  
2419 # if ($process) {
2420 # # do something in (each) forked process ...
2421 # $process->exit;
2422 # }
2423 # else {
2424 # # do something in parent process ...
2425 # $parent->wait($_) for @$pids;
2426 # }
2427  
2428 # in child process
2429  
2430 # bless({...}, 'Venus::Process')
2431  
2432 =back
2433  
2434 =cut
2435  
2436 =head2 future
2437  
2438 future(coderef $code, any @args) (Venus::Future)
2439  
2440 The future method creates a new object via L</async> which runs the callback
2441 asynchronously and returns a L<Venus::Future> object with a promise which
2442 eventually resolves to the value emitted or error raised.
2443  
2444 I<Since C<3.55>>
2445  
2446 =over 4
2447  
2448 =item future example 1
2449  
2450 # given: synopsis;
2451  
2452 my $future = $parent->future(sub{
2453 my ($process) = @_;
2454 # in forked process ...
2455 $process->exit;
2456 });
2457  
2458 # bless({...}, 'Venus::Future')
2459  
2460 =back
2461  
2462 =over 4
2463  
2464 =item future example 2
2465  
2466 # given: synopsis;
2467  
2468 my $future = $parent->future(sub{
2469 ($process) = @_;
2470 # in forked process ...
2471 return 'done';
2472 });
2473  
2474 # $future->fulfill;
2475  
2476 # true
2477  
2478 # $future->value;
2479  
2480 # 'done'
2481  
2482 =back
2483  
2484 =over 4
2485  
2486 =item future example 3
2487  
2488 # given: synopsis;
2489  
2490 my $future = $parent->future(sub{
2491 ($process) = @_;
2492 # in forked process ...
2493 return {status => 'done'};
2494 });
2495  
2496 # $future->fulfill;
2497  
2498 # true
2499  
2500 # $future->value
2501  
2502 # {status => 'done'}
2503  
2504 =back
2505  
2506 =over 4
2507  
2508 =item future example 4
2509  
2510 # given: synopsis;
2511  
2512 my $future = $parent->future(sub{
2513 ($process) = @_;
2514 # in forked process ...
2515 return ['done'];
2516 });
2517  
2518 # $future->fulfill;
2519  
2520 # true
2521  
2522 # my ($await) = $future->value;
2523  
2524 # ['done']
2525  
2526 =back
2527  
2528 =over 4
2529  
2530 =item future example 5
2531  
2532 # given: synopsis;
2533  
2534 my $future = $parent->future(sub{
2535 ($process) = @_;
2536 # in forked process ...
2537 $process->sendall(['send 1', 'send 2', 'send 3']);
2538 $process->sendall(['send 4']);
2539 $process->sendall(['send 5']);
2540 return;
2541 });
2542  
2543 # $future->fulfill;
2544  
2545 # true
2546  
2547 # my ($await) = $future->value;
2548  
2549 # ['send 1', 'send 2', 'send 3']
2550  
2551 =back
2552  
2553 =cut
2554  
2555 =head2 is_dyadic
2556  
2557 is_dyadic() (boolean)
2558  
2559 The is_dyadic method returns true is the process is configured to exclusively
2560 communicate with one other process, otherwise returns false.
2561  
2562 I<Since C<3.40>>
2563  
2564 =over 4
2565  
2566 =item is_dyadic example 1
2567  
2568 package main;
2569  
2570 use Venus::Process;
2571  
2572 my $process = Venus::Process->new;
2573  
2574 my $is_dyadic = $process->is_dyadic;
2575  
2576 # false
2577  
2578 =back
2579  
2580 =over 4
2581  
2582 =item is_dyadic example 2
2583  
2584 package main;
2585  
2586 use Venus::Process;
2587  
2588 my $process = Venus::Process->new->async(sub{
2589 return 'done';
2590 });
2591  
2592 my $is_dyadic = $process->is_dyadic;
2593  
2594 # true
2595  
2596 =back
2597  
2598 =cut
2599  
2600 =head2 is_follower
2601  
2602 is_follower() (boolean)
2603  
2604 The is_follower method returns true if the process is not the L</leader>, otherwise
2605 returns false.
2606  
2607 I<Since C<2.91>>
2608  
2609 =over 4
2610  
2611 =item is_follower example 1
2612  
2613 package main;
2614  
2615 use Venus::Process;
2616  
2617 my $process = Venus::Process->new;
2618  
2619 my $is_follower = $process->is_follower;
2620  
2621 # false
2622  
2623 =back
2624  
2625 =over 4
2626  
2627 =item is_follower example 2
2628  
2629 package main;
2630  
2631 use Venus::Process;
2632  
2633 my $process_1 = Venus::Process->new(12345)->register;
2634 my $process_2 = Venus::Process->new(12346)->register;
2635 my $process_3 = Venus::Process->new(12347)->register;
2636  
2637 my $is_follower = $process_1->is_follower;
2638  
2639 # false
2640  
2641 # my $is_follower = $process_2->is_follower;
2642  
2643 # true
2644  
2645 # my $is_follower = $process_3->is_follower;
2646  
2647 # true
2648  
2649 =back
2650  
2651 =over 4
2652  
2653 =item is_follower example 3
2654  
2655 package main;
2656  
2657 use Venus::Process;
2658  
2659 my $process_1 = Venus::Process->new(12345)->register;
2660 my $process_2 = Venus::Process->new(12346)->register;
2661 my $process_3 = Venus::Process->new(12347)->register;
2662  
2663 # my $is_follower = $process_1->is_follower;
2664  
2665 # false
2666  
2667 my $is_follower = $process_2->is_follower;
2668  
2669 # true
2670  
2671 # my $is_follower = $process_3->is_follower;
2672  
2673 # true
2674  
2675 =back
2676  
2677 =cut
2678  
2679 =head2 is_leader
2680  
2681 is_leader() (boolean)
2682  
2683 The is_leader method returns true if the process is the L</leader>, otherwise
2684 returns false.
2685  
2686 I<Since C<2.91>>
2687  
2688 =over 4
2689  
2690 =item is_leader example 1
2691  
2692 package main;
2693  
2694 use Venus::Process;
2695  
2696 my $process = Venus::Process->new;
2697  
2698 my $is_leader = $process->is_leader;
2699  
2700 # true
2701  
2702 =back
2703  
2704 =over 4
2705  
2706 =item is_leader example 2
2707  
2708 package main;
2709  
2710 use Venus::Process;
2711  
2712 my $process_1 = Venus::Process->new(12345)->register;
2713 my $process_2 = Venus::Process->new(12346)->register;
2714 my $process_3 = Venus::Process->new(12347)->register;
2715  
2716 my $is_leader = $process_1->is_leader;
2717  
2718 # true
2719  
2720 # my $is_leader = $process_2->is_leader;
2721  
2722 # false
2723  
2724 # my $is_leader = $process_3->is_leader;
2725  
2726 # false
2727  
2728 =back
2729  
2730 =over 4
2731  
2732 =item is_leader example 3
2733  
2734 package main;
2735  
2736 use Venus::Process;
2737  
2738 my $process_1 = Venus::Process->new(12345)->register;
2739 my $process_2 = Venus::Process->new(12346)->register;
2740 my $process_3 = Venus::Process->new(12347)->register;
2741  
2742 # my $is_leader = $process_1->is_leader;
2743  
2744 # true
2745  
2746 my $is_leader = $process_2->is_leader;
2747  
2748 # false
2749  
2750 # my $is_leader = $process_3->is_leader;
2751  
2752 # false
2753  
2754 =back
2755  
2756 =cut
2757  
2758 =head2 is_registered
2759  
2760 is_registered() (boolean)
2761  
2762 The is_registered method returns true if the process has registered using the
2763 L</register> method, otherwise returns false.
2764  
2765 I<Since C<2.91>>
2766  
2767 =over 4
2768  
2769 =item is_registered example 1
2770  
2771 package main;
2772  
2773 use Venus::Process;
2774  
2775 my $process = Venus::Process->new;
2776  
2777 my $is_registered = $process->is_registered;
2778  
2779 # false
2780  
2781 =back
2782  
2783 =over 4
2784  
2785 =item is_registered example 2
2786  
2787 package main;
2788  
2789 use Venus::Process;
2790  
2791 my $process = Venus::Process->new(12345)->register;
2792  
2793 my $is_registered = $process->is_registered;
2794  
2795 # true
2796  
2797 =back
2798  
2799 =cut
2800  
2801 =head2 is_unregistered
2802  
2803 is_unregistered() (boolean)
2804  
2805 The is_unregistered method returns true if the process has unregistered using
2806 the L</unregister> method, or had never registered at all, otherwise returns
2807 false.
2808  
2809 I<Since C<2.91>>
2810  
2811 =over 4
2812  
2813 =item is_unregistered example 1
2814  
2815 package main;
2816  
2817 use Venus::Process;
2818  
2819 my $process = Venus::Process->new;
2820  
2821 my $is_unregistered = $process->is_unregistered;
2822  
2823 # true
2824  
2825 =back
2826  
2827 =over 4
2828  
2829 =item is_unregistered example 2
2830  
2831 package main;
2832  
2833 use Venus::Process;
2834  
2835 my $process = Venus::Process->new(12345);
2836  
2837 my $is_unregistered = $process->is_unregistered;
2838  
2839 # true
2840  
2841 =back
2842  
2843 =over 4
2844  
2845 =item is_unregistered example 3
2846  
2847 package main;
2848  
2849 use Venus::Process;
2850  
2851 my $process = Venus::Process->new(12345)->register;
2852  
2853 my $is_unregistered = $process->is_unregistered;
2854  
2855 # false
2856  
2857 =back
2858  
2859 =cut
2860  
2861 =head2 join
2862  
2863 join(string $name) (Venus::Process)
2864  
2865 The join method sets the L</exchange>, registers the process with the exchange
2866 using L</register>, and clears the L</watchlist>, then returns the invocant.
2867  
2868 I<Since C<2.91>>
2869  
2870 =over 4
2871  
2872 =item join example 1
2873  
2874 package main;
2875  
2876 use Venus::Process;
2877  
2878 my $process = Venus::Process->new;
2879  
2880 $process = $process->join;
2881  
2882 # bless({...}, 'Venus::Process')
2883  
2884 =back
2885  
2886 =over 4
2887  
2888 =item join example 2
2889  
2890 package main;
2891  
2892 use Venus::Process;
2893  
2894 my $process = Venus::Process->new;
2895  
2896 $process = $process->join('procs');
2897  
2898 # bless({...}, 'Venus::Process')
2899  
2900 =back
2901  
2902 =cut
2903  
2904 =head2 kill
2905  
2906 kill(string $signal, number @pids) (number)
2907  
2908 The kill method calls the system L<perlfunc/kill> function which sends a signal
2909 to a list of processes and returns truthy or falsy. B<Note:> A truthy result
2910 doesn't necessarily mean all processes were successfully signalled.
2911  
2912 I<Since C<0.06>>
2913  
2914 =over 4
2915  
2916 =item kill example 1
2917  
2918 # given: synopsis;
2919  
2920 if ($process = $parent->fork) {
2921 # in forked process ...
2922 $process->exit;
2923 }
2924  
2925 my $kill = $parent->kill('term', int $process);
2926  
2927 # 1
2928  
2929 =back
2930  
2931 =cut
2932  
2933 =head2 killall
2934  
2935 killall(string $name, number @pids) (arrayref)
2936  
2937 The killall method accepts a list of PIDs (or uses the L</watchlist> if not
2938 provided) and returns the result of calling the L</kill> method for each PID.
2939 Returns a list in list context.
2940  
2941 I<Since C<2.40>>
2942  
2943 =over 4
2944  
2945 =item killall example 1
2946  
2947 # given: synopsis
2948  
2949 package main;
2950  
2951 if ($process = $parent->fork) {
2952 # in forked process ...
2953 $process->exit;
2954 }
2955  
2956 my $killall = $parent->killall('term');
2957  
2958 # [1]
2959  
2960 =back
2961  
2962 =over 4
2963  
2964 =item killall example 2
2965  
2966 # given: synopsis
2967  
2968 package main;
2969  
2970 if ($process = $parent->fork) {
2971 # in forked process ...
2972 $process->exit;
2973 }
2974  
2975 my $killall = $parent->killall('term', 1001..1004);
2976  
2977 # [1, 1, 1, 1]
2978  
2979 =back
2980  
2981 =cut
2982  
2983 =head2 leader
2984  
2985 leader() (number)
2986  
2987 The leader method uses a simple leader election algorithm to determine the
2988 process leader and returns the PID for that process. The leader is always the
2989 lowest value active PID (i.e. that responds to L</ping>).
2990  
2991 I<Since C<2.91>>
2992  
2993 =over 4
2994  
2995 =item leader example 1
2996  
2997 # given: synopsis
2998  
2999 package main;
3000  
3001 my $leader = $parent->leader;
3002  
3003 # 12345
3004  
3005 =back
3006  
3007 =over 4
3008  
3009 =item leader example 2
3010  
3011 # given: synopsis
3012  
3013 package main;
3014  
3015 # in process 1
3016  
3017 my $process_1 = Venus::Process->new(12345)->register;
3018  
3019 # in process 2
3020  
3021 my $process_2 = Venus::Process->new(12346)->register;
3022  
3023 # in process 3
3024  
3025 my $process_3 = Venus::Process->new(12347)->register;
3026  
3027 # in process 1
3028  
3029 my $leader = $process_3->leader;
3030  
3031 # 12345
3032  
3033 =back
3034  
3035 =over 4
3036  
3037 =item leader example 3
3038  
3039 # given: synopsis
3040  
3041 package main;
3042  
3043 my $leader = $parent->register->leader;
3044  
3045 # 12345
3046  
3047 =back
3048  
3049 =cut
3050  
3051 =head2 leave
3052  
3053 leave(string $name) (Venus::Process)
3054  
3055 The leave method sets the L</exchange> to undefined, unregisters the process
3056 using L</unregister>, and clears the L</watchlist>, then returns the invocant.
3057  
3058 I<Since C<2.91>>
3059  
3060 =over 4
3061  
3062 =item leave example 1
3063  
3064 package main;
3065  
3066 use Venus::Process;
3067  
3068 my $process = Venus::Process->new;
3069  
3070 $process = $process->leave;
3071  
3072 # bless({...}, 'Venus::Process')
3073  
3074 =back
3075  
3076 =over 4
3077  
3078 =item leave example 2
3079  
3080 package main;
3081  
3082 use Venus::Process;
3083  
3084 my $process = Venus::Process->new;
3085  
3086 $process = $process->leave('procs');
3087  
3088 # bless({...}, 'Venus::Process')
3089  
3090 =back
3091  
3092 =cut
3093  
3094 =head2 limit
3095  
3096 limit(number $count) (boolean)
3097  
3098 The limit method blocks the execution of the current process until the number
3099 of processes in the L</watchlist> falls bellow the count specified. The method
3100 returns true once execution continues if execution was blocked, and false if
3101 the limit has yet to be reached.
3102  
3103 I<Since C<3.40>>
3104  
3105 =over 4
3106  
3107 =item limit example 1
3108  
3109 package main;
3110  
3111 use Venus::Process;
3112  
3113 my $parent = Venus::Process->new;
3114  
3115 $parent->work(sub {
3116 my ($process) = @_;
3117 # in forked process ...
3118 $process->exit;
3119 });
3120  
3121 my $limit = $parent->limit(2);
3122  
3123 # false
3124  
3125 =back
3126  
3127 =over 4
3128  
3129 =item limit example 2
3130  
3131 package main;
3132  
3133 use Venus::Process;
3134  
3135 my $parent = Venus::Process->new;
3136  
3137 $parent->works(2, sub {
3138 my ($process) = @_;
3139 # in forked process ...
3140 $process->exit;
3141 });
3142  
3143 my $limit = $parent->limit(2);
3144  
3145 # true
3146  
3147 =back
3148  
3149 =cut
3150  
3151 =head2 new
3152  
3153 new(any @args) (Venus::Process)
3154  
3155 The new method constructs an instance of the package.
3156  
3157 I<Since C<4.15>>
3158  
3159 =over 4
3160  
3161 =item new example 1
3162  
3163 package main;
3164  
3165 use Venus::Process;
3166  
3167 my $new = Venus::Process->new;
3168  
3169 # bless(..., "Venus::Process")
3170  
3171 =back
3172  
3173 =over 4
3174  
3175 =item new example 2
3176  
3177 package main;
3178  
3179 use Venus::Process;
3180  
3181 my $new = Venus::Process->new(1);
3182  
3183 # bless(..., "Venus::Process")
3184  
3185 =back
3186  
3187 =over 4
3188  
3189 =item new example 3
3190  
3191 package main;
3192  
3193 use Venus::Process;
3194  
3195 my $new = Venus::Process->new(value => 1);
3196  
3197 # bless(..., "Venus::Process")
3198  
3199 =back
3200  
3201 =cut
3202  
3203 =head2 others
3204  
3205 others() (arrayref)
3206  
3207 The others method returns all L</registrants> other than the current process,
3208 i.e. all other registered process PIDs whether active or inactive.
3209  
3210 I<Since C<2.91>>
3211  
3212 =over 4
3213  
3214 =item others example 1
3215  
3216 # given: synopsis
3217  
3218 package main;
3219  
3220 my $others = $parent->others;
3221  
3222 # []
3223  
3224 =back
3225  
3226 =over 4
3227  
3228 =item others example 2
3229  
3230 # given: synopsis
3231  
3232 package main;
3233  
3234 # in process 1
3235  
3236 my $process_1 = Venus::Process->new(12345)->register;
3237  
3238 # in process 2
3239  
3240 my $process_2 = Venus::Process->new(12346)->register;
3241  
3242 # in process 3
3243  
3244 my $process_3 = Venus::Process->new(12347)->register;
3245  
3246 # in process 1
3247  
3248 my $others = $process_1->others;
3249  
3250 # [12346, 12347]
3251  
3252 =back
3253  
3254 =cut
3255  
3256 =head2 others_active
3257  
3258 others_active() (arrayref)
3259  
3260 The others_active method returns all L</registrants> other than the current
3261 process which are active, i.e. all other registered process PIDs that responds
3262 to L</ping>.
3263  
3264 I<Since C<2.91>>
3265  
3266 =over 4
3267  
3268 =item others_active example 1
3269  
3270 # given: synopsis
3271  
3272 package main;
3273  
3274 # in process 1
3275  
3276 my $process_1 = Venus::Process->new(12345)->register;
3277  
3278 # in process 2
3279  
3280 my $process_2 = Venus::Process->new(12346)->register;
3281  
3282 # in process 3
3283  
3284 my $process_3 = Venus::Process->new(12347)->register;
3285  
3286 # in process 1
3287  
3288 my $others_active = $process_1->others_active;
3289  
3290 # [12346, 12347]
3291  
3292 =back
3293  
3294 =cut
3295  
3296 =head2 others_inactive
3297  
3298 others_inactive() (arrayref)
3299  
3300 The others_inactive method returns all L</registrants> other than the current
3301 process which are inactive, i.e. all other registered process PIDs that do not
3302 respond to L</ping>.
3303  
3304 I<Since C<2.91>>
3305  
3306 =over 4
3307  
3308 =item others_inactive example 1
3309  
3310 # given: synopsis
3311  
3312 package main;
3313  
3314 # in process 1
3315  
3316 my $process_1 = Venus::Process->new(12345)->register;
3317  
3318 # in process 2
3319  
3320 my $process_2 = Venus::Process->new(12346)->register;
3321  
3322 # in process 3
3323  
3324 my $process_3 = Venus::Process->new(12347)->register;
3325  
3326 # in process 1 (assuming all processes exited)
3327  
3328 my $others_inactive = $process_1->others_inactive;
3329  
3330 # [12346, 12347]
3331  
3332 =back
3333  
3334 =cut
3335  
3336 =head2 pid
3337  
3338 pid() (number)
3339  
3340 The pid method returns the PID of the current process.
3341  
3342 I<Since C<2.40>>
3343  
3344 =over 4
3345  
3346 =item pid example 1
3347  
3348 package main;
3349  
3350 use Venus::Process;
3351  
3352 my $parent = Venus::Process->new;
3353  
3354 my $pid = $parent->pid;
3355  
3356 # 00000
3357  
3358 =back
3359  
3360 =cut
3361  
3362 =head2 pids
3363  
3364 pids() (arrayref)
3365  
3366 The pids method returns the PID of the current process, and the PIDs of any
3367 child processes.
3368  
3369 I<Since C<2.40>>
3370  
3371 =over 4
3372  
3373 =item pids example 1
3374  
3375 package main;
3376  
3377 use Venus::Process;
3378  
3379 my $parent = Venus::Process->new;
3380  
3381 my $pids = $parent->pids;
3382  
3383 # [00000]
3384  
3385 =back
3386  
3387 =over 4
3388  
3389 =item pids example 2
3390  
3391 package main;
3392  
3393 use Venus::Process;
3394  
3395 my $parent = Venus::Process->new;
3396  
3397 $parent->watch(1001..1004);
3398  
3399 my $pids = $parent->pids;
3400  
3401 # [00000, 1001..1004]
3402  
3403 =back
3404  
3405 =cut
3406  
3407 =head2 ping
3408  
3409 ping(number @pids) (number)
3410  
3411 The ping method returns truthy if the process of the PID provided is active. If
3412 multiple PIDs are provided, this method will return the count of active PIDs.
3413  
3414 I<Since C<2.01>>
3415  
3416 =over 4
3417  
3418 =item ping example 1
3419  
3420 # given: synopsis;
3421  
3422 if ($process = $parent->fork) {
3423 # in forked process ...
3424 $process->exit;
3425 }
3426  
3427 my $ping = $parent->ping(int $process);
3428  
3429 # 1
3430  
3431 =back
3432  
3433 =cut
3434  
3435 =head2 poll
3436  
3437 poll(number $timeout, string | coderef $code, any @args) (arrayref)
3438  
3439 The poll method continuously calls the named method or coderef and returns the
3440 result that's not undefined, or throws an exception on timeout. If no method
3441 name is provided this method will default to calling L</recvall>.
3442  
3443 I<Since C<2.91>>
3444  
3445 =over 4
3446  
3447 =item poll example 1
3448  
3449 # given: synopsis
3450  
3451 package main;
3452  
3453 my $poll = $parent->poll(0, 'ping', $parent->pid);
3454  
3455 # [1]
3456  
3457 =back
3458  
3459 =over 4
3460  
3461 =item poll example 2
3462  
3463 # given: synopsis
3464  
3465 package main;
3466  
3467 my $poll = $parent->poll(5, 'ping', $parent->pid);
3468  
3469 # [1]
3470  
3471 =back
3472  
3473 =over 4
3474  
3475 =item poll example 3
3476  
3477 # given: synopsis
3478  
3479 package main;
3480  
3481 my $poll = $parent->poll(0, 'recv', $parent->pid);
3482  
3483 # Exception! (isa Venus::Process::Error) (see error_on_timeout_poll)
3484  
3485 =back
3486  
3487 =over 4
3488  
3489 =item poll example 4
3490  
3491 # given: synopsis
3492  
3493 package main;
3494  
3495 my $poll = $parent->poll(5, sub {
3496 int(rand(2)) ? "" : ()
3497 });
3498  
3499 # [""]
3500  
3501 =back
3502  
3503 =cut
3504  
3505 =head2 pool
3506  
3507 pool(number $count, number $timeout) (Venus::Process)
3508  
3509 The pool method blocks the execution of the current process until the number of
3510 L</other> processes are registered and pingable. This method returns the
3511 invocant when successful, or throws an exception if the operation timed out.
3512  
3513 I<Since C<2.91>>
3514  
3515 =over 4
3516  
3517 =item pool example 1
3518  
3519 # given: synopsis
3520  
3521 package main;
3522  
3523 # in process 1
3524  
3525 my $process_1 = Venus::Process->new(12345)->register;
3526  
3527 # in process 2
3528  
3529 my $process_2 = Venus::Process->new(12346)->register;
3530  
3531 # in process 1
3532  
3533 $process_1 = $process_1->pool;
3534  
3535 # bless({...}, 'Venus::Process')
3536  
3537 =back
3538  
3539 =over 4
3540  
3541 =item pool example 2
3542  
3543 # given: synopsis
3544  
3545 package main;
3546  
3547 # in process 1
3548  
3549 my $process_1 = Venus::Process->new(12345)->register;
3550  
3551 # in process 2
3552  
3553 my $process_2 = Venus::Process->new(12346)->register;
3554  
3555 # in process 3
3556  
3557 my $process_3 = Venus::Process->new(12347)->register;
3558  
3559 # in process 1
3560  
3561 $process_1 = $process_1->pool(2);
3562  
3563 # bless({...}, 'Venus::Process')
3564  
3565 =back
3566  
3567 =over 4
3568  
3569 =item pool example 3
3570  
3571 # given: synopsis
3572  
3573 package main;
3574  
3575 # in process 1
3576  
3577 my $process_1 = Venus::Process->new(12345)->register;
3578  
3579 # in process 2
3580  
3581 my $process_2 = Venus::Process->new(12346)->register;
3582  
3583 # in process 3
3584  
3585 my $process_3 = Venus::Process->new(12347)->register;
3586  
3587 # in process 1
3588  
3589 $process_1 = $process_1->pool(3, 0);
3590  
3591 # Exception! (isa Venus::Process::Error) (see error_on_timeout_pool)
3592  
3593 =back
3594  
3595 =cut
3596  
3597 =head2 ppid
3598  
3599 ppid() (number)
3600  
3601 The ppid method returns the PID of the parent process (i.e. the process which
3602 forked the current process, if any).
3603  
3604 I<Since C<2.91>>
3605  
3606 =over 4
3607  
3608 =item ppid example 1
3609  
3610 # given: synopsis;
3611  
3612 my $ppid = $parent->ppid;
3613  
3614 # undef
3615  
3616 =back
3617  
3618 =over 4
3619  
3620 =item ppid example 2
3621  
3622 # given: synopsis;
3623  
3624 $process = $parent->fork;
3625  
3626 # in child process
3627  
3628 my $ppid = $process->ppid;
3629  
3630 # 00000
3631  
3632 =back
3633  
3634 =cut
3635  
3636 =head2 prune
3637  
3638 prune() (Venus::Process)
3639  
3640 The prune method removes all stopped processes and returns the invocant.
3641  
3642 I<Since C<2.40>>
3643  
3644 =over 4
3645  
3646 =item prune example 1
3647  
3648 package main;
3649  
3650 use Venus::Process;
3651  
3652 my $parent = Venus::Process->new;
3653  
3654 $parent->watch(1001);
3655  
3656 $parent = $parent->prune;
3657  
3658 # bless({...}, 'Venus::Process')
3659  
3660 =back
3661  
3662 =over 4
3663  
3664 =item prune example 2
3665  
3666 package main;
3667  
3668 use Venus::Process;
3669  
3670 my $parent = Venus::Process->new;
3671  
3672 my $process = $parent->fork;
3673  
3674 if ($process) {
3675 # in forked process ...
3676 $process->exit;
3677 }
3678  
3679 $parent = $parent->prune;
3680  
3681 # bless({...}, 'Venus::Process')
3682  
3683 =back
3684  
3685 =over 4
3686  
3687 =item prune example 3
3688  
3689 package main;
3690  
3691 use Venus::Process;
3692  
3693 my $parent = Venus::Process->new;
3694  
3695 $parent->work(sub {
3696 my ($process) = @_;
3697 # in forked process ...
3698 $process->exit;
3699 });
3700  
3701 $parent = $parent->prune;
3702  
3703 # bless({...}, 'Venus::Process')
3704  
3705 =back
3706  
3707 =cut
3708  
3709 =head2 recall
3710  
3711 recall(number $pid) (any)
3712  
3713 The recall method returns the earliest message, sent by the current process to
3714 the process specified by the PID provided, which is no longer active (i.e.
3715 responding to L</ping>).
3716  
3717 I<Since C<2.91>>
3718  
3719 =over 4
3720  
3721 =item recall example 1
3722  
3723 # given: synopsis
3724  
3725 package main;
3726  
3727 # in process 1
3728  
3729 my $process_1 = Venus::Process->new(12345)->register;
3730  
3731 # in process 2
3732  
3733 my $process_2 = Venus::Process->new(12346)->register;
3734  
3735 # in process 1
3736  
3737 $process_1->send($process_2->pid, {from => $process_1->pid});
3738  
3739 # in process 1 (process 2)
3740  
3741 my $recall = $process_1->recall($process_2->pid);
3742  
3743 # {from => 12345}
3744  
3745 =back
3746  
3747 =cut
3748  
3749 =head2 recallall
3750  
3751 recallall() (arrayref)
3752  
3753 The recallall method performs a L</recall> on the parent process (if any) via
3754 L</ppid> and any process listed in the L</watchlist>, and returns the results.
3755  
3756 I<Since C<2.91>>
3757  
3758 =over 4
3759  
3760 =item recallall example 1
3761  
3762 # given: synopsis
3763  
3764 package main;
3765  
3766 # in process 1
3767  
3768 my $process_1 = Venus::Process->new(12345)->register;
3769  
3770 # in process 2
3771  
3772 my $process_2 = Venus::Process->new(12346)->register;
3773  
3774 # in process 3
3775  
3776 my $process_3 = Venus::Process->new(12347)->register;
3777  
3778 # in process 1
3779  
3780 $process_1->send($process_2->pid, {from => $process_1->pid});
3781  
3782 $process_1->send($process_3->pid, {from => $process_1->pid});
3783  
3784 $process_1->watch($process_2->pid, $process_3->pid);
3785  
3786 # in process 1 (process 2 and 3 died)
3787  
3788 my $recallall = $process_1->recallall;
3789  
3790 # [{from => 12345}, {from => 12345}]
3791  
3792 =back
3793  
3794 =cut
3795  
3796 =head2 recv
3797  
3798 recv(number $pid) (any)
3799  
3800 The recv method returns the earliest message found from the process specified
3801 by the PID provided.
3802  
3803 I<Since C<2.91>>
3804  
3805 =over 4
3806  
3807 =item recv example 1
3808  
3809 # given: synopsis
3810  
3811 package main;
3812  
3813 my $recv = $parent->recv;
3814  
3815 # undef
3816  
3817 =back
3818  
3819 =over 4
3820  
3821 =item recv example 2
3822  
3823 # given: synopsis
3824  
3825 package main;
3826  
3827 # in process 1
3828  
3829 my $process_1 = Venus::Process->new(12345);
3830  
3831 # in process 2
3832  
3833 my $process_2 = Venus::Process->new(12346);
3834  
3835 # in process 1
3836  
3837 my $recv = $process_1->recv($process_2->pid);
3838  
3839 # undef
3840  
3841 # in process 2
3842  
3843 $process_2->send($process_1->pid, {from => $process_2->pid, said => 'hello'});
3844  
3845 # in process 1
3846  
3847 $recv = $process_1->recv($process_2->pid);
3848  
3849 # {from => 12346, said => 'hello'}
3850  
3851 =back
3852  
3853 =cut
3854  
3855 =head2 recvall
3856  
3857 recvall() (arrayref)
3858  
3859 The recvall method performs a L</recv> on the parent process (if any) via
3860 L</ppid> and any process listed in the L</watchlist>, and returns the results.
3861  
3862 I<Since C<2.91>>
3863  
3864 =over 4
3865  
3866 =item recvall example 1
3867  
3868 # given: synopsis
3869  
3870 package main;
3871  
3872 # in process 1
3873  
3874 my $process_1 = Venus::Process->new(12345)->register;
3875  
3876 # in process 2
3877  
3878 my $process_2 = Venus::Process->new(12346)->register;
3879  
3880 $process_2->send($process_1->pid, {from => $process_2->pid});
3881  
3882 # in process 3
3883  
3884 my $process_3 = Venus::Process->new(12347)->register;
3885  
3886 $process_3->send($process_1->pid, {from => $process_3->pid});
3887  
3888 # in process 1
3889  
3890 my $recvall = $process_1->pool(2)->recvall;
3891  
3892 # [{from => 12346}, {from => 12347}]
3893  
3894 =back
3895  
3896 =over 4
3897  
3898 =item recvall example 2
3899  
3900 # given: synopsis
3901  
3902 package main;
3903  
3904 # in process 1
3905  
3906 my $process_1 = Venus::Process->new(12345)->register;
3907  
3908 # in process 2
3909  
3910 my $process_2 = Venus::Process->new(12346)->register;
3911  
3912 $process_2->send($process_1->pid, {from => $process_2->pid});
3913  
3914 # in process 3
3915  
3916 my $process_3 = Venus::Process->new(12347)->register;
3917  
3918 $process_3->send($process_1->pid, {from => $process_3->pid});
3919  
3920 # in process 1
3921  
3922 my $recvall = $process_1->pool(2)->recvall;
3923  
3924 # [{from => 12346}, {from => 12347}]
3925  
3926 # in process 2
3927  
3928 $process_2->send($process_1->pid, {from => $process_2->pid});
3929  
3930 # in process 1
3931  
3932 $recvall = $process_1->recvall;
3933  
3934 # [{from => 12346}]
3935  
3936 =back
3937  
3938 =cut
3939  
3940 =head2 register
3941  
3942 register() (Venus::Process)
3943  
3944 The register method declares that the process is willing to cooperate with
3945 others (e.g. L</send> nad L</recv> messages), in a way that's discoverable by
3946 other processes, and returns the invocant.
3947  
3948 I<Since C<2.91>>
3949  
3950 =over 4
3951  
3952 =item register example 1
3953  
3954 # given: synopsis
3955  
3956 package main;
3957  
3958 my $register = $parent->register;
3959  
3960 # bless({...}, 'Venus::Process')
3961  
3962 =back
3963  
3964 =cut
3965  
3966 =head2 registrants
3967  
3968 registrants() (arrayref)
3969  
3970 The registrants method returns the PIDs for all the processes that registered
3971 using the L</register> method whether they're currently active or not.
3972  
3973 I<Since C<2.91>>
3974  
3975 =over 4
3976  
3977 =item registrants example 1
3978  
3979 # given: synopsis
3980  
3981 package main;
3982  
3983 # in process 1
3984  
3985 my $process_1 = Venus::Process->new(12345)->register;
3986  
3987 # in process 2
3988  
3989 my $process_2 = Venus::Process->new(12346)->register;
3990  
3991 # in process 3
3992  
3993 my $process_3 = Venus::Process->new(12347)->register;
3994  
3995 # in process 1
3996  
3997 my $registrants = $process_1->registrants;
3998  
3999 # [12345, 12346, 12347]
4000  
4001 =back
4002  
4003 =cut
4004  
4005 =head2 restart
4006  
4007 restart(coderef $callback) (arrayref)
4008  
4009 The restart method executes the callback provided for each PID returned by the
4010 L</stopped> method, passing the pid and the results of L</check> to the
4011 callback as arguments, and returns the result of each call as an arrayref. In
4012 list context, this method returns a list.
4013  
4014 I<Since C<2.40>>
4015  
4016 =over 4
4017  
4018 =item restart example 1
4019  
4020 # given: synopsis
4021  
4022 package main;
4023  
4024 $parent->watch(1001);
4025  
4026 my $restart = $parent->restart(sub {
4027 my ($pid, $check, $exit) = @_;
4028  
4029 # redeploy stopped process
4030  
4031 return [$pid, $check, $exit];
4032 });
4033  
4034 # [[1001, 1001, 255]]
4035  
4036 =back
4037  
4038 =cut
4039  
4040 =head2 send
4041  
4042 send(number $pid, any $data) (Venus::Process)
4043  
4044 The send method makes the data provided available to the process specified by
4045 the PID provided.
4046  
4047 I<Since C<2.91>>
4048  
4049 =over 4
4050  
4051 =item send example 1
4052  
4053 # given: synopsis
4054  
4055 package main;
4056  
4057 my $send = $parent->send;
4058  
4059 # bless({...}, 'Venus::Process')
4060  
4061 =back
4062  
4063 =over 4
4064  
4065 =item send example 2
4066  
4067 # given: synopsis
4068  
4069 package main;
4070  
4071 # in process 1
4072  
4073 my $process_1 = Venus::Process->new(12345);
4074  
4075 # in process 2
4076  
4077 my $process_2 = Venus::Process->new(12346);
4078  
4079 # in process 1
4080  
4081 $process_1 = $process_1->send($process_2->pid, {
4082 from => $process_1->pid, said => 'hello',
4083 });
4084  
4085 # bless({...}, 'Venus::Process')
4086  
4087 # in process 2
4088  
4089 # $process_2->recv($process_1->pid);
4090  
4091 # {from => 12345, said => 'hello'}
4092  
4093 =back
4094  
4095 =cut
4096  
4097 =head2 sendall
4098  
4099 sendall(any $data) (Venus::Process)
4100  
4101 The sendall method performs a L</send> on the parent process (if any) via
4102 L</ppid> and any process listed in the L</watchlist>, and returns the invocant.
4103  
4104 I<Since C<2.91>>
4105  
4106 =over 4
4107  
4108 =item sendall example 1
4109  
4110 # given: synopsis
4111  
4112 package main;
4113  
4114 # in process 1
4115  
4116 my $process_1 = Venus::Process->new(12345)->register;
4117  
4118 # in process 2
4119  
4120 my $process_2 = Venus::Process->new(12346)->register;
4121  
4122 # in process 3
4123  
4124 my $process_3 = Venus::Process->new(12347)->register;
4125  
4126 # in process 1
4127  
4128 $process_1 = $process_1->pool(2)->sendall({
4129 from => $process_1->pid, said => 'hello',
4130 });
4131  
4132 # bless({...}, 'Venus::Process')
4133  
4134 =back
4135  
4136 =cut
4137  
4138 =head2 serve
4139  
4140 serve(number $count, coderef $callback) (Venus::Process)
4141  
4142 The serve method executes the callback using L</work> until L</limit> blocks
4143 the execution of the current process, indefinitely. It has the effect of
4144 serving the callback and maintaining the desired number of forks until killed
4145 or gracefully shutdown.
4146  
4147 I<Since C<3.40>>
4148  
4149 =over 4
4150  
4151 =item serve example 1
4152  
4153 package main;
4154  
4155 use Venus::Process;
4156  
4157 my $parent = Venus::Process->new;
4158  
4159 $parent->serve(2, sub {
4160 my ($process) = @_;
4161 # in forked process ...
4162 $process->exit;
4163 });
4164  
4165 # ...
4166  
4167 # bless({...}, "Venus::Process")
4168  
4169 =back
4170  
4171 =over 4
4172  
4173 =item serve example 2
4174  
4175 package main;
4176  
4177 use Venus::Process;
4178  
4179 my $parent = Venus::Process->new;
4180  
4181 $parent->serve(10, sub {
4182 my ($process) = @_;
4183 # in forked process ...
4184 $process->exit;
4185 });
4186  
4187 # ...
4188  
4189 # bless({...}, "Venus::Process")
4190  
4191 =back
4192  
4193 =cut
4194  
4195 =head2 setsid
4196  
4197 setsid() (number)
4198  
4199 The setsid method calls the L<POSIX/setsid> function and sets the process group
4200 identifier of the current process.
4201  
4202 I<Since C<0.06>>
4203  
4204 =over 4
4205  
4206 =item setsid example 1
4207  
4208 # given: synopsis;
4209  
4210 my $setsid = $parent->setsid;
4211  
4212 # 1
4213  
4214 =back
4215  
4216 =over 4
4217  
4218 =item setsid example 2
4219  
4220 # given: synopsis;
4221  
4222 my $setsid = $parent->setsid;
4223  
4224 # Exception! (isa Venus::Process::Error) (see error_on_setid)
4225  
4226 =back
4227  
4228 =cut
4229  
4230 =head2 started
4231  
4232 started() (arrayref)
4233  
4234 The started method returns a list of PIDs whose processes have been started and
4235 which have not terminated. Returns a list in list context.
4236  
4237 I<Since C<2.40>>
4238  
4239 =over 4
4240  
4241 =item started example 1
4242  
4243 # given: synopsis
4244  
4245 package main;
4246  
4247 my $started = $parent->started;
4248  
4249 # child not terminated
4250  
4251 # [...]
4252  
4253 =back
4254  
4255 =over 4
4256  
4257 =item started example 2
4258  
4259 # given: synopsis
4260  
4261 package main;
4262  
4263 my $started = $parent->started;
4264  
4265 # child terminated
4266  
4267 # []
4268  
4269 =back
4270  
4271 =cut
4272  
4273 =head2 status
4274  
4275 status(coderef $callback) (arrayref)
4276  
4277 The status method executes the callback provided for each PID in the
4278 L</watchlist>, passing the pid and the results of L</check> to the callback as
4279 arguments, and returns the result of each call as an arrayref. In list context,
4280 this method returns a list.
4281  
4282 I<Since C<2.40>>
4283  
4284 =over 4
4285  
4286 =item status example 1
4287  
4288 package main;
4289  
4290 use Venus::Process;
4291  
4292 my $parent = Venus::Process->new;
4293  
4294 $parent->watch(12346);
4295  
4296 my $status = $parent->status(sub {
4297 my ($pid, $check, $exit) = @_;
4298  
4299 # assuming PID 12346 is still running (not terminated)
4300 return [$pid, $check, $exit];
4301 });
4302  
4303 # [[12346, 0, -1]]
4304  
4305 =back
4306  
4307 =over 4
4308  
4309 =item status example 2
4310  
4311 package main;
4312  
4313 use Venus::Process;
4314  
4315 my $parent = Venus::Process->new;
4316  
4317 $parent->watch(12346);
4318  
4319 my $status = $parent->status(sub {
4320 my ($pid, $check, $exit) = @_;
4321  
4322 # assuming process 12346 terminated with exit code 255
4323 return [$pid, $check, $exit];
4324 });
4325  
4326 # [[12346, 12346, 255]]
4327  
4328 =back
4329  
4330 =over 4
4331  
4332 =item status example 3
4333  
4334 package main;
4335  
4336 use Venus::Process;
4337  
4338 my $parent = Venus::Process->new;
4339  
4340 $parent->watch(12346);
4341  
4342 my @status = $parent->status(sub {
4343 my ($pid, $check, $exit) = @_;
4344  
4345 # assuming process 12346 terminated with exit code 255
4346 return [$pid, $check, $exit];
4347 });
4348  
4349 # ([12346, 12346, 255])
4350  
4351 =back
4352  
4353 =cut
4354  
4355 =head2 stderr
4356  
4357 stderr(string $path) (Venus::Process)
4358  
4359 The stderr method redirects C<STDERR> to the path provided, typically
4360 C</dev/null> or some equivalent. If called with no arguments C<STDERR> will be
4361 restored to its default.
4362  
4363 I<Since C<0.06>>
4364  
4365 =over 4
4366  
4367 =item stderr example 1
4368  
4369 # given: synopsis;
4370  
4371 $parent = $parent->stderr;
4372  
4373 # bless({...}, 'Venus::Process')
4374  
4375 =back
4376  
4377 =over 4
4378  
4379 =item stderr example 2
4380  
4381 # given: synopsis;
4382  
4383 $parent = $parent->stderr('/nowhere');
4384  
4385 # Exception! (isa Venus::Process:Error) (see error_on_stderr)
4386  
4387 =back
4388  
4389 =over 4
4390  
4391 =item B<may raise> L<Venus::Process::Error> C<on.stderr>
4392  
4393 # given: synopsis;
4394  
4395 $parent->stderr('/path/to/nowhere');
4396  
4397 # Error! (on.stderr)
4398  
4399 =back
4400  
4401 =cut
4402  
4403 =head2 stdin
4404  
4405 stdin(string $path) (Venus::Process)
4406  
4407 The stdin method redirects C<STDIN> to the path provided, typically
4408 C</dev/null> or some equivalent. If called with no arguments C<STDIN> will be
4409 restored to its default.
4410  
4411 I<Since C<0.06>>
4412  
4413 =over 4
4414  
4415 =item stdin example 1
4416  
4417 # given: synopsis;
4418  
4419 $parent = $parent->stdin;
4420  
4421 # bless({...}, 'Venus::Process')
4422  
4423 =back
4424  
4425 =over 4
4426  
4427 =item stdin example 2
4428  
4429 # given: synopsis;
4430  
4431 $parent = $parent->stdin('/nowhere');
4432  
4433 # Exception! (isa Venus::Process::Error) (see error_on_stdin)
4434  
4435 =back
4436  
4437 =over 4
4438  
4439 =item B<may raise> L<Venus::Process::Error> C<on.stdin>
4440  
4441 # given: synopsis;
4442  
4443 $parent->stdin('/path/to/nowhere');
4444  
4445 # Error! (on.stdin)
4446  
4447 =back
4448  
4449 =cut
4450  
4451 =head2 stdout
4452  
4453 stdout(string $path) (Venus::Process)
4454  
4455 The stdout method redirects C<STDOUT> to the path provided, typically
4456 C</dev/null> or some equivalent. If called with no arguments C<STDOUT> will be
4457 restored to its default.
4458  
4459 I<Since C<0.06>>
4460  
4461 =over 4
4462  
4463 =item stdout example 1
4464  
4465 # given: synopsis;
4466  
4467 $parent = $parent->stdout;
4468  
4469 # bless({...}, 'Venus::Process')
4470  
4471 =back
4472  
4473 =over 4
4474  
4475 =item stdout example 2
4476  
4477 # given: synopsis;
4478  
4479 $parent = $parent->stdout('/nowhere');
4480  
4481 # Exception! Venus::Process::Error (error_on_stdout)
4482  
4483 =back
4484  
4485 =over 4
4486  
4487 =item B<may raise> L<Venus::Process::Error> C<on.stdout>
4488  
4489 # given: synopsis;
4490  
4491 $parent->stdout('/path/to/nowhere');
4492  
4493 # Error! (on.stdout)
4494  
4495 =back
4496  
4497 =cut
4498  
4499 =head2 stopped
4500  
4501 stopped() (arrayref)
4502  
4503 The stopped method returns a list of PIDs whose processes have terminated.
4504 Returns a list in list context.
4505  
4506 I<Since C<2.40>>
4507  
4508 =over 4
4509  
4510 =item stopped example 1
4511  
4512 # given: synopsis
4513  
4514 package main;
4515  
4516 my $stopped = $parent->stopped;
4517  
4518 # child terminated
4519  
4520 # [...]
4521  
4522 =back
4523  
4524 =over 4
4525  
4526 =item stopped example 2
4527  
4528 # given: synopsis
4529  
4530 package main;
4531  
4532 my $stopped = $parent->stopped;
4533  
4534 # child not terminated
4535  
4536 # []
4537  
4538 =back
4539  
4540 =cut
4541  
4542 =head2 sync
4543  
4544 sync(number $count, number $timeout) (Venus::Process)
4545  
4546 The sync method blocks the execution of the current process until the number of
4547 L</other> processes are registered, pingable, and have each sent at-least one
4548 message to the current process. This method returns the invocant when
4549 successful, or throws an exception if the operation timed out.
4550  
4551 I<Since C<2.91>>
4552  
4553 =over 4
4554  
4555 =item sync example 1
4556  
4557 # given: synopsis
4558  
4559 package main;
4560  
4561 # in process 1
4562  
4563 my $process_1 = Venus::Process->new(12345)->register;
4564  
4565 # in process 2
4566  
4567 my $process_2 = Venus::Process->new(12346)->register;
4568  
4569 $process_2->send($process_1->pid, {from => $process_2->pid, said => "hello"});
4570  
4571 # in process 1
4572  
4573 $process_1 = $process_1->sync;
4574  
4575 # bless({...}, 'Venus::Process')
4576  
4577 =back
4578  
4579 =over 4
4580  
4581 =item sync example 2
4582  
4583 # given: synopsis
4584  
4585 package main;
4586  
4587 # in process 1
4588  
4589 my $process_1 = Venus::Process->new(12345)->register;
4590  
4591 # in process 2
4592  
4593 my $process_2 = Venus::Process->new(12346)->register;
4594  
4595 $process_2->send($process_1->pid, {from => $process_2->pid, said => "hello"});
4596  
4597 # in process 3
4598  
4599 my $process_3 = Venus::Process->new(12347)->register;
4600  
4601 $process_3->send($process_1->pid, {from => $process_3->pid, said => "hello"});
4602  
4603 # in process 1
4604  
4605 $process_1 = $process_1->sync(2);
4606  
4607 # bless({...}, 'Venus::Process')
4608  
4609 =back
4610  
4611 =over 4
4612  
4613 =item sync example 3
4614  
4615 # given: synopsis
4616  
4617 package main;
4618  
4619 # in process 1
4620  
4621 my $process_1 = Venus::Process->new(12345)->register;
4622  
4623 # in process 2
4624  
4625 my $process_2 = Venus::Process->new(12346)->register;
4626  
4627 $process_2->send($process_1->pid, {from => $process_2->pid, said => "hello"});
4628  
4629 # in process 3
4630  
4631 my $process_3 = Venus::Process->new(12347)->register;
4632  
4633 $process_3->send($process_1->pid, {from => $process_3->pid, said => "hello"});
4634  
4635 # in process 1
4636  
4637 $process_1 = $process_1->sync(3, 0);
4638  
4639 # Exception! (isa Venus::Process::Error) (see error_on_timeout_sync)
4640  
4641 =back
4642  
4643 =cut
4644  
4645 =head2 trap
4646  
4647 trap(string $name, string | coderef $expr) (Venus::Process)
4648  
4649 The trap method registers a process signal trap (or callback) which will be
4650 invoked whenever the current process receives that matching signal. The signal
4651 traps are globally installed and will overwrite any preexisting behavior.
4652 Signal traps are inherited by child processes (or forks) but can be overwritten
4653 using this method, or reverted to the default behavior by using the L</untrap>
4654 method.
4655  
4656 I<Since C<0.06>>
4657  
4658 =over 4
4659  
4660 =item trap example 1
4661  
4662 # given: synopsis;
4663  
4664 $parent = $parent->trap(term => sub{
4665 die 'Something failed!';
4666 });
4667  
4668 # bless({...}, 'Venus::Process')
4669  
4670 =back
4671  
4672 =cut
4673  
4674 =head2 unregister
4675  
4676 unregister() (Venus::Process)
4677  
4678 The unregister method declares that the process is no longer willing to
4679 cooperate with others (e.g. L</send> nad L</recv> messages), and will no longer
4680 be discoverable by other processes, and returns the invocant.
4681  
4682 I<Since C<2.91>>
4683  
4684 =over 4
4685  
4686 =item unregister example 1
4687  
4688 # given: synopsis
4689  
4690 package main;
4691  
4692 my $unregister = $parent->unregister;
4693  
4694 # bless({...}, 'Venus::Process')
4695  
4696 =back
4697  
4698 =cut
4699  
4700 =head2 untrap
4701  
4702 untrap(string $name) (Venus::Process)
4703  
4704 The untrap method restores the process signal trap specified to its default
4705 behavior. If called with no arguments, it restores all signal traps overwriting
4706 any user-defined signal traps in the current process.
4707  
4708 I<Since C<0.06>>
4709  
4710 =over 4
4711  
4712 =item untrap example 1
4713  
4714 # given: synopsis;
4715  
4716 $parent->trap(chld => 'ignore')->trap(term => sub{
4717 die 'Something failed!';
4718 });
4719  
4720 $parent = $parent->untrap('term');
4721  
4722 # bless({...}, 'Venus::Process')
4723  
4724 =back
4725  
4726 =over 4
4727  
4728 =item untrap example 2
4729  
4730 # given: synopsis;
4731  
4732 $parent->trap(chld => 'ignore')->trap(term => sub{
4733 die 'Something failed!';
4734 });
4735  
4736 $parent = $parent->untrap;
4737  
4738 # bless({...}, 'Venus::Process')
4739  
4740 =back
4741  
4742 =cut
4743  
4744 =head2 unwatch
4745  
4746 unwatch(number @pids) (arrayref)
4747  
4748 The unwatch method removes the PIDs provided from the watchlist and returns the
4749 list of PIDs remaining to be watched. In list context returns a list.
4750  
4751 I<Since C<2.40>>
4752  
4753 =over 4
4754  
4755 =item unwatch example 1
4756  
4757 package main;
4758  
4759 use Venus::Process;
4760  
4761 my $parent = Venus::Process->new;
4762  
4763 my $unwatch = $parent->unwatch;
4764  
4765 # []
4766  
4767 =back
4768  
4769 =over 4
4770  
4771 =item unwatch example 2
4772  
4773 package main;
4774  
4775 use Venus::Process;
4776  
4777 my $parent = Venus::Process->new;
4778  
4779 $parent->watch(1001..1004);
4780  
4781 my $unwatch = $parent->unwatch(1001);
4782  
4783 # [1002..1004]
4784  
4785 =back
4786  
4787 =over 4
4788  
4789 =item unwatch example 3
4790  
4791 package main;
4792  
4793 use Venus::Process;
4794  
4795 my $parent = Venus::Process->new;
4796  
4797 $parent->watch(1001..1004);
4798  
4799 my $unwatch = $parent->unwatch(1002, 1004);
4800  
4801 # [1001, 1003]
4802  
4803 =back
4804  
4805 =cut
4806  
4807 =head2 wait
4808  
4809 wait(number $pid) (number, number)
4810  
4811 The wait method does a blocking L<perlfunc/waitpid> operation and returns the
4812 wait status. In list context, returns the specified process' exit code (if
4813 terminated).
4814  
4815 I<Since C<0.06>>
4816  
4817 =over 4
4818  
4819 =item wait example 1
4820  
4821 package main;
4822  
4823 use Venus::Process;
4824  
4825 my $parent = Venus::Process->new;
4826  
4827 my ($process, $pid) = $parent->fork;
4828  
4829 if ($process) {
4830 # in forked process ...
4831 $process->exit;
4832 }
4833  
4834 my $wait = $parent->wait($pid);
4835  
4836 # 0
4837  
4838 =back
4839  
4840 =over 4
4841  
4842 =item wait example 2
4843  
4844 package main;
4845  
4846 use Venus::Process;
4847  
4848 my $parent = Venus::Process->new;
4849  
4850 my ($process, $pid) = $parent->fork;
4851  
4852 if ($process) {
4853 # in forked process ...
4854 $process->exit;
4855 }
4856  
4857 my ($wait, $status) = $parent->wait('00000');
4858  
4859 # (-1, -1)
4860  
4861 =back
4862  
4863 =over 4
4864  
4865 =item wait example 3
4866  
4867 package main;
4868  
4869 use Venus::Process;
4870  
4871 my $parent = Venus::Process->new;
4872  
4873 my ($process, $pid) = $parent->fork(sub{ $_->exit(1) });
4874  
4875 if ($process) {
4876 # in forked process ...
4877 $process->exit;
4878 }
4879  
4880 my ($wait, $status) = $parent->wait($pid);
4881  
4882 # ($pid, 1)
4883  
4884 =back
4885  
4886 =cut
4887  
4888 =head2 waitall
4889  
4890 waitall(number @pids) (arrayref)
4891  
4892 The waitall method does a blocking L</wait> call for all processes based on the
4893 PIDs provided (or the PIDs returned by L</watchlist> if not provided) and
4894 returns an arrayref of results from calling L</wait> on each PID. Returns a
4895 list in list context.
4896  
4897 I<Since C<2.40>>
4898  
4899 =over 4
4900  
4901 =item waitall example 1
4902  
4903 package main;
4904  
4905 use Venus::Process;
4906  
4907 my $parent = Venus::Process->new;
4908  
4909 my $waitall = $parent->waitall;
4910  
4911 # []
4912  
4913 =back
4914  
4915 =over 4
4916  
4917 =item waitall example 2
4918  
4919 package main;
4920  
4921 use Venus::Process;
4922  
4923 my $parent = Venus::Process->new;
4924  
4925 my $waitall = $parent->waitall(1001);
4926  
4927 # [[1001, 0]]
4928  
4929 =back
4930  
4931 =over 4
4932  
4933 =item waitall example 3
4934  
4935 package main;
4936  
4937 use Venus::Process;
4938  
4939 my $parent = Venus::Process->new;
4940  
4941 my ($process, $pid) = $parent->fork;
4942  
4943 if ($process) {
4944 # in forked process ...
4945 $process->exit;
4946 }
4947  
4948 my $waitall = $parent->waitall;
4949  
4950 # [[$pid, 0]]
4951  
4952 =back
4953  
4954 =cut
4955  
4956 =head2 watch
4957  
4958 watch(number @pids) (arrayref)
4959  
4960 The watch method records PIDs to be watched, e.g. using the L</status> method
4961 and returns all PIDs being watched. Returns a list in list context.
4962  
4963 I<Since C<2.40>>
4964  
4965 =over 4
4966  
4967 =item watch example 1
4968  
4969 package main;
4970  
4971 use Venus::Process;
4972  
4973 my $parent = Venus::Process->new;
4974  
4975 my $watch = $parent->watch;
4976  
4977 # []
4978  
4979 =back
4980  
4981 =over 4
4982  
4983 =item watch example 2
4984  
4985 package main;
4986  
4987 use Venus::Process;
4988  
4989 my $parent = Venus::Process->new;
4990  
4991 my $watch = $parent->watch(1001..1004);
4992  
4993 # [1001..1004]
4994  
4995 =back
4996  
4997 =over 4
4998  
4999 =item watch example 3
5000  
5001 package main;
5002  
5003 use Venus::Process;
5004  
5005 my $parent = Venus::Process->new;
5006  
5007 my $watch = $parent->watch(1001..1004, 1001..1004);
5008  
5009 # [1001..1004]
5010  
5011 =back
5012  
5013 =over 4
5014  
5015 =item watch example 4
5016  
5017 package main;
5018  
5019 use Venus::Process;
5020  
5021 my $parent = Venus::Process->new;
5022  
5023 $parent->watch(1001..1004);
5024  
5025 my $watch = $parent->watch;
5026  
5027 # [1001..1004]
5028  
5029 =back
5030  
5031 =over 4
5032  
5033 =item watch example 5
5034  
5035 package main;
5036  
5037 use Venus::Process;
5038  
5039 my $parent = Venus::Process->new;
5040  
5041 my @watch = $parent->watch(1001..1004);
5042  
5043 # (1001..1004)
5044  
5045 =back
5046  
5047 =cut
5048  
5049 =head2 watchlist
5050  
5051 watchlist() (arrayref)
5052  
5053 The watchlist method returns the recorded PIDs. Returns a list in list context.
5054  
5055 I<Since C<2.40>>
5056  
5057 =over 4
5058  
5059 =item watchlist example 1
5060  
5061 package main;
5062  
5063 use Venus::Process;
5064  
5065 my $parent = Venus::Process->new;
5066  
5067 my $watchlist = $parent->watchlist;
5068  
5069 # []
5070  
5071 =back
5072  
5073 =over 4
5074  
5075 =item watchlist example 2
5076  
5077 package main;
5078  
5079 use Venus::Process;
5080  
5081 my $parent = Venus::Process->new;
5082  
5083 $parent->watch(1001..1004);
5084  
5085 my $watchlist = $parent->watchlist;
5086  
5087 # [1001..1004]
5088  
5089 =back
5090  
5091 =cut
5092  
5093 =head2 work
5094  
5095 work(string | coderef $code, any @args) (number)
5096  
5097 The work method forks the current process, runs the callback provided in the
5098 child process, and immediately exits after. This method returns the I<PID> of
5099 the child process. It is recommended to install an L<perlfunc/alarm> in the
5100 child process (i.e. callback) to avoid creating zombie processes in situations
5101 where the parent process might exit before the child process is done working.
5102  
5103 I<Since C<0.06>>
5104  
5105 =over 4
5106  
5107 =item work example 1
5108  
5109 # given: synopsis;
5110  
5111 my $pid = $parent->work(sub{
5112 my ($process) = @_;
5113 # in forked process ...
5114 $process->exit;
5115 });
5116  
5117 # $pid
5118  
5119 =back
5120  
5121 =cut
5122  
5123 =head2 works
5124  
5125 works(number $count, coderef $callback, any @args) (arrayref)
5126  
5127 The works method creates multiple forks by calling the L</work> method C<n>
5128 times, based on the count specified. The works method runs the callback
5129 provided in the child process, and immediately exits after with an exit code of
5130 C<0> by default. This method returns the I<PIDs> of the child processes. It is
5131 recommended to install an L<perlfunc/alarm> in the child process (i.e.
5132 callback) to avoid creating zombie processes in situations where the parent
5133 process might exit before the child process is done working.
5134  
5135 I<Since C<2.40>>
5136  
5137 =over 4
5138  
5139 =item works example 1
5140  
5141 # given: synopsis;
5142  
5143 my $pids = $parent->works(5, sub{
5144 my ($process) = @_;
5145 # in forked process ...
5146 $process->exit;
5147 });
5148  
5149 # $pids
5150  
5151 =back
5152  
5153 =cut
5154  
5155 =head1 OPERATORS
5156  
5157 This package overloads the following operators:
5158  
5159 =cut
5160  
5161 =over 4
5162  
5163 =item operation: C<("")>
5164  
5165 This package overloads the C<""> operator.
5166  
5167 B<example 1>
5168  
5169 # given: synopsis;
5170  
5171 my $result = "$parent";
5172  
5173 # $pid
5174  
5175 =back
5176  
5177 =over 4
5178  
5179 =item operation: C<(~~)>
5180  
5181 This package overloads the C<~~> operator.
5182  
5183 B<example 1>
5184  
5185 # given: synopsis;
5186  
5187 my $result = $parent ~~ /^\d+$/;
5188  
5189 # 1
5190  
5191 =back
5192  
5193 =head1 AUTHORS
5194  
5195 Awncorp, C<awncorp@cpan.org>
5196  
5197 =cut
5198  
5199 =head1 LICENSE
5200  
5201 Copyright (C) 2022, Awncorp, C<awncorp@cpan.org>.
5202  
5203 This program is free software, you can redistribute it and/or modify it under
5204 the terms of the Apache license version 2.0.
5205  
5206 =cut
« blib/lib/Venus/String.pm ↑ Summary blib/lib/Venus/Role/Coercible.pm »