ruby-brs 1.1.2 → 1.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f79255ffdaf743bde0edc13c314d1cf7f12402a9993389d6a86dea3d449b4e21
-  data.tar.gz: 8ca40ddca9e58f2876c33bd17bc353bdb739cf79d344ff5bf3c217c52a9cd2ac
+  metadata.gz: f7c98f5678a0545688d9a0bb7537d2eb55507559c2f6d61855796983e4b8a763
+  data.tar.gz: 19bbed82c75ecf25c17a7848b97890dfad5387a3d9244b16db2447bb21425c1b
 SHA512:
-  metadata.gz: 801a6df0e461a1df124647362c10a6af08d0e5621ef5682987d6d0615b548e3fa51d5c184afd804be33cf4da74ce0ef810f8209851f5b5efe31037ac6912f205
-  data.tar.gz: ef62bbc6958e7de16d59eb0a56f84cc9c7ae7f88738219d642562455d7d7815df29cd94fa32da7f23dbf7065310c46e0081e3d0ce0443af8aa5d0257d1a765ba
+  metadata.gz: c7a82e47ac99a515794cc5e56153d10993b5b87fdb9f091dd04a685689dadcee2aec961b2cefbd1fd9531c457cd45af5d0d05af87178642b5bb545fa2f9f9246
+  data.tar.gz: 481e233bfd17fe958a384787b2dd0f469b9017d7005cb9c1b88bdf48cad578767c5003e52b53ce6fcda35635a57339115a6cd21f0768281626df99995ee308ee

data/README.md

@@ -1,8 +1,8 @@
 # Ruby bindings for brotli library
 
