IO::Bu...Select(3pm)

💖 IO::BufferedSelect — the manual page, but make it a group chat 💖

okay bestie, so this is the manual page for IO::BufferedSelect(3pm) (yes the header truncates it all cute like IO::Bu...Select(3pm), but we know her full name 💅). Sit down, grab a strawberry 🍓, and let's talk about reading from a whole bunch of filehandles at once without losing your entire mind.

---

✨ NAME ✨

IO::BufferedSelect — Line-buffered select interface. that's it. that's the whole vibe. 🦋

---

✨ SYNOPSIS ✨

here's the moment you've been waiting for, the main character entrance 👑

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";
    }
}

like. it's giving effortless. look at her go. 😌

---

✨ DESCRIPTION ✨

so the select system call (and the IO::Select interface) is the girl who lets you process multiple streams at the same time, blocking until one or more of them is ready for reading or writing. iconic behavior. BUT 🚨 there's a catch, and the catch is that she makes you use sysread and syswrite instead of Perl's buffered I/O functions. rude honestly.

and when we're talking about reading, combining select with readline gives you two whole problems:

1. select might block — but the data we want is already in Perl's input buffer, just sitting there, ready to be slurped in by readline. 😭
2. select might indicate that data is available, but readline will block anyway because there isn't a full $/-terminated line available. 💀

so the whole purpose of this module? it implements a buffered version of the select interface that operates on lines, rather than characters. give her a set of filehandles and she will block until a full line is available on one or more of them. periodt. 🌸

⚠️ and now the fine print, bestie, listen up: 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 ) — creates a BufferedSelect object for a set of filehandles. and here's the important part, no cap: because this class buffers input from these filehandles internally, you should only use the BufferedSelect object for reading from them. do NOT read from them directly, and do NOT pass them to other BufferedSelect instances. she's possessive like that 🙈

---

✨ METHODS ✨

• read_line
• read_line ($timeout)
• read_line ($timeout, @handles)

blocks until a line is available on one of the filehandles. if $timeout is undef, she blocks indefinitely; otherwise, she returns after at most $timeout seconds. ⏳

if @handles is specified, then only these filehandles will be considered; otherwise, she'll use all the filehandles you passed to the constructor. you pick, queen 👑

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. and ngl, "reached EOF" here 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. she finishes what she started. 💅

---

✨ SEE ALSO ✨

• IO::Select — the OG, go say hi 🫶

---

✨ AUTHOR ✨

Antal Novak, <afn@cpan.org> — we love you, icon 💜

---

✨ 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.

---

and that's the whole page, bestie 🎀 perl v5.36.0, dated 2022-11-20, and yes the footer also calls her IO::Bu...Select(3pm) because even the manpage renderer couldn't handle all that name 💀 now go forth and read your lines ✨💖