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.

perl v5.36.0                                       2022-11-20                            IO::BufferedSelect(3pm)