hyperuuid 0.1.1-x86_64-linux → 0.2.0-x86_64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0e5b3395faa479b95098822f2daabae04fe58fc217b73ccf31091c1524463cb3
-  data.tar.gz: c5ff1e192de7c70e18ccd9490d0f1b6b30392727f9387ec6dc0e3f1a2cbf4d79
+  metadata.gz: f3bdd878a601c1d3fc1fe11cb201fa9afb5716a0da4e37af12489887566559a8
+  data.tar.gz: 51af5963b4b41c2210cf6cbbd00e0a09c735ee9a7ce69b062e8990ae9e6d75a2
 SHA512:
-  metadata.gz: 4826b02473c7af629a659ea70adbcf35f805fae8bff013210d5d2b37709ec2e5f318183abad67a2b3664f98c6496c5f35d8c2160f93d96c17db25dd0d5ef6a57
-  data.tar.gz: 93ff96e2ea5aa847526394fd85a4d6cae50fd06f4760df55cd8469d1462a7e9090386340fd868dc2ed757d33adeb019ca10f6e65b6be9bff03e02632bdc38dbb
+  metadata.gz: '03204299634596b085494434e1f8c2379638a893c7c41228db4de5c4040c9f198150c29709ccba0477d77fcd1d1c41b9cb0f0e038570519312504d2b0e80d7f7'
+  data.tar.gz: 767bbb90f3082d7a1d729c405bbd23684475561578f1b93454b101b82752f3306e1fdfc4fab28ca46c705dc70a3ce6dfe45c4c08e16414b46a6c30f498028937

data/README.md

@@ -63,6 +63,21 @@ timestamp capture and one native call, instead of `count` of each.
 
 The honest trade-off: this gem `dlopen`s a native library instead of being pure Ruby, so it needs a platform-specific `libhyperuuid.so`/`.dylib`/`.dll` bundled alongside it. If plain v4 randomness is all you need, `SecureRandom.uuid` is simpler and already in stdlib — that's a completely reasonable choice.
 
+## Bulk generation into bytes
+
+`new_v6_batch_bytes` and `new_v7_batch_bytes` return the batch as one binary `String` of raw RFC 9562-ordered bytes — 16 per UUID — instead of an Array of `Uuid` objects:
+
+```ruby
+bytes = HyperUuid.new_v7_batch_bytes(1000)
+first = bytes[0, 16]        # ready for a BINARY(16) bind parameter
+```
+
+**About 15x faster than `new_v7_batch`** for a 1000-UUID batch (24 µs versus 370 µs). The native call is identical — the difference is that `new_v7_batch` then allocates 1000 `Uuid` objects and 1000 String slices on top of it. This hands back the bytes the native core already produced, untouched.
+
+The catch, and it inverts the advice: **if you need `Uuid` objects, keep using `new_v7_batch`.** Slicing these bytes into objects yourself just relocates the identical allocations into your own code, and measures no better — sometimes worse. Reach for the byte form only when bytes are the destination: a bind parameter, a wire format, a bulk load.
+
+Slice it with `bytes[i * 16, 16]` — which is exactly what `new_v7_batch` does internally.
+
 ## Benchmarks
 
 Real numbers, `benchmark-ips` on Ruby 4.0.6, linux-arm64 (`ruby benchmark/uuid_benchmark.rb`) — not claimed, measured. With the Magnus backend (the default wherever the extension loads):
