POE::Quickie - A lazy way to wrap blocking programs
use POE::Quickie;
sub handler {
my $heap = $_[HEAP];
# the really lazy interface
my ($stdout, $stderr, $exit_status) = quickie('foo.pl');
print $stdout;
# the more involved interface
my $heap->{quickie} = POE::Quickie->new();
$heap->{quickie}->run(
Program => ['foo.pl', 'bar'],
StdoutEvent => 'stdout',
Context => 'remember this',
);
}
sub stdout {
my ($output, $context) = @_[ARG0, ARG1];
print "got output: '$output' in the context of '$context'\n";
}If you need nonblocking access to an external program, or want to execute some blocking code in a separate process, but you don't want to write a wrapper module or some POE::Wheel::Run boilerplate code, then POE::Quickie can help. You just specify what you're interested in (stdout, stderr, and/or exit code), and POE::Quickie will handle the rest in a sensible way.
It has some convenience features, such as killing processes after a timeout, and storing process-specific context information which will be delivered with every event.
There is also an even lazier API which suspends the execution of your event handler and gives control back to POE while your task is running, the same way LWP::UserAgent::POE does. This is provided by the quickie_* functions which are exported by default.
Constructs a POE::Quickie object. You'll want to hold on to it.
Takes 3 optional parameters: 'debug', 'default', and 'trace'. These will be passed to the object's POE::Session constructor. See its documentation for details.
This method starts a new program. It returns the process id of the newly executed program.
You can either call it with a single argument (string, arrayref, or coderef), which will used as the 'Program' argument, or you can supply the following key-value pairs:
'Program' (required), will be passed to POE::Wheel::Run's constructor.
'AltFork' (optional), if true, a new instance of the active Perl interpreter ($^X) will be launched with 'Program' (which must be a string) as the code (-e) argument, and the current @INC passed as include (-I) arguments. Default is false.
'ProgramArgs' (optional), same as the epynomous parameter to POE::Wheel::Run.
'StdoutEvent' (optional), the event for delivering lines from the program's STDOUT. If you don't supply this, they will be printed to the main program's STDOUT. To explicitly ignore them, set this to undef.
'StderrEvent' (optional), the event for delivering lines from the program's STDERR. If you don't supply this, they will be printed to the main program's STDERR. To explicitly ignore them, set this to undef.
'ExitEvent' (optional), the event to be called when the program has exited. If you don't supply this, a warning will be printed if the exit status is nonzero. To explicitly ignore it, set this to undef.
'Timeout' (optional), a timeout in seconds after which the program will be forcibly killed if it is still running. There is no timeout by default.
'Context' (optional), a variable which will be sent back to you with every event. If you pass a reference, that same reference will be delivered back to you later (not a copy), so you can update it as you see fit.
'WheelArgs' (optional), a hash reference of options which will be passed verbatim to the underlying POE::Wheel::Run object's constructor. Possibly useful if you want to change the input/output filters and such.
This kills all currently running programs which POE::Quickie is managing.
Returns a hash reference of all the currently running programs. The key is the process id, and the value is the context variable, if any.
The following events might get sent to your session. The names correspond to the options to run.
ARG0: the chunk of STDOUT generated by the programARG1: the process id of the child processARG2: the context variable, if any
ARG0: the chunk of STDERR generated by the programARG1: the process id of the child processARG2: the context variable, if any
ARG0: the exit code produced by the programARG1: the process id of the child processARG2: the context variable, if any
The usage of these functions is modeled after the ones provided by Capture::Tiny. They will not return until the executed program has exited. However, run_one_timeslice in POE::Kernel will be called in the meantime, so the rest of your application will continue to run.
They all take the same arguments as the run method, except for the '*Event' and 'Context' arguments.
Returns 3 values: the stdout, stderr, and exit code of the program.
Returns 3 values: the stdout, stderr, and exit code of the program. In addition, it will echo the stdout/stderr to your program's stdout/stderr. Beware that stdout and stderr in the merged result are not guaranteed to be properly ordered due to buffering.
Returns 2 values: the merged stdout & stderr, and exit code of the program.
Returns 2 values: the merged stdout & stderr, and exit code of the program. In addition, it will echo the merged stdout & stderr to your program's stdout. Beware that stdout and stderr in the merged result are not guaranteed to be properly ordered due to buffering.
Hinrik Örn Sigurðsson, hinrik.sig@gmail.com
Copyright 2010 Hinrik Örn Sigurðsson
This program is free software, you can redistribute it and/or modify it under the same terms as Perl itself.