NAME

IPC::Simple - simple, non-blocking IPC

VERSION

version 0.04

SYNOPSIS

  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
  }

DESCRIPTION

Provides a simplified interface for managing and kibbitzing with a child process.

EXPORTS

Nothing is exported by default, but the following subroutines may be requested for import.

spawn

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.

spawn does not launch the process.

  my $proc = spawn ["echo", "hello world"], eol => "\n";

Is equivalent to:

  my $proc = IPC::Simple->new(
    cmd => ["echo", "hello world"],
    eol => "\n",
  );

process_group

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;

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. This may be specified as the entire command string or as an array ref of the command and its arguments.

name

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.

eol

The end-of-line character to print at the end of each call to "send". Defaults to "\n".

recv_cb

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;

term_cb

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;
    ...
  };

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 the value of "eol".

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 a IPC::Simple::Message with the following significant methods:

source

The IPC::Simple object from which the message originated.

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.

MSWIN32 SUPPORT

Nope.

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.

cpanm IPC::Simple

perl -MCPAN -e shell
install IPC::Simple