NAME
IPC::Simple - simple, non-blocking IPC
VERSION
version 0.01
SYNOPSIS
use IPC::Simple;
my $ssh = IPC::Simple->new(
cmd => 'ssh',
args => [ $host ],
eol => "\n",
);
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
}DESCRIPTION
Provides a simplified interface for managing and kibbitzing with a child process.
METHODS
new
Creates a new IPC::Simple process object. The process is not immediately launched; see "launch".
constructor arguments
- cmd
-
The command to launch in a child process.
- args
-
An array ref of arguments to
cmd. - eol
-
The end-of-line character to print at the end of each call to "send". Defaults to
"\n".
pid
Once launched, returns the pid of the child process.
exit_status
Once a child process exits, this is set to the exit status ($?) of the child process.
exit_code
Once a child process has terminated, this is set to the exit code of the child process.
launch
Starts the child process. Returns true on success, croaks on failure to launch the process.
terminate
Sends the child process a `SIGTERM`. Returns immediately. Use "join" to wait for the process to finish.
join
Blocks until the child process has exited.
send
Sends a string of text to the child process. The string will be appended with a single newline.
recv
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).
Each message returned by recv is an object overloaded so that it can be treated as a string as well as providing the following methods:
async
Schedules a callback for the next line of input to be received, returning immediately.
$proc->async(sub{
my $msg = shift;
if ($msg->stdout) {
...
}
});This is done with "CONDITION-VARIABLES" in AnyEvent, so the same caveats about races and dead locks apply. It is up to the caller to manage their event loop.
- stdout
-
True when the message came from the child process'
STDOUT. - stderr
-
True when the message came from the child process'
STDERR. - error
-
True when the message is a sub-process communication error.
DEBUGGING
IPC::Simple will emit highly verbose messages to STDERR if the environment variable IPC_SIMPLE_DEBUG is set to a true value.
AUTHOR
Jeff Ober <sysread@fastmail.fm>
COPYRIGHT AND LICENSE
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.