Module: LZ4Native::LZ4Frame

Defined in:

ext/lz4_native/lz4_native.c

Class Method Summary

• .compress_frame(source, options = {}) ⇒ Object

  Compresses data into a complete LZ4 frame (self-contained format).

• .compression_level_max ⇒ Integer

  Returns the maximum compression level supported.

• .decompress_frame(source) ⇒ Object

  Decompresses a complete LZ4 frame.

• .version ⇒ Integer

  Returns the LZ4F API version number.

Class Method Details

.compress_frame(source, options = {}) ⇒ Object

Compresses data into a complete LZ4 frame (self-contained format). Options hash can include:

- block_size: :max64KB, :max256KB, :max1MB, :max4MB (default :max64KB)
- block_mode: :linked, :independent (default :linked)
- checksum: true/false (default false)
- compression_level: 0-12 (default 0 = fast mode)

# File 'ext/lz4_native/lz4_native.c', line 242

static VALUE
lz4frame_compress_frame_wrapper(int argc, VALUE *argv, VALUE self)
{
    VALUE source, options;
    rb_scan_args(argc, argv, "11", &source, &options);

    Check_Type(source, T_STRING);

    const char* src = RSTRING_PTR(source);
    size_t src_size = RSTRING_LEN(source);

    /* Set up preferences */
    LZ4F_preferences_t prefs;
    memset(&prefs, 0, sizeof(prefs));
    prefs.frameInfo.blockSizeID = LZ4F_max64KB;
    prefs.frameInfo.blockMode = LZ4F_blockLinked;
    prefs.frameInfo.contentChecksumFlag = LZ4F_noContentChecksum;
    prefs.compressionLevel = 0;

    /* Parse options if provided */
    if (!NIL_P(options)) {
        Check_Type(options, T_HASH);

        VALUE block_size = rb_hash_aref(options, ID2SYM(rb_intern("block_size")));
        if (!NIL_P(block_size)) {
            ID bs_id = SYM2ID(block_size);
            if (bs_id == rb_intern("max64KB")) prefs.frameInfo.blockSizeID = LZ4F_max64KB;
            else if (bs_id == rb_intern("max256KB")) prefs.frameInfo.blockSizeID = LZ4F_max256KB;
            else if (bs_id == rb_intern("max1MB")) prefs.frameInfo.blockSizeID = LZ4F_max1MB;
            else if (bs_id == rb_intern("max4MB")) prefs.frameInfo.blockSizeID = LZ4F_max4MB;
        }

        VALUE block_mode = rb_hash_aref(options, ID2SYM(rb_intern("block_mode")));
        if (!NIL_P(block_mode)) {
            ID bm_id = SYM2ID(block_mode);
            if (bm_id == rb_intern("linked")) prefs.frameInfo.blockMode = LZ4F_blockLinked;
            else if (bm_id == rb_intern("independent")) prefs.frameInfo.blockMode = LZ4F_blockIndependent;
        }

        VALUE checksum = rb_hash_aref(options, ID2SYM(rb_intern("checksum")));
        if (RTEST(checksum)) {
            prefs.frameInfo.contentChecksumFlag = LZ4F_contentChecksumEnabled;
        }

        VALUE comp_level = rb_hash_aref(options, ID2SYM(rb_intern("compression_level")));
        if (!NIL_P(comp_level)) {
            prefs.compressionLevel = NUM2INT(comp_level);
        }
    }

    size_t dst_capacity = LZ4F_compressFrameBound(src_size, &prefs);
    VALUE result = rb_str_buf_new(dst_capacity);
    char* dst = RSTRING_PTR(result);

    size_t compressed_size = LZ4F_compressFrame(dst, dst_capacity, src, src_size, &prefs);

    if (LZ4F_isError(compressed_size)) {
        rb_raise(eLZ4FrameError, "Frame compression failed: %s",
                 LZ4F_getErrorName(compressed_size));
    }

    rb_str_set_len(result, compressed_size);
    return result;
}

.compression_level_max ⇒ Integer

Returns the maximum compression level supported.

Returns:

• (Integer)

# File 'ext/lz4_native/lz4_native.c', line 395

static VALUE
lz4frame_compression_level_max_wrapper(VALUE self)
{
    return INT2NUM(LZ4F_compressionLevel_max());
}

.decompress_frame(source) ⇒ Object

Decompresses a complete LZ4 frame.

# File 'ext/lz4_native/lz4_native.c', line 313

static VALUE
lz4frame_decompress_frame_wrapper(VALUE self, VALUE source)
{
    Check_Type(source, T_STRING);

    const char* src = RSTRING_PTR(source);
    size_t src_size = RSTRING_LEN(source);

    /* Create decompression context */
    LZ4F_dctx* dctx;
    LZ4F_errorCode_t err = LZ4F_createDecompressionContext(&dctx, LZ4F_VERSION);
    if (LZ4F_isError(err)) {
        rb_raise(eLZ4FrameError, "Failed to create decompression context: %s",
                 LZ4F_getErrorName(err));
    }

    /* Allocate output buffer - start with 4x input size, may need to grow */
    size_t dst_capacity = src_size * 4;
    if (dst_capacity < 1024) dst_capacity = 1024;

    VALUE result = rb_str_buf_new(dst_capacity);
    char* dst = RSTRING_PTR(result);
    size_t total_decompressed = 0;

    size_t src_pos = 0;

    while (src_pos < src_size) {
        size_t src_remaining = src_size - src_pos;
        size_t dst_remaining = dst_capacity - total_decompressed;

        /* Ensure we have space, grow if needed */
        if (dst_remaining < 64 * 1024) {
            dst_capacity *= 2;
            rb_str_resize(result, dst_capacity);
            dst = RSTRING_PTR(result);
            dst_remaining = dst_capacity - total_decompressed;
        }

        size_t ret = LZ4F_decompress(dctx,
                                     dst + total_decompressed, &dst_remaining,
                                     src + src_pos, &src_remaining,
                                     NULL);

        if (LZ4F_isError(ret)) {
            LZ4F_freeDecompressionContext(dctx);
            rb_raise(eLZ4FrameError, "Frame decompression failed: %s",
                     LZ4F_getErrorName(ret));
        }

        src_pos += src_remaining;
        total_decompressed += dst_remaining;

        /* ret == 0 means frame is complete */
        if (ret == 0) {
            break;
        }
    }

    LZ4F_freeDecompressionContext(dctx);

    rb_str_set_len(result, total_decompressed);
    return result;
}

.version ⇒ Integer

Returns the LZ4F API version number.

Returns:

• (Integer)

# File 'ext/lz4_native/lz4_native.c', line 383

static VALUE
lz4frame_version_wrapper(VALUE self)
{
    return INT2NUM(LZ4F_getVersion());
}