1System::Command::ReaperU(s3e)r Contributed Perl DocumentaStyisotnem::Command::Reaper(3)
2
3
4
6 System::Command::Reaper - Reap processes started by System::Command
7
9 version 1.122
10
12 This class is used for internal purposes. Move along, nothing to see
13 here.
14
16 The System::Command objects delegate the reaping of child processes to
17 System::Command::Reaper objects. This allows a user to create a
18 System::Command and discard it after having obtained one or more
19 references to its handles connected to the child process.
20
21 The typical use case looks like this:
22
23 my $fh = System::Command->new( @cmd )->stdout();
24
25 The child process is reaped either through a direct call to close() or
26 when the command object and all its handles have been destroyed, thus
27 avoiding zombies (which would be reaped by the system at the end of the
28 main program).
29
30 This is possible thanks to the following reference graph:
31
32 System::Command
33 | | | ^|
34 v v v !|
35 in out err !|
36 ^| ^| ^| !|
37 !v !v !v !v
38 System::Command::Reaper
39
40 Legend:
41 | normal ref
42 ! weak ref
43
44 The System::Command::Reaper object acts as a sentinel, that takes care
45 of reaping the child process when the original System::Command and its
46 filehandles have been destroyed (or when System::Command close() method
47 is being called).
48
50 System::Command::Reaper supports the following methods:
51
52 new
53 my $reaper = System::Command::Reaper->new( $cmd, \%extra );
54
55 Create a new System::Command::Reaper object attached to the
56 System::Command object passed as a parameter.
57
58 An optional hash reference can be used to pass extra attributes to the
59 object.
60
61 close
62 $reaper->close();
63
64 Close all the opened filehandles of the main System::Command object,
65 reaps the child process, and updates the main object with the status
66 information of the child process.
67
68 "DESTROY" calls close() when the sentinel is being destroyed.
69
70 is_terminated
71 if ( $reaper->is_terminated ) {...}
72
73 Returns a true value if the underlying process was terminated.
74
75 If the process was indeed terminated, collects exit status, etc.
76
77 Accessors
78 The attributes of a System::Command::Reaper object are also accessible
79 through a number of accessors.
80
81 The object returned by new() will have the following attributes defined
82 (as copied from the System::Command object that created the reaper):
83
84 pid The PID of the underlying command.
85
86 stdin
87 A filehandle opened in write mode to the child process' standard
88 input.
89
90 stdout
91 A filehandle opened in read mode to the child process' standard
92 output.
93
94 stderr
95 A filehandle opened in read mode to the child process' standard
96 error output.
97
98 After the call to close() or after is_terminated() returns true, the
99 following attributes will be defined:
100
101 exit
102 The exit status of the underlying command.
103
104 core
105 A boolean value indicating if the command dumped core.
106
107 signal
108 The signal, if any, that killed the command.
109
111 Philippe Bruhat (BooK), "<book at cpan.org>"
112
114 This scheme owes a lot to Vincent Pit who on #perlfr provided the
115 general idea (use a proxy to delay object destruction and child process
116 reaping) with code examples, which I then adapted to my needs.
117
119 Copyright 2010-2016 Philippe Bruhat (BooK), all rights reserved.
120
122 This program is free software; you can redistribute it and/or modify it
123 under the same terms as Perl itself.
124
125
126
127perl v5.38.0 2023-07-21 System::Command::Reaper(3)