-| Travis | AppVeyor | Cirrus | Circle | Codecov |
-| :---:  | :---:    | :---:  | :---:  | :---:   |
-| [![Travis test status](https://travis-ci.com/andrew-aladev/ruby-brs.svg?branch=master)](https://travis-ci.com/andrew-aladev/ruby-brs) | [![AppVeyor test status](https://ci.appveyor.com/api/projects/status/github/andrew-aladev/ruby-brs?branch=master&svg=true)](https://ci.appveyor.com/project/andrew-aladev/ruby-brs/branch/master) | [![Cirrus test status](https://api.cirrus-ci.com/github/andrew-aladev/ruby-brs.svg?branch=master)](https://cirrus-ci.com/github/andrew-aladev/ruby-brs) | [![Circle test status](https://circleci.com/gh/andrew-aladev/ruby-brs/tree/master.svg?style=shield)](https://circleci.com/gh/andrew-aladev/ruby-brs/tree/master) | [![Codecov](https://codecov.io/gh/andrew-aladev/ruby-brs/branch/master/graph/badge.svg)](https://codecov.io/gh/andrew-aladev/ruby-brs) |
+| AppVeyor | Circle | Github actions | Codecov | Gem  |
+| :------: | :----: | :------------: | :-----: | :--: |
+| [![AppVeyor test status](https://ci.appveyor.com/api/projects/status/github/andrew-aladev/ruby-brs?branch=master&svg=true)](https://ci.appveyor.com/project/andrew-aladev/ruby-brs/branch/master) | [![Circle test status](https://circleci.com/gh/andrew-aladev/ruby-brs/tree/master.svg?style=shield)](https://circleci.com/gh/andrew-aladev/ruby-brs/tree/master) | [![Github Actions test status](https://github.com/andrew-aladev/ruby-brs/workflows/test/badge.svg?branch=master)](https://github.com/andrew-aladev/ruby-brs/actions) | [![Codecov](https://codecov.io/gh/andrew-aladev/ruby-brs/branch/master/graph/badge.svg)](https://codecov.io/gh/andrew-aladev/ruby-brs) | [![Gem](https://img.shields.io/gem/v/ruby-brs.svg)](https://rubygems.org/gems/ruby-brs) |
 
 See [brotli library](https://github.com/google/brotli).
 
@@ -21,6 +21,8 @@ rake gem
 gem install pkg/ruby-brs-*.gem
 ```
 
+You can also use [overlay](https://github.com/andrew-aladev/overlay) for gentoo.
+
 ## Usage
 
 There are simple APIs: `String` and `File`. Also you can use generic streaming API: `Stream::Writer` and `Stream::Reader`.
@@ -36,9 +38,30 @@ BRS::File.decompress "file.txt.br", "file.txt"
 
 BRS::Stream::Writer.open("file.txt.br") { |writer| writer << "sample string" }
 puts BRS::Stream::Reader.open("file.txt.br") { |reader| reader.read }
+
+writer = BRS::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 = BRS::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.br` archives with `minitar` for example.
+You can create and read `tar.br` archives with [minitar](https://github.com/halostatue/minitar).
 
 ```ruby
 require "brs"
@@ -60,76 +83,70 @@ BRS::Stream::Reader.open "file.tar.br" do |reader|
 end
 ```
 
-## Options
-
-Each API supports several options:
-
-```
-:source_buffer_length
-:destination_buffer_length
-```
-
-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.
-
-Values: 0 - infinity, default value: 0.
-0 means automatic buffer length selection.
-
-```
-:mode
-```
-
-Values: `BRS::Option::MODES`, default value: `:generic`.
+You can also use `Content-Encoding: br` with [sinatra](http://sinatrarb.com):
 
-```
-:quality
-```
-
-Values: `BRS::Option::MIN_QUALITY` - `BRS::Option::MAX_QUALITY`, default value: `BRS::Option::MAX_QUALITY`.
+```ruby
+require "brs"
+require "sinatra"
 
-```
-:lgwin
+get "/" do
+  headers["Content-Encoding"] = "br"
+  BRS::String.compress "sample string"
+end
 ```
 
-Values: `BRS::Option::MIN_LGWIN` - `BRS::Option::MAX_LGWIN`, default value: `22`.
+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.
 
-```
-:lgblock
-```
-
-Values: `BRS::Option::MIN_LGBLOCK` - `BRS::Option::MAX_LGBLOCK`, default value: none.
+```ruby
+require "brs"
+require "parallel"
 
-```
-:disable_literal_context_modeling
+Parallel.each large_datas do |large_data|
+  BRS::String.compress large_data
+end
 ```
 
-Values: true/false, default value: false.
+## Options
 
-```
-:disable_ring_buffer_reallocation
-```
+| 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 |
+| `mode`                             | `MODES`    | `:generic` | compressor mode |
+| `quality`                          | 0 - 11     | 11         | compression level |
+| `lgwin`                            | 10 - 24    | 22         | compressor window size |
+| `lgblock`                          | 16 - 24    | nil (auto) | compressor input block size |
+| `disable_literal_context_modeling` | true/false | false      | disables literal context modeling format |
+| `disable_ring_buffer_reallocation` | true/false | false      | disables ring buffer reallocation |
+| `size_hint`                        | 0 - inf    | 0 (auto)   | size of input (if known) |
+| `large_window`                     | true/false | false      | enables large window |
 
-Values: true/false, default value: false.
+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`.
 
-```
-:size_hint
-```
+`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.
 
-Values: 0 - infinity, default value: 0.
-It is reasonable to provide size of input (if known) for streaming api.
 `String` and `File` will set `:size_hint` automaticaly.
 
-```
-:large_window
-```
-
-Values: true/false, default value: false.
+You can also read brotli docs for more info about options.
 
-Please read brotli docs for more info about options.
+| Option    | Related constants |
+|-----------|-------------------|
+| `mode`    | `BRS::Option::MODES` = `%i[text font generic]` |
+| `quality` | `BRS::Option::MIN_QUALITY` = 0, `BRS::Option::MAX_QUALITY` = 11 |
+| `lgwin`   | `BRS::Option::MIN_LGWIN` = 10, `BRS::Option::MAX_LGWIN` = 24 |
+| `lgblock` | `BRS::Option::MIN_LGBLOCK` = 16, `BRS::Option::MAX_LGBLOCK` = 24 |
 
 Possible compressor options:
 ```
+:source_buffer_length
+:destination_buffer_length
+:gvl
 :mode
 :quality
 :lgwin
@@ -141,6 +158,9 @@ Possible compressor options:
 
 Possible decompressor options:
 ```
+:source_buffer_length
+:destination_buffer_length
+:gvl
 :disable_ring_buffer_reallocation
 :large_window
 ```
@@ -154,18 +174,6 @@ data = BRS::String.compress "sample string", :quality => 5
 puts BRS::String.decompress(data, :disable_ring_buffer_reallocation => true)
 ```
 
-HTTP encoding (`Content-Encoding: br`) using default options:
-
-```ruby
-require "brs"
-require "sinatra"
-
-get "/" do
-  headers["Content-Encoding"] = "br"
-  BRS::String.compress "sample string"
-end
-```
-
 ## String
 
 String maintains destination buffer only, so it accepts `destination_buffer_length` option only.
@@ -190,7 +198,7 @@ File maintains both source and destination buffers, it accepts both `source_buff
 
 ## Stream::Writer
 
-Its behaviour is similar to builtin [`Zlib::GzipWriter`](https://ruby-doc.org/stdlib-2.7.0/libdoc/zlib/rdoc/Zlib/GzipWriter.html).
+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.
 
@@ -228,7 +236,7 @@ Set another encodings, `nil` is just for compatibility with `IO`.
 #tell
 ```
 
-See [`IO`](https://ruby-doc.org/core-2.7.0/IO.html) docs.
+See [`IO`](https://ruby-doc.org/core/IO.html) docs.
 
 ```
 #write(*objects)
@@ -238,7 +246,7 @@ See [`IO`](https://ruby-doc.org/core-2.7.0/IO.html) docs.
 #closed?
 ```
 
-See [`Zlib::GzipWriter`](https://ruby-doc.org/stdlib-2.7.0/libdoc/zlib/rdoc/Zlib/GzipWriter.html) docs.
+See [`Zlib::GzipWriter`](https://ruby-doc.org/stdlib/libdoc/zlib/rdoc/Zlib/GzipWriter.html) docs.
 
 ```
 #write_nonblock(object, *options)
@@ -252,6 +260,9 @@ Special asynchronous methods missing in `Zlib::GzipWriter`.
 So it is possible to have asynchronous variants for these synchronous methods.
 Behaviour is the same as `IO#write_nonblock` method.
 
+All nonblock operations for file will raise `EBADF` error on Windows.
+Setting file into nonblocking mode is [not available on Windows](https://github.com/ruby/ruby/blob/master/win32/win32.c#L4388).
+
 ```
 #<<(object)
 #print(*objects)
@@ -260,11 +271,11 @@ Behaviour is the same as `IO#write_nonblock` method.
 #puts(*objects)
 ```
 
-Typical helpers, see [`Zlib::GzipWriter`](https://ruby-doc.org/stdlib-2.7.0/libdoc/zlib/rdoc/Zlib/GzipWriter.html) docs.
+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-2.7.0/libdoc/zlib/rdoc/Zlib/GzipReader.html).
+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.
 
@@ -299,7 +310,7 @@ Set another encodings.
 #tell
 ```
 
-See [`IO`](https://ruby-doc.org/core-2.7.0/IO.html) docs.
+See [`IO`](https://ruby-doc.org/core/IO.html) docs.
 
 ```
 #read(bytes_to_read = nil, out_buffer = nil)
@@ -309,14 +320,14 @@ See [`IO`](https://ruby-doc.org/core-2.7.0/IO.html) docs.
 #closed?
 ```
 
-See [`Zlib::GzipReader`](https://ruby-doc.org/stdlib-2.7.0/libdoc/zlib/rdoc/Zlib/GzipReader.html) docs.
+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-2.7.0/IO.html) docs.
+See [`IO`](https://ruby-doc.org/core/IO.html) docs.
 
 ```
 #getbyte
@@ -339,16 +350,26 @@ See [`IO`](https://ruby-doc.org/core-2.7.0/IO.html) docs.
 #ungetline(line)
 ```
 
-Typical helpers, see [`Zlib::GzipReader`](https://ruby-doc.org/stdlib-2.7.0/libdoc/zlib/rdoc/Zlib/GzipReader.html) docs.
+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.
+
+## Operating systems
+
+GNU/Linux, FreeBSD, OSX, Windows (MinGW).
 
 ## CI
 
-See universal test script [scripts/ci_test.sh](scripts/ci_test.sh) for CI.
 Please visit [scripts/test-images](scripts/test-images).
-You can run this test script using many native and cross images.
-
-Cirrus CI uses `x86_64-pc-linux-gnu` image, Circle CI - `x86_64-gentoo-linux-musl` image.
+See universal test script [scripts/ci_test.sh](scripts/ci_test.sh) for CI.
 
 ## License
 
-MIT license, see LICENSE and AUTHORS.
+MIT license, see [LICENSE](LICENSE) and [AUTHORS](AUTHORS).

data/ext/brs_ext/buffer.c

@@ -10,10 +10,11 @@ VALUE brs_ext_create_string_buffer(VALUE length)
   return rb_str_new(NULL, NUM2SIZET(length));
 }
 
-VALUE brs_ext_resize_string_buffer(VALUE args)
+VALUE brs_ext_resize_string_buffer(VALUE buffer_args)
 {
-  VALUE buffer = rb_ary_entry(args, 0);
-  VALUE length = rb_ary_entry(args, 1);
+  VALUE buffer = rb_ary_entry(buffer_args, 0);
+  VALUE length = rb_ary_entry(buffer_args, 1);
+
   return rb_str_resize(buffer, NUM2SIZET(length));
 }
 
@@ -21,8 +22,21 @@ void brs_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(BRS_DEFAULT_SOURCE_BUFFER_LENGTH_FOR_COMPRESSOR));
-  rb_define_const(module, "DEFAULT_DESTINATION_BUFFER_LENGTH_FOR_COMPRESSOR", SIZET2NUM(BRS_DEFAULT_DESTINATION_BUFFER_LENGTH_FOR_COMPRESSOR));
-  rb_define_const(module, "DEFAULT_SOURCE_BUFFER_LENGTH_FOR_DECOMPRESSOR", SIZET2NUM(BRS_DEFAULT_SOURCE_BUFFER_LENGTH_FOR_DECOMPRESSOR));
-  rb_define_const(module, "DEFAULT_DESTINATION_BUFFER_LENGTH_FOR_DECOMPRESSOR", SIZET2NUM(BRS_DEFAULT_DESTINATION_BUFFER_LENGTH_FOR_DECOMPRESSOR));
+  rb_define_const(
+    module, "DEFAULT_SOURCE_BUFFER_LENGTH_FOR_COMPRESSOR", SIZET2NUM(BRS_DEFAULT_SOURCE_BUFFER_LENGTH_FOR_COMPRESSOR));
+
+  rb_define_const(
+    module,
+    "DEFAULT_DESTINATION_BUFFER_LENGTH_FOR_COMPRESSOR",
+    SIZET2NUM(BRS_DEFAULT_DESTINATION_BUFFER_LENGTH_FOR_COMPRESSOR));
+
+  rb_define_const(
+    module,
+    "DEFAULT_SOURCE_BUFFER_LENGTH_FOR_DECOMPRESSOR",
+    SIZET2NUM(BRS_DEFAULT_SOURCE_BUFFER_LENGTH_FOR_DECOMPRESSOR));
+
+  rb_define_const(
+    module,
+    "DEFAULT_DESTINATION_BUFFER_LENGTH_FOR_DECOMPRESSOR",
+    SIZET2NUM(BRS_DEFAULT_DESTINATION_BUFFER_LENGTH_FOR_DECOMPRESSOR));
 }

data/ext/brs_ext/buffer.h

@@ -6,10 +6,10 @@
 
 #include "ruby.h"
 
-#define BRS_DEFAULT_SOURCE_BUFFER_LENGTH_FOR_COMPRESSOR (1 << 18)      // 256 KB
+#define BRS_DEFAULT_SOURCE_BUFFER_LENGTH_FOR_COMPRESSOR      (1 << 18) // 256 KB
 #define BRS_DEFAULT_DESTINATION_BUFFER_LENGTH_FOR_COMPRESSOR (1 << 16) // 64 KB
 
-#define BRS_DEFAULT_SOURCE_BUFFER_LENGTH_FOR_DECOMPRESSOR (1 << 16)      // 64 KB
+#define BRS_DEFAULT_SOURCE_BUFFER_LENGTH_FOR_DECOMPRESSOR      (1 << 16) // 64 KB
 #define BRS_DEFAULT_DESTINATION_BUFFER_LENGTH_FOR_DECOMPRESSOR (1 << 18) // 256 KB
 
 VALUE brs_ext_create_string_buffer(VALUE length);
@@ -17,12 +17,12 @@ VALUE brs_ext_create_string_buffer(VALUE length);
 #define BRS_EXT_CREATE_STRING_BUFFER(buffer, length, exception) \
   VALUE buffer = rb_protect(brs_ext_create_string_buffer, SIZET2NUM(length), &exception);
 
-VALUE brs_ext_resize_string_buffer(VALUE args);
+VALUE brs_ext_resize_string_buffer(VALUE buffer_args);
 
-#define BRS_EXT_RESIZE_STRING_BUFFER(buffer, length, exception)            \
-  VALUE args = rb_ary_new_from_args(2, buffer, SIZET2NUM(length));         \
-  buffer     = rb_protect(brs_ext_resize_string_buffer, args, &exception); \
-  RB_GC_GUARD(args);
+#define BRS_EXT_RESIZE_STRING_BUFFER(buffer, length, exception)                          \
+  VALUE buffer_args = rb_ary_new_from_args(2, buffer, SIZET2NUM(length));                \
+  buffer            = rb_protect(brs_ext_resize_string_buffer, buffer_args, &exception); \
+  RB_GC_GUARD(buffer_args);
 
 void brs_ext_buffer_exports(VALUE root_module);
 

data/ext/brs_ext/error.c

@@ -39,7 +39,7 @@ brs_ext_result_t brs_ext_get_decompressor_error(BrotliDecoderErrorCode error_cod
   }
 }
 
-static inline NORETURN(void raise(const char* name, const char* description))
+static inline NORETURN(void raise_error(const char* name, const char* description))
 {
   VALUE module = rb_define_module(BRS_EXT_MODULE_NAME);
   VALUE error  = rb_const_get(module, rb_intern(name));
@@ -50,28 +50,28 @@ void brs_ext_raise_error(brs_ext_result_t ext_result)
 {
   switch (ext_result) {
     case BRS_EXT_ERROR_ALLOCATE_FAILED:
-      raise("AllocateError", "allocate error");
+      raise_error("AllocateError", "allocate error");
     case BRS_EXT_ERROR_VALIDATE_FAILED:
-      raise("ValidateError", "validate error");
+      raise_error("ValidateError", "validate error");
 
     case BRS_EXT_ERROR_USED_AFTER_CLOSE:
-      raise("UsedAfterCloseError", "used after closed");
+      raise_error("UsedAfterCloseError", "used after closed");
     case BRS_EXT_ERROR_NOT_ENOUGH_SOURCE_BUFFER:
-      raise("NotEnoughSourceBufferError", "not enough source buffer");
+      raise_error("NotEnoughSourceBufferError", "not enough source buffer");
     case BRS_EXT_ERROR_NOT_ENOUGH_DESTINATION_BUFFER:
-      raise("NotEnoughDestinationBufferError", "not enough destination buffer");
+      raise_error("NotEnoughDestinationBufferError", "not enough destination buffer");
     case BRS_EXT_ERROR_DECOMPRESSOR_CORRUPTED_SOURCE:
-      raise("DecompressorCorruptedSourceError", "decompressor received corrupted source");
+      raise_error("DecompressorCorruptedSourceError", "decompressor received corrupted source");
 
     case BRS_EXT_ERROR_ACCESS_IO:
-      raise("AccessIOError", "failed to access IO");
+      raise_error("AccessIOError", "failed to access IO");
     case BRS_EXT_ERROR_READ_IO:
-      raise("ReadIOError", "failed to read IO");
+      raise_error("ReadIOError", "failed to read IO");
     case BRS_EXT_ERROR_WRITE_IO:
-      raise("WriteIOError", "failed to write IO");
+      raise_error("WriteIOError", "failed to write IO");
 
     default:
       // BRS_EXT_ERROR_UNEXPECTED
-      raise("UnexpectedError", "unexpected error");
+      raise_error("UnexpectedError", "unexpected error");
   }
 }

data/ext/brs_ext/error.h

@@ -11,7 +11,8 @@
 
 // Results for errors listed in "lib/brs/error" used in c extension.
 
-enum {
+enum
+{
   BRS_EXT_ERROR_ALLOCATE_FAILED = 1,
   BRS_EXT_ERROR_VALIDATE_FAILED,