Child(3) User Contributed Perl Documentation Child(3)NAMEPOE::Component::Child - Child management component
SYNOPSIS
use POE qw(Component::Child);
$p = POE::Component::Child->new();
$p->run("ls", "-alF", "/tmp");
POE::Kernel->run();
DESCRIPTION
This POE component serves as a wrapper for POE::Wheel::Run, obviating
the need to create a session to receive the events it dishes out.
METHODS
The module provides an object-oriented interface as follows:
new [hash[-ref]]
Used to initialise the system and create a component instance. The
function may be passed either a hash or a reference to a hash. The
keys below are meaningful to the component, all others are passed to
the provided callbacks.
alias
Indicates the name of a session to which module callbacks will be
posted. Default: "main".
events
This hash reference contains mappings for the events the component
will generate. Callers can set these values to either event
handler names (strings) or to callbacks (code references). If
names are given, the events are thrown at the alias specified; when
a code reference is given, it is called directly. Allowable keys
are listed below under section "Event Callbacks".
- exempli gratia -
$p = POE::Component::Child->new(
alias => "my_session",
events => { stdout => "my_out", stderr => \&my_err }
);
In the above example, any output produced by children on stdout
generates an event my_out for the my_session session, whilst output
on stderr causes a call to my_err().
writemap
This item may be set to a hash reference containing a mapping of
method names to strings that will be written to the client.
- exempli gratia -
writemap => { quit => "bye", louder => "++" }
In the above example a caller can issue a call to $self-quit()>, in
which case the string "bye" will be written to the client, or
$self-louder()> to have the client receive the string "++".
conduit
If left unspecified, POE::Wheel::Run assumes "pipe". Alternatively
"pty" may be provided in which case no stderr events will be fired.
debug
Setting this parameter to a true value generates debugging output
(useful mostly to hacks).
run {array}
This method requires an array indicating the command (and optional
parameters) to run. The command and its parameters may also be passed
as a single string. The method returns the id of the wheel which is
needed when running several commands simultasneously.
Before calling this function, the caller may set stdio filter to a
value of his choice. The example below shows the default used.
$p->{StdioFilter} = POE::Filter::Line->new(OutputLiteral => '\n');
write {array}
This method is used to send input to the child. It can accept an array
and will be passed through as such to the child.
quit [command]
This method requests that the currently selected wheel quit. An
optional command string may be passed which is sent to the child - this
is useful for graceful shutdown of interactive children e.g. the ftp
command understands "bye" to quit.
If no command is specified, the system will use whatever string was
passed as the quit item in the writemap hash argument to new(). If
this too was left unspecified, a kill is issued. Please note if the
child is instructed to quit, it will not generate a died event, but a
done instead (even when hard killed).
Please note that quitting all children will not shut the component down
- for that use the shutdown method.
kill [HARD/SIG = TERM, NODIE = 0]
Instructs the component to send the child a signal. By default the
TERM signal is sent but the SIG named parameter allows the caller to
specify anything else. If HARD => 1 is specified, a hard kill (-9) is
done and any specific signal passed is ignored.
Note that by default killing the child will generate a died event (not
a done) unless the named parameter NODIE is passed a true value.
Additionally, note that kills are done immediately, not scheduled.
- exempli gratia -
$obj->kill(); # a TERM signal is sent
$obj->kill(HARD => 1); # a -9 gets sent
$obj->kill(SIG => 'INT'); # obvious
$obj->kill(HARD => 1, NODIE => 1); # hard kill w/o a C<died> event
shutdown
This method causes the component to kill all children and shut down.
attr <key> [val]
Gets or sets the value of a certain key. Values inside of hashes may
be specified by separating the keys with slashes e.g.
$self->attr("events/quit", "bye"); whould store "bye" in {events}{quit}
inside of the object.
wheelid
Used to set the current wheel for other methods to work with. Please
note that ->write(), ->quit() and ->kill() will work on the wheel most
recently created. I you wish to work with a previously created wheel,
set it with this method.
wheel [id]
Returns a reference to the current wheel. If an id is provided then
that wheel is returned.
EVENTS / CALLBACKS
Events are are thrown at the session indicated as alias and may be
specified using the callbacks argument to the new() method. If no such
preference is indicated, the default event names listed below are used.
Whenever callbacks are specified, they are called directly instead of
generating an event.
Event handlers are passed two arguments: ARG0 which is a reference to
the component instance being used (i.e. $self), and ARG1, a hash
reference containing the wheel id being used (as wheel) + values
specific to the event. Callbacks are passed the same arguments but as
@_[0,1] instead.
stdout
This event is fired upon any generation of output from the client. The
output produced is provided in "out", e.g.:
$_[ARG1]->{out}
stderr
Works exactly as with stdout but for the error channel.
done
Fired upon termination of the child, including such cases as when the
child is asked to quit or when it ends naturally (as with non-
interactive children). Please note that the event is fired when _both_
the OS death signal has been received _and_ the child has closed its
output pipes (this also holds true for the died event described below).
died
Fired upon abnormal ending of a child. This event is generated only
for interactive children who terminate without having been asked to.
Inclusion of the "died" key in the "callbacks" hash passed to ->new()
qualifies a process for receiving this event and distinguishes it as
interactive. This event is mutually exclusive with "done".
error
This event is fired upon generation of any error by the child.
Arguments passed include: syscall, err (the numeric value of the
error), error (a textual description), and fh (the file handle
involved).
AUTHOR
Erick Calder <ecalder@cpan.org>
ACKNOWLEDGEMENTS
1e6 thx pushed to Rocco Caputo for suggesting this needed putting
together, for giving me the privilege to do it, and for all the late
night help.
AVAILABILITY
This module may be found on the CPAN. Additionally, both the module
and its RPM package are available from:
http://perl.arix.com
SUPPORT
Thank you notes, expressions of aggravation and suggestions may be
mailed directly to the author :)
LICENSE AND COPYRIGHT
Copyright (c) 2002-2003 Erick Calder.
This product is free and distributed under the Gnu Public License
(GPL). A copy of this license was included in this distribution in a
file called LICENSE. If for some reason, this file was not included,
please see http://www.gnu.org/licenses/ to obtain a copy of this
license.
$Id: Child.pm,v 1.39 2005/12/30 04:14:38 ekkis Exp $
POD ERRORS
Hey! The above document had some coding errors, which are explained
below:
Around line 388:
'=item' outside of any '=over'
Around line 427:
You forgot a '=back' before '=head2'
perl v5.14.1 2005-12-30 Child(3)
