=head1 NAME
IO::Mux::Pipe::Read -
read
from an external command
=head1 INHERITANCE
IO::Mux::Pipe::Read
is a IO::Mux::Handler::Read
is a IO::Mux::Handler
=head1 SYNOPSIS
my
$mux
= IO::Mux::Select->new;
my
$pipe
=
$mux
->
open
(
'-|'
,
$command
,
@cmd_options
);
my
$pipe
= IO::Mux::Pipe::Read->new
(
command
=> [
$command
,
@cmd_options
] );
$mux
->add(
$pipe
);
$pipe
->getline(
sub
{
print
"$_[0]\n"
});
=head1 DESCRIPTION
In an event driven program, reading is harder to
use
than writing: the
read
will very probably be stalled
until
data
has
arrived, so you will
need a callback to handle the resulting data.
=head1 METHODS
=head2 Constructors
=over 4
=item IO::Mux::Pipe::Read-E<gt>B<bare>(OPTIONS)
Creates a
pipe
, but does not start a process (yet). Used by
L<IO::Mux::IPC|IO::Mux::IPC>, which needs three pipes
for
one process. Returned
is not only a new
pipe
object, but also a
write
handle to be
connected to the other side.
All OPTIONS which are available to L<IO::Mux::Handler::Read::new()|IO::Mux::Handler::Read/
"Constructors"
>
can be used here as well.
-Option --Default
read_size 4096
=over 2
=item
read_size
=> INTEGER
=back
example:
my
(
$out
,
$out_rh
)
= IO::Mux::Pipe::Read->bare(
name
=>
'stdout'
);
=item IO::Mux::Pipe::Read-E<gt>B<new>(OPTIONS)
-Option --Defined in --Default
command <required>
fh IO::Mux::Handler <required>
name IO::Mux::Handler
'$cmd|'
read_size IO::Mux::Handler::Read 4096
=over 2
=item
command
=> COMMAND|ARRAY
The external command to be executed. Either the COMMAND needs to
parameters, or you need to pass an ARRAY of the command name and
all its parameters.
=item
fh
=> FILEHANDLE
=item
name
=> STRING
=item
read_size
=> INTEGER
=back
=item IO::Mux::Pipe::Read-E<gt>B<
open
>(MODE, (CMD, CMDOPTS)|(CMDARRAY, OPTIONS))
Open the
pipe
to
read
. MODE is always C<< -| >>. When you need to
pass additional OPTIONS to the implied L<new()|IO::Mux::Pipe::Read/
"Constructors"
>, then you must
use
an ARRAY
for
command name and its optional parameters.
example:
my
$mux
= IO::Mux::Poll->new;
$mux
->
open
(
'-|'
,
'who'
,
'-H'
);
$mux
->
open
(
'-|'
, [
'who'
,
'-H'
],
%opts
);
$mux
->
open
(
'-|'
,
'who'
);
$mux
->
open
(
'-|'
, [
'who'
],
%opts
);
=back
=head2 Accessors
=over 4
=item
$obj
-E<gt>B<childPid>
The process id of the child on the other side of the
pipe
.
=item
$obj
-E<gt>B<fh>
See L<IO::Mux::Handler/
"Accessors"
>
=item
$obj
-E<gt>B<
fileno
>
See L<IO::Mux::Handler/
"Accessors"
>
=item
$obj
-E<gt>B<mode>
The bits of the
open
mode.
=item
$obj
-E<gt>B<mux>
See L<IO::Mux::Handler/
"Accessors"
>
=item
$obj
-E<gt>B<name>
See L<IO::Mux::Handler/
"Accessors"
>
=item
$obj
-E<gt>B<readSize>([INTEGER])
See L<IO::Mux::Handler::Read/
"Accessors"
>
=item
$obj
-E<gt>B<usesSSL>
See L<IO::Mux::Handler/
"Accessors"
>
=back
=head2 User interface
=head3 Connection
=over 4
=item
$obj
-E<gt>B<
close
>([CALLBACK])
See L<IO::Mux::Handler/
"Connection"
>
=item
$obj
-E<gt>B<timeout>([TIMEOUT])
See L<IO::Mux::Handler/
"Connection"
>
=back
=head3 Reading
=over 4
=item
$obj
-E<gt>B<
readline
>(CALLBACK)
See L<IO::Mux::Handler::Read/
"Reading"
>
=item
$obj
-E<gt>B<slurp>(CALLBACK)
See L<IO::Mux::Handler::Read/
"Reading"
>
=back
=head2 Multiplexer
=head3 Connection
=over 4
=item
$obj
-E<gt>B<mux_init>(MUX, [HANDLER])
See L<IO::Mux::Handler/
"Connection"
>
=item
$obj
-E<gt>B<mux_remove>
See L<IO::Mux::Handler/
"Connection"
>
=item
$obj
-E<gt>B<mux_timeout>
See L<IO::Mux::Handler/
"Connection"
>
=back
=head3 Reading
=over 4
=item
$obj
-E<gt>B<mux_eof>(INPUT)
See L<IO::Mux::Handler::Read/
"Reading"
>
=item
$obj
-E<gt>B<mux_except_flagged>(FILENO)
See L<IO::Mux::Handler/
"Reading"
>
=item
$obj
-E<gt>B<mux_input>(BUFFER)
See L<IO::Mux::Handler::Read/
"Reading"
>
=item
$obj
-E<gt>B<mux_read_flagged>(FILENO)
See L<IO::Mux::Handler/
"Reading"
>
=back
=head3 Writing
=over 4
=item
$obj
-E<gt>B<mux_write_flagged>(FILENO)
See L<IO::Mux::Handler/
"Writing"
>
=back
=head3 Service
=head2 Helpers
=over 4
=item
$obj
-E<gt>B<extractSocket>(HASH)
=item IO::Mux::Pipe::Read-E<gt>B<extractSocket>(HASH)
See L<IO::Mux::Handler/
"Helpers"
>
=item
$obj
-E<gt>B<fdset>(STATE, READ, WRITE, ERROR)
See L<IO::Mux::Handler/
"Helpers"
>
=item
$obj
-E<gt>B<show>
See L<IO::Mux::Handler/
"Helpers"
>
=back
=head1 SEE ALSO
This module is part of IO-Mux distribution version 0.11,
All modules in this suite:
L</Any::Daemon>,
L</IO::Mux>, and
L</IO::Mux::HTTP>.
Please post questions or ideas to F<perl
@overmeer
.net>
=head1 LICENSE
Copyrights 2011 by Mark Overmeer. For other contributors see ChangeLog.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.