POE::Wheel::Run(3pm) - phpMan

POE::Wheel::Run(3pm) User Contributed Perl Documentation POE::Wheel::Run(3pm)

NAME
POE::Wheel::Run - abstract pipe/fork/exec mix-in (also runs subroutines)

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

$wheel = POE::Wheel::Run->new(
# Set the program to execute, and optionally some parameters.
Program => $program,
ProgramArgs => \@program_args,

# Define I/O events to emit. Most are optional.
StdinEvent => 'stdin', # Flushed all data to the child's STDIN.
StdoutEvent => 'stdout', # Received data from the child's STDOUT.
StderrEvent => 'stderr', # Received data from the child's STDERR.
ErrorEvent => 'oops', # An I/O error occurred.
CloseEvent => 'child_closed', # Child closed all output handles.

# Optionally adjust the child process priority, user ID, and/or
# group ID. You may need to be root to do this.
Priority => +5,
User => scalar(getpwnam 'nobody'),
Group => scalar(getgrnam 'nobody'),

# Optionally specify different I/O formats.
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.

# Shorthand to set StdinFilter and StdoutFilter together.
StdioFilter => POE::Filter::Line->new(), # Or some other filter.
);

# Information about the wheel and its process.
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' );

# Kill the child.
$wheel->kill(9); # TERM by default.

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

Wheel::Run does not reap child processes. For that, you need to register a SIGCHLD
handler:

$kernel->sig(CHLD => "your_event");

The session will then receive your_event with details about $? when the wheel's process
exits and is reaped. POE will reap child processes as a side effect.

Another way to do it is to register $SIG{CHLD} = "IGNORE". Use sparingly and with
caution: This may clobber a handler that POE has already registered for SIGCHLD. Why does
IGNORE work this way? See the discussion in perldoc perlipc.

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. By default it
will try various forms of inter-process communication to build a pipe between the
parent and child processes. If a particular method is preferred, it can be set to
"pipe", "socketpair", or "inet". It may also be set to "pty" if the child process
should have its own pseudo tty. Setting it to "pty-pipe" gives the child process a
stdin and stdout pseudo-tty, but keeps stderr as a pipe, rather than merging stdout
and stderr as with "pty".

The reasons to define this parameter would be if you want to use "pty", if the default
pipe type doesn't work properly on your system, or the default pipe type's performance
is poor.

Pty conduits require the IO::Pty module.

Winsize
"Winsize" is only valid for "Conduit = "pty"" and used to set the window size of the
pty device.

The window size is given as an array reference. The first element is the number of
lines, the second the number of columns. The third and the fourth arguments are
optional and specify the X and Y dimensions in pixels.

CloseOnCall
"CloseOnCall" emulates the close-on-exec feature for child processes which are not
started by exec(). When it is set to 1, all open file handles whose descriptors are
greater than $^F are closed in the child process. This is only effective when
POE::Wheel::Run is called with a code reference for its Program parameter.

CloseOnCall => 1,
Program => \&some_function,

CloseOnCall defaults to 0 (off) to remain compatible with existing programs.

For more details, please the discussion of $^F in perlvar.

StdioDriver
StdinDriver
StdoutDriver
StderrDriver
These parameters change the drivers for Wheel::Run. The default drivers are created
internally with "<POE::Driver::SysRW-"new()>>.

"StdioDriver" changes both "StdinDriver" and "StdoutDriver" at the same time.

CloseEvent
ErrorEvent
StdinEvent
StdoutEvent
StderrEvent
See "EVENTS AND PARAMETERS" below for a more detailed description of these events and
their parameters.

"CloseEvent" contains the name of an event to emit when the child process closes all
its output handles. This is a consistent notification that the child will not be
sending any more output. It does not, however, signal that the client process has
stopped accepting input.

"ErrorEvent" contains the name of an event to emit if something fails. It is optional
and if omitted, the wheel will not notify its session if any errors occur.

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

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

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

StdioFilter
StdinFilter
StdoutFilter
StderrFilter
"StdioFilter" contains an instance of a POE::Filter subclass. The filter describes
how the child process performs input and output. "Filter" will be used to describe
the child's stdin and stdout methods. If stderr is also to be used, StderrFilter will
need to be specified separately.

"Filter" is optional. If left blank, it will default to an instance of
"POE::Filter::Line->new(Literal => "\n");"

"StdinFilter" and "StdoutFilter" can be used instead of or in addition to
"StdioFilter". They will override the default filter's selection in situations where
a process' input and output are in different formats.

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.

NoSetSid
When true, "NoSetSid" disables setsid() in the child process. By default, setsid() is
called to execute the child process in a separate Unix session.

NoSetPgrp
When true, "NoSetPgrp" disables setprgp() in the child process. By default, setprgp()
is called to change the process group for the child process, if the OS supports
process groups. If the conduit is a pty or pty-pipe setsid() is used instead, see
"NoSetSid".

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. See
"Nested POE Kernel" for instructions on how to properly use POE within the child.

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

