Wx::Perl::ProcessStream(3pm)

1Wx::Perl::ProcessStreamU(s3e)r Contributed Perl DocumentaWtxi:o:nPerl::ProcessStream(3)
2
3
4

NAME

6       Wx::Perl::ProcessStream - access IO of external processes via events
7

VERSION

9       Version 0.27
10

SYNOPSYS

12           use Wx::Perl::ProcessStream qw( :everything );
13
14           EVT_WXP_PROCESS_STREAM_STDOUT    ( $self, \&evt_process_stdout );
15           EVT_WXP_PROCESS_STREAM_STDERR    ( $self, \&evt_process_stderr );
16           EVT_WXP_PROCESS_STREAM_EXIT      ( $self, \&evt_process_exit   );
17           EVT_WXP_PROCESS_STREAM_MAXLINES  ( $self, \&evt_process_maxlines  );
18
19           my $proc1 = Wx::Perl::ProcessStream::Process->new('perl -e"print qq($_\n) for(@INC);"', 'MyName1', $self);
20           $proc1->Run;
21
22           my $command = 'executable.exe parm1 parm2 parm3'
23           my $proc2 = Wx::Perl::ProcessStream::Process->new($command, 'MyName2', $self)
24                                                       ->Run;
25
26           my @args = qw( executable.exe parm1 parm2 parm3 );
27           my $proc3 = Wx::Perl::ProcessStream::Process->new(\@args, 'MyName2', $self);
28           $proc3->Run;
29
30           my $proc4 = Wx::Perl::ProcessStream::Process->new(\@args, 'MyName2', $self, 'readline')->Run;
31
32           my $proc5 = Wx::Perl::ProcessStream::Process->new(\@args, 'MyName2', $self);
33
34           sub evt_process_stdout {
35               my ($self, $event) = @_;
36               $event->Skip(1);
37               my $process = $event->GetProcess;
38               my $line = $event->GetLine;
39
40               if($line eq 'something we are waiting for') {
41                   $process->WriteProcess('a message to stdin');
42
43                   $process->CloseInput() if($finishedwriting);
44               }
45               ............
46               # To Clear Buffer
47               my @buffers = @{ $process->GetStdOutBuffer };
48
49           }
50
51           sub evt_process_stderr {
52               my ($self, $event) = @_;
53               $event->Skip(1);
54               my $process = $event->GetProcess;
55               my $line = $event->GetLine;
56               print STDERR qq($line\n);
57               # To Clear Buffer
58               my @errors = @{ $process->GetStdErrBuffer };
59           }
60
61           sub evt_process_exit {
62               my ($self, $event) = @_;
63               $event->Skip(1);
64               my $process = $event->GetProcess;
65               my $line = $event->GetLine;
66               my @buffers = @{ $process->GetStdOutBuffer };
67               my @errors = @{ $process->GetStdErrBuffer };
68               my $exitcode = $process->GetExitCode;
69               ............
70               $process->Destroy;
71           }
72
73           sub evt_process_maxlines {
74               my ($self, $event) = @_;
75               my $process = $event->GetProcess;
76
77               ..... bad process
78
79               $process->Kill;
80           }
81

DESCRIPTION

