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.

callbacks

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",
	callbacks => { 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().

quit

Indicates a string which should be sent to the child when attempting to quit. This is only useful for interactive clients e.g. ftp, for whom either "bye" or "quit" will work.

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 client 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 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).

kill

Instructs the component to hard kill (-9) the child. Note that the event generated is died and not done.

wheel

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.

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 produces 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).

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

DATE

$Date: 2002/09/30 01:07:44 $

VERSION

$Revision: 1.16 $

LICENSE AND COPYRIGHT

Copyright (c) 2002 Erick Calder. This product is distributed under the MIT License. A copy of this license was included in a file called LICENSE. If for some reason, this file was not included, please see http://www.opensource.org/licenses/mit-license.html to obtain a copy of this license.

cpanm POE::Component::Child

perl -MCPAN -e shell
install POE::Component::Child