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

VERSION
    0.18

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.

    Patches that enable the "read" event to see the difference between
    STDERR and STDOUT are more than welcome.

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

      # 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("pty");

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

  In a Mojolicios::Controller
    See
    <https://github.com/jhthorsen/mojo-ioloop-readwritefork/tree/master/exam
    ple/tail.pl>.

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.

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

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

ATTRIBUTES
  conduit
      $str  = $self->conduit;
      $self = $self->conduit("pty");

    Used to set the conduit. Can be either "pty" or "pipe" (default).

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

    Holds a Mojo::IOLoop object.

  pid
      $int = $self->pid;

    Holds the child process ID.

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

    Close STDIN stream to the child process immediately.

  run
      $self = $self->run($program, @program_args);

    Simpler version of "start".

  start
      $self->start(
        program            => $str,
        program_args       => [@str],
        conduit            => $str,      # pipe or pty
        raw                => $bool,
        clone_winsize_from => \*STDIN,
      );

    Used to fork and exec a child process.

    raw and "clone_winsize_from|IO::Pty" only makes sense if "conduit" is
    "pty".

  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.

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"