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

SYNOPSIS
     use POE::Quickie;

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

         # the more involved interface
         my $pid = POE::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";
     }

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

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

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

  "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

FUNCTIONS
    The usage of these functions is 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.

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

  "quickie_tee"
    Returns 3 values: the stdout, stderr, and exit code ($?) of the child
    process. In addition, it will echo the stdout/stderr to your process'
    stdout/stderr. Beware that stdout and stderr in the merged result are
    not guaranteed to be properly ordered due to buffering.

  "quickie_merged"
    Returns 2 values: the merged stdout & stderr, and exit code ($?) of the
    child process.

  "quickie_tee_merged"
    Returns 2 values: the merged stdout & stderr, and 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, hinrik.sig@gmail.com

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.

