Data::TxnBuffer - binary read/write buffer supporting transaction read
use Data::TxnBuffer; # create buffer my $buf = Data::TxnBuffer->new; # or create buffer from some data my $buf = Data::TxnBuffer->new($data); # read some data use Try::Tiny; try { my $u32 = $buf->read_u32; # read unsigned int my $bytes = $buf->read(10); # read 10 bytes $buf->spin; # all data received. clear these data from buffer. } catch { $buf->reset; # reset read cursor. try again later }; # or more easy way. this way automatically call spin or reset method like above. try { $buf->txn_read(sub { my $u32 = $buf->read_u32; # read unsigned int my $bytes = $buf->read(10); # read 10 bytes }); } catch { # try again later }; # write some data to filehandle or buffer $buf->write_u32(100); $buf->write("Hello World"); # got written data my $data = $buf->data; # clear all data from buffer $buf->clear;
Data::TxnBuffer provides some binary buffering functions, such as basic read/write function for buffer, more convenience r/w methods (read_u32/write_u32, etc), and transaction read method.
This module use XS implementation by default, but fallback to ::PP implementation in pure perl environment or PERL_ONLY environment variable is set.
PERL_ONLY
XS implementation is several times faster than PP implementation.
Create a Data::TxnBuffer object. If you passed some $data, create buffer from the data.
$data
Return buffer read cursor point. This value increase by read methods automatically and reset to 0 by reset method.
read
reset
Return buffer's whole data.
Return buffer's data length. (bytes)
Read $bytes data from buffer and return the data. If there's not enough data in buffer, throw exception.
$bytes
Write $data into buffer.
$buf->write('foo'); $buf->write('bar'); my $foo = $buf->read(3); # foo $buf->spin; # clear only foo $buf->data; # == 'bar'
Clear *only* read data from buffer. When read cursor == 0, this method does nothing.
And also, this method returns cleared data. For example $buf->spin in above example returns 'foo';
$buf->spin
Reset read cursor to 0.
Clear all data from buffer.
By combination of read, spin, and reset methods, you can read some data like transaction:
spin
use Try::Tiny; try { my $foo = $buf->read(3); my $bar = $buf->read(3); $buf->spin; # clear read data 'foobar' } catch { $buf->reset; };
read method throw exception if there's not enough data in buffer, catch this exception and reset read cursor, then you can read first data again after some seconds.
Shortcut method for above transaction read example.
use Try::Tiny; try { $buf->txn_read(sub { my $foo = $buf->read(3); my $bar = $buf->read(3); }); # spin automatically called } catch { # reset automatically called # try later };
This method automatically call spin method and returns spin'ed data if all data successfully read, or throw exception not enough data in buffer and call reset method automatically. This method is very useful for typical transaction read functions.
This module provides not only basic read($bytes) method but also useful methods to read integer values easily.
read($bytes)
Read unsigned integers. uXX is bit length. (ex: u32 is 32bit unsigned int)
uXX
Read singed integers.
Write unsigned integers
Write signed integers
(In XS implementation, this is just an alias to write_uXX)
Read/Write unsigned integers in network byte order.
Read/Write floating points (float = 32bit single precision float, double = 64bit double precision float)
Daisuke Murase <typester@cpan.org>
Copyright (c) 2011 by KAYAC Inc.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
The full text of the license can be found in the LICENSE file included with this module.
To install Data::TxnBuffer, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Data::TxnBuffer
CPAN shell
perl -MCPAN -e shell install Data::TxnBuffer
For more information on module installation, please visit the detailed CPAN module installation guide.