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

SYNOPSIS
     use POE::Quickie;

     sub handler {
         my $heap = $_[HEAP];

         my $heap->{quickie} = POE::Quickie->new();
         $heap->{quickie}->run(
             Program     => ['foo', '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.

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

  "run"
    This method starts a new program. It returns the process id of the newly
    executed program. It takes the following arguments:

    'Program' (required), will be passed to POE::Wheel::Run's constructor.

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

  "shutdown"
    This shuts down the POE::Quickie instance. Any running jobs will be
    killed.

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

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 program
    "ARG1": the process id of the child process
    "ARG2": the context variable, if any

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

  ExitEvent
    "ARG0": the exit code produced by the program
    "ARG1": the process id of the child process
    "ARG2": the context variable, if any

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.