NAME
SYNOPSIS
DESCRIPTION
XS implementation
CLASS METHOD
- my $buf = Data::TxnBuffer->new($data);
ACCESSORS
BASIC METHODS
TRANSACTION READ
- $buf->txn_read($code)
READ/WRITE HELPER METHODS
AUTHOR
COPYRIGHT AND LICENSE

NAME

Data::TxnBuffer - binary read/write buffer supporting transaction read

SYNOPSIS

    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;

DESCRIPTION

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.

XS implementation

This module use XS implementation by default, but fallback to ::PP implementation in pure perl environment or PERL_ONLY environment variable is set.

XS implementation is several times faster than PP implementation.

CLASS METHOD

my $buf = Data::TxnBuffer->new($data);

Create a Data::TxnBuffer object. If you passed some $data, create buffer from the data.

ACCESSORS

$buf->cursor

Return buffer read cursor point. This value increase by read methods automatically and reset to 0 by reset method.

BASIC METHODS

$buf->read($bytes)

Read $bytes data from buffer and return the data. If there's not enough data in buffer, throw exception.

$buf->spin

    $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';

TRANSACTION READ

By combination of read, spin, and reset methods, you can read some data like transaction:

    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.

$buf->txn_read($code)

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.