Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/sysread/ipc-simple

Easy to use non-blocking IPC for perl
https://github.com/sysread/ipc-simple

async ipc non-blocking perl process

Last synced: 23 days ago
JSON representation

Easy to use non-blocking IPC for perl

Awesome Lists containing this project

README 

        
=pod



=encoding UTF-8



=head1 NAME



IPC::Simple - simple, non-blocking IPC



=head1 VERSION



version 0.09



=head1 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

  }



=head1 DESCRIPTION



Provides a simplified interface for managing and kibbitzing with a child

process.



=head1 EXPORTS



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

for import.



=head2 spawn



Returns a new C 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.



C does I 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",

  );



=head2 process_group



Builds a combined message queue for a group of I C

objects that may be used to process all of the group's messages together.

Returns an L.



  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;



=head1 METHODS



=head1 new



Creates a new C process object. The process is not immediately

launched; see L.



=head2 constructor arguments



=over



=item 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.



=item 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.



=item eol



The end-of-line character to print at the end of each call to L.

Defaults to C<"\n">.



=item 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;



=item term_cb



Another optional callback to be triggered when the process is terminated. The

exit status and exit code are available once the L 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;

    ...

  };



=back



=head2 pid



Once launched, returns the pid of the child process.



=head2 exit_status



Once a child process exits, this is set to the exit status (C<$?>) of the child

process.



=head2 exit_code



Once a child process has terminated, this is set to the exit code of the child

process.



=head2 launch



Starts the child process. Returns true on success, croaks on failure to launch

the process.



=head2 terminate



Sends the child process a C. Returns immediately. Use L to wait

for the process to finish. An optional timeout may be specified in fractional

seconds, after which the child process is issued a C.



=head2 signal



Sends a signal to the child process. Accepts a single argument, the signal type

to send.



  $proc->signal('TERM');



=head2 join



Blocks until the child process has exited.



=head2 send



Sends a string of text to the child process. The string will be appended with

the value of L.



=head2 recv



Waits for and returns the next line of output from the process, which may be

from C, from C, or it could be an error message resulting from

an I/O error while communicating with the process (e.g. a C or

abnormal termination).



Each message returned by C is an object overloaded so that it can be

treated as a string as well as a L with the following

significant methods:



=over



=item source



The C object from which the message originated.



=item stdout



True when the message came from the child process' C.



=item stderr



True when the message came from the child process' C.



=item error



True when the message is a sub-process communication error.



=back



=head1 DEBUGGING



C will emit highly verbose messages to C if the

environment variable C is set to a true value.



=head1 MSWIN32 SUPPORT



Nope.



=head1 AUTHOR



Jeff Ober 



=head1 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.



=cut