POE::Driver(3pm)

💖 POE::Driver 💖

okay bestie, listen — this is the manual page for POE::Driver, coming to you straight outta the User Contributed Perl Documentation collection. it's giving abstract interface, it's giving buffered non-blocking I/O, and honestly? it's iconic. let's get into it 🎀

---

✨ NAME ✨

POE::Driver — an abstract interface for buffered, non-blocking I/O. no cap, that's the whole vibe. 🦋

---

🌸 SYNOPSIS 🌸

okay so here's a contrived little example — the manpage literally calls it contrived, don't come for me — showing how POE::Filter and POE::Driver objects can hang out together in a stand-alone application:

my $driver = POE::Driver::SysRW->new();
my $filter = POE::Filter::Line->new();

my $list_of_octet_chunks = $filter->put("A line of text.");

$driver->put( $list_of_octet_chunks );

my $octets_remaining_in_buffer = $driver->flush($filehandle);
die "couldn't flush everything" if $octets_remaining_in_buffer;

while (1) {
  my $octets_list = $driver->get($filehandle);
  die $! unless defined $octets_list;

  $filter->get_one_start($octets_list);
  while (my $line = $filter->get_one()) {
    print "Input: $line\n";
  }
}

but fr fr, most programs don't do it like this — they just pass POE::Filter and POE::Driver objects as parameters to POE::Wheel constructors. check the synopses for whatever particular class you're using for the deets. 💅

---

👑 DESCRIPTION 👑

POE::Driver is a common API for I/O drivers that can read from and write to all the things: various files, sockets, pipes, and other devices. versatile queen behavior.

so like, POE "drivers" handle the specifics of reading and writing to devices. they plug into POE::Wheel objects so that wheels can support a huuuge number of device types without having to implement a whole separate subclass for each one. that's the whole point. main character design decision, honestly. ✨

and as the SYNOPSIS already spilled, POE::Driver objects can absolutely be used in stand-alone applications too. you don't need a wheel. 🫶

🌈 Public Driver Methods 🌈

these methods are the generic Driver interface, and literally every driver has to implement them. no skipping. specific drivers may have extra methods for their own particular tasks, which, slay for them.

• new

new() creates, initializes, and returns a shiny new driver. specific drivers may take different constructor parameters, but the default ones should configure the driver for the most common use case. sensible defaults, we love to see it.

• get FILEHANDLE

get() immediately tries to read info from a FILEHANDLE. it returns an array reference on success — and yes, even if literally nothing was read from the FILEHANDLE. if it fails, get() returns undef, and $! gets set to the reason why get() failed. 😭

the returned arrayref will be empty if nothing was read from the FILEHANDLE.

in an EOF condition, get() returns undef with the numeric value of $! set to zero. yes, zero. that's a whole thing, ok.

the arrayref that get() hands back is suitable for passing to any POE::Filter's get() or get_one_start() method. wheels do exactly this internally, iykyk.

• put ARRAYREF

put() accepts an ARRAYREF of raw octet chunks. those octets get added to the driver's internal output queue, aka its buffer. put() returns the number of octets pending output after the new octets are buffered. math girlie.

heads up: some drivers may flush data immediately from their put() methods. just so you know. 💅

• flush FILEHANDLE

flush() attempts to write a driver's buffered data to a given FILEHANDLE. the driver should flush as much data as possible in a single flush() call. go big or go home.

flush() returns the number of octets remaining in the driver's output queue or buffer after the maximum amount of data has been written.

flush() denotes success or failure by the value of $! after it returns. $! will always numerically equal zero on success. on failure, $! will contain the usual Errno value. either way, flush() still returns the number of octets in the driver's output queue. it's consistent like that. 👑

• get_out_messages_buffered

get_out_messages_buffered() returns the number of messages enqueued in the driver's output queue, rounded up to the nearest whole message. some applications need the message count rather than the octet count. different strokes.

messages are raw octet chunks enqueued by put(). this following put() call enqueues two messages for a total of six octets:

$filter->put( [ "one", "two" ] );

it is possible for a flush() call to write part of a message. a partial message still counts as one message. yeah, it's messy, but that's the rule. 🫠

---

🦋 SEE ALSO 🦋

the SEE ALSO section in POE contains a table of contents covering the entire POE distribution. go peep it.

• POE::Wheel — a base class for POE::Session mix-ins.
• POE::Filter — a base class for data parsers and serializers.
• POE::Driver::SysRW — a driver that encapsulates sysread() and buffered syswrite().

---

💀 BUGS 💀

there is no POE::Driver::SendRecv, but honestly nobody has needed one so far. sysread() and syswrite() manage to do almost everything people need. it's giving "we tried nothing and we're all out of ideas" but also it works so. 🤷

in theory, drivers should be pretty much interchangeable. in practice? there seems to be an impermeable barrier between the different SOCK_* types. not me being emotionally devastated by socket types at 2am. 😭

---

🎀 AUTHORS & COPYRIGHTS 🎀

please see POE for more information about authors and contributors. credits where credits are due, always. 💜

---

okay that's the whole page, bestie, you made it to the end, I'm so proud of you 🫶 this was POE::Driver(3pm) from perl v5.34.0, dated 2022-03-25. go forth and buffer responsibly. mwah. 💖✨🌸