ruby-bzs 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6d373c300f975749d0d050492c8f9d878fd20094e54570309dc9d1b7a55e71f7
+  data.tar.gz: f9c9ff5fd689912ee06405f3bf66ccdc7947f3b97b5bea470ba801ba3514caca
+SHA512:
+  metadata.gz: b34eec93d12fd7c96463568f21f2d9b21f16f7d005b4f86694d30f637ff147ce6639924ed98ed8142d4991b3af65b61f7c5bfb338b66530dc333bf1fdfb4eabd
+  data.tar.gz: 1eb1a9bb30c926971fdd3aa61d0182f1b894ecc8ae6c0fedc32d0e29f1340e08f5cabec30c81edf6a5253d75271e05bba98e8cf0afd8d3e96d23c07f6a651b23

data/AUTHORS

@@ -0,0 +1 @@
+Andrew Aladjev

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 AUTHORS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,368 @@
+# Ruby bindings for bzip2 library
+
+| AppVeyor | Jenkins | Github actions | Codecov | Gem  |
+| :------: | :-----: | :------------: | :-----: | :--: |
+| [![AppVeyor test status](https://ci.appveyor.com/api/projects/status/github/andrew-aladev/ruby-bzs?branch=main&svg=true)](https://ci.appveyor.com/project/andrew-aladev/ruby-bzs/branch/main) | [![Jenkins test status](http://37.187.122.190:58182/buildStatus/icon?job=ruby-bzs)](http://37.187.122.190:58182/job/ruby-bzs) | [![Github Actions test status](https://github.com/andrew-aladev/ruby-bzs/workflows/test/badge.svg?branch=main)](https://github.com/andrew-aladev/ruby-bzs/actions) | [![Codecov](https://codecov.io/gh/andrew-aladev/ruby-bzs/branch/main/graph/badge.svg)](https://codecov.io/gh/andrew-aladev/ruby-bzs) | [![Gem](https://img.shields.io/gem/v/ruby-bzs.svg)](https://rubygems.org/gems/ruby-bzs) |
+
+See [bzip2 library](https://gitlab.com/bzip2/bzip2).
+
+## Installation
+
+Operating systems: GNU/Linux, FreeBSD, OSX.
+
+Dependencies: [bzip2](https://gitlab.com/bzip2/bzip2) 1.0.0+ version.
+
+| Popular OS | Dependencies              |
+|------------|---------------------------|
+| Ubuntu     | `libbz2-dev`              |
+| CentOS     | `bzip2-devel`             |
+| ArchLinux  | `bzip2`                   |
+| OSX        | `bzip2`                   |
+
+```sh
+gem install ruby-bzs
+```
+
+You can build it from source.
+
+```sh
+rake gem
+gem install pkg/ruby-bzs-*.gem
+```
+
+You can also use [overlay](https://github.com/andrew-aladev/overlay) for gentoo.
+
+### Installation in macOS on Apple Silicon
+
+On M1 Macs, Homebrew installs to /opt/homebrew, so you'll need to specify its
+include and lib paths when building the native extension for bzip2.
+
+```sh
+brew install bzip2
+gem install ruby-bzs -- --with-opt-include=/opt/homebrew/include --with-opt-lib=/opt/homebrew/lib
+```
+
+You can also configure Bundler to use those options when installing:
+
+```sh
+bundle config set build.ruby-bzs "--with-opt-include=/opt/homebrew/include --with-opt-lib=/opt/homebrew/lib"
+```
+
+## Usage
+
+There are simple APIs: `String` and `File`. Also you can use generic streaming API: `Stream::Writer` and `Stream::Reader`.
+
+```ruby
+require "bzs"
+
+data = BZS::String.compress "sample string"
+puts BZS::String.decompress(data)
+
+BZS::File.compress "file.txt", "file.txt.bz2"
+BZS::File.decompress "file.txt.bz2", "file.txt"
+
+BZS::Stream::Writer.open("file.txt.bz2") { |writer| writer << "sample string" }
+puts BZS::Stream::Reader.open("file.txt.bz2") { |reader| reader.read }
+
+writer = BZS::Stream::Writer.new output_socket
+begin
+  bytes_written = writer.write_nonblock "sample string"
+  # handle "bytes_written"
+rescue IO::WaitWritable
+  # handle wait
+ensure
+  writer.close
+end
+
+reader = BZS::Stream::Reader.new input_socket
+begin
+  puts reader.read_nonblock(512)
+rescue IO::WaitReadable
+  # handle wait
+rescue ::EOFError
+  # handle eof
+ensure
+  reader.close
+end
+```
+
+You can create and read `tar.bz2` archives with [minitar](https://github.com/halostatue/minitar).
+
+```ruby
+require "bzs"
+require "minitar"
+
+BZS::Stream::Writer.open "file.tar.bz2" do |writer|
+  Minitar::Writer.open writer do |tar|
+    tar.add_file_simple "file", :data => "sample string"
+  end
+end
+
+BZS::Stream::Reader.open "file.tar.bz2" do |reader|
+  Minitar::Reader.open reader do |tar|
+    tar.each_entry do |entry|
+      puts entry.name
+      puts entry.read
+    end
+  end
+end
+```
+
+All functionality (including streaming) can be used inside multiple threads with [parallel](https://github.com/grosser/parallel).
+This code will provide heavy load for your CPU.
+
+```ruby
+require "bzs"
+require "parallel"
+
+Parallel.each large_datas do |large_data|
+  BZS::String.compress large_data
+end
+```
+
+# Docs
+
+Please review [rdoc generated docs](https://andrew-aladev.github.io/ruby-bzs).
+
+## Options
+
+| Option                          | Values         | Default    | Description |
+|---------------------------------|----------------|------------|-------------|
+| `source_buffer_length`          | 0 - inf        | 0 (auto)   | internal buffer length for source data |
+| `destination_buffer_length`     | 0 - inf        | 0 (auto)   | internal buffer length for description data |
+| `gvl`                           | true/false     | false      | enables global VM lock where possible |
+| `block_size`                    | 1 - 9          | 9          | block size to be used for compression |
+| `work_factor`                   | 0 - 250        | 0          | controls threshold for switching from standard to fallback algorithm |
+| `small`                         | true/false     | true       | enables alternative decompression algorithm with less memory |
+| `quiet`                         | true/false     | false      | disables bzip2 library logging |
+
+There are internal buffers for compressed and decompressed data.
+For example you want to use 1 KB as `source_buffer_length` for compressor - please use 256 B as `destination_buffer_length`.
+You want to use 256 B as `source_buffer_length` for decompressor - please use 1 KB as `destination_buffer_length`.
+
+`gvl` is disabled by default, this mode allows running multiple compressors/decompressors in different threads simultaneously.
+Please consider enabling `gvl` if you don't want to launch processors in separate threads.
+If `gvl` is enabled ruby won't waste time on acquiring/releasing VM lock.
+
+You can also read bzs docs for more info about options.
+
+Possible compressor options:
+```
+:source_buffer_length
+:destination_buffer_length
+:gvl
+:block_size
+:work_factor
+:quiet
+```
+
+Possible decompressor options:
+```
+:source_buffer_length
+:destination_buffer_length
+:gvl
+:small
+:quiet
+```
+
+Example:
+
+```ruby
+require "bzs"
+
+data = BZS::String.compress "sample string", :block_size => 1
+puts BZS::String.decompress(data, :block_size => 1)
+```
+
+## String
+
+String maintains destination buffer only, so it accepts `destination_buffer_length` option only.
+
+```
+::compress(source, options = {})
+::decompress(source, options = {})
+```
+
+`source` is a source string.
+
+## File
+
+File maintains both source and destination buffers, it accepts both `source_buffer_length` and `destination_buffer_length` options.
+
+```
+::compress(source, destination, options = {})
+::decompress(source, destination, options = {})
+```
+
+`source` and `destination` are file pathes.
+
+## Stream::Writer
+
+Its behaviour is similar to builtin [`Zlib::GzipWriter`](https://ruby-doc.org/stdlib/libdoc/zlib/rdoc/Zlib/GzipWriter.html).
+
+Writer maintains destination buffer only, so it accepts `destination_buffer_length` option only.
+
+```
+::open(file_path, options = {}, :external_encoding => nil, :transcode_options => {}, &block)
+```
+
+Open file path and create stream writer associated with opened file.
+Data will be transcoded to `:external_encoding` using `:transcode_options` before compressing.
+
+It may be tricky to use both `:pledged_size` and `:transcode_options`. You have to provide size of transcoded input.
+
+```
+::new(destination_io, options = {}, :external_encoding => nil, :transcode_options => {})
+```
+
+Create stream writer associated with destination io.
+Data will be transcoded to `:external_encoding` using `:transcode_options` before compressing.
+
+It may be tricky to use both `:pledged_size` and `:transcode_options`. You have to provide size of transcoded input.
+
+```
+#set_encoding(external_encoding, nil, transcode_options)
+```
+
+Set another encodings, `nil` is just for compatibility with `IO`.
+
+```
+#io
+#to_io
+#stat
+#external_encoding
+#transcode_options
+#pos
+#tell
+```
+
+See [`IO`](https://ruby-doc.org/core/IO.html) docs.
+
+```
+#write(*objects)
+#flush
+#rewind
+#close
+#closed?
+```
+
+See [`Zlib::GzipWriter`](https://ruby-doc.org/stdlib/libdoc/zlib/rdoc/Zlib/GzipWriter.html) docs.
+
+```
+#write_nonblock(object, *options)
+#flush_nonblock(*options)
+#rewind_nonblock(*options)
+#close_nonblock(*options)
+```
+
+Special asynchronous methods missing in `Zlib::GzipWriter`.
+`rewind` wants to `close`, `close` wants to `write` something and `flush`, `flush` want to `write` something.
+So it is possible to have asynchronous variants for these synchronous methods.
+Behaviour is the same as `IO#write_nonblock` method.
+
+```
+#<<(object)
+#print(*objects)
+#printf(*args)
+#putc(object, :encoding => 'ASCII-8BIT')
+#puts(*objects)
+```
+
+Typical helpers, see [`Zlib::GzipWriter`](https://ruby-doc.org/stdlib/libdoc/zlib/rdoc/Zlib/GzipWriter.html) docs.
+
+## Stream::Reader
+
+Its behaviour is similar to builtin [`Zlib::GzipReader`](https://ruby-doc.org/stdlib/libdoc/zlib/rdoc/Zlib/GzipReader.html).
+
+Reader maintains both source and destination buffers, it accepts both `source_buffer_length` and `destination_buffer_length` options.
+
+```
+::open(file_path, options = {}, :external_encoding => nil, :internal_encoding => nil, :transcode_options => {}, &block)
+```
+
+Open file path and create stream reader associated with opened file.
+Data will be force encoded to `:external_encoding` and transcoded to `:internal_encoding` using `:transcode_options` after decompressing.
+
+```
+::new(source_io, options = {}, :external_encoding => nil, :internal_encoding => nil, :transcode_options => {})
+```
+
+Create stream reader associated with source io.
+Data will be force encoded to `:external_encoding` and transcoded to `:internal_encoding` using `:transcode_options` after decompressing.
+
+```
+#set_encoding(external_encoding, internal_encoding, transcode_options)
+```
+
+Set another encodings.
+
+```
+#io
+#to_io
+#stat
+#external_encoding
+#internal_encoding
+#transcode_options
+#pos
+#tell
+```
+
+See [`IO`](https://ruby-doc.org/core/IO.html) docs.
+
+```
+#read(bytes_to_read = nil, out_buffer = nil)
+#eof?
+#rewind
+#close
+#closed?
+```
+
+See [`Zlib::GzipReader`](https://ruby-doc.org/stdlib/libdoc/zlib/rdoc/Zlib/GzipReader.html) docs.
+
+```
+#readpartial(bytes_to_read = nil, out_buffer = nil)
+#read_nonblock(bytes_to_read, out_buffer = nil, *options)
+```
+
+See [`IO`](https://ruby-doc.org/core/IO.html) docs.
+
+```
+#getbyte
+#each_byte(&block)
+#readbyte
+#ungetbyte(byte)
+
+#getc
+#readchar
+#each_char(&block)
+#ungetc(char)
+
+#lineno
+#lineno=
+#gets(separator = $OUTPUT_RECORD_SEPARATOR, limit = nil)
+#readline
+#readlines
+#each(&block)
+#each_line(&block)
+#ungetline(line)
+```
+
+Typical helpers, see [`Zlib::GzipReader`](https://ruby-doc.org/stdlib/libdoc/zlib/rdoc/Zlib/GzipReader.html) docs.
+
+## Thread safety
+
+`:gvl` option is disabled by default, you can use bindings effectively in multiple threads.
+Please be careful: bindings are not thread safe.
+You should lock all shared data between threads.
+
+For example: you should not use same compressor/decompressor inside multiple threads.
+Please verify that you are using each processor inside single thread at the same time.
+
+## CI
+
+Please visit [scripts/test-images](scripts/test-images).
+See universal test script [scripts/ci_test.sh](scripts/ci_test.sh) for CI.
+
+## License
+
+MIT license, see [LICENSE](LICENSE) and [AUTHORS](AUTHORS).

data/ext/bzs_ext/buffer.c

@@ -0,0 +1,40 @@
+// Ruby bindings for bzip2 library.
+// Copyright (c) 2022 AUTHORS, MIT License.
+
+#include "bzs_ext/buffer.h"
+
+VALUE bzs_ext_create_string_buffer(VALUE length)
+{
+  return rb_str_new(NULL, NUM2SIZET(length));
+}
+
+VALUE bzs_ext_resize_string_buffer(VALUE buffer_args)
+{
+  VALUE buffer = rb_ary_entry(buffer_args, 0);
+  VALUE length = rb_ary_entry(buffer_args, 1);
+
+  return rb_str_resize(buffer, NUM2SIZET(length));
+}
+
+void bzs_ext_buffer_exports(VALUE root_module)
+{
+  VALUE module = rb_define_module_under(root_module, "Buffer");
+
+  rb_define_const(
+    module, "DEFAULT_SOURCE_BUFFER_LENGTH_FOR_COMPRESSOR", SIZET2NUM(BZS_DEFAULT_SOURCE_BUFFER_LENGTH_FOR_COMPRESSOR));
+
+  rb_define_const(
+    module,
+    "DEFAULT_DESTINATION_BUFFER_LENGTH_FOR_COMPRESSOR",
+    SIZET2NUM(BZS_DEFAULT_DESTINATION_BUFFER_LENGTH_FOR_COMPRESSOR));
+
+  rb_define_const(
+    module,
+    "DEFAULT_SOURCE_BUFFER_LENGTH_FOR_DECOMPRESSOR",
+    SIZET2NUM(BZS_DEFAULT_SOURCE_BUFFER_LENGTH_FOR_DECOMPRESSOR));
+
+  rb_define_const(
+    module,
+    "DEFAULT_DESTINATION_BUFFER_LENGTH_FOR_DECOMPRESSOR",
+    SIZET2NUM(BZS_DEFAULT_DESTINATION_BUFFER_LENGTH_FOR_DECOMPRESSOR));
+}

data/ext/bzs_ext/buffer.h

@@ -0,0 +1,29 @@
+// Ruby bindings for bzip2 library.
+// Copyright (c) 2022 AUTHORS, MIT License.
+
+#if !defined(BZS_EXT_BUFFER_H)
+#define BZS_EXT_BUFFER_H
+
+#include "ruby.h"
+
+#define BZS_DEFAULT_SOURCE_BUFFER_LENGTH_FOR_COMPRESSOR      (1 << 18) // 256 KB
+#define BZS_DEFAULT_DESTINATION_BUFFER_LENGTH_FOR_COMPRESSOR (1 << 16) // 64 KB
+
+#define BZS_DEFAULT_SOURCE_BUFFER_LENGTH_FOR_DECOMPRESSOR      (1 << 16) // 64 KB
+#define BZS_DEFAULT_DESTINATION_BUFFER_LENGTH_FOR_DECOMPRESSOR (1 << 18) // 256 KB
+
+VALUE bzs_ext_create_string_buffer(VALUE length);
+
+#define BZS_EXT_CREATE_STRING_BUFFER(buffer, length, exception) \
+  VALUE buffer = rb_protect(bzs_ext_create_string_buffer, SIZET2NUM(length), &exception);
+
+VALUE bzs_ext_resize_string_buffer(VALUE buffer_args);
+
+#define BZS_EXT_RESIZE_STRING_BUFFER(buffer, length, exception)                          \
+  VALUE buffer_args = rb_ary_new_from_args(2, buffer, SIZET2NUM(length));                \
+  buffer            = rb_protect(bzs_ext_resize_string_buffer, buffer_args, &exception); \
+  RB_GC_GUARD(buffer_args);
+
+void bzs_ext_buffer_exports(VALUE root_module);
+
+#endif // BZS_EXT_BUFFER_H

data/ext/bzs_ext/common.h

@@ -0,0 +1,16 @@
+// Ruby bindings for bzip2 library.
+// Copyright (c) 2022 AUTHORS, MIT License.
+
+#if !defined(BZS_EXT_COMMON_H)
+#define BZS_EXT_COMMON_H
+
+#include <stdint.h>
+
+#define BZS_EXT_MODULE_NAME "BZS"
+
+typedef uint_fast8_t bzs_ext_result_t;
+typedef int          bzs_result_t;
+
+typedef uint8_t bzs_ext_byte_t;
+
+#endif // BZS_EXT_COMMON_H

data/ext/bzs_ext/error.c

@@ -0,0 +1,62 @@
+// Ruby bindings for bzip2 library.
+// Copyright (c) 2022 AUTHORS, MIT License.
+
+#include <bzlib.h>
+
+#include "bzs_ext/error.h"
+
+bzs_ext_result_t bzs_ext_get_error(bzs_result_t error_code)
+{
+  switch (error_code) {
+    case BZ_MEM_ERROR:
+      return BZS_EXT_ERROR_ALLOCATE_FAILED;
+    case BZ_PARAM_ERROR:
+      return BZS_EXT_ERROR_VALIDATE_FAILED;
+    case BZ_DATA_ERROR:
+    case BZ_DATA_ERROR_MAGIC:
+    case BZ_UNEXPECTED_EOF:
+      return BZS_EXT_ERROR_DECOMPRESSOR_CORRUPTED_SOURCE;
+    default:
+      return BZS_EXT_ERROR_UNEXPECTED;
+  }
+}
+
+static inline NORETURN(void raise_error(const char* name, const char* description))
+{
+  VALUE module = rb_define_module(BZS_EXT_MODULE_NAME);
+  VALUE error  = rb_const_get(module, rb_intern(name));
+  rb_raise(error, "%s", description);
+}
+
+void bzs_ext_raise_error(bzs_ext_result_t ext_result)
+{
+  switch (ext_result) {
+    case BZS_EXT_ERROR_ALLOCATE_FAILED:
+      raise_error("AllocateError", "allocate error");
+    case BZS_EXT_ERROR_VALIDATE_FAILED:
+      raise_error("ValidateError", "validate error");
+
+    case BZS_EXT_ERROR_USED_AFTER_CLOSE:
+      raise_error("UsedAfterCloseError", "used after closed");
+    case BZS_EXT_ERROR_NOT_ENOUGH_SOURCE_BUFFER:
+      raise_error("NotEnoughSourceBufferError", "not enough source buffer");
+    case BZS_EXT_ERROR_NOT_ENOUGH_DESTINATION_BUFFER:
+      raise_error("NotEnoughDestinationBufferError", "not enough destination buffer");
+    case BZS_EXT_ERROR_DECOMPRESSOR_CORRUPTED_SOURCE:
+      raise_error("DecompressorCorruptedSourceError", "decompressor received corrupted source");
+
+    case BZS_EXT_ERROR_ACCESS_IO:
+      raise_error("AccessIOError", "failed to access IO");
+    case BZS_EXT_ERROR_READ_IO:
+      raise_error("ReadIOError", "failed to read IO");
+    case BZS_EXT_ERROR_WRITE_IO:
+      raise_error("WriteIOError", "failed to write IO");
+
+    case BZS_EXT_ERROR_NOT_IMPLEMENTED:
+      raise_error("NotImplementedError", "not implemented error");
+
+    default:
+      // BZS_EXT_ERROR_UNEXPECTED
+      raise_error("UnexpectedError", "unexpected error");
+  }
+}

data/ext/bzs_ext/error.h

@@ -0,0 +1,34 @@
+// Ruby bindings for bzip2 library.
+// Copyright (c) 2022 AUTHORS, MIT License.
+
+#if !defined(BZS_EXT_ERROR_H)
+#define BZS_EXT_ERROR_H
+
+#include "bzs_ext/common.h"
+#include "ruby.h"
+
+// Results for errors listed in "lib/bzs/error" used in c extension.
+
+enum
+{
+  BZS_EXT_ERROR_ALLOCATE_FAILED = 1,
+  BZS_EXT_ERROR_VALIDATE_FAILED,
+
+  BZS_EXT_ERROR_USED_AFTER_CLOSE,
+  BZS_EXT_ERROR_NOT_ENOUGH_SOURCE_BUFFER,
+  BZS_EXT_ERROR_NOT_ENOUGH_DESTINATION_BUFFER,
+  BZS_EXT_ERROR_DECOMPRESSOR_CORRUPTED_SOURCE,
+
+  BZS_EXT_ERROR_ACCESS_IO,
+  BZS_EXT_ERROR_READ_IO,
+  BZS_EXT_ERROR_WRITE_IO,
+
+  BZS_EXT_ERROR_NOT_IMPLEMENTED,
+  BZS_EXT_ERROR_UNEXPECTED
+};
+
+bzs_ext_result_t bzs_ext_get_error(bzs_result_t error_code);
+
+NORETURN(void bzs_ext_raise_error(bzs_ext_result_t ext_result));
+
+#endif // BZS_EXT_ERROR_H

data/ext/bzs_ext/gvl.h

@@ -0,0 +1,24 @@
+// Ruby bindings for bzip2 library.
+// Copyright (c) 2022 AUTHORS, MIT License.
+
+#if !defined(BZS_EXT_GVL_H)
+#define BZS_EXT_GVL_H
+
+#if defined(HAVE_RB_THREAD_CALL_WITHOUT_GVL)
+
+#include "ruby/thread.h"
+
+#define BZS_EXT_GVL_WRAP(gvl, function, data)                              \
+  if (gvl) {                                                               \
+    function((void*) data);                                                \
+  } else {                                                                 \
+    rb_thread_call_without_gvl(function, (void*) data, RUBY_UBF_IO, NULL); \
+  }
+
+#else
+
+#define BZS_EXT_GVL_WRAP(_gvl, function, data) function((void*) data);
+
+#endif // HAVE_RB_THREAD_CALL_WITHOUT_GVL
+
+#endif // BZS_EXT_GVL_H