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.

  $buf->data
    Return buffer's whole data.

  $buf->length
    Return buffer's data length. (bytes)

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->write($data)
    Write $data into buffer.

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

  $buf->reset
    Reset read cursor to 0.

  $buf->clear
    Clear all data from buffer.

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.

READ/WRITE HELPER METHODS
    This module provides not only basic "read($bytes)" method but also
    useful methods to read integer values easily.

  $buf->read_u32
  $buf->read_u24
  $buf->read_u16
  $buf->read_u8
    Read unsigned integers. "uXX" is bit length. (ex: u32 is 32bit unsigned
    int)

  $buf->read_i32
  $buf->read_i24
  $buf->read_i16
  $buf->read_i8
    Read singed integers.

  $buf->write_u32
  $buf->write_u24
  $buf->write_u16
  $buf->write_u8
    Write unsigned integers

  $buf->write_i32
  $buf->write_i24
  $buf->write_i16
  $buf->write_i8
    Write signed integers

    (In XS implementation, this is just an alias to write_uXX)

  $buf->read_n32
  $buf->read_n24
  $buf->read_n16
  $buf->write_n32
  $buf->write_n24
  $buf->write_n16
    Read/Write unsigned integers in network byte order.

  $buf->read_float
  $buf->read_double
  $buf->write_float
  $buf->write_double
    Read/Write floating points (float = 32bit single precision float, double
    = 64bit double precision float)

AUTHOR
    Daisuke Murase <typester@cpan.org>

COPYRIGHT AND LICENSE
    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.