NAME
   POE::Quickie - A lazy way to wrap blocking code and programs

SYNOPSIS
    use POE::Quickie;

    sub event_handler {
        # the really lazy interface, which will block
        my ($stdout, $stderr, $exit_status) = quickie('foo.pl');
        print $stdout;

        # the more involved interface
        quickie_run(
            Program     => ['foo.pl', 'bar'],
            StdoutEvent => 'stdout',
            Context     => 'remember this',
        );

        # a combination of the two approaches
        quickie_run(
            Program     => ['foo.pl', 'bar'],
            Context     => 'remember this',
            ResultEvent => 'result',
        );
    }

    # this will get called once for every output line
    sub stdout {
        my ($output, $context) = @_[ARG0, ARG1];
        print "got output: '$output' in the context of '$context'\n";
    }

    # only called when the task is finished
    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;
    }

DESCRIPTION
   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.

METHODS
 "new"
   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.

 "run"
   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.

 "killall"
   This kills all processes which POE::Quickie is managing for your
   session. Takes one optional argument, a signal name (e.g. 'SIGTERM').

 "processes"
   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.

OUTPUT
   The following events might get sent to your session. The names
   correspond to the options to "run".

 StdoutEvent
   "ARG0": the chunk of STDOUT generated by the process
   "ARG1": the process id of the child process
   "ARG2": the context variable, if any

 StderrEvent
   "ARG0": the chunk of STDERR generated by the process
   "ARG1": the process id of the child process
   "ARG2": the context variable, if any

 ExitEvent
   "ARG0": the exit code ($?) of the child process
   "ARG1": the process id of the child process
   "ARG2": the context variable, if any

 ResultEvent
   "ARG0": the process id of the child process
   "ARG1": an array of every chunk of stdout generated by the child process
   "ARG2": an array of every chunk of stderr generated by the child process
   "ARG3": an array of the interleaved stdout and stderr chunks
   "ARG4": the exit code ($?) of the child process
   "ARG5": the context variable, if any

FUNCTIONS
 "quickie_run"
   Equivalent to "POE::Quickie->run()", provided as a convenience.

 Blocking functions
   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.

  "quickie"
   Returns 3 values: the stdout, stderr, and exit code ($?) of the child
   process.

  "quickie_tee"
   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.

  "quickie_merged"
   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.

  "quickie_tee_merged"
   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.

AUTHOR
   Hinrik Örn Sigurðsson, [email protected]

LICENSE AND COPYRIGHT
   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.

POD ERRORS
   Hey! The above document had some coding errors, which are explained
   below:

   Around line 607:
       You forgot a '=back' before '=head2'

   Around line 625:
       =back without =over

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.