Data::BitStream::XS version 0.02
================================

A class providing read/write access to bit streams, implemented in XS for
speed.  It includes many integer coding methods.

Bit streams are often used in data compression and in embedded products where
memory is at a premium.


SYNOPSIS

  use Data::BitStream::XS;
  my $stream = Data::BitStream::XS->new;
  $stream->put_gamma($_) for (1 .. 20);
  $stream->rewind_for_read;
  my @values = $stream->get_gamma(-1);

See the POD module documentation for examples and more information on all the
methods included.


INSTALLATION

To install this module type the following:

   perl Makefile.PL
   make
   make test
   make install


DEPENDENCIES

Perl 5.6.2 or later.  No modules outside of Core have been used.


TESTING

Tested with perl 5.8.0 and 5.14.2 on 32-bit big-endian PA-RISC HP/UX.

Tested with perl 5.6.2, 5.8.9, 5.10.1, 5.12.4, 5.14.2, and 5.15.2
   on 64-bit x86 RHEL6 Linux.

There is currently an issue with some CPAN Testers platforms, mainly Solaris
and AMD.  On those machines, Perl is reporting that it is an LLP64 model:
long is 32-bit and long long is 64-bit, and is compiled with 64-bit support.
However my XS code is reporting LP64 behavior (as expected for Solaris), and
the mismatch seems to be causing havoc.  I've attempted to make this code use
whatever Perl is using, which may or may not fix things.  There may be a
compiler or option mismatch between what was used for Perl and what gets used
to compile our XS class that may still cause problems.


PERFORMANCE

If you're a typical C programmer, then I would say the base C code is reasonably
optimized -- more than Bit::Vector and similar to the Scalar::Vec::Util code,
for instance.  On the other hand, if you're an embedded programmer used to
counting cycles in inner loops, it could certainly use improvement.  People
have very different ideas of what "highly optimized code" means.
  While shaving cycles is crucial for the inner loops on embedded products,
this code is being called from Perl so the main benefit will come from
efficiently getting in and out of the C code.  This class is over 50x faster
than the Pure Perl Mouse class, and over 100x faster than Pure Perl Moo/Moose.

It turns out that for most uses we can get almost all the performance benefit
while still using the Moose/Mouse wrapper for Yummy Perly Goodness.  The
Data::BitStream class will attempt to use this module if it is installed.

Times for encoding/decoding some Gamma codes, in ns per value
  5342ns   7782ns   Data::BitStream::BitVec  (using Bit::Vector)
  2780ns   8072ns   Data::BitStream::WordVec (using Perl vec)
    51ns    166ns   Data::BitStream::BLVec   (using Data::BitStream::XS)
    39ns     88ns   Data::BitStream::XS      (Data::BitStream::XS directly)

Clearly having this module installed is a huge improvement, even if you use
the Data::BitStream class.  The above times are for inserting an array of
values.  Here are timing for one-at-a-time insertion and extraction:
  9038ns  11554ns   Data::BitStream::BitVec  (using Bit::Vector)
  7434ns  11771ns   Data::BitStream::WordVec (using Perl vec)
  5415ns   5770ns   Data::BitStream::BLVec   (using Data::BitStream::XS)
   839ns   1015ns   Data::BitStream::XS      (Data::BitStream::XS directly

showing:
  (1) regardless of implementation, sending or getting multiple values
      spends more time doing work and less time in object code.
  (2) there is still an advantage to having the XS class installed.
  (3) the XS class has less overhead than even the Mouse version of
      Data::BitStream (Mouse being much faster at this than Moo and Moose,
      as of late 2011, due to its XS accessor code).
Reinforcing point #1, note the time difference between this module inserting
values one at a time (839ns / 1015ns) and Mouse Data::BitStream internally
using this module (51ns / 166ns).  Always insert values as a list if it works
for your application.


COPYRIGHT AND LICENCE

Copyright (C) 2011 by Dana Jacobsen <dana@acm.org>

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.