NAME

       POE::Driver - an abstract interface for buffered, non-blocking I/O

SYNOPSIS

       This is a contrived example of how POE::Filter and POE::Driver objects may be used 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";
           }
         }

       Most programs will use POE::Filter and POE::Driver objects as parameters to POE::Wheel
       constructors.  See the synopses for particular classes for details.

DESCRIPTION

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

       POE "drivers" implement the specifics of reading and writing to devices.  Drivers plug
       into POE::Wheel objects so that wheels may support a large number of device types without
       implementing a separate subclass for each.

       As mentioned in the SYNOPSIS, POE::Driver objects may be used in stand-alone applications.

   Public Driver Methods
       These methods are the generic Driver interface, and every driver must implement them.
       Specific drivers may have additional methods related to their particular tasks.

       new

       new() creates, initializes, and returns a new driver.  Specific drivers may have different
       constructor parameters.  The default constructor parameters should configure the driver
       for the most common use case.

       get FILEHANDLE

       get() immediately tries to read information from a FILEHANDLE.  It returns an array
       reference on success---even if nothing was read from the FILEHANDLE.  get() returns undef
       on error, and $! will be 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.

       The arrayref returned by get() is suitable for passing to any POE::Filter's get() or
       get_one_start() method.  Wheels do exactly this internally.

       put ARRAYREF
           put() accepts an ARRAYREF of raw octet chunks.  These octets are added to the driver's
           internal output queue or buffer.  put() returns the number of octets pending output
           after the new octets are buffered.

           Some drivers may flush data immediately from their put() methods.

       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.

           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.  In either case, flush() will return the number of octets in the driver's
           output queue.

       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 require the
           message count rather than the octet count.

           Messages are raw octet chunks enqueued by put().  The 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.

SEE ALSO

       The SEE ALSO section in POE contains a table of contents covering the entire POE
       distribution.

       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 nobody has needed one so far.  sysread() and
       syswrite() manage to do almost everything people need.

       In theory, drivers should be pretty much interchangeable.  In practice, there seems to be
       an impermeable barrier between the different SOCK_* types.

AUTHORS & COPYRIGHTS

       Please see POE for more information about authors and contributors.