pod::Prima::File(3)

🦋 pod::Prima::File(3) 🦋

okay bestie, so this is the manual page for pod::Prima::File(3) — part of the User Contributed Perl Documentation, and it's literally all about making file handles vibe with your event loop. stay with me, it's actually so good 💅

---

✨ NAME ✨

Prima::File — asynchronous stream I/O ⚡

---

🎀 SYNOPSIS 🎀

like, here's the whole thing in action, no notes:

use strict;
use Prima qw(Application);

# create pipe and autoflush the writer end
pipe(READ, WRITE) or die "pipe():$!\n";
select WRITE;
$|=1;
select STDOUT;

# create a Prima listener on the reader end
my $read = Prima::File-> new(
    file => \*READ,
    mask => fe::Read,
    onRead => sub {
       $_ = <READ>;
       print "read:$_\n";
    },
);

print WRITE "line\n";
run Prima;

iconic behavior, honestly 🫶

---

🌈 DESCRIPTION 🌈

so the Prima::File class is your plug for I/O stream notifications — the ones that fire when a file handle becomes readable, writable, or when an exception / out-of-band message happens. register your file handles with Prima::File objects and suddenly stream operations can coexist with the event loop. it's giving teamwork, fr fr 💖

---

🍓 USAGE 🍓

Prima::File is a descendant of Prima::Component. but heads up — objects of the Prima::File class must be bounded to a valid file handle object before any of the associated events can even happen:

my $f = Prima::File-> create();
$f-> file( *STDIN);

when a file handle bound via the ::file property becomes readable, writable, or when an exception/out-of-band message is signaled, one of three corresponding events gets sent — Read, Write, or Exception. slay 💅

and when the file handle is always readable, or always writable, or — plot twist — you want some of these events blocked instead, you set the file event mask via the ::mask property:

$f-> mask( fe::Read | fe::Exception);

when you don't need the file handle anymore, the expectation is that you detach it from the object explicitly, like so:

$f-> file( undef);

but lowkey, if the system detects the file handle is no longer valid, it auto-detaches for you. want to check if a file handle is still valid? just call the is_active() method. easy 🎀

okay and important detail: Prima::File events are based on the events provided by the select() function on unix, or on the WSAEnumNetworkEvents function on Win32. iykyk ⭐

---

👑 API 👑

💜 Properties 💜

• file HANDLE — picks the file handle to be monitored for the I/O events. if the HANDLE is undef, the object goes back to its passive state and the previously bonded file handle is de-selected.

if the OS reports an error when attaching the file — for example because there are too many objects to monitor — the file handle is reverted to undef. use that to check for an error 👀

• fd INTEGER — same as file(), but for file descriptors instead. note that when this property is used, consequent get-calls to file() will return undef. 🙈

and same deal: if the OS reports an error when attaching the file — for example because there are too many objects to monitor — the file handle is reverted to undef. use that to check for an error.

• mask EVENT_MASK — selects the event mask, which is a combination of the fe::XXX integer constants, each one representing an event:

fe::Read
fe::Write
fe::Exception

the masked events are effectively excluded from the system file event multiplexing mechanism. so like, they're out of the group chat 💀

🧚 Methods 🧚

• get_handle — returns the sprintf("0x%08x", fileno( file )) string. if ::file is undef, then -1 gets used instead of the fileno() result.
• is_active AUTODETACH = 0 — returns the boolean flag indicating whether the file handle is valid. if AUTODETACH is 1 and the file handle is not a valid one, file(undef) gets called. clean 🧼

🔥 Events 🔥

• Read — called when the file handle becomes readable. the callback procedure is expected to call a non-blocking read() on the file handle.
• Write — called when the file handle becomes writable. the callback procedure is expected to call a non-blocking write() on the file handle.
• Exception — called when an exception is signaled on the file handle. these exceptions are specific to the handle type and the operating system. for example, a unix socket may signal the Exception event when control status data for a pseudoterminal or an out-of-band message arrives.

---

🌸 OS considerations 🌸

🐧 Unix 🐧

Prima can monitor a max of FD_SETSIZE file handles — and no, that's not Prima::File objects, those can all refer to the same file handles just fine. see also man 2 select. 📖

🪟 Win32 🪟

💀 Files 💀

if Prima detects the handle is neither a socket nor a console, it assumes it's a regular file. Prima doesn't use any win32 api for checking on regular file handle availability for reading and writing, and therefore sends synthetic events without any actual correlation on whether the file handle is readable or writable. (yeah. that's the vibe. 🙈)

🥤 Pipes 🥤

pipe handles are not implemented and won't work. periodt. 🚫

🔌 Sockets 🔌

sockets work natively, however there's a single catch: according to the MSDN, WSAEventSelect() sets sockets in a non-blocking mode — however, the author couldn't confirm that when experimenting. so if you want to be 100% covered, remember to save and restore the blocking flag in your event handlers. 💯

there can normally be a maximum of 63 sockets (not Prima::File objects — those can refer to the same sockets just fine). or a maximum of 62 sockets if STDIN is monitored too. see also https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-msgwaitformultipleobjectsex 🌈

⌨️ STDIN ⌨️

STDIN works fine when it's a console. use Prima::sys::win32::ReadConsoleInput for detailed input parsing. see also https://learn.microsoft.com/en-us/windows/console/readconsoleinputex. 🫶

---

💖 AUTHOR 💖

Dmitry Karasik, <dmitry@karasik.eu.org>. 👑

---

⭐ SEE ALSO ⭐

Prima, Prima::Object — go read those next, bestie, they're literally right there 🦋

---

and that's the whole page, bestie! huge thank you to the footer for the receipts: this was perl v5.42.0, dated 2024-08-20, filed under pod::Prima::File(3). mwah, go write something asynchronous 💋✨🎀