ndav 0.0.2 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8d1ffc6b4d3e19aa1f6abab6aa9e16c03cb9078c4567fa7451305523d2b5f660
-  data.tar.gz: f4a8be1e3d8981870385e027f4b665fe305858dce2d38119b3222e98a3770bbb
+  metadata.gz: e27d78e17f22830ab47cba80120c7fa3ad3139690dd276e1267abb8696c6ffe3
+  data.tar.gz: 1a3ab5273684a54a5920528663fa5ebcab8ab861213b622b60afe3267ff184e5
 SHA512:
-  metadata.gz: d5acded105c270841b4d107ab8ceaed11624ec4c79cfeeded5039ca9e4336a33d33c9c0a8d5d640a9e841084895a715e914c60e3f16d0e7b7bd64dfa0b2f0447
-  data.tar.gz: ec9c3d18e521385acab9c156cf36e74f2271735759d8ce3b00bb351682187e4900382d01611ebe498e38488be868898969ec48186e7106267105495424e94cd5
+  metadata.gz: 6fe639a15fd780e5add9dcf124f3222214f6dd82cef28e4c16589f0f9dae936dda08e378ed28a3fa9bb810933250caf48bad2a18885a6261685451b3faf14bf0
+  data.tar.gz: 3b3769ce7d12622bd231d0f4bffeb590b631a4c6be42984e2c998c49b64d2c24499bf922744d11b02c27dd308735c8f29d3385c70d5f3753509ce3bd70d4415f

data/.gitignore

@@ -6,3 +6,5 @@ ext/Makefile
 *.o
 *.bundle.dSYM
 pkg/
+doc/
+.yardoc/

data/.gitlab-ci.yml

@@ -12,3 +12,15 @@ test:
       - /root/.local/share/gem/ruby
   script:
     - rake test
+
+pages:
+  stage: deploy
+  image: ruby:4.0
+  script:
+    - bundle exec rake yard
+    - mv doc public
+  artifacts:
+    paths:
+      - public
+  only:
+    - main

data/.yardopts

@@ -0,0 +1,3 @@
+--asset NDAV.png
+-
+LICENSE.txt

data/README.md

@@ -1,9 +1,173 @@
 NDAV - N-Dimensional Array View
 ===============================
 
