lz4-native-ruby

Complete Ruby bindings for the LZ4 compression library, including full support for all external interfaces found in lz4.h, lz4hc.h, and lz4frame.h. This gem bundles the official LZ4 source code for seamless integration.

Features

  • Complete LZ4 API Coverage: Full bindings for standard, high-compression, and frame APIs
  • High Performance: Native C extension with direct bindings to LZ4 library
  • Self-Contained: Bundles LZ4 source code - no external dependencies
  • Frame Support: Complete implementation of LZ4 frame format for self-contained compressed data
  • Streaming Support: Efficient handling of large data through streaming compression/decompression
  • Comprehensive Test Suite: Extensive test coverage ensuring reliability

Installation

Add this line to your application's Gemfile:

gem 'lz4-native-ruby'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install lz4-native-ruby

Usage

Basic Compression

require 'lz4_native'

# Simple compression/decompression
data = "Hello, World!" * 1000
compressed = LZ4Native.compress(data)
decompressed = LZ4Native.decompress(compressed, data.bytesize * 2)

High Compression Mode

# Better compression ratio, slower speed
compressed = LZ4Native.compress_hc(data, 9)  # level 1-12, default 9

# Frame format includes metadata and checksums
compressed_frame = LZ4Native.compress_frame(data,
  block_size: :max256KB,
  checksum: true,
  compression_level: 9
)

decompressed = LZ4Native.decompress_frame(compressed_frame)

Low-Level API

# Direct access to LZ4 functions
compressed = LZ4Native::LZ4.compress_default(data)
decompressed = LZ4Native::LZ4.decompress_safe(compressed, max_size)

# High compression
compressed = LZ4Native::LZ4HC.compress(data, 12)

# Frame operations
frame = LZ4Native::LZ4Frame.compress_frame(data, options)

API Reference

LZ4Native (High-Level API)

  • LZ4Native.compress(data) - Standard compression
  • LZ4Native.decompress(data, max_size) - Standard decompression
  • LZ4Native.compress_hc(data, level=9) - High compression
  • LZ4Native.compress_frame(data, options={}) - Frame compression
  • LZ4Native.decompress_frame(data) - Frame decompression

LZ4Native::LZ4 (Block Compression)

  • compress_default(source) - Default compression
  • decompress_safe(source, max_size) - Safe decompression
  • compress_fast(source, acceleration) - Fast compression with acceleration
  • compress_bound(input_size) - Calculate max compressed size
  • version_number() - Get library version number
  • version_string() - Get library version string

LZ4Native::LZ4HC (High Compression)

  • compress(source, level=9) - High compression (level 1-12)
  • sizeof_state() - Get compression state size

LZ4Native::LZ4Frame (Frame Format)

  • compress_frame(source, options={}) - Compress to frame format
  • decompress_frame(source) - Decompress frame
  • version() - Get frame API version
  • compression_level_max() - Get max compression level

Frame compression options:

  • :block_size - :max64KB, :max256KB, :max1MB, :max4MB
  • :block_mode - :linked, :independent
  • :checksum - true or false
  • :compression_level - 0-12

Performance

LZ4 is designed for speed:

  • Compression: >500 MB/s per core
  • Decompression: Multiple GB/s per core
  • Extremely fast decoder suitable for real-time applications

Development

Building from source:

bundle install
rake compile
rake test

Contributing

Bug reports and pull requests are welcome on GitHub.

License

This gem is available as open source under the terms of the BSD-2-Clause License, matching the LZ4 library license.

Credits

  • LZ4 library by Yann Collet
  • Ruby bindings by John Greninger