NAME

       IO::BufferedSelect - Line-buffered select interface

SYNOPSIS

           use IO::BufferedSelect;
           my $bs = new BufferedSelect($fh1, $fh2);
           while(1)
           {
               my @ready = $bs->read_line();
               foreach(@ready)
               {
                   my ($fh, $line) = @$_;
                   my $fh_name = ($fh == $fh1 ? "fh1" : "fh2");
                   print "$fh_name: $line";
               }
           }

DESCRIPTION

       The "select" system call (and the "IO::Select" interface) allows us to process multiple
       streams simultaneously, blocking until one or more of them is ready for reading or
       writing.  Unfortunately, this requires us to use "sysread" and "syswrite" rather than
       Perl's buffered I/O functions.  In the case of reading, there are two issues with
       combining "select" with "readline": (1) "select" might block but the data we want is
       already in Perl's input buffer, ready to be slurped in by "readline"; and (2) "select"
       might indicate that data is available, but "readline" will block because there isn't a
       full $/-terminated line available.

       The purpose of this module is to implement a buffered version of the "select" interface
       that operates on lines, rather than characters.  Given a set of filehandles, it will block
       until a full line is available on one or more of them.

       Note that this module is currently limited, in that (1) it only does "select" for
       readability, not writability or exceptions; and (2) it does not support arbitrary line
       separators ($/): lines must be delimited by newlines.

CONSTRUCTOR

       new ( HANDLES )
           Create a "BufferedSelect" object for a set of filehandles.  Note that because this
           class buffers input from these filehandles internally, you should only use the
           "BufferedSelect" object for reading from them (you shouldn't read from them directly
           or pass them to other BufferedSelect instances).

METHODS

       read_line
       read_line ($timeout)
       read_line ($timeout, @handles)
           Block until a line is available on one of the filehandles.  If $timeout is "undef", it
           blocks indefinitely; otherwise, it returns after at most $timeout seconds.

           If @handles is specified, then only these filehandles will be considered; otherwise,
           it will use all filehandles passed to the constructor.

           Returns a list of pairs "[$fh, $line]", where $fh is a filehandle and $line is the
           line that was read (including the newline, ala "readline").  If the filehandle reached
           EOF, then $line will be undef.  Note that "reached EOF" is to be interpreted in the
           buffered sense: if a filehandle is at EOF but there are newline-terminated lines in
           "BufferedSelect"'s buffer, "read_line" will continue to return lines until the buffer
           is empty.

SEE ALSO

       IO::Select

AUTHOR

       Antal Novak, <afn@cpan.org>

COPYRIGHT AND LICENSE

       Copyright (C) 2007 by Antal Novak

       This library is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of
       Perl 5 you may have available.