-Wrapper for MemoryView and pointer.
+[![Gem Version](https://badge.fury.io/rb/ndav.svg)](https://badge.fury.io/rb/ndav)
+
+A thin wrapper around [MemoryView][] ("buffer protocol" for Ruby).
+
+It provides an interoperability layer for multi-dimensional arrays which can be shared between libraries.
+
+![NDAV converts library data each other](./NDAV.png)
+
+SYNOPSIS
+--------
+
+    waveform, sample_rate = TorchAudio.load("path/to/audio.wav")
+    
+    # Convert Torch::Tensor to NDAV
+    # so that you can convert it to OrtValue,
+    # a data format for ONNX Runtime
+    input = waveform
+              .to_ndav
+              .to_ort_value
+    
+    # Make ONNX Runtime return result as OrtValue
+    outputs = OnnxRuntime::Session.new("path/to/model.onnx")
+                .run(
+                  [:output_name],
+                  {input_name: input},
+                  output_type: :ort_value
+                )
+    
+    # You may convert OrtValue to Torch::Tensor via NDAV
+    output_tensor = outputs[0]
+                      .to_ndav
+                      .to_torch_tensor # converts back to Torch::Tensor
+    
+    TorchAudio.save("path/to/output.wav", output_tensor, sample_rate)
+
+ABSTRACT
+--------
+
+NDAV acts as an interoperability layer between multi-dimensional arrays including images, audio and tensors such as [Numo::NArray][], [Torch.rb][]'s `Torch::Tensor`, [ONNX Runtime Ruby][]'s `OnnxRuntime::OrtValue`, [Red Arrow][]'s `Arrow::Array` and so on.
+
+It allows data to be shared without copying.
+
+BACKGROUND
+----------
+
+In the modern Ruby community, [Numo::NArray][] is often used for data conversion. But, data are copied when converting to and from Numo::NArray. In addition, Numo::NArray neither exports nor accepts MemoryView.
+
+[Red Arrow][] is also used and it can export MemoryView from `Arrow::Array` (not from `Arrow::Tensor`, though). It also can be converted to and from Numo::NArray using [Red Arrow Numo::NArray][]. But, in real-world usage, we need, for example, to convert data with many hops:
+
+    Torch::Tensor -> Numo::NArray -> Red Arrow -> MemoryView -> some process...
+
+It might not be difficult, but a little bit cumbersome. Additionally, Red Arrow doesn't accept MemoryView.
+
+USAGE
+-----
+
+`ndav` gem is just a base library. You need to install bridges as well. Say, assume you want to make conversions between Numo::NArray each other.
+
+    require "numo/narray"
+    require "ndav"
+    require "ndav/numo/narray"
+    
+    numo = Numo::SFloat.new(3, 5).seq # => Numo::SFloat
+    ndav = numo.to_ndav               # => NDAV
+    
+    numo = Numo::SFloat.from_ndav(ndav) # => Numo::SFloat
+    ndav = NDAV.from_numo_narray(numo)  # => NDAV
+    
+    include NDAV::Converter
+    numo = NumoNArray(ndav) #=> Numo::SFloat
+    ndav = NDAV(numo)       # => NDAV
+
+For `Torch::Tensor` and `OnnxRuntime::OrtValue`, you can do the same operation, therefore you may convert them to each other, like this:
+
+    numo
+      .to_ndav
+      .to_torch_tensor
+      .then {|torch_tensor| some_process(torch_tensor)}
+      .to_ndav
+      .to_ort_value
+      .then {|ort_value|
+        OnnxRuntime::Session.new("model.onnx")
+          .run(
+            [:output],
+            {input: ort_value},
+            output_type: :ort_value
+          )[0]
+      }
+      .to_ndav
+      .to_torch_tensor
+      .then {|torch_tensor| TorchAudio.save(torch_tensor, sample_rate)}
+
+### Working With MemoryView ###
+
+NDAV can be initialized *directly* from libraries which export [MemoryView][] such as [Red Arrow][], without any bridge library:
+
+    arrow = Arrow::Int16Array.new([1, 2, 3])
+    ndav = NDAV.new(arrow)
+
+On the other hand, it also exports MemoryView. You can pass NDAV arrays *directly* to methods which accept MemoryView such as whispercpp without bridge libraries:
+
+    waveform, sample_rate = TorchAudio.load("path/to/audio.wav")
+    samples = waveform.to_ndav
+    whisper.full(params, samples)
+
+### Notice On Memory Sharing ###
+
+Notice that NDAV is just a memory view and libraries share a memory address. If you change source data destructively, it affects converted data.
+
+Additionally, you potentially encounter odd data corruption or segmentation fault. These might be bugs in bridge libraries such as [ndav-numo-narray][]. As a user, you don't need to worry about this kind of memory management, but it's worth knowing such situations may occur.
+
+INSTALLATION
+------------
+
+    % gem install ndav
+
+or,
+
+    % bundle add ndav
+
+But, you need bridges for real-world use. See each bridge's documentation for individual requirements.
+
+BRIDGES
+-------
+
+There are some bridges using NDAV:
+
+* [ndav/ffi][]: [`FFI::MemoryPointer`][FFI Pointer], [`FFI::Pointer`][FFI Pointer] <-> `NDAV`
+* [ndav-numo-narray][]: [`Numo::NArray`][Numo::NArray] <-> `NDAV`
+* [ndav-ort_value][]: [`OnnxRuntime::OrtValue`][ONNX Runtime Ruby] <-> `NDAV`
+* [ndav-torch-tensor][]: [`Torch::Tensor`][Torch.rb] <-> `NDAV`
+* [onnxruntime-torch-tensor][]: [`Torch::Tensor`][Torch.rb] <-> [`OnnxRuntime::OrtValue`][ONNX Runtime Ruby] via `NDAV`
+
+CREATING BRIDGES
+----------------
+
+Refer to existing bridge implementations listed above to create your bridge.
+
+The points are:
+
+* Implement `FromNDAV#from_ndav`, `ToNDAV#to_ndav` and `NDAV.register` them, and `NDAV.from_your_data` and `NDAV#to_your_data` are automatically derived
+* When initializing NDAV object from your object, use `lifetime` keyword argument for `NDAV.new` effectively to prevent Ruby from GCing your object, which would lead to a dangling pointer
+* When initializing your object from NDAV object, keep NDAV object alive to prevent Ruby from GCing NDAV object, which would lead to a dangling pointer, [ndav-numo-narray][], for instance, embeds the NDAV object in an instance variable
+
+An advantage of NDAV over raw MemoryView is that you can write bridges in pure Ruby in most cases. It helps prototyping and experimentation. As an exception, I had to write C code for ndav-numo-narray because Numo::NArray only provides methods that access data by copying and does not directly expose its raw data pointer to Ruby API. However, in even such case, pure Ruby bridge remains a viable option for prototyping and experiments where a single initial copy is acceptable.
+
+If you are a library author, I want you to consider making your library work with [MemoryView][] instead of creating an NDAV bridge.
+
+FUTURE
+------
+
+If [MemoryView][] gets popular enough in the Ruby ecosystem, this library will end its role and will no longer be needed. I hope such future.
 
 LICENSE
 -------
 
 BSD-2-Clause license. See LICENSE.txt file.
+
+[MemoryView]: https://docs.ruby-lang.org/en/master/contributing/memory_view_md.html
+[Numo::NArray]: https://ruby-numo.github.io/narray/
+[Torch.rb]: https://github.com/ankane/torch.rb
+[ONNX Runtime Ruby]: https://github.com/ankane/onnxruntime-ruby
+[Red Arrow]: https://github.com/apache/arrow/tree/main/ruby
+[Red Arrow Numo::NArray]: https://github.com/red-data-tools/red-arrow-numo-narray
+[ndav/ffi]: https://gitlab.com/KitaitiMakoto/ndav/-/blob/main/lib/ndav/ffi.rb?ref_type=heads
+[FFI Pointer]: https://github.com/ffi/ffi/wiki/Pointers
+[ndav-numo-narray]: https://gitlab.com/KitaitiMakoto/ndav-numo-narray
+[ndav-ort_value]: https://gitlab.com/KitaitiMakoto/ndav-ort_value
+[ndav-torch-tensor]: https://gitlab.com/KitaitiMakoto/ndav-torch-tensor
+[onnxruntime-torch-tensor]: https://gitlab.com/KitaitiMakoto/onnxruntime-torch-tensor

data/Rakefile

@@ -1,18 +1,20 @@
 require "rake/clean"
 require "rake/testtask"
 require "rubygems/tasks"
+require "yard"
 
 DL_NAME = "ndav".ext(RbConfig::CONFIG["DLEXT"])
 DL_BUILD_PATH = File.join("ext", DL_NAME)
 DL_PATH = File.join("lib", DL_NAME)
 
 SRC = FileList["ext/**.{h,c,rb}"]
+CLEAN.include SRC.select {|src| src.end_with?(".o", ".so", ".bundle", ".dll") }
 
 task default: :test
 
 Rake::TestTask.new test: DL_PATH
-tasks = Gem::Tasks.new
-gemspec = tasks.build.gem.project.gemspec
+Gem::Tasks.new
+YARD::Rake::YardocTask.new
 
 file DL_PATH => DL_BUILD_PATH do |t|
   copy t.source, t.name

data/lib/ndav/converter.rb

@@ -3,6 +3,33 @@ class NDAV
     alias from_memory_view new
     alias from_fiddle_memory_view new
     alias from_fiddle_pointer new
+
+    def from_string(str, *, **)
+      new(Fiddle::Pointer[str], *, **)
+    end
+
+    def register(cls, mdl, name:)
+      if mdl.const_defined?(:FromNDAV)
+        cls.extend mdl::FromNDAV
+
+        define_method "to_#{name}" do |*args, **kwargs|
+          cls.from_ndav(self, *args, **kwargs)
+        end
+      end
+
+      if mdl.const_defined?(:ToNDAV)
+        cls.include mdl::ToNDAV
+
+        define_singleton_method "from_#{name}" do |array, *args, **kwargs|
+          array.to_ndav(*args, **kwargs)
+        end
+      end
+
+      if mdl.const_defined?(:Converter)
+        Converter.prepend mdl::Converter
+        Converter.singleton_class.prepend mdl::Converter
+      end
+    end
   end
 
   module Converter

data/lib/ndav/ffi.rb

@@ -18,17 +18,24 @@ class NDAV
       end
 
       module ToNDAV
-        def to_ndav(format: nil, lifetime: nil, **)
-          ::NDAV.from_ffi_memory_pointer(self, shape: [size / type_size], format: format || TYPE_SIZE_TO_FORMAT[type_size], lifetime: lifetime || self, **)
+        def to_ndav(format: TYPE_SIZE_TO_FORMAT[type_size], lifetime: self, **)
+          shape = [size / type_size]
+          byte_size = shape.reduce(ITEM_SIZES[format], :*)
+          ptr = ::Fiddle::Pointer.new(address, byte_size)
+          ::NDAV.new(ptr, shape:, format:, lifetime:, **)
         end
       end
 
       module Converter
-        def NDAV(array, *, **)
-          if array.kind_of? ::FFI::MemoryPointer
-            array.to_ndav(**)
+        def FFIMemoryPointer(array, *, **)
+          if ::FFI::MemoryPointer === array
+            array
+          elsif array.respond_to? :to_ffi_memory_pointer
+            array.to_ffi_memory_pointer(*, **)
+          elsif array.respond_to? :to_ndav
+            array.to_ndav(*, **).to_ffi_memory_pointer
           else
-            super
+            ::NDAV.new(array, *, **).to_ffi_memory_pointer
           end
         end
       end
@@ -41,53 +48,31 @@ class NDAV
         end
       end
 
-      module ToDAV
-        def to_ndav(format: nil, lifetime: nil, **)
-          ::NDAV.from_ffi_pointer(self, shape: [size / type_size], format: format || TYPE_SIZE_TO_FORMAT[type_size], lifetime: lifetime || self, **)
+      module ToNDAV
+        def to_ndav(shape:, format: TYPE_SIZE_TO_FORMAT[type_size], lifetime: self, **)
+          byte_size = shape.reduce(ITEM_SIZES[format], :*)
+          ptr = ::Fiddle::Pointer.new(address, byte_size)
+          ::NDAV.new(ptr, shape:, format:, lifetime:, **)
         end
       end
 
       module Converter
-        def NDAV(array, *, **)
-          # use instance_of? instead of kind_of? because MemoryPointer < Pointer
+        def FFIPointer(array, *, **)
+          # use instance_of? instead of kind_of? beacuase MemoryPointer is subclass of Pointer
           if array.instance_of? ::FFI::Pointer
-            array.to_ndav(**)
+            array
+          elsif array.respond_to? :to_ffi_pointer
+            array.to_ffi_pointer(*, **)
+          elsif array.respond_to? :to_ndav
+            array.to_ndav(*, **).to_ffi_pointer
           else
-            super
+            ::NDAV.new(array, *, **).to_ffi_pointer
           end
         end
       end
     end
 
-    module FromFFI
-      def from_ffi_memory_pointer(array, shape:, format:, **)
-        byte_size = shape.reduce(ITEM_SIZES[format], :*)
-        ptr = ::Fiddle::Pointer.new(array.address, byte_size)
-        new(ptr, shape:, format:, **)
-      end
-
-      def from_ffi_pointer(array, lifetime:, **)
-        from_ffi_memory_pointer(array, lifetime:, **)
-      end
-    end
-
-    module ToFFI
-      def to_ffi_memory_pointer
-        ::FFI::MemoryPointer.from_ndav(self)
-      end
-
-      def to_ffi_pointer
-        ::FFI::Pointer.from_ndav(self)
-      end
-    end
-
-    ::FFI::MemoryPointer.extend MemoryPointer::FromNDAV
-    ::FFI::MemoryPointer.include MemoryPointer::ToNDAV
-    ::FFI::Pointer.extend Pointer::FromNDAV
-    ::FFI::Pointer.include Pointer::ToDAV
-    ::NDAV.extend FromFFI
-    ::NDAV.include ToFFI
-    ::NDAV::Converter.singleton_class.prepend Pointer::Converter
-    ::NDAV::Converter.singleton_class.prepend MemoryPointer::Converter
+    ::NDAV.register ::FFI::MemoryPointer, MemoryPointer, name: :ffi_memory_pointer
+    ::NDAV.register ::FFI::Pointer, Pointer, name: :ffi_pointer
   end
 end

data/ndav.gemspec

@@ -1,10 +1,11 @@
 Gem::Specification.new do |s|
   s.name = "ndav"
-  s.version = "0.0.2"
+  s.version = "0.0.4"
   s.summary = "N-Dimensional Array View"
   s.authors = ["Kitaiti Makoto"]
   s.licenses = ["BSD-2-Clause"]
-  s.homepage = "https://gitlab.com/KitaitiMakoto/ndav"
+  s.homepage = "https://kitaitimakoto.gitlab.io/ndav"
+  s.metadata["source_code_uri"] = "https://gitlab.com/KitaitiMakoto/ndav"
 
   s.files = Dir.chdir(__dir__) {`git ls-files -z`.split("\x0")}
   s.extensions = ["ext/extconf.rb"]
@@ -20,4 +21,5 @@ Gem::Specification.new do |s|
   s.add_development_dependency "rubygems-requirements-system"
   s.add_development_dependency "red-arrow"
   s.add_development_dependency "ffi"
+  s.add_development_dependency "yard"
 end

data/test/test_ffi.rb

@@ -57,6 +57,26 @@ class TestFFI < TestBase
       assert_int_array ndav
     end
 
+    def test_ffi_memory_pointer_from_ndav
+      ndav = ::NDAV.new(Arrow::Int16Array.new([1, 2, 3]))
+
+      assert_instance_of ::FFI::MemoryPointer, ::NDAV::Converter::FFIMemoryPointer(ndav)
+    end
+
+    def test_FFIMemoryPointer
+      c = Class.new {
+        include ::NDAV::Converter
+
+        def to_ffi_memory_pointer(ndav)
+          FFIMemoryPointer(ndav)
+        end
+      }
+
+      ndav = ::NDAV.new(Arrow::Int16Array.new([1, 2, 3]))
+
+      assert_instance_of ::FFI::MemoryPointer, c.new.to_ffi_memory_pointer(ndav)
+    end
+
     def test_ndav_from_ffi_pointer
       str = [1, 2, 3].pack("s*")
       address = ::Fiddle::Pointer[str].to_i
@@ -65,5 +85,25 @@ class TestFFI < TestBase
 
       assert_int_array ndav
     end
+
+    def test_ffi_pointer_from_ndav
+      ndav = ::NDAV.new(Arrow::Int16Array.new([1, 2, 3]))
+
+      assert_instance_of ::FFI::Pointer, ::NDAV::Converter::FFIPointer(ndav)
+    end
+
+    def test_FFIPointer
+      c = Class.new {
+        include ::NDAV::Converter
+
+        def to_ffi_pointer(ndav)
+          FFIPointer(ndav)
+        end
+      }
+
+      ndav = ::NDAV.new(Arrow::Int16Array.new([1, 2, 3]))
+
+      assert_instance_of ::FFI::Pointer, c.new.to_ffi_pointer(ndav)
+    end
   end
 end

data/test/test_ndav.rb

@@ -28,4 +28,11 @@ class TestNDAV < TestBase
     assert_equal ptr, ndav.to_fiddle_pointer
     assert_int_array ndav
   end
+
+  def test_string
+    str = [1, 2, 3].pack("s*")
+    ndav = NDAV.from_string(str, format: "s")
+
+    assert_int_array ndav
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ndav
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.4
 platform: ruby
 authors:
 - Kitaiti Makoto
@@ -149,6 +149,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 executables: []
 extensions:
 - ext/extconf.rb
@@ -156,8 +170,10 @@ extra_rdoc_files: []
 files:
 - ".gitignore"
 - ".gitlab-ci.yml"
+- ".yardopts"
 - Gemfile
 - LICENSE.txt
+- NDAV.png
 - README.md
 - Rakefile
 - ext/extconf.rb
@@ -173,10 +189,11 @@ files:
 - test/test_ffi.rb
 - test/test_ndav.rb
 - test/test_package.rb
-homepage: https://gitlab.com/KitaitiMakoto/ndav
+homepage: https://kitaitimakoto.gitlab.io/ndav
 licenses:
 - BSD-2-Clause
-metadata: {}
+metadata:
+  source_code_uri: https://gitlab.com/KitaitiMakoto/ndav
 rdoc_options: []
 require_paths:
 - lib