view release on metacpan or  search on metacpan

lib/Gnuplot/Builder/Process.pm  view on Meta::CPAN

1;

__END__

=pod

=head1 NAME

Gnuplot::Builder::Process - gnuplot process manager

=head1 SYNOPSIS

    use Gnuplot::Builder::Process;
    
    @Gnuplot::Builder::Process::COMMAND = ("/path/to/gnuplot", "-p");
    $Gnuplot::Builder::Process::ENCODING = "utf8";

=head1 DESCRIPTION

L<Gnuplot::Builder::Process> class manages gnuplot processes spawned
by all L<Gnuplot::Builder::Script> objects.

You can configure its package variables to change its behavior.

=head1 CLASS METHODS

=head2 Gnuplot::Builder::Process->wait_all()

Wait for all gnuplot processes to finish.

If there is no gnuplot process running, this method returns immediately.

=head1 PACKAGE VARIABLES

B<< The default values for these variables may be changed in future releases. >>

=head2 $ASYNC

If set to true, plotting methods of L<Gnuplot::Builder::Script> run in the asynchronous mode by default.
See L<Gnuplot::Builder::Script> for detail.

By default, it's C<0> (false).

You can also set this variable by the environment variable
C<PERL_GNUPLOT_BUILDER_PROCESS_ASYNC>.

=head2 @COMMAND

The command and arguments to run a gnuplot process.

By default, it's C<("gnuplot", "--persist")>.

You can also set this variable by the environment variable
C<PERL_GNUPLOT_BUILDER_PROCESS_COMMAND>.


=head2 $ENCODING

If set, L<Gnuplot::Builder> encodes the script string in the specified encoding just before streaming into the gnuplot process.
You can specify any encoding names recognizable by L<Encode> module.

By default it's C<undef>, meaning it doesn't encode the script.

You can also set this variable by the environment variable
C<PERL_GNUPLOT_BUILDER_PROCESS_ENCODING>.

=head2 $MAX_PROCESSES

Maximum number of gnuplot processes that can run in parallel.
If C<$MAX_PROCESSES> <= 0, the number of processes is unlimited.

By default, it's C<2>.

You can also set this variable by the environment variable
C<PERL_GNUPLOT_BUILDER_PROCESS_MAX_PROCESSES>.

=head2 $NO_STDERR

If set to true, gnuplot's STDERR will not appear in the return value of L<Gnuplot::Builder::Script>'s plotting methods
(C<plot()>, C<plot_with()>, C<splot()> ... etc).
It returns STDOUT only. You can use this to prevent warnings in the output.

By default it is C<0> (false).
You can also set this variable by the environment variable
C<PERL_GNUPLOT_BUILDER_PROCESS_NO_STDERR>.


=head2 $PAUSE_FINISH

If set to true, L<Gnuplot::Builder> sends "pause mouse close" command to the gnuplot process
just before finishing the script.

By default, it's C<0> (false).

You can also set this variable by the environment variable
C<PERL_GNUPLOT_BUILDER_PROCESS_PAUSE_FINISH>.

=head2 $TAP

A subroutine reference to tap the IPC with the gnuplot process. This is useful for debugging.

If set, the subroutine reference is called for each event.

    $TAP->($pid, $event, $body)

where C<$pid> is the PID of the gnuplot process,
C<$event> is a string describing the event type,
and C<$body> is an object describing the event.

Currently C<$event> is always C<"write">, which is called every time some data is written to the gnuplot process.
C<$body> is the written string.

To set C<$TAP> from outside the program, use L<Gnuplot::Builder::Tap>.

Example:

    local $Gnuplot::Builder::Process::TAP = sub {
        my ($pid, $event, $body) = @_;
        warn "PID:$pid, EVENT:$event, BODY:$body";