view release on metacpan or  search on metacpan

lib/IPC/Run.pm  view on Meta::CPAN

   $h->finish;

   warn $err if $err;

=cut

sub pump {
    die "pump() takes only a single harness as a parameter"
      unless @_ == 1 && UNIVERSAL::isa( $_[0], __PACKAGE__ );

    my IPC::Run $self = shift;

    local $cur_self = $self;

    _debug "** pumping"
      if _debugging;

    $self->start if $self->{STATE} < _started;
    croak "process ended prematurely" unless $self->pumpable;

    $self->{auto_close_ins} = 0;
    $self->{break_on_io}    = 1;
    $self->_select_loop;
    return $self->pumpable;
}

=pod

=item pump_nb

   pump_nb $h;
   $h->pump_nb;

"pump() non-blocking", pumps if anything's ready to be pumped, returns
immediately otherwise.  This is useful if you're doing some long-running
task in the foreground, but don't want to starve any child processes.

=cut

sub pump_nb {
    my IPC::Run $self = shift;

    $self->{non_blocking} = 1;
    my $r = eval { $self->pump };
    $self->{non_blocking} = 0;
    die $@ if $@;
    return $r;
}

=pod

=item close_stdin

   $h->close_stdin;

Closes the input pipe(s) to the child process(es), signaling EOF on
the child's STDIN.  Does B<not> wait for the child to finish or drain
remaining output.  After calling this, the caller can continue to
C<pump()> to retrieve output incrementally.

This is useful when streaming large amounts of data through a child
process (e.g., decompression) where you want to signal end-of-input
but continue draining output without buffering it all in memory:

   my ( $in, $out ) = ( '', '' );
   my $h = start \@cmd, \$in, \$out, timeout( 30 );

   while ( read_more_input_into( $in ) ) {
       $h->pump;
       process_output( $out ) if length $out;
       $out = '';
   }

   $h->close_stdin;

   while ( $h->pumpable ) {
       $h->pump;
       process_output( $out ) if length $out;
       $out = '';
   }

   $h->finish;

B<Note:> Always use a C<timeout()> with this pattern.  Without one, the
C<pump()> calls can deadlock if the child blocks on writing output while
you are blocked trying to write input (or vice versa).

Without C<close_stdin()>, calling C<finish()> would accumulate all
remaining output in C<$out> before returning, potentially exhausting
memory for children that produce large output (like decompressors).

Returns the harness object for chaining.

=cut

sub close_stdin {
    my IPC::Run $self = shift;

    local $cur_self = $self;

    croak "harness has not been started" unless $self->{STATE} >= _started;

    _debug "** closing stdin" if _debugging;

    # Match all input pipe types: '<' (plain), '<pipe', '<pty<', etc.
    # _clobber() handles each type appropriately: for regular pipes it
    # closes the fd (signaling EOF to the child); for input ptys it
    # removes them from the select vectors without closing the pty
    # master (consistent with _clobber's existing pty safety logic).
    for my $pipe ( @{ $self->{PIPES} } ) {
        next unless $pipe->{TYPE} =~ /^</;
        $self->_clobber($pipe);
    }

    return $self;
}

=pod

=item started