1Child(3) User Contributed Perl Documentation Child(3)
2
6 POE::Component::Child - Child management component
7
9 use POE qw(Component::Child);
10 $p = POE::Component::Child->new();
12 $p->run("ls", "-alF", "/tmp");
13 POE::Kernel->run();
15
17 This POE component serves as a wrapper for POE::Wheel::Run, obviating
18 the need to create a session to receive the events it dishes out.
19
21 The module provides an object-oriented interface as follows:
22 new [hash[-ref]]
24 Used to initialise the system and create a component instance. The
25 function may be passed either a hash or a reference to a hash. The
26 keys below are meaningful to the component, all others are passed to
27 the provided callbacks.
28 alias
30 Indicates the name of a session to which module callbacks will be
31 posted. Default: "main".
32 events
34 This hash reference contains mappings for the events the component
35 will generate. Callers can set these values to either event
36 handler names (strings) or to callbacks (code references). If
37 names are given, the events are thrown at the alias specified; when
38 a code reference is given, it is called directly. Allowable keys
39 are listed below under section "Event Callbacks".
40 - exempli gratia -
42 $p = POE::Component::Child->new(
44 alias => "my_session",
45 events => { stdout => "my_out", stderr => \&my_err }
46 );
47 In the above example, any output produced by children on stdout
49 generates an event my_out for the my_session session, whilst output
50 on stderr causes a call to my_err().
51 writemap
53 This item may be set to a hash reference containing a mapping of
54 method names to strings that will be written to the client.
55 - exempli gratia -
57 writemap => { quit => "bye", louder => "++" }
59 In the above example a caller can issue a call to $self-quit()>, in
61 which case the string "bye" will be written to the client, or
62 $self-louder()> to have the client receive the string "++".
63 conduit
65 If left unspecified, POE::Wheel::Run assumes "pipe". Alternatively
66 "pty" may be provided in which case no stderr events will be fired.
67 debug
69 Setting this parameter to a true value generates debugging output
70 (useful mostly to hacks).
71 run {array}
73 This method requires an array indicating the command (and optional
74 parameters) to run. The command and its parameters may also be passed
75 as a single string. The method returns the id of the wheel which is
76 needed when running several commands simultasneously.
77 Before calling this function, the caller may set stdio filter to a
79 value of his choice. The example below shows the default used.
80 $p->{StdioFilter} = POE::Filter::Line->new(OutputLiteral => '\n');
82 write {array}
84 This method is used to send input to the child. It can accept an array
85 and will be passed through as such to the child.
86 quit [command]
88 This method requests that the currently selected wheel quit. An
89 optional command string may be passed which is sent to the child - this
90 is useful for graceful shutdown of interactive children e.g. the ftp
91 command understands "bye" to quit.
92 If no command is specified, the system will use whatever string was
94 passed as the quit item in the writemap hash argument to new(). If
95 this too was left unspecified, a kill is issued. Please note if the
96 child is instructed to quit, it will not generate a died event, but a
97 done instead (even when hard killed).
98 Please note that quitting all children will not shut the component down
100 - for that use the shutdown method.
101 kill [HARD/SIG = TERM, NODIE = 0]
103 Instructs the component to send the child a signal. By default the
104 TERM signal is sent but the SIG named parameter allows the caller to
105 specify anything else. If HARD => 1 is specified, a hard kill (-9) is
106 done and any specific signal passed is ignored.
107 Note that by default killing the child will generate a died event (not
109 a done) unless the named parameter NODIE is passed a true value.
110 Additionally, note that kills are done immediately, not scheduled.
112 - exempli gratia -
114 $obj->kill(); # a TERM signal is sent
116 $obj->kill(HARD => 1); # a -9 gets sent
117 $obj->kill(SIG => 'INT'); # obvious
118 $obj->kill(HARD => 1, NODIE => 1); # hard kill w/o a C<died> event
119 shutdown
121 This method causes the component to kill all children and shut down.
122 attr <key> [val]
124 Gets or sets the value of a certain key. Values inside of hashes may
125 be specified by separating the keys with slashes e.g.
126 $self->attr("events/quit", "bye"); whould store "bye" in {events}{quit}
127 inside of the object.
128 wheelid
130 Used to set the current wheel for other methods to work with. Please
131 note that ->write(), ->quit() and ->kill() will work on the wheel most
132 recently created. I you wish to work with a previously created wheel,
133 set it with this method.
134 wheel [id]
136 Returns a reference to the current wheel. If an id is provided then
137 that wheel is returned.
138
140 Events are are thrown at the session indicated as alias and may be
141 specified using the callbacks argument to the new() method. If no such
142 preference is indicated, the default event names listed below are used.
143 Whenever callbacks are specified, they are called directly instead of
144 generating an event.
145 Event handlers are passed two arguments: ARG0 which is a reference to
147 the component instance being used (i.e. $self), and ARG1, a hash
148 reference containing the wheel id being used (as wheel) + values
149 specific to the event. Callbacks are passed the same arguments but as
150 @_[0,1] instead.
151 stdout
153 This event is fired upon any generation of output from the client. The
154 output produced is provided in "out", e.g.:
155 $_[ARG1]->{out}
157 stderr
159 Works exactly as with stdout but for the error channel.
160 done
162 Fired upon termination of the child, including such cases as when the
163 child is asked to quit or when it ends naturally (as with non-
164 interactive children). Please note that the event is fired when _both_
165 the OS death signal has been received _and_ the child has closed its
166 output pipes (this also holds true for the died event described below).
167 died
169 Fired upon abnormal ending of a child. This event is generated only
170 for interactive children who terminate without having been asked to.
171 Inclusion of the "died" key in the "callbacks" hash passed to ->new()
172 qualifies a process for receiving this event and distinguishes it as
173 interactive. This event is mutually exclusive with "done".
174 error
176 This event is fired upon generation of any error by the child.
177 Arguments passed include: syscall, err (the numeric value of the
178 error), error (a textual description), and fh (the file handle
179 involved).
180
182 Erick Calder <ecalder@cpan.org>
183
185 1e6 thx pushed to Rocco Caputo for suggesting this needed putting
186 together, for giving me the privilege to do it, and for all the late
187 night help.
188
190 This module may be found on the CPAN. Additionally, both the module
191 and its RPM package are available from:
192 http://perl.arix.com
194
196 Thank you notes, expressions of aggravation and suggestions may be
197 mailed directly to the author :)
198
200 Copyright (c) 2002-2003 Erick Calder.
201 This product is free and distributed under the Gnu Public License
203 (GPL). A copy of this license was included in this distribution in a
204 file called LICENSE. If for some reason, this file was not included,
205 please see http://www.gnu.org/licenses/ to obtain a copy of this
206 license.
207 $Id: Child.pm,v 1.39 2005/12/30 04:14:38 ekkis Exp $
209
211 Hey! The above document had some coding errors, which are explained
212 below:
213 Around line 388:
215 '=item' outside of any '=over'
216 Around line 427:
218 You forgot a '=back' before '=head2'
219perl v5.38.0 2023-07-21 Child(3)