IO::Select(3perl)

📦
version 5.44.0 · 14 versions
, in arch rolling

💖 IO::Select — the select system call, but make it fashion ✨

Okay bestie, listen. This is the manual page for IO::Select, from the Perl Programmers Reference Guide, and it's literally the object-oriented glow-up of the select system call. No cap. Let's get into it. 🫶

✨ NAME ✨

IO::Select — OO interface to the "select" system call 💅

🌸 SYNOPSIS 🌸

use IO::Select;

my $s = IO::Select->new();

$s->add(\*STDIN);
$s->add($some_handle);

my @ready1 = $s->can_read($timeout);

my @ready2 = IO::Select->new(@handles)->can_read(0);

Look at that chaining on the last line, she said one-liner energy. 👑

🦋 DESCRIPTION 🦋

So the "IO::Select" package does the whole object thing to the system "select" function call. Basically it lets you, the user, peek at which IO handles — yes, see IO::Handle — are ready for reading, ready for writing, or have an exception just pending. It's giving waiting-room-but-make-it-useful. 😭

🎀 CONSTRUCTOR 🎀

  • new ( [ HANDLES ] ) — this makes you a brand new object, and if you wanna be extra you can hand it a set of handles right at the start to initialise it. Optional, but cute.

💜 METHODS 💜

  • add ( HANDLES ) — adds that list of handles to your "IO::Select" object. These are the exact values that come back at you when an event happens, so they're kind of the whole point. Now here's the tea: "IO::Select" keeps these in a cache indexed by the "fileno" of the handle, which means if you specify more than one handle with the same "fileno", only the last one gets cached. First one, gone. Sorry babe. 💀

Also, each handle can be an "IO::Handle" object, an integer, or an array reference where the first element is an "IO::Handle" or an integer. Flexible, we love her.

  • remove ( HANDLES ) — yeets all the given handles out of the object. This one also works off the "fileno" of the handles, so like... you don't have to pass back the exact handles you added? Just pass handles with an equivalent "fileno" and she's gone. The vibes-based removal system. 🧚
  • exists ( HANDLE ) — returns a true value (actually, the handle itself, dramatic) if it's present. Otherwise you get undef. It's giving "are you there? no? okay." 🙈
  • handles — hands you back an array of all the registered handles. The whole roster. The full guest list. ⭐
  • can_read ( [ TIMEOUT ] ) — returns an array of handles that are ready for reading. "TIMEOUT" is the max amount of time to wait before returning an empty list (with $! unchanged), measured in seconds, and yes it can be fractional, we're precise like that. If "TIMEOUT" is not given and any handles are registered, the call will block indefinitely — bye bestie, see you whenever. 😴 Upon error, you get an empty list back, with $! set to indicate the error. And to tell timeout apart from error: set $! to zero before you call this method, then check it after an empty list comes back. That's the trick, iykyk. 🔥
  • can_write ( [ TIMEOUT ] ) — same as "can_read" except it checks for handles that can be written to. ✍️
  • has_exception ( [ TIMEOUT ] ) — same as "can_read" except it checks for handles that have an exception condition, for example pending out-of-band data. Main character with baggage. 🚩
  • count () — returns how many handles the object is gonna check for when one of the "can_" methods gets called, or when the object gets passed to the "select" static method. Girl math, but accurate. 🍓
  • bits() — returns the bit string suitable as an argument to the core select() call. Raw. Unpolished. Iconic. ✨
  • select ( READ, WRITE, EXCEPTION [, TIMEOUT ] ) — "select" is a static method, okay, so you call it with the package name, just like "new". "READ", "WRITE" and "EXCEPTION" are either "undef" or "IO::Select" objects. "TIMEOUT" is optional and does the same thing it does for the core select call.

If at least one handle is ready for the kind of operation you asked about, the result is an array of 3 elements — each one a reference to an array holding the handles that are ready for reading, writing, and have exceptions, respectively. So: three groups, three refs, three vibes. 🌈

Upon timeout, an empty list comes back with $! unchanged. Upon error, an empty list comes back with $! set to indicate the error. And literally same deal as before to tell them apart: set $! to zero before calling this method, then check it after an empty list is returned. You got this. 💪

🔥 EXAMPLE 🔥

Okay here's a lil short one showing how "IO::Select" could be used to write a server that talks to several sockets while also listening for more connections on a listen socket. Multi-tasking queen.

use IO::Select;
use IO::Socket;

my $lsn = IO::Socket::INET->new(Listen => 1, LocalPort => 8080);
my $sel = IO::Select->new( $lsn );

while(my @ready = $sel->can_read) {
    foreach my $fh (@ready) {
        if($fh == $lsn) {
            # Create a new socket
            my $new = $lsn->accept;
            $sel->add($new);
        }
        else {
            # Process socket

            # Maybe we have finished with the socket
            $sel->remove($fh);
            $fh->close;
        }
    }
}

👑 AUTHOR 👑

Graham Barr. Currently maintained by the Perl Porters. Please report all bugs at <https://github.com/Perl/perl5/issues>. (They're lovely, be nice. 🫶)

Copyright (c) 1997-8 Graham Barr <gbarr@pobox.com>. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Okay so that's the whole page, no skipped bits, every flag, default, path and caveat accounted for. Slay. 💅

And that's a wrap bestie! This was IO::Select, page 3perl, straight from perl v5.44.0, dated 2026-10-17. Go forth and multiplex. 🌟

📦 where this page comes from