83       This module provides the STDOUT, STDERR and exit codes of
84       asynchronously running processes via events.  It may be used for long
85       running or blocking processes that provide periodic updates on state
86       via STDOUT. Simple IPC is possible via STDIN.
87
88       Do not use this module simply to collect the output of another process.
89       For that, it is much simpler to do:
90
91           my ($status, $output) = Wx::ExecuteStdout( 'perl -e"print qq($_\n) for(@INC);"' );
92
93   Wx::Perl::ProcessStream::Process
94       Methods
95
96       new         Create a new Wx::Perl::ProcessStream::Process object. You
97                   must then use the Run method to execute your command.
98
99                       my $process = Wx::Perl::ProcessStream::Process->new($command, $name, $eventhandler, $readmethod);
100
101                       $command      = command text (and parameters) you wish to run. You may also pass a
102                                       reference to an array containing the command and parameters.
103                       $name         = an arbitray name for the process.
104                       $eventhandler = the Wx EventHandler (Wx:Window) that will handle events for this process.
105                       $readmethod   = 'read' or 'readline' (default = 'readline') an optional param. From Wx version
106                                       0.75 you can specify the method you wish to use to read the output of an
107                                       external process.
108                                       The default depends on your Wx version ( 'getc' < 0.75,'readline' >= 0.75)
109                                       read       -- uses the Wx::InputStream->READ method to read bytes.
110                                       readline   -- uses the Wx::InputStream->READLINE method to read bytes
111                                       getc       -- alias for read (getc not actually used)
112
113       SetMaxLines Set the maximum number of lines that will be read from a
114                   continuous stream before raising a
115                   EVT_WXP_PROCESS_STREAM_MAXLINES event. The default is 1000.
116                   A continuous stream will cause your application to hang.
117
118                       $process->SetMaxLines(10);
119
120       Run         Run the process with the parameters passed to new. On
121                   success, returns the process object itself.  This allows
122                   you to do: my $process =
123                   Wx::Perl::ProcessStream->new($command, $name, $self)->Run;
124                   Returns undef if the process could not be started.
125
126                       my $process = Wx::Perl::ProcessStream::Process->new($command, $name, $eventhandler, $readmethod);
127                       $process->Run;
128
129       CloseInput  Close the STDIN stream of the external process. (Some
130                   processes may not close until STDIN is closed.)
131
132                       $process->CloseInput();
133
134       GetAppCloseAction
135                   Returns the current process signal that will used on
136                   application exit. Either wxpSIGTERM or wxpSIGKILL.  See
137                   SetAppCloseAction.
138
139                       my $action = $process->GetAppCloseAction();
140
141       GetExitCode Returns the process exit code. It is undefined until a
142                   wxpEVT_PROCESS_STREAM_EXIT event has been received.
143
144                       my $exitcode = $process->GetExitCode();
145
146       GetProcessName
147                   Returns the process name as passed to the OpenProcess
148                   constructor.
149
150                       my $processname = $process->GetProcessName();
151
152       GetStdErrBuffer
153                   This returns a reference to an array containing all the
154                   lines sent by the process to stderr.  Calling this clears
155                   the process object internal stderr buffer.  (This has no
156                   effect on the actual process I/O buffers.)
157
158                       my $arryref = $process->GetStdErrBuffer();
159
160       GetStdOutBuffer
161                   This returns a reference to an array containing all the
162                   lines sent by the process to stdout.  Calling this clears
163                   the process object internal stdout buffer.  (This has no
164                   effect on the actual process I/O buffers.)
165
166                       my $arryref = $process->GetStdOutBuffer();
167
168       GetStdErrBufferLineCount
169                   This returns the number of lines currently in the stderr
170                   buffer.
171
172                       my $count = $process->GetStdErrBufferLineCount();
173
174       GetStdOutBufferLineCount
175                   This returns the number of lines currently in the stdout
176                   buffer.
177
178                       my $count = $process->GetStdOutBufferLineCount();
179
180       PeekStdErrBuffer
181                   This returns a reference to an array containing all the
182                   lines sent by the process to stderr.  To retrieve the
183                   buffer and clear it, call GetStdErrBuffer instead.
184
185                       my $arryref = $process->PeekStdErrBuffer();
186
187       PeekStdOutBuffer
188                   This returns a reference to an array containing all the
189                   lines sent by the process to stdout.  To retrieve the
190                   buffer and clear it, call GetStdOutBuffer instead.
191
192                       my $arryref = $process->PeekStdOutBuffer();
193
194       GetProcessId
195                   Returns the process id assigned by the system.
196
197                       my $processid = $process->GetProcessId();
198
199       GetPid      Returns the process id assigned by the system.
200
201                       my $processid = $process->GetPid();
202
203       IsAlive     Check if the process still exists in the system.  Returns 1
204                   if process exists, 0 if process does not exist. If the
205                   process has already signalled its exit, the IsAlive method
206                   will always return 0. Therefore IsAlive should always
207                   return 0 (false) once a EVT_WXP_PROCESS_STREAM_EXIT event
208                   has been sent.
209
210                       my $isalive = $process->IsAlive();
211
212       KillProcess Send a SIGKILL signal to the external process.
213
214                       $process->KillProcess();
215
216       SetAppCloseAction
217                   When your application exits, any remaining
218                   Wx::Perl::ProcessStream::Process objects will be signaled
219                   to close.  The default signal is wxpSIGTERM but you can
220                   change this to wxpSIGKILL if you are sure this is what you
221                   want.
222
223                       $process->SetAppCloseAction( $newaction );
224
225                       $newaction = one of wxpSIGTERM, wxpSIGKILL
226
227       TerminateProcess
228                   Send a SIGTERM signal to the external process.
229
230                       $process->TerminateProcess();
231
232       WriteProcess
233                   Write to the STDIN of process.
234
235                       $process->WriteProcess( $writedata . "\n" );
236
237                       $writedata = The data you wish to write. Remember to add any appropriate line endings your external process may expect.
238
239   Wx::Perl::ProcessStream
240       Methods
241
242       OpenProcess Run an external process. DEPRECATED - use
243                   Wx::Perl::ProcessStream::Process->new()->Run; If the
244                   process is launched successfully, returns a
245                   Wx::Perl::ProcessStream::Process object.  If the process
246                   could not be launched, returns undef;
247
248                       my $process = Wx::Perl::ProcessStream->OpenProcess($command, $name, $eventhandler, $readmethod);
249
250                       $command      = command text (and parameters) you wish to run. You may also pass a
251                                       reference to an array containing the command and parameters.
252                       $name         = an arbitray name for the process.
253                       $eventhandler = the Wx object that will handle events for this process.
254                       $process      = Wx::Perl::ProcessStream::Process object
255                       $readmethod   = 'getc' or 'readline' (default = 'readline') an optional param. From Wx version
256                                       0.75 you can specifiy the method you wish to use to read the output of an
257                                       external process. The default depends on your Wx version ( 'getc' < 0.75,
258                                       'readline' >= 0.75)
259                                       'getc' uses the Wx::InputStream->GetC method to read bytes.
260                                       'readline', uses the wxPerl implementation of Wx::InputStream->READLINE.
261
262                   If the process could not be started then zero is returned.
263                   You should destroy each process after it has completed. You
264                   can do this after receiving the exit event.
265
266       GetDefaultAppCloseAction
267                   Returns the default on application close action that will
268                   be given to new processes.  When your application exits,
269                   any remaining Wx::Perl::ProcessStream::Process objects will
270                   be signalled to close.  The default signal is wxpSIGTERM
271                   but you can change this to wxpSIGKILL if you are sure this
272                   is what you want.  Whenever a mew process is opened, it is
273                   given the application close action returned by
274                   GetDefaultAppCloseAction.  You can also set the application
275                   close action at an individual process level.
276
277                       my $def-action = Wx::Perl::ProcessStream->SetDefaultAppCloseAction();
278
279                       $def-action will be one of wxpSIGTERM or wxpSIGKILL; (default wxpSIGTERM)
280
281       SetDefaultAppCloseAction
282                   Sets the default on application close action that will be
283                   given to new processes.  See GetDefaultAppCloseAction.
284
285                       Wx::Perl::ProcessStream->SetDefaultAppCloseAction( $newdefaction );
286
287                       $newdefaction = one of wxpSIGTERM or wxpSIGKILL
288
289       SetDefaultMaxLines
290                   Sets the default maximum number of lines that will be
291                   processed continuously from an individual process. If a
292                   process produces a continuous stream of output, this would
293                   hang your application. This setting provides a maximum
294                   number of lines that will be read from the process streams
295                   before control is yielded and the events can be processed.
296                   Additionally, a EVT_WXP_PROCESS_STREAM_MAXLINES event will
297                   be sent to the eventhandler.  The setting can also be set
298                   on an individual process basis using $process->SetMaxLines
299
300                       Wx::Perl::ProcessStream->SetDefaultMaxLines( $maxlines );
301
302                       the default maxlines number is 1000
303
304       GetPollInterval
305                   Get the current polling interval. See SetPollInterval.
306
307                       $milliseconds = Wx::Perl::ProcessStream->GetPollInterval();
308
309       SetPollInterval
310                   When all buffers are empty but there are still running
311                   external process, the module will pause before polling the
312                   processes again for output.  By default, the module waits
313                   for 500 milliseconds. You can set the value of this polling
314                   intrval with this method.  Internally, a Wx::Timer object
315                   is used to handle polling and the value you set here is
316                   passed directly to that.  The precision of the intervals is
317                   OS dependent.
318
319                       Wx::Perl::ProcessStream->SetPollInterval( $milliseconds );
320
321                       $milliseconds = number of milliseconds to wait when no buffer activity
322
323   Wx::Perl::ProcessStream::ProcessEvent
324       A Wx::Perl::ProcessStream::ProcessEvent is sent whenever an external
325       process started with OpenProcess writes to STDOUT, STDERR or when the
326       process exits.
327
328       Event Connectors
329
330       EVT_WXP_PROCESS_STREAM_STDOUT
331                   Install an event handler for an event of type
332                   wxpEVT_PROCESS_STREAM_STDOUT exported on request by this
333                   module.  The event subroutine will receive a
334                   Wx::Perl::ProcessStream::ProcessEvent for every line
335                   written to STDOUT by the external process.
336
337                       EVT_WXP_PROCESS_STREAM_STDOUT( $eventhandler, $codref );
338
339       EVT_WXP_PROCESS_STREAM_STDERR
340                   Install an event handler for an event of type
341                   wxpEVT_PROCESS_STREAM_STDERR exported on request by this
342                   module.  The event subroutine will receive a
343                   Wx::Perl::ProcessStream::ProcessEvent for every line
344                   written to STDERR by the external process.
345
346                       EVT_WXP_PROCESS_STREAM_STDERR( $eventhandler, $codref );
347
348       EVT_WXP_PROCESS_STREAM_EXIT
349                   Install an event handler for an event of type
350                   wxpEVT_PROCESS_STREAM_EXIT exported on request by this
351                   module.  The event subroutine will receive a
352                   Wx::Perl::ProcessStream::ProcessEvent when the external
353                   process exits.
354
355                       EVT_WXP_PROCESS_STREAM_EXIT( $eventhandler, $codref );
356
357       EVT_WXP_PROCESS_STREAM_MAXLINES
358                   Install an event handler for an event of type
359                   wxpEVT_PROCESS_STREAM_MAXLINES exported on request by this
360                   module.  The event subroutine will receive a
361                   Wx::Perl::ProcessStream::ProcessEvent when the external
362                   process produces a continuous stream of lines on stderr and
363                   stdout that exceed the max lines set via
364                   $process->SetMaxLines or
365                   Wx::Perl::ProcessStream->SetDefaultMaxLines.
366
367                       EVT_WXP_PROCESS_STREAM_MAXLINES( $eventhandler, $codref );
368
369       Methods
370
371       GetLine     For events of type wxpEVT_PROCESS_STREAM_STDOUT and
372                   wxpEVT_PROCESS_STREAM_STDERR this will return the line
373                   written by the process.
374
375       GetProcess  This returns the process that raised the event. If this is
376                   a wxpEVT_PROCESS_STREAM_EXIT event you should destroy the
377                   process with $process->Destroy;
378

COPYRIGHT & LICENSE

380       Copyright (C) 2007-2010 Mark Dootson, all rights reserved.
381
382       This program is free software; you can redistribute it and/or modify it
383       under the same terms as Perl itself.
384

ACKNOWLEDGEMENTS

386       Thanks to Johan Vromans for testing and suggesting a better interface.
387

AUTHOR

389       Mark Dootson, "<mdootson at cpan.org>"
390