1Child(3)              User Contributed Perl Documentation             Child(3)
2
3
4

NAME

6       POE::Component::Child - Child management component
7

SYNOPSIS

9        use POE qw(Component::Child);
10
11        $p = POE::Component::Child->new();
12        $p->run("ls", "-alF", "/tmp");
13
14        POE::Kernel->run();
15

DESCRIPTION

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

METHODS

21       The module provides an object-oriented interface as follows:
22
23   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
29       alias
30           Indicates the name of a session to which module callbacks will be
31           posted.  Default: "main".
32
33       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
41               - exempli gratia -
42
43                   $p = POE::Component::Child->new(
44                           alias => "my_session",
45                           events => { stdout => "my_out", stderr => \&my_err }
46                           );
47
48           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
52       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
56           - exempli gratia -
57
58                   writemap => { quit => "bye", louder => "++" }
59
60           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
64       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
68       debug
69           Setting this parameter to a true value generates debugging output
70           (useful mostly to hacks).
71
72   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
78       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
81       $p->{StdioFilter} = POE::Filter::Line->new(OutputLiteral => '\n');
82
83   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
87   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
93       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
99       Please note that quitting all children will not shut the component down
100       - for that use the shutdown method.
101
102   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
108       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
111       Additionally, note that kills are done immediately, not scheduled.
112
113           - exempli gratia -
114
115               $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
120   shutdown
121       This method causes the component to kill all children and shut down.
122
123   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
129   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
135   wheel [id]
136       Returns a reference to the current wheel.  If an id is provided then
137       that wheel is returned.
138

EVENTS / CALLBACKS

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
146       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
152   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
156       $_[ARG1]->{out}
157
158   stderr
159       Works exactly as with stdout but for the error channel.
160
161   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
168   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
175   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

AUTHOR

182       Erick Calder <ecalder@cpan.org>
183

ACKNOWLEDGEMENTS

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

AVAILABILITY

190       This module may be found on the CPAN.  Additionally, both the module
191       and its RPM package are available from:
192
193       http://perl.arix.com
194

SUPPORT

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
202       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
208       $Id: Child.pm,v 1.39 2005/12/30 04:14:38 ekkis Exp $
209

POD ERRORS

211       Hey! The above document had some coding errors, which are explained
212       below:
213
214       Around line 388:
215           '=item' outside of any '=over'
216
217       Around line 427:
218           You forgot a '=back' before '=head2'
219
220
221
222perl v5.36.0                      2022-07-22                          Child(3)
Impressum