POE::Quickie - A lazy way to wrap blocking code and programs
use POE::Quickie;
sub event_handler {
# the "I'll wait until it's finished" approach, which will block your
# session until the command has finished
my ($stdout, $stderr, $exit_status) = quickie('foo.pl');
print $stdout;
# the "keep me posted" approach, which will give you each line of output
# as it is appears
quickie_run(
Program => ['foo.pl', 'bar'],
StdoutEvent => 'stdout',
Context => 'remember this',
);
# the "get back to me when it's done" approach, which will notify you
# of the entire output when the command has finished
quickie_run(
Program => ['foo.pl', 'bar'],
Context => 'remember this',
ResultEvent => 'result',
);
}
sub stdout {
my ($output, $context) = @_[ARG0, ARG1];
print "got output: '$output' in the context of '$context'\n";
}
sub result {
my ($pid, $stdout, $stderr, $merged, $status, $context) = @_[ARG0..$#_];
print "got all this output in the context of '$context':\n";
print "$_\n" for @$stdout;
}
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 only need to do this if you want to specify any of the parameters below, since a POE::Quickie object will be constructed automatically when it is needed. The rest of the methods can be called on the object ($object->run()
) or as class methods (POE::Quickie->run()
). You can safely let the object go out of scope; POE::Quickie will continue to run your processes until they finish.
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 spawns a new child process. It returns its process id.
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 directly to POE::Wheel::Run's constructor.
'ProgramArgs' (optional), will be passed directly to POE::Wheel::Run's constructor.
'Input' (optional), a string containing the input to the process. This string, if provided, will be sent immediately to the child, and its stdin will then be shut down. Note: no processing will be done on the data before it is sent. For instance, if you are executing a program which expects line-based input, be sure to end your input with a newline.
'StdoutEvent' (optional), the event for delivering lines from the process' STDOUT. If you don't supply this, they will be printed to the main process's STDOUT. To explicitly ignore them, set this to undef
.
'StderrEvent' (optional), the event for delivering lines from the process' STDERR. If you don't supply this, they will be printed to the main process' STDERR. To explicitly ignore them, set this to undef
.
'ExitEvent' (optional), the event to be called when the process has exited. If you don't supply this, a warning indicating the exit code will be printed if it is nonzero. To explicitly ignore it, set this to undef
.
'ResultEvent' (optional), like 'ExitEvent', but it will also contain all the stdout/stderr generated by the child process.
'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.
'Timeout' (optional), a timeout in seconds after which the process will be forcibly killed if it is still running. There is no timeout by default.
'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 argument (-e), and the current @INC
passed as include arguments (-I). Default is false.
All other arguments will be passed to POE::Wheel::Run's new
method. Useful if you want to specify the input/output filters and such.
This kills all processes which POE::Quickie is managing for your session. Takes one optional argument, a signal name (e.g. 'SIGTERM').
Returns a hash reference of all the currently running processes. 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 processARG1
: the process id of the child processARG2
: the context variable, if any
ARG0
: the chunk of STDERR generated by the processARG1
: the process id of the child processARG2
: the context variable, if any
ARG0
: the exit code ($?
) of the child processARG1
: the process id of the child processARG2
: the context variable, if any
ARG0
: the process id of the child processARG1
: an array of every chunk of stdout generated by the child processARG2
: an array of every chunk of stderr generated by the child processARG3
: an array of the interleaved stdout and stderr chunksARG4
: the exit code ($?
) of the child processARG5
: the context variable, if any
Equivalent to POE::Quickie->run()
, provided as a convenience.
The following functions are modeled after the ones provided by Capture::Tiny. They will not return until the executed process 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.
Note: Since these functions block, you must be careful not to call them in event handlers which were executed with $poe_kernel->call()
by other sessions, so you don't hold them up. A simple way to avoid that is to yield()
or post()
a new event to your session and do it from there.
Returns 3 values: the stdout, stderr, and exit code ($?
) of the child process.
Returns 3 values: an array of all stdout chunks, an array of all stderr chunks, and the exit code ($?
) of the child process. In addition, it will echo the stdout/stderr to your process' stdout/stderr.
Returns 2 values: an array of interleaved stdout and stderr chunks, and the exit code ($?
) of the child process. Beware that stdout and stderr in the merged result are not guaranteed to be properly ordered due to buffering.
Returns 2 values: an array of interleaved stdout and stderr chunks, and the exit code ($?
) of the child process. In addition, it will echo the merged stdout & stderr to your process' 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-2011 Hinrik Örn Sigurðsson
This program is free software, you can redistribute it and/or modify it under the same terms as Perl itself.
Hey! The above document had some coding errors, which are explained below:
- Around line 181:
-
You forgot a '=back' before '=head2'
- Around line 199:
-
=back without =over