Wx::Perl::ProcessStreaUser Contributed Perl DocumentWx::Perl::ProcessStream(3)NAMEWx::Perl::ProcessStream - access IO of external processes via events
VERSION
Version 0.29
SYNOPSYS
use Wx::Perl::ProcessStream qw( :everything );
EVT_WXP_PROCESS_STREAM_STDOUT ( $self, \&evt_process_stdout );
EVT_WXP_PROCESS_STREAM_STDERR ( $self, \&evt_process_stderr );
EVT_WXP_PROCESS_STREAM_EXIT ( $self, \&evt_process_exit );
EVT_WXP_PROCESS_STREAM_MAXLINES ( $self, \&evt_process_maxlines );
my $proc1 = Wx::Perl::ProcessStream::Process->new('perl -e"print qq($_\n) for(@INC);"', 'MyName1', $self);
$proc1->Run;
my $command = 'executable.exe parm1 parm2 parm3'
my $proc2 = Wx::Perl::ProcessStream::Process->new($command, 'MyName2', $self)
->Run;
my @args = qw( executable.exe parm1 parm2 parm3 );
my $proc3 = Wx::Perl::ProcessStream::Process->new(\@args, 'MyName2', $self);
$proc3->Run;
my $proc4 = Wx::Perl::ProcessStream::Process->new(\@args, 'MyName2', $self, 'readline')->Run;
my $proc5 = Wx::Perl::ProcessStream::Process->new(\@args, 'MyName2', $self);
sub evt_process_stdout {
my ($self, $event) = @_;
$event->Skip(1);
my $process = $event->GetProcess;
my $line = $event->GetLine;
if($line eq 'something we are waiting for') {
$process->WriteProcess('a message to stdin');
$process->CloseInput() if($finishedwriting);
}
............
# To Clear Buffer
my @buffers = @{ $process->GetStdOutBuffer };
}
sub evt_process_stderr {
my ($self, $event) = @_;
$event->Skip(1);
my $process = $event->GetProcess;
my $line = $event->GetLine;
print STDERR qq($line\n);
# To Clear Buffer
my @errors = @{ $process->GetStdErrBuffer };
}
sub evt_process_exit {
my ($self, $event) = @_;
$event->Skip(1);
my $process = $event->GetProcess;
my $line = $event->GetLine;
my @buffers = @{ $process->GetStdOutBuffer };
my @errors = @{ $process->GetStdErrBuffer };
my $exitcode = $process->GetExitCode;
............
$process->Destroy;
}
sub evt_process_maxlines {
my ($self, $event) = @_;
my $process = $event->GetProcess;
..... bad process
$process->Kill;
}
DESCRIPTION
This module provides the STDOUT, STDERR and exit codes of
asynchronously running processes via events. It may be used for long
running or blocking processes that provide periodic updates on state
via STDOUT. Simple IPC is possible via STDIN.
Do not use this module simply to collect the output of another process.
For that, it is much simpler to do:
my ($status, $output) = Wx::ExecuteStdout( 'perl -e"print qq($_\n) for(@INC);"' );
Wx::Perl::ProcessStream::Process
Methods
new Create a new Wx::Perl::ProcessStream::Process object. You
must then use the Run method to execute your command.
my $process = Wx::Perl::ProcessStream::Process->new($command, $name, $eventhandler, $readmethod);
$command = command text (and parameters) you wish to run. You may also pass a
reference to an array containing the command and parameters.
$name = an arbitray name for the process.
$eventhandler = the Wx EventHandler (Wx:Window) that will handle events for this process.
$readmethod = 'read' or 'readline' (default = 'readline') an optional param. From Wx version
0.75 you can specify the method you wish to use to read the output of an
external process.
The default depends on your Wx version ( 'getc' < 0.75,'readline' >= 0.75)
read -- uses the Wx::InputStream->READ method to read bytes.
readline -- uses the Wx::InputStream->READLINE method to read bytes
getc -- alias for read (getc not actually used)
SetMaxLines Set the maximum number of lines that will be read from a
continuous stream before raising a
EVT_WXP_PROCESS_STREAM_MAXLINES event. The default is 1000.
A continuous stream will cause your application to hang.
$process->SetMaxLines(10);
Run Run the process with the parameters passed to new. On
success, returns the process object itself. This allows
you to do: my $process =
Wx::Perl::ProcessStream->new($command, $name, $self)->Run;
Returns undef if the process could not be started.
my $process = Wx::Perl::ProcessStream::Process->new($command, $name, $eventhandler, $readmethod);
$process->Run;
CloseInput Close the STDIN stream of the external process. (Some
processes may not close until STDIN is closed.)
$process->CloseInput();
GetAppCloseAction
Returns the current process signal that will used on
application exit. Either wxpSIGTERM or wxpSIGKILL. See
SetAppCloseAction.
my $action = $process->GetAppCloseAction();
GetExitCode Returns the process exit code. It is undefined until a
wxpEVT_PROCESS_STREAM_EXIT event has been received.
my $exitcode = $process->GetExitCode();
GetProcessName
Returns the process name as passed to the OpenProcess
constructor.
my $processname = $process->GetProcessName();
GetStdErrBuffer
This returns a reference to an array containing all the
lines sent by the process to stderr. Calling this clears
the process object internal stderr buffer. (This has no
effect on the actual process I/O buffers.)
my $arryref = $process->GetStdErrBuffer();
GetStdOutBuffer
This returns a reference to an array containing all the
lines sent by the process to stdout. Calling this clears
the process object internal stdout buffer. (This has no
effect on the actual process I/O buffers.)
my $arryref = $process->GetStdOutBuffer();
GetStdErrBufferLineCount
This returns the number of lines currently in the stderr
buffer.
my $count = $process->GetStdErrBufferLineCount();
GetStdOutBufferLineCount
This returns the number of lines currently in the stdout
buffer.
my $count = $process->GetStdOutBufferLineCount();
PeekStdErrBuffer
This returns a reference to an array containing all the
lines sent by the process to stderr. To retrieve the
buffer and clear it, call GetStdErrBuffer instead.
my $arryref = $process->PeekStdErrBuffer();
PeekStdOutBuffer
This returns a reference to an array containing all the
lines sent by the process to stdout. To retrieve the
buffer and clear it, call GetStdOutBuffer instead.
my $arryref = $process->PeekStdOutBuffer();
GetProcessId
Returns the process id assigned by the system.
my $processid = $process->GetProcessId();
GetPid Returns the process id assigned by the system.
my $processid = $process->GetPid();
IsAlive Check if the process still exists in the system. Returns 1
if process exists, 0 if process does not exist. If the
process has already signalled its exit, the IsAlive method
will always return 0. Therefore IsAlive should always
return 0 (false) once a EVT_WXP_PROCESS_STREAM_EXIT event
has been sent.
my $isalive = $process->IsAlive();
KillProcess Send a SIGKILL signal to the external process.
$process->KillProcess();
SetAppCloseAction
When your application exits, any remaining
Wx::Perl::ProcessStream::Process objects will be signaled
to close. The default signal is wxpSIGTERM but you can
change this to wxpSIGKILL if you are sure this is what you
want.
$process->SetAppCloseAction( $newaction );
$newaction = one of wxpSIGTERM, wxpSIGKILL
TerminateProcess
Send a SIGTERM signal to the external process.
$process->TerminateProcess();
WriteProcess
Write to the STDIN of process.
$process->WriteProcess( $writedata . "\n" );
$writedata = The data you wish to write. Remember to add any appropriate line endings your external process may expect.
Wx::Perl::ProcessStream
Methods
OpenProcess Run an external process. DEPRECATED - use
Wx::Perl::ProcessStream::Process->new()->Run; If the
process is launched successfully, returns a
Wx::Perl::ProcessStream::Process object. If the process
could not be launched, returns undef;
my $process = Wx::Perl::ProcessStream->OpenProcess($command, $name, $eventhandler, $readmethod);
$command = command text (and parameters) you wish to run. You may also pass a
reference to an array containing the command and parameters.
$name = an arbitray name for the process.
$eventhandler = the Wx object that will handle events for this process.
$process = Wx::Perl::ProcessStream::Process object
$readmethod = 'getc' or 'readline' (default = 'readline') an optional param. From Wx version
0.75 you can specifiy the method you wish to use to read the output of an
external process. The default depends on your Wx version ( 'getc' < 0.75,
'readline' >= 0.75)
'getc' uses the Wx::InputStream->GetC method to read bytes.
'readline', uses the wxPerl implementation of Wx::InputStream->READLINE.
If the process could not be started then zero is returned.
You should destroy each process after it has completed. You
can do this after receiving the exit event.
GetDefaultAppCloseAction
Returns the default on application close action that will
be given to new processes. When your application exits,
any remaining Wx::Perl::ProcessStream::Process objects will
be signalled to close. The default signal is wxpSIGTERM
but you can change this to wxpSIGKILL if you are sure this
is what you want. Whenever a mew process is opened, it is
given the application close action returned by
GetDefaultAppCloseAction. You can also set the application
close action at an individual process level.
my $def-action = Wx::Perl::ProcessStream->SetDefaultAppCloseAction();
$def-action will be one of wxpSIGTERM or wxpSIGKILL; (default wxpSIGTERM)
SetDefaultAppCloseAction
Sets the default on application close action that will be
given to new processes. See GetDefaultAppCloseAction.
Wx::Perl::ProcessStream->SetDefaultAppCloseAction( $newdefaction );
$newdefaction = one of wxpSIGTERM or wxpSIGKILL
SetDefaultMaxLines
Sets the default maximum number of lines that will be
processed continuously from an individual process. If a
process produces a continuous stream of output, this would
hang your application. This setting provides a maximum
number of lines that will be read from the process streams
before control is yielded and the events can be processed.
Additionally, a EVT_WXP_PROCESS_STREAM_MAXLINES event will
be sent to the eventhandler. The setting can also be set
on an individual process basis using $process->SetMaxLines
Wx::Perl::ProcessStream->SetDefaultMaxLines( $maxlines );
the default maxlines number is 1000
GetPollInterval
Get the current polling interval. See SetPollInterval.
$milliseconds = Wx::Perl::ProcessStream->GetPollInterval();
SetPollInterval
When all buffers are empty but there are still running
external process, the module will pause before polling the
processes again for output. By default, the module waits
for 500 milliseconds. You can set the value of this polling
intrval with this method. Internally, a Wx::Timer object
is used to handle polling and the value you set here is
passed directly to that. The precision of the intervals is
OS dependent.
Wx::Perl::ProcessStream->SetPollInterval( $milliseconds );
$milliseconds = number of milliseconds to wait when no buffer activity
Wx::Perl::ProcessStream::ProcessEvent
A Wx::Perl::ProcessStream::ProcessEvent is sent whenever an external
process started with OpenProcess writes to STDOUT, STDERR or when the
process exits.
Event Connectors
EVT_WXP_PROCESS_STREAM_STDOUT
Install an event handler for an event of type
wxpEVT_PROCESS_STREAM_STDOUT exported on request by this
module. The event subroutine will receive a
Wx::Perl::ProcessStream::ProcessEvent for every line
written to STDOUT by the external process.
EVT_WXP_PROCESS_STREAM_STDOUT( $eventhandler, $codref );
EVT_WXP_PROCESS_STREAM_STDERR
Install an event handler for an event of type
wxpEVT_PROCESS_STREAM_STDERR exported on request by this
module. The event subroutine will receive a
Wx::Perl::ProcessStream::ProcessEvent for every line
written to STDERR by the external process.
EVT_WXP_PROCESS_STREAM_STDERR( $eventhandler, $codref );
EVT_WXP_PROCESS_STREAM_EXIT
Install an event handler for an event of type
wxpEVT_PROCESS_STREAM_EXIT exported on request by this
module. The event subroutine will receive a
Wx::Perl::ProcessStream::ProcessEvent when the external
process exits.
EVT_WXP_PROCESS_STREAM_EXIT( $eventhandler, $codref );
EVT_WXP_PROCESS_STREAM_MAXLINES
Install an event handler for an event of type
wxpEVT_PROCESS_STREAM_MAXLINES exported on request by this
module. The event subroutine will receive a
Wx::Perl::ProcessStream::ProcessEvent when the external
process produces a continuous stream of lines on stderr and
stdout that exceed the max lines set via
$process->SetMaxLines or
Wx::Perl::ProcessStream->SetDefaultMaxLines.
EVT_WXP_PROCESS_STREAM_MAXLINES( $eventhandler, $codref );
Methods
GetLine For events of type wxpEVT_PROCESS_STREAM_STDOUT and
wxpEVT_PROCESS_STREAM_STDERR this will return the line
written by the process.
GetProcess This returns the process that raised the event. If this is
a wxpEVT_PROCESS_STREAM_EXIT event you should destroy the
process with $process->Destroy;
COPYRIGHT & LICENSE
Copyright (C) 2007-2010 Mark Dootson, all rights reserved.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
ACKNOWLEDGEMENTS
Thanks to Johan Vromans for testing and suggesting a better interface.
AUTHOR
Mark Dootson, "<mdootson at cpan.org>"
SEE ALSO
The distribution includes examples in the 'example' folder. From the
source root, run
perl -Ilib example/psexample.pl
You can enter commands, execute them and view results.
You may also wish to consult the wxWidgets manuals for:
Wx::Process
Wx::Execute
Wx::ExecuteArgs
Wx::ExecuteCommand
Wx::ExecuteStdout
Wx::ExecuteStdoutStderr
perl v5.14.1 2011-02-04 Wx::Perl::ProcessStream(3)
