NAME

POE::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

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'