view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

            use IO::Handle;
            flush HANDLE;

        Perl needs the equivalent of C's fflush( (FILE \*)NULL ).

    - adopt

        Experimental feature. NOT FUNCTIONAL YET, NEED TO CLOSE FDS BETTER IN CHILDREN.  SEE t/adopt.t for a test suite.

    - pump

            pump $h;
            $h->pump;

        Pump accepts a single parameter harness.  It blocks until it delivers some
        input or receives some output.  It returns TRUE if there is still input or
        output to be done, FALSE otherwise.

        pump() will automatically call start() if need be, so you may call harness()
        then proceed to pump() if that helps you structure your application.

        If pump() is called after all harnessed activities have completed, a "process
        ended prematurely" exception to be thrown.  This allows for simple scripting
        of external applications without having to add lots of error handling code at
        each step of the script:

            $h = harness \@smbclient, \$in, \$out, $err;

            $in = "cd /foo\n";
            $h->pump until $out =~ /^smb.*> \Z/m;
            die "error cding to /foo:\n$out" if $out =~ "ERR";
            $out = '';

            $in = "mget *\n";
            $h->pump until $out =~ /^smb.*> \Z/m;
            die "error retrieving files:\n$out" if $out =~ "ERR";

            $h->finish;

            warn $err if $err;

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

    - close\_stdin

            $h->close_stdin;

        Closes the input pipe(s) to the child process(es), signaling EOF on
        the child's STDIN.  Does **not** wait for the child to finish or drain
        remaining output.  After calling this, the caller can continue to
        `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;

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

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

        Returns the harness object for chaining.

    - started

        Returns TRUE if the harness has been started and has not yet finished.
        This is useful when a harness may or may not have been started by the
        caller, and you want to conditionally start it:

            $h->start unless $h->started;

    - pumpable

        Returns TRUE if calling pump() won't throw an immediate "process ended
        prematurely" exception.  This means that there are open I/O channels or
        active processes. May yield the parent processes' time slice for 0.01
        second if all pipes are to the child and all are paused.  In this case
        we can't tell if the child is dead, so we yield the processor and
        then attempt to reap the child in a nonblocking way.

        To wait for child processes to exit during an event loop, poll
        `$h-`pumpable> until it returns false, then call `finish`.
        See also ["finished"](#finished) to test whether the harness has already been
        finished.

    - reap\_nb

        Attempts to reap child processes, but does not block.

        Does not currently take any parameters, one day it will allow specific
        children to be reaped.