Note: Do not call exit() explicitly when executing a subroutine. POE::Wheel::Run
takes special care to avoid object destructors and END blocks in the child process,
and calling exit() will thwart that. You may see "POE::Kernel's run() method was
never called." or worse.

ProgramArgs => ARRAY
If specified, "ProgramArgs" should refer to a list of parameters for the program being
run.

my @parameters = qw(foo bar baz); # will be passed to Program
ProgramArgs => \@parameters;

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

get_stdin_filter
get_stdout_filter
get_stderr_filter
Get "StdinFilter", "StdoutFilter", or "StderrFilter" respectively.

set_stdio_filter FILTER_REFERENCE
Set "StdinFilter" and "StdoutFilter" at once.

set_stdin_filter FILTER_REFERENCE
set_stdout_filter FILTER_REFERENCE
set_stderr_filter FILTER_REFERENCE
Set "StdinFilter", "StdoutFilter", or "StderrFilter" respectively.

pause_stdout
pause_stderr
resume_stdout
resume_stderr
Pause or resume "StdoutEvent" or "StderrEvent" events. By using these methods a session
can control the flow of Stdout and Stderr events coming in from this child process.

shutdown_stdin
Closes the child process' STDIN and stops the wheel from reporting StdinEvent. It is
extremely useful for running utilities that expect to receive EOF on their standard
inputs before they respond.

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.

kill SIGNAL
Sends a signal to the child process. It's useful for processes which tend to be
reluctant to exit when their terminals are closed.

The kill() method will send SIGTERM if SIGNAL is undef or omitted.

get_driver_out_messages
get_driver_out_octets
Return driver statistics.

EVENTS AND PARAMETERS
CloseEvent
CloseEvent contains the name of the event Wheel::Run emits whenever a child process has
closed all its output handles. It signifies that the child will not be sending more
information. In addition to the usual POE parameters, each CloseEvent comes with one of
its own:

"ARG0" contains the wheel's unique ID. This can be used to keep several child processes
separate when they're managed by the same session.

A sample close event handler:

sub close_state {
my ($heap, $wheel_id) = @_[HEAP, ARG0];

my $child = delete $heap->{child}->{$wheel_id};
print "Child ", $child->PID, " has finished.\n";
}

ErrorEvent
ErrorEvent contains the name of 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', 'write',
'fork', 'exec' or the name of some other function or task. 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. "$!" will eq ""
for read error 0 (child process closed STDOUT or STDERR).

"ARG3" contains the wheel's unique ID.

"ARG4" contains the name of the child filehandle that has the error. It may be "STDIN",
"STDOUT", or "STDERR". The sense of "ARG0" will be the opposite of what you might
normally expect for these handles. For example, Wheel::Run will report a "read" error
on "STDOUT" because it tried to read data from that handle.

A sample error event handler:

sub error_state {
my ($operation, $errnum, $errstr, $wheel_id) = @_[ARG0..ARG3];
$errstr = "remote end closed" if $operation eq "read" and !$errnum;
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 generates new 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";
}

TIPS AND TRICKS
Execution environment

One common task is scrubbing a child process' environment. This amounts to clearing the
contents of %ENV and setting it up with some known, secure values.

Environment scrubbing is easy when the child process is running a subroutine, but it's not
so easy---or at least not as intuitive---when executing external programs.

The way we do it is to run a small subroutine in the child process that performs the
exec() call for us.

Program => \&exec_with_scrubbed_env,

sub exec_with_scrubbed_env {
delete @ENV{keys @ENV};
$ENV{PATH} = "/bin";
exec(@program_and_args);
}

That deletes everything from the environment, sets a simple, secure PATH, and executes a
program with its arguments.

Nested POE Kernel

When the process forks the kernel's queue is effectively duplicated, giving the child
process it's own copy.

This means that if you call "$poe_kernel->run" in the coderef variant of "Program", the
kernel will deliver all currently queued events twice, causing the universe to implode, or
worse.

This is why POE::Wheel::Run will exit immediately after executing the code reference,
before the kernel's loop can dequeue anything more.

In order to allow a POE kernel to be run inside the child process without having to "exec"
a new perl script with a fresh POE environment, you can call the "stop" in POE::Kernel
method.

Here is an example:

Program => sub {
$poe_kernel->stop; # flush all the kernel structures

# now that the kernel is clean we can do POEish stuff:
POE::Session->create(
...
);

$poe_kernel->run; # this DWIMs now
}

If you do not call "stop" in POE::Kernel, but do call "run" in POE::Kernel inside the
child process strange things are bound to happen.

The advantage of calling "POE::Kernel/stop" is that it allows all the advantages of a
"fork" without an "exec", namely sharing of read only data, but without having to forefit
POE's facilities in the child.