1POE::Driver(3)        User Contributed Perl Documentation       POE::Driver(3)
2
3
4

NAME

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

SYNOPSIS

9       This is a contrived example of how POE::Filter and POE::Driver objects
10       may be used in a stand-alone application.
11
12         my $driver = POE::Driver::SysRW->new();
13         my $filter = POE::Filter::Line->new();
14
15         my $list_of_octet_chunks = $filter->put("A line of text.");
16
17         $driver->put( $list_of_octet_chunks );
18
19         my $octets_remaining_in_buffer = $driver->flush($filehandle);
20         die "couldn't flush everything" if $octets_remaining_in_buffer;
21
22         while (1) {
23           my $octets_list = $driver->get($filehandle);
24           die $! unless defined $octets_list;
25
26           $filter->get_one_start($octets_list);
27           while (my $line = $filter->get_one()) {
28             print "Input: $line\n";
29           }
30         }
31
32       Most programs will use POE::Filter and POE::Driver objects as
33       parameters to POE::Wheel constructors.  See the synopses for particular
34       classes for details.
35

DESCRIPTION

37       POE::Driver is a common API for I/O drivers that can read from and
38       write to various files, sockets, pipes, and other devices.
39
40       POE "drivers" implement the specifics of reading and writing to
41       devices.  Drivers plug into POE::Wheel objects so that wheels may
42       support a large number of device types without implementing a separate
43       subclass for each.
44
45       As mentioned in the SYNOPSIS, POE::Driver objects may be used in stand-
46       alone applications.
47
48   Public Driver Methods
49       These methods are the generic Driver interface, and every driver must
50       implement them.  Specific drivers may have additional methods related
51       to their particular tasks.
52
53       new
54
55       new() creates, initializes, and returns a new driver.  Specific drivers
56       may have different constructor parameters.  The default constructor
57       parameters should configure the driver for the most common use case.
58
59       get FILEHANDLE
60
61       get() immediately tries to read information from a FILEHANDLE.  It
62       returns an array reference on success---even if nothing was read from
63       the FILEHANDLE.  get() returns undef on error, and $! will be set to
64       the reason why get() failed.
65
66       The returned arrayref will be empty if nothing was read from the
67       FILEHANDLE.
68
69       In an EOF condition, get() returns undef with the numeric value of $!
70       set to zero.
71
72       The arrayref returned by get() is suitable for passing to any
73       POE::Filter's get() or get_one_start() method.  Wheels do exactly this
74       internally.
75
76       put ARRAYREF
77           put() accepts an ARRAYREF of raw octet chunks.  These octets are
78           added to the driver's internal output queue or buffer.  put()
79           returns the number of octets pending output after the new octets
80           are buffered.
81
82           Some drivers may flush data immediately from their put() methods.
83
84       flush FILEHANDLE
85           flush() attempts to write a driver's buffered data to a given
86           FILEHANDLE.  The driver should flush as much data as possible in a
87           single flush() call.
88
89           flush() returns the number of octets remaining in the driver's
90           output queue or buffer after the maximum amount of data has been
91           written.
92
93           flush() denotes success or failure by the value of $! after it
94           returns.  $! will always numerically equal zero on success.  On
95           failure, $! will contain the usual Errno value.  In either case,
96           flush() will return the number of octets in the driver's output
97           queue.
98
99       get_out_messages_buffered
100           get_out_messages_buffered() returns the number of messages enqueued
101           in the driver's output queue, rounded up to the nearest whole
102           message.  Some applications require the message count rather than
103           the octet count.
104
105           Messages are raw octet chunks enqueued by put().  The following
106           put() call enqueues two messages for a total of six octets:
107
108             $filter->put( [ "one", "two" ] );
109
110           It is possible for a flush() call to write part of a message.  A
111           partial message still counts as one message.
112

SEE ALSO

114       The SEE ALSO section in POE contains a table of contents covering the
115       entire POE distribution.
116
117       POE::Wheel - A base class for POE::Session mix-ins.
118
119       POE::Filter - A base class for data parsers and serializers.
120
121       POE::Driver::SysRW - A driver that encapsulates sysread() and buffered
122       syswrite().
123

BUGS

125       There is no POE::Driver::SendRecv, but nobody has needed one so far.
126       sysread() and syswrite() manage to do almost everything people need.
127
128       In theory, drivers should be pretty much interchangeable.  In practice,
129       there seems to be an impermeable barrier between the different SOCK_*
130       types.
131

AUTHORS & COPYRIGHTS

133       Please see POE for more information about authors and contributors.
134
135
136
137perl v5.36.0                      2023-01-20                    POE::Driver(3)