NAME

POE::Wheel::Run - event driven fork/exec with added value

SYNOPSIS

  # Program may be scalar or \@array.
  $program = '/usr/bin/cat -';
  $program = [ '/usr/bin/cat', '-' ];

  $wheel = POE::Wheel::Run->new(
    Program    => $program,
    Priority   => +5,                 # Adjust priority.  May need to be root.
    User       => getpwnam('nobody'), # Adjust UID. May need to be root.
    Group      => getgrnam('nobody'), # Adjust GID. May need to be root.
    ErrorEvent => 'oops',             # Event to emit on errors.

    StdinEvent  => 'stdin',  # Event to emit when stdin is flushed to child.
    StdoutEvent => 'stdout', # Event to emit with child stdout information.
    StderrEvent => 'stderr', # Event to emit with child stderr information.

    # Identify the child process' I/O type.
    Filter => POE::Filter::Line->new(), # Or some other filter.

    # May also specify filters per handle.
    StdinFilter  => POE::Filter::Line->new(),   # Child accepts input as lines.
    StdoutFilter => POE::Filter::Stream->new(), # Child output is a stream.
    StderrFilter => POE::Filter::Line->new(),   # Child errors are lines.
  );

  print "Unique wheel ID is  : ", $wheel->ID;
  print "Wheel's child PID is: ", $wheel->PID;

  # Send something to the child's STDIN.
  $wheel->put( 'input for the child' );

DESCRIPTION

Wheel::Run spawns child processes and establishes non-blocking, event based communication with them.

PUBLIC METHODS

new LOTS_OF_STUFF

new() creates a new Run wheel. If successful, the new wheel represents a child process and the input, output and error pipes that speak with it.

new() accepts lots of stuff. Each parameter is name/value pair.

Conduit

Conduit describes how Wheel::Run should talk with the child process. It may either be 'pipe' (the default), or 'pty'.

Pty conduits require the IO::Pty module.

ErrorEvent

StdinEvent

StdoutEvent

StderrEvent

ErrorEvent contains the name of an event to emit if something fails. It's optional, and if omitted, it won't emit any errors.

Wheel::Run requires at least one of the following three events:

StdinEvent contains the name of an event that Wheel::Run emits whenever all its output has been flushed to the child process' STDIN handle.

StdoutEvent and StderrEvent contain names of events that Wheel::Run emits whenever the child process writes something to its STDOUT or STDERR handles, respectively.

Filter

StdinFilter

StdoutFilter

StderrFilter

Filter contains a reference to a POE::Filter class that describes how the child process performs input and output. Filter will be used to describe the child's stdin, stdout and stderr.

StdinFilter, StdoutFilter and StderrFilter can be used instead of Filter to set different filters for each handle.

Group

Group contains a numerical group ID that the child process should run at. This may not be meaningful on systems that have no concept of group IDs. The current process may need to run as root in order to change group IDs. Mileage varies considerably.

Priority

Priority contains an offset from the current process's priority. The child will be executed at the current priority plus the offset. The priority offset may be negative, but the current process may need to be running as root for that to work.

Program

Program is the program to exec() once pipes and fork have been set up. Program's type determines how the program will be run.

If Program holds a scalar, it will be executed as exec($scalar). Shell metacharacters will be expanded in this form.

If Program holds an array reference, it will executed as exec(@$array). This form of exec() doesn't expand shell metacharacters.

If Program holds a code reference, it will be called in the forked child process, and then the child will exit. This allows Wheel::Run to fork off bits of long-running code which can accept STDIN input and pass responses to STDOUT and/or STDERR. Note, however, that POE's services are effectively disabled in the child process.

perlfunc has more information about exec() and the different ways to call it.

event EVENT_TYPE => EVENT_NAME, ...

event() changes the event that Wheel::Run emits when a certain type of event occurs. EVENT_TYPE may be one of the event parameters in Wheel::Run's constructor.

  $wheel->event( StdinEvent  => 'new-stdin-event',
                 StdoutEvent => 'new-stdout-event',
               );

put LIST

put() queues a LIST of different inputs for the child process. They will be flushed asynchronously once the current state returns. Each item in the LIST is processed according to the StdinFilter.

set_filter FILTER_REFERENCE

Set StdinFilter, StdoutFilter, and StderrFilter all at once. Not yet implemented.

set_stdin_filter FILTER_REFERENCE

Set StdinFilter to something else. Not yet implemented.

set_stdout_filter FILTER_REFERENCE

Set StdoutFilter to something else. Not yet implemented.

set_stderr_filter FILTER_REFERENCE

Set StderrFilter to something else. Not yet implemented.

ID

Returns the wheel's unique ID, which is not the same as the child process' ID. Every event generated by Wheel::Run includes a wheel ID so that it can be matched up with its generator. This lets a single session manage several wheels without becoming confused about which one generated what event.

PID

Returns the child process' ID. It's useful for matching up to SIGCHLD events, which include child process IDs as well, so that wheels can be destroyed properly when children exit.

EVENTS AND PARAMETERS

ErrorEvent

ErrorEvent contains the name on an event that Wheel::Run emits whenever an error occurs. Every error event comes with four parameters:

ARG0 contains the name of the operation that failed. It may be 'read' or 'write' or 'fork' or 'exec' or something. The actual values aren't yet defined. Note: This is not necessarily a function name.

ARG1 and ARG2 hold numeric and string values for $!, respectively.

ARG3 contains the wheel's unique ID.

A sample error event handler:

  sub error_state {
    my ($operation, $errnum, $errstr, $wheel_id) = @_[ARG0..ARG3];
    warn "Wheel $wheel_id generated $operation error $errnum: $errstr\n";
  }

StdinEvent

StdinEvent contains the name of an event that Wheel::Run emits whenever everything queued by its put() method has been flushed to the child's STDIN handle.

StdinEvent's ARG0 parameter contains its wheel's unique ID.

StdoutEvent

StderrEvent

StdoutEvent and StderrEvent contain names for events that Wheel::Run emits whenever the child process makes output. StdoutEvent contains information the child wrote to its STDOUT handle, and StderrEvent includes whatever arrived from the child's STDERR handle.

Both of these events come with two parameters. ARG0 contains the information that the child wrote. ARG1 holds the wheel's unique ID.

  sub stdout_state {
    my ($heap, $input, $wheel_id) = @_[HEAP, ARG0, ARG1];
    print "Child process in wheel $wheel_id wrote to STDOUT: $input\n";
  }

  sub stderr_state {
    my ($heap, $input, $wheel_id) = @_[HEAP, ARG0, ARG1];
    print "Child process in wheel $wheel_id wrote to STDERR: $input\n";
  }

SEE ALSO

POE::Wheel.

The SEE ALSO section in POE contains a table of contents covering the entire POE distribution.

BUGS

Wheel::Run's constructor doesn't emit proper events when it fails. Instead, it just dies, carps or croaks.

Filter changing hasn't been implemented yet. Let the author know if it's needed. Better yet, patch the file based on the code in Wheel::ReadWrite.

Wheel::Run generates SIGCHLD. This may eventually cause Perl to segfault. Bleah.

Priority is a delta; there's no way to set it directly to some value.

User must be specified by UID. It would be nice to support login names.

Group must be specified by GID. It would be nice to support group names.

ActiveState Perl is not going to like this module one bit.

AUTHORS & COPYRIGHTS

Please see POE for more information about authors and contributors.