marianopeck / LZ4

This is a binding for LZ4 C library. Notice that the license of LZ4 is BSD. The main goal of this compressor is to be really fast in compressing and uncompressing but not to obtain the biggest compression ratio possible.

Installing instructions

The following are the instructions of how to make LZ4 work in Linux or Mac. I couldn't test it in Windows yet, sorry.

• Get a Pharo image (tested in 1.4 and 2.0).

• Open a terminal (in Linux or Mac) and do:

  svn checkout http://lz4.googlecode.com/svn/trunk/ lz4-read-only
  cd lz4-read-only/
  gcc lz4.c lz4hc.c  \
      -m32 \
      -DHAVE_CONFIG_H \
      -fPIC -O2 -DNDEBUG -shared -static-libgcc \
      -o liblz4.dylib
  

We need to compile and generate a dynamic shared library because LZ4 does not provide it out of the box. It is important the -m32 because otherwise FFI won't work with this library.

• Copy liblz4.dylib to where your .image is.

• Install LZ4 in Pharo:

  Gofer it url: 'http://smalltalkhub.com/mc/marianopeck/LZ4/main'; package: 'ConfigurationOfLZ4'; load. (Smalltalk at: #ConfigurationOfLZ4) perform: #load.

• You need a VM with NativeBoost plugin. You can get it from the archive or from Jenkins.

• Open the image with the VM with NB plugin and run tests from LZ4CompressorTests package. Tests should be green.

Basic usage

The input to compress it a ByteArray and the way to do it is:

LZ4Compressor new compress: aByteArray.

Example:

LZ4Compressor new compress: 'mariano' asByteArray.

To uncompress, the input is also a (compressed) ByteArray:

LZ4Compressor new uncompress: aCompressedByteArray

Example:

| compressed uncompressed |
compressed := LZ4Compressor new compress: 'mariano' asByteArray.
uncompressed := LZ4Compressor new uncompress: compressed.
self assert: 'mariano' asByteArray equals: uncompressed.

For more details see tests in Z4CompressorTests package.

There is also a special (different) compression algorithms that is slower to compress (for uncompressing it is the same speed or even faster than the default) but that brings better compression ratio:

LZ4Compressor new compressHC: aByteArray.

And the uncompress is the same as the one before.

Advanced usage

There is another method:

compress: aByteArray  maxOutputSize: maxOutputSize

That compresses aByteArray but if the results gets bigger than maxOutputSize, it stops and throws an error, for example:

    | compressed byteArray |
    byteArray := 'This should fail because the bytearray cannot be compressed with only 4 bytes' asByteArray.
    self should: [self compress: byteArray maxOutputSize: 4] raise: Error.