NAME
    Mojo::IOLoop::ReadWriteFork - Fork a process and read/write from it

VERSION
    0.22

SYNOPSIS
      my $fork = Mojo::IOLoop::ReadWriteFork->new;

      # Emitted if something terrible happens
      $fork->on(error => sub { my ($fork, $error) = @_; warn $error; });

      # Emitted when the child completes
      $fork->on(close => sub { my ($fork, $exit_value, $signal) = @_; Mojo::IOLoop->stop; });

      # Emitted when the child prints to STDOUT or STDERR
      $fork->on(read => sub {
        my ($fork, $buf) = @_;
        print qq(Child process sent us "$buf");
      });

      # Need to set "conduit" for bash, ssh, and other programs that require a pty
      $fork->conduit({type => "pty"});

      # Start the application
      $fork->run("bash", -c => q(echo $YIKES foo bar baz));

    See also
    <https://github.com/jhthorsen/mojo-ioloop-readwritefork/tree/master/exam
    ple/tail.pl> for an example usage from a Mojo::Controller.

DESCRIPTION
    This class enable you to fork a child process and "read" and "write"
    data to. You can also send signals to the child and see when the process
    ends. The child process can be an external program (bash, telnet,
    ffmpeg, ...) or a CODE block running perl.

    Patches <https://github.com/jhthorsen/mojo-ioloop-readwritefork/pulls>
    that enable the "read" event to see the difference between STDERR and
    STDOUT are more than welcome.

EVENTS
  close
      $self->on(close => sub { my ($self, $exit_value, $signal) = @_; });

    Emitted when the child process exit.

  error
      $self->on(error => sub { my ($self, $str) = @_; });

    Emitted when when the there is an issue with creating, writing or
    reading from the child process.

  fork
      $self->on(fork => sub { my ($self) = @_; });

    Emitted after "fork()" has been called. Note that the child process
    might not yet have been started. The order of things is impossible to
    say, but it's something like this:

                .------.
                | fork |
                '------'
                   |
               ___/ \_________________
              |                       |
              | (parent)              | (child)
          .-------------.             |
          | emit "fork" |    .--------------------.
          '-------------'    | set up filehandles |
                             '--------------------'
                                      |
                              .---------------.
                              | exec $program |
                              '---------------'

    See also "pid" for example usage of this event.

  read
      $self->on(read => sub { my ($self, $buf) = @_; });

    Emitted when the child has written a chunk of data to STDOUT or STDERR.

ATTRIBUTES
  conduit
      $hash = $self->conduit;
      $self = $self->conduit({type => "pipe"});

    Used to set the conduit and conduit options. Example:

      $self->conduit({raw => 1, type => "pty"});

  ioloop
      $ioloop = $self->ioloop;
      $self = $self->ioloop(Mojo::IOLoop->singleton);

    Holds a Mojo::IOLoop object.

  pid
      $int = $self->pid;

    Holds the child process ID. Note that "start" will start the process
    after the IO loop is started. This means that the code below will not
    work:

      $fork->run("bash", -c => q(echo $YIKES foo bar baz));
      warn $fork->pid; # pid() is not yet set

    This will work though:

      $fork->on(spawn => sub { my $self = shift; warn $self->pid });
      $fork->run("bash", -c => q(echo $YIKES foo bar baz));

METHODS
  close
      $self = $self->close("stdin");

    Close STDIN stream to the child process immediately.

  run
      $self = $self->run($program, @program_args);
      $self = $self->run(\&Some::Perl::function, @function_args);

    Simpler version of "start". Can either start an application or run a
    perl function.

  start
      $self = $self->start(\%args);

    Used to fork and exec a child process. %args can have:

    * program

      Either an application or a CODE ref.

    * program_args

      A list of options passed on to "program" or as input to the CODE ref.

      Note that this module will start "program" with this code:

        exec $program, @$program_args;

      This means that the code is subject for shell injection
      <https://en.wikipedia.org/wiki/Code_injection#Shell_injection> unless
      invoked with more than one argument. This is considered a feature, but
      something you should be avare of. See also "exec" in perlfunc for more
      details.

    * env

      Passing in "env" will override the default set of environment
      variables, stored in %ENV.

    * conduit

      Either "pipe" (default) or "pty". "pty" will use IO::Pty to simulate a
      "pty", while "pipe" will just use "pipe" in perlfunc. This can also be
      specified by using the "conduit" attribute.

    * clone_winsize_from

      See "clone_winsize_from" in IO::Pty. This only makes sense if
      "conduit" is set to "pty". This can also be specified by using the
      "conduit" attribute.

    * raw

      See "set_raw" in IO::Pty. This only makes sense if "conduit" is set to
      "pty". This can also be specified by using the "conduit" attribute.

  write
      $self = $self->write($chunk);
      $self = $self->write($chunk, $cb);

    Used to write data to the child process STDIN. An optional callback will
    be called once STDIN is drained.

    Example:

      $self->write("some data\n", sub {
        my ($self) = @_;
        $self->close;
      });

  kill
      $bool = $self->kill;
      $bool = $self->kill(15); # default

    Used to signal the child.

SEE ALSO
    Mojo::IOLoop::ForkCall.

    <https://github.com/jhthorsen/mojo-ioloop-readwritefork/tree/master/exam
    ple/tail.pl>

COPYRIGHT AND LICENSE
    Copyright (C) 2013-2016, Jan Henning Thorsen

    This program is free software, you can redistribute it and/or modify it
    under the terms of the Artistic License version 2.0.

AUTHOR
    Jan Henning Thorsen - "jhthorsen@cpan.org"