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
26 function may be passed either a hash or a reference to a hash. The
27 keys below are meaningful to the component, all others are passed to
28 the provided callbacks.
29alias
31Indicates the name of a session to which module callbacks will be posted.
32Default: "main".
33events
35This hash reference contains mappings for the events the component will gener‐
36ate. Callers can set these values to either event handler names (strings) or
37to callbacks (code references). If names are given, the events are thrown at
38the alias specified; when a code reference is given, it is called directly.
39Allowable keys 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 );
47In the above example, any output produced by children on stdout generates an
49event my_out for the my_session session, whilst output on stderr causes a call
50to my_err().
51writemap
53This item may be set to a hash reference containing a mapping of method names
54to strings that will be written to the client.
55- exempli gratia -
57 writemap => { quit => "bye", louder => "++" }
59In the above example a caller can issue a call to $self-quit()>, in which case
61the string "bye" will be written to the client, or $self-louder()> to have the
62client receive the string "++".
63conduit
65If left unspecified, POE::Wheel::Run assumes "pipe". Alternatively "pty" may
66be provided in which case no stderr events will be fired.
67debug
69Setting this parameter to a true value generates debugging output (useful
70mostly to hacks).
71
73This method requires an array indicating the command (and optional parameters)
75to run. The command and its parameters may also be passed as a single string.
76The method returns the id of the wheel which is needed when running several
77commands simultasneously.
78Before calling this function, the caller may set stdio filter to a value of
80his choice. The example below shows the default used.
81
83
85This method is used to send input to the child. It can accept an array and
87will be passed through as such to the child.
88
90This method requests that the currently selected wheel quit. An optional com‐
93graceful shutdown of interactive children e.g. the ftp command understands
94"bye" to quit.
95If no command is specified, the system will use whatever string was passed as
97the quit item in the writemap hash argument to new(). If this too was left
98unspecified, a kill is issued. Please note if the child is instructed to
99quit, it will not generate a died event, but a done instead (even when hard
100killed).
101Please note that quitting all children will not shut the component down - for
103that use the shutdown method.
104
106Instructs the component to send the child a signal. By default the TERM sig‐
108nal is sent but the SIG named parameter allows the caller to specify anything
109else. If HARD => 1 is specified, a hard kill (-9) is done and any specific
110signal passed is ignored.
111Note that by default killing the child will generate a died event (not a done)
113unless the named parameter NODIE is passed a true value.
114Additionally, note that kills are done immediately, not scheduled.
116 - exempli gratia -
118 $obj->kill(); # a TERM signal is sent
120 $obj->kill(HARD => 1); # a -9 gets sent
121 $obj->kill(SIG => 'INT'); # obvious
122 $obj->kill(HARD => 1, NODIE => 1); # hard kill w/o a C<died> event
123
125This method causes the component to kill all children and shut down.
127
129Gets or sets the value of a certain key. Values inside of hashes may be spec‐
131ified by separating the keys with slashes e.g. $self->attr("events/quit",
132"bye"); whould store "bye" in {events}{quit} inside of the object.
133
135Used to set the current wheel for other methods to work with. Please note
137that ->write(), ->quit() and ->kill() will work on the wheel most recently
138created. I you wish to work with a previously created wheel, set it with this
139method.
140
142Returns a reference to the current wheel. If an id is provided then that
144wheel is returned.
145
147 Events are are thrown at the session indicated as alias and may be
148 specified using the callbacks argument to the new() method. If no such
149 preference is indicated, the default event names listed below are used.
150 Whenever callbacks are specified, they are called directly instead of
151 generating an event.
152 Event handlers are passed two arguments: ARG0 which is a reference to
154 the component instance being used (i.e. $self), and ARG1, a hash refer‐
155 ence containing the wheel id being used (as wheel) + values specific to
156 the event. Callbacks are passed the same arguments but as @_[0,1]
157 instead.
158 stdout
160 This event is fired upon any generation of output from the client. The
162 output produced is provided in "out", e.g.:
163 $_[ARG1]->{out}
165 stderr
167 Works exactly as with stdout but for the error channel.
169 done
171 Fired upon termination of the child, including such cases as when the
173 child is asked to quit or when it ends naturally (as with non-interac‐
174 tive children). Please note that the event is fired when _both_ the OS
175 death signal has been received _and_ the child has closed its output
176 pipes (this also holds true for the died event described below).
177 died
179 Fired upon abnormal ending of a child. This event is generated only
181 for interactive children who terminate without having been asked to.
182 Inclusion of the "died" key in the "callbacks" hash passed to ->new()
183 qualifies a process for receiving this event and distinguishes it as
184 interactive. This event is mutually exclusive with "done".
185 error
187 This event is fired upon generation of any error by the child. Argu‐
189 ments passed include: syscall, err (the numeric value of the error),
190 error (a textual description), and fh (the file handle involved).
191
193 Erick Calder <ecalder@cpan.org>
194
196 1e6 thx pushed to Rocco Caputo for suggesting this needed putting
197 together, for giving me the privilege to do it, and for all the late
198 night help.
199
201 This module may be found on the CPAN. Additionally, both the module
202 and its RPM package are available from:
203 http://perl.arix.com
205
207 Thank you notes, expressions of aggravation and suggestions may be
208 mailed directly to the author :)
209
211 Copyright (c) 2002-2003 Erick Calder.
212 This product is free and distributed under the Gnu Public License
214 (GPL). A copy of this license was included in this distribution in a
215 file called LICENSE. If for some reason, this file was not included,
216 please see http://www.gnu.org/licenses/ to obtain a copy of this
217 license.
218 $Id: Child.pm,v 1.39 2005/12/30 04:14:38 ekkis Exp $
220perl v5.8.8 2005-12-29 Child(3)