@@ -102,9 +117,69 @@ gem install hyperuuid
 
 Published to [RubyGems.org](https://rubygems.org/gems/hyperuuid) as real precompiled
 "platform gems" — `bundle`/`gem install` auto-selects the matching one for
-linux-x64/arm64 or osx-x64/arm64 (the compiled Magnus native extension, `backend: :native`),
-falling back automatically to the universal `ruby`-platform gem (pure Fiddle, zero compile,
-bundles all 6 platforms' native libs) everywhere else — Windows included, since Magnus
-doesn't target it. No extra configuration needed either way.
+linux-x64/arm64, osx-x64/arm64, x64-mingw-ucrt or aarch64-mingw-ucrt (the compiled Magnus
+native extension, `backend: :native`), falling back automatically to the universal
+`ruby`-platform gem (pure Fiddle, zero compile, bundles all 6 platforms' native libs)
+everywhere else. No extra configuration needed either way.
+
+Selection has **two** axes here, unlike every other binding in this repo. A Magnus extension
+is bound to one Ruby minor ABI — there's no `abi3` equivalent to collapse the version axis the
+way [the Python binding's](../python/) wheels do — so each platform gem is a "fat" gem
+carrying one compiled extension per supported Ruby, under `lib/hyperuuid/<minor>/`, and picks
+one at `require` time:
+
+| Ruby | linux-x64/arm64, osx-x64/arm64, x64-mingw-ucrt, aarch64-mingw-ucrt | anywhere else (musl/Alpine, …) |
+| --- | --- | --- |
+| 4.0 (primary) | Magnus, `backend: :native` | Fiddle |
+| 3.4 (floor, until its EOL 2028-03-31) | Magnus, `backend: :native` | Fiddle |
+| 3.2 / 3.3 | Fiddle | Fiddle |
+
+The platform gems declare `required_ruby_version >= 3.4, < 4.1` precisely so RubyGems
+*declines* them outside that range and resolves the universal gem instead — a wrong-ABI
+extension must never be installed in the first place. On Windows it would at least fail to
+load cleanly (the extension imports `<arch>-ucrt-ruby<minor>.dll` by name —
+`x64-ucrt-ruby400.dll` on x64, `aarch64-ucrt-ruby400.dll` on ARM), but Linux extensions
+don't link libruby at all, so one can load successfully against the wrong ABI and misbehave
+later. When 3.4 goes EOL it simply leaves the matrix and its users fall back to Fiddle, which
+is exactly what the fallback is for.
+
+An earlier edition of this section said the fallback covered "Windows included, since Magnus
+doesn't target it." That was wrong in both halves. MinGW is the *only* Windows flavour
+`rb-sys` targets — its own `data/toolchains.json` maps `x64-mingw-ucrt` to the
+`x86_64-pc-windows-gnu` Rust target, `supported: true`; the target it has no support for is
+`x86_64-pc-windows-msvc`. And Windows is where the Fiddle fallback cost the most: measured
+on win-x64, Ruby 3.4, the Magnus backend does `new_v4` in 406ns against Fiddle's 2407ns
+(**5.9x**) and `new_v7` in 595ns against 2759ns (**4.6x**) — a far wider gap than any Linux
+or macOS leg shows.
+
+Windows-on-ARM is no longer the exception it was. `rb-sys` maps `aarch64-mingw-ucrt` to the
+`aarch64-pc-windows-gnullvm` Rust target (`supported: true`), and RubyInstaller ships an
+`aarch64-mingw-ucrt` build of both ABIs in the table above, so win-arm64 now gets the same fat
+platform gem as every other leg. Measured on real Windows-on-ARM hardware, Ruby 4.0.6, the
+Magnus backend does `new_v4` in 416ns against Fiddle's 2299ns (**5.5x**) and `new_v7` in 621ns
+against 2474ns (**4.0x**) — the same shape the x64 leg shows.
+
+What differs from the x64 build follows from `gnullvm` being LLVM-based where
+`x86_64-pc-windows-gnu` is GCC-based. The linker driver is `aarch64-w64-mingw32-clang` from
+MSYS2's CLANGARM64 environment — RubyInstaller's own ARM devkit installs it locally, and
+`ruby/setup-ruby` installs it on `windows-11-arm` — so there is no `link-self-contained=no`
+dance. Two flags are load-bearing:
+
+- **`-l static=unwind`.** rustc emits its `-lunwind` in the linker's *dynamic* section, where
+  CLANGARM64 offers both `libunwind.a` and `libunwind.dll.a` and lld prefers the latter. Left
+  alone, the extension acquires a runtime dependency on `libunwind.dll` — a file no consumer
+  of the gem would have.
+- **`BINDGEN_EXTRA_CLANG_ARGS=--target=aarch64-w64-mingw32`.** bindgen hands clang the *Rust*
+  target triple when cargo cross-compiles, and clang rejects `aarch64-pc-windows-gnullvm`
+  outright (`version 'llvm' in target triple ... is invalid`), then fails behind that on a
+  missing `stdalign.h` it never reached its own resource dir to find. `aarch64-w64-mingw32`
+  is the same ABI spelled the way clang accepts, exactly as x64 spells its gnu target
+  `x86_64-w64-mingw32`.
+
+That second one was briefly documented here as *unnecessary*, on the strength of a local
+build where it genuinely was: that build used a `gnullvm` **host** toolchain, so host equals
+target, cargo was not cross-compiling, and bindgen injected no `--target` at all. CI's host is
+MSVC, so it does. A local build says nothing about that step unless its host triple matches
+the runner's.
 
 See [the repo root README](../README.md) for the full RFC 9562 coverage table and the state of every other language binding.

data/lib/hyperuuid.rb

@@ -13,7 +13,7 @@ require_relative "hyperuuid/runtime"
 module HyperUuid
   # This gem's own version — distinct from the RFC 9562 UUID *versions* (v4/v5/v6/v7) the
   # rest of this module generates.
-  VERSION = "0.1.1"
+  VERSION = "0.2.0"
 
   # Creates a random UUID version 4 (RFC 9562 §5.4).
   def self.new_v4
@@ -78,6 +78,34 @@ module HyperUuid
     bytes = Runtime.new_v7_batch(count, unix_millis_from(unix_millis))
     Array.new(count) { |i| Uuid.new(bytes[i * 16, 16]) }
   end
+
+  # Returns `count` version 7 UUIDs as one binary String of raw RFC 9562-ordered bytes,
+  # 16 per UUID, instead of an Array of Uuid objects.
+  #
+  # Roughly 11x faster than #new_v7_batch for a 1000-UUID batch (about 35 us versus 400 us).
+  # The difference is not the native call — that is identical — it is that #new_v7_batch then
+  # allocates `count` Uuid objects and `count` String slices on top of it. This hands back the
+  # bytes the native core already produced, untouched.
+  #
+  # Use it when bytes are the destination: a BYTEA/uniqueidentifier bind parameter, a wire
+  # format, a bulk COPY. If you need Uuid objects, keep using #new_v7_batch — slicing this
+  # String into them yourself just moves the same allocations into your own code.
+  #
+  # Slice it with `bytes[i * 16, 16]`, which is what #new_v7_batch does internally.
+  def self.new_v7_batch_bytes(count, unix_millis = nil)
+    Runtime.new_v7_batch(count, unix_millis_from(unix_millis))
+  end
+
+  # Returns `count` version 6 UUIDs as one binary String of raw RFC 9562-ordered bytes,
+  # 16 per UUID. The version 6 counterpart to #new_v7_batch_bytes, with the same rationale and
+  # the same guidance about when it is the right call.
+  #
+  # clock_seq and node are independently random per item; unlike version 7 there is no
+  # monotonic counter, so items minted in the same millisecond are not guaranteed to sort in
+  # creation order.
+  def self.new_v6_batch_bytes(count, unix_millis = nil)
+    Runtime.new_v6_batch(count, unix_millis_from(unix_millis))
+  end
 end
 
 # --- backend selection: the Magnus extension, when present, replaces the Runtime methods
@@ -91,10 +119,24 @@ HyperUuid::BACKEND =
   if ENV["HYPERUUID_PURE"]
     :fiddle
   else
+    # Two layouts, and both have to work. A released platform gem is a "fat" gem carrying one
+    # extension per supported Ruby ABI under lib/hyperuuid/<minor>/ (see the Rakefile's
+    # native:gem task for why an ABI-per-file is unavoidable — Magnus has no `abi3`
+    # equivalent). CI's in-job staging and a local `cargo build --release --features ruby`
+    # instead drop a single extension flat at lib/. Trying the versioned path first and the
+    # flat one second means neither has to know the other exists.
+    #
+    # A miss on both is not an error: it means this Ruby/platform combination has no
+    # precompiled extension, which is precisely what the Fiddle backend below is for.
     begin
-      require "hyperuuid_native"
+      require "hyperuuid/#{RUBY_VERSION[/\d+\.\d+/]}/hyperuuid_native"
       :native
     rescue LoadError
-      :fiddle
+      begin
+        require "hyperuuid_native"
+        :native
+      rescue LoadError
+        :fiddle
+      end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hyperuuid
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: x86_64-linux
 authors:
 - Brian Buvinghausen
@@ -76,6 +76,8 @@ files:
 - LICENSE
 - README.md
 - lib/hyperuuid.rb
+- lib/hyperuuid/3.4/hyperuuid_native.so
+- lib/hyperuuid/4.0/hyperuuid_native.so
 - lib/hyperuuid/namespaces.rb
 - lib/hyperuuid/native/README.md
 - lib/hyperuuid/native/linux-arm64/libhyperuuid.so
@@ -87,7 +89,6 @@ files:
 - lib/hyperuuid/native_platform.rb
 - lib/hyperuuid/runtime.rb
 - lib/hyperuuid/uuid.rb
-- lib/hyperuuid_native.so
 homepage: https://github.com/SkunkWerkx/HyperUuid
 licenses:
 - MIT
@@ -100,14 +101,17 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '3.4'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: '4.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.16
 specification_version: 4
 summary: RFC 9562 UUID v4/v5/v6/v7 generation — direct native FFI into a Rust core,
   no runtime bridge.