IPC::Simple - simple, non-blocking IPC
version 0.09
use IPC::Simple qw(spawn); my $ssh = spawn ['ssh', $host]; if ($ssh->launch) { $ssh->send('ls -lah'); # get directory listing $ssh->send('echo'); # signal our loop that the listing is done while (my $msg = $ssh->recv) { # echo's output will be an empty string if ($msg->error) { # I/O error croak $msg; } elsif ($msg->stderr) { # output to STDERR warn $msg; } elsif ($msg->stdout) { # output to STDOUT say $msg; } } $ssh->send('exit'); # terminate the connection $ssh->join; # wait for the process to terminate }
Provides a simplified interface for managing and kibbitzing with a child process.
Nothing is exported by default, but the following subroutines may be requested for import.
Returns a new IPC::Simple object. The first argument is either the command line string or an array ref of the command and its arguments. Any remaining arguments are treated as keyword pairs for the constructor.
IPC::Simple
spawn does not launch the process.
spawn
my $proc = spawn ["echo", "hello world"], eol => "\n";
Is equivalent to:
my $proc = IPC::Simple->new( cmd => ["echo", "hello world"], eol => "\n", );
Builds a combined message queue for a group of unlaunched IPC::Simple objects that may be used to process all of the group's messages together. Returns an IPC::Simple::Group.
my $group = process_group( spawn('...', name => 'foo'), spawn('...', name => 'bar'), spawn('...', name => 'baz'), ); $group->launch; while (my $msg = $group->recv) { if ($msg->source->name eq 'foo') { ... } } $group->terminate; $group->join;
Creates a new IPC::Simple process object. The process is not immediately launched; see "launch".
The command to launch in a child process. This may be specified as the entire command string or as an array ref of the command and its arguments.
Optionally specify a name for this process. This is useful when grouping processes together to identify the source of a message. If not provided, the command string is used by default.
The end-of-line character to print at the end of each call to "send". Defaults to "\n".
"\n"
Optionally, a callback may be specified to receive messages as they arrive.
my $proc = spawn [...], recv_cb => sub{ my $msg = shift; my $proc = $msg->source; ... }; $proc->launch; $proc->join;
Another optional callback to be triggered when the process is terminated. The exit status and exit code are available once the "join" method has been called on the process object passed to the callback.
my $proc = spawn [...], term_cb => sub{ my $proc = shift; $proc->join; my $code = $proc->exit_code; my $status = $proc->exit_status; ... };
Once launched, returns the pid of the child process.
Once a child process exits, this is set to the exit status ($?) of the child process.
$?
Once a child process has terminated, this is set to the exit code of the child process.
Starts the child process. Returns true on success, croaks on failure to launch the process.
Sends the child process a SIGTERM. Returns immediately. Use "join" to wait for the process to finish. An optional timeout may be specified in fractional seconds, after which the child process is issued a SIGKILL.
SIGTERM
SIGKILL
Sends a signal to the child process. Accepts a single argument, the signal type to send.
$proc->signal('TERM');
Blocks until the child process has exited.
Sends a string of text to the child process. The string will be appended with the value of "eol".
Waits for and returns the next line of output from the process, which may be from STDOUT, from STDERR, or it could be an error message resulting from an I/O error while communicating with the process (e.g. a SIGPIPE or abnormal termination).
STDOUT
STDERR
SIGPIPE
Each message returned by recv is an object overloaded so that it can be treated as a string as well as a IPC::Simple::Message with the following significant methods:
recv
The IPC::Simple object from which the message originated.
True when the message came from the child process' STDOUT.
True when the message came from the child process' STDERR.
True when the message is a sub-process communication error.
IPC::Simple will emit highly verbose messages to STDERR if the environment variable IPC_SIMPLE_DEBUG is set to a true value.
IPC_SIMPLE_DEBUG
Nope.
Jeff Ober <sysread@fastmail.fm>
This software is copyright (c) 2020 by Jeff Ober.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install IPC::Simple, copy and paste the appropriate command in to your terminal.
cpanm
cpanm IPC::Simple
CPAN shell
perl -MCPAN -e shell install IPC::Simple
For more information on module installation, please visit the detailed CPAN module installation guide.