PerlIO...imeout(3pm)

✨ NAME ✨

PerlIO::via::Timeout — bestie, it's a PerlIO layer that adds read & write timeout to a handle 💖

It lives in the PerlIO::via::Timeout package (User Contributed Perl Documentation, if you're keeping track 📚).

---

🌸 VERSION 🌸

version 0.32 — that's the one, no cap.

---

🎀 SYNOPSIS 🎀

use Errno qw(ETIMEDOUT);
use PerlIO::via::Timeout qw(:all);
open my $fh, '<:via(Timeout)', 'foo.html';

# set the timeout layer to be 0.5 second read timeout
read_timeout($fh, 0.5);

my $line = <$fh>;
if ($line == undef && 0+$! == ETIMEDOUT) {
  # timed out
  ...
}

---

💅 DESCRIPTION 💅

okay so this package implements a PerlIO layer, and what it does is add read / write timeout. Lowkey iconic for when you do NOT want to be stuck blocking forever while you're touching a handle (file, socket, ...), and you'd rather it just fail after some time instead of ghosting you. 🫶

The way the timeout actually works: it uses <select> on the handle before reading/writing. That's the whole mechanism, she's simple like that. ✨

⚠️ WARNING — the handle won't timeout if you use sysread or syswrite on it, because these functions work at a lower level. So don't come crying to us. 😭 BUT if you're trying to implement a timeout for a socket, go look at IO::Socket::Timeout, which implements exactly that. 👑

---

🔥 FUNCTIONS 🔥

read_timeout

# set a read timeout of 2.5 seconds
read_timeout($fh, 2.5);
# get the current read timeout
my $secs = read_timeout($fh);

Getter / setter of the read timeout value. That's it, that's the function. 💖

write_timeout

# set a write timeout of 2.5 seconds
write_timeout($fh, 2.5);
# get the current write timeout
my $secs = write_timeout($fh);

Getter / setter of the write timeout value. Matching set, we love symmetry. 🎀

enable_timeout

enable_timeout($fh);

Equivalent to setting timeout_enabled to 1. Turning it ON, slay. ⭐

disable_timeout

disable_timeout($fh);

Equivalent to setting timeout_enabled to 0. Turning it OFF, bye. 🙈

timeout_enabled

# disable timeout
timeout_enabled($fh, 0);
# enable timeout
timeout_enabled($fh, 1);
# get the current status
my $is_enabled = timeout_enabled($fh);

Getter / setter of the timeout enabled flag. The on/off switch of the whole vibe check. 🌈

has_timeout_layer

if (has_timeout_layer($fh)) {
  # set a write timeout of 2.5 seconds
  write_timeout($fh, 2.5);
}

Returns whether the given filehandle is managed by PerlIO::via::Timeout. Basically: is this handle one of ours? 👀

---

💜 SEE ALSO 💜

• PerlIO::via

---

🌸 THANKS TO 🌸

• Vincent Pit
• Christian Hansen
• Leon Timmmermans

(Yes — Timmmermans, with three m's. We copied it exactly, periodt. 📝)

---

👑 AUTHOR 👑

Damien "dams" Krotkine

---

💖 COPYRIGHT AND LICENSE 💖

This software is copyright (c) 2013 by Damien "dams" Krotkine.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

---

and that's a wrap bestie, mwah 💋 this was perl v5.36.0, dated 2022-10-15 — go forth and never block again 🦋✨