1POE::Driver::SysRW(3) User Contributed Perl DocumentationPOE::Driver::SysRW(3)
2
6 POE::Driver::SysRW - an abstract sysread/syswrite file driver
7
9 $driver = POE::Driver::SysRW->new();
10 $arrayref_of_data_chunks = $driver->get($filehandle);
11 $queue_octets = $driver->put($arrayref_of_data_chunks);
12 $queue_octets = $driver->flush($filehandle);
13 $queue_messages = $driver->get_out_messages_buffered();
14
16 This driver implements an abstract interface to sysread and syswrite.
17
19 new BlockSize => $block_size
20 new
21 new() creates a new SysRW driver. It accepts one optional named
22 parameter, BlockSize, which indicates the maximum number of octets it
23 will read at a time. For speed, syswrite() tries to send as much
24 information as it can.
25 BlockSize defaults to 65536 if it is omitted. Higher values improve
27 performance in high-throughput applications at the expense of consum‐
28 ing more resident memory. Lower values reduce memory consumption
29 with corresponding throughput penalties.
30 my $driver = POE::Driver::SysRW->new( BlockSize => $block_size );
32 my $driver = POE::Driver::SysRW->new;
34 get FILEHANDLE
36 get() immediately tries to read information from a filehandle. It
37 returns a reference to an array containing whatever it managed to
38 read, or an empty array if nothing could be read. It returns undef
39 on error, and $! will be set.
40 The arrayref get() returns is suitable for passing to any POE::Fil‐
42 ter's get() method. This is exactly what the ReadWrite wheel does
43 with it.
44 put ARRAYREF
46 put() places raw data chunks into the driver's output queue. it
47 accepts a reference to a list of raw data chunks, and it returns the
48 number of octets remaining in its output queue.
49 Some drivers may flush data immediately from their put() methods.
51 flush FILEHANDLE
53 flush() attempts to flush some data from the driver's output queue to
54 the FILEHANDLE. It returns the number of octets remaining in the
55 output queue after the flush attempt.
56 flush() does the physical write, counterpoint to get's read. If
58 flush() fails for any reason, $! will be set with the reason for its
59 failure. Otherwise $! will be zero.
60 get_out_messages_buffered
62 This data accessor returns the number of messages in the driver's
63 output queue. Partial messages are counted as whole ones.
64
66 Driver::SysRW uses a queue of output messages. This means that
67 BLOCK_SIZE is not used for writing. Rather, each message put() through
68 the driver is written in its entirety (or not, if it fails). This
69 often means more syswrite() calls than necessary, however it makes mem‐
70 ory management much easier.
71 If the driver used a scalar buffer for output, it would be necessary to
73 use substr() to remove the beginning of it after it was written. Each
74 substr() call requires the end of the string be moved down to its
75 beginning. That is a lot of memory copying.
76 The buffer could be allowed to grow until it has flushed entirely.
78 This would be eliminate extra memory copies entirely, but it would then
79 be possible to create programs where the buffer was not allowed to
80 shrink at all. That would quickly become bad.
81 Better ideas are welcome.
83
85 POE::Driver.
86 The SEE ALSO section in POE contains a table of contents covering the
88 entire POE distribution.
89
91 Please see POE for more information about authors and contributors.
92perl v5.8.8 2006-09-01 POE::Driver::SysRW(3)