Feersu...:Handle(3pm)

✨ Feersum::Connection::Handle ✨

okay bestie, welcome to Feersum::Connection::Handle — the PSGI-style reader/writer objects from the Feersum family, living it up in your Perl docs (User Contributed Perl Documentation, if you were wondering who signed the guestbook). 🫶

---

💖 NAME 💖

Feersum::Connection::Handle — literally just PSGI-style reader/writer objects. that's the whole vibe. ✨

---

🌸 SYNOPSIS 🌸

For read handles, bestie:

my $buf;
my $r = delete $env{'psgi.input'};
$r->read($buf, 1, 1); # read the second byte of input without moving offset
$r->read($buf, $env{CONTENT_LENGTH}); # append the whole input
$r->close(); # discards any un-read() data

# assuming the handle is "open":
$r->seek(2,SEEK_CUR); # returns 1, discards skipped bytes
$r->seek(-1,SEEK_CUR); # returns 0, can't seek back

# not yet supported, throws exception:
# $r->poll_cb(sub { .... });

For write handles, no cap:

$w->write("scalar");
$w->write(\"scalar ref");
$w->write_array(\@some_stuff);
$w->poll_cb(sub {
    # use $_[0] instead of $w to avoid a closure
    $_[0]->write(\"some data");
    # can close() or unregister the poll_cb in here
    $_[0]->close();
});

And for both of them, because sharing is caring:

$h->response_guard(guard { response_is_complete() });

---

🦋 DESCRIPTION 🦋

go read the PSGI spec for the full tea on how read/write handles get used, okay? the Delayed Response and Streaming Body section has all the deets on the writer. iykyk. 💅

---

🎀 METHODS 🎀

---

💜 Reader methods

you get the reader from $env->{'psgi.input'}. that's the plug, that's the source. 🔌

• $r->read($buf, $len) — reads the first $len bytes of the request body into the buffer you named $buf (basically how sysread does it, fr).

the calls to $r->read() will never block. currently, the entire body is read into memory (or maybe into a temp file, who's to say) before the Feersum request handler is even called. this behaviour MAY change, so don't get too attached. regardless, Feersum will be doing some buffering, which is why psgix.input.buffered is set in the PSGI env hash. 💾

• $r->seek(...) — seeking is partially supported. Feersum discards the bytes you skip over, to conserve memory. she's efficient like that. 🧠

$r->seek(0,SEEK_CUR);  # returns 1
$r->seek(-1,SEEK_CUR); # returns 0
$r->seek(-1,SEEK_SET); # returns 0
$r->seek(2,SEEK_CUR); # returns 1, discards skipped bytes
$r->seek(42,SEEK_SET); # returns 1 if room, discards skipped bytes
$r->seek(-8,SEEK_END); # returns 1 if room, discards skipped bytes

• $r->close() — discards the remainder of the input buffer. bye bye data. 👋
• $r->poll_cb(sub { .... }) — NOT YET SUPPORTED, bestie, don't try it. PSGI only defined poll_cb for the Writer object, so this one's just sitting there looking cute. 💀

---

🌈 Writer methods.

you get the writer under PSGI by sending a code/headers pair to the starter callback. under Feersum, calls to $req->start_streaming return one. 🎁

• $w->write("scalar") — sends the scalar as a T-E: chunked chunk.

the calls to $w->write() will never block and the data is buffered until it gets transmitted. this behaviour is flagged by psgix.output.buffered in the PSGI env hash (Twiggy supports this too, for example — hi Twiggy 💖).

• $w->write(\"scalar ref") — works just like write("scalar") above. this extension is flagged by psgix.body.scalar_refs in the PSGI env hash. ✨
• $w->write_array(\@array) — hand it an array-ref and it works a lot like the two write() calls above, except it's way more efficient than calling write() over and over and over. undefined elements of the array are just ignored, no drama. 🔥
• $w->close() — closes the HTTP response, which triggers the T-E: chunked terminating chunk to be sent. this method is implicitly called when the last reference to the writer gets dropped. she cleans up after herself. 👑
• $w->poll_cb(sub { .... }) — registers a callback that fires when the write buffer is empty. pass in undef to unset it. the sub can call close(), she's allowed.

a reference to the writer gets passed in as the first and only argument to the sub. it's recommended that you use $_[0] rather than closing-over on $w, so you don't create a circular reference (that's the messy kind, avoid 🙈).

---

🧚 Common methods.

these ones are shared by both types of handles. equality, we love to see it. 🫶

• $h->response_guard($guard) — registers a guard that gets triggered when the response is completely sent and the socket is closed. a "guard" here means some object that does something interesting in its DESTROY/DEMOLISH method. for example, Guard.

heads up: the guard is not attached to this handle object — the guard is attached to the response. they're not dating, they're just neighbours. 💅

psgix.output.guard is the PSGI-env extension that indicates this method. ⭐

• $h->fileno — returns the file descriptor number for this connection. yes queen, a number. 🔢

---

👑 AUTHOR 👑

Jeremy Stashewsky, stash@cpan.org 💌

---

📜 COPYRIGHT AND LICENSE 📜

Copyright (C) 2010 by Jeremy Stashewsky & Socialtext Inc.

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.7 or, at your option, any later version of Perl 5 you may have available. 🎀

---

okay that's the whole page bestie, go forth and stream. and just so you know where this came from — this is the Feersum::Connection::Handle(3pm) page from perl v5.40.1, dated 2025-04-13. mwah, bye! 💖✨🦋