hyperuuid 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d36a27a93cdb9a4a6bffeb6a6b9ddb8da61bbc9d20b8fda29ad7c8b2238465c2
-  data.tar.gz: cbe47ffb022c0ccb23d98ff9543c56d515ecc6928dbf7df11533593c097247ae
+  metadata.gz: b32cd1cbc875c0d6a64d08feecec431d09b8f51f79f0a3551ad9494e7310d069
+  data.tar.gz: 4ed09018086e92c7c4f275b367106d2174320494996e4d621af8b1b0ef714ae0
 SHA512:
-  metadata.gz: eb071fda1c20cb7f44d0b64fbcf2833768bac66cfe7d71951d1ba2e4ef0fe3d3d166d6a545b347bba22b52dee932e979f8e7b0059719f92c6308fc70629dbd04
-  data.tar.gz: 8630e51665339db93b4a6c90230b08649f8b9bf2e86520b09a803bff435d0e977df6bdfc88601b412d33f8aa8b19104afd854329d409c0894d9bb3c98258c2ef
+  metadata.gz: '0069495aa996730427430e5ecc7314a99b2dd496e3e78ffed28c982cf85b1177470ecdf80c6920947ea88d5cd729b04036443a6d44e5447014b58be80011d8de'
+  data.tar.gz: a5ecd9e090c7bf5411a8144f5c9968e095d64a8d0cdf6d63dd6c899a6d185b6f4306255669c83da936045c030c4d02408b0be85d58e9d9dab9a04c33c12f98d9

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Skunk Werkx
+
+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

@@ -1,5 +1,8 @@
 # hyperuuid
 
+[![CI](https://github.com/SkunkWerkx/HyperUuid/actions/workflows/ci.yml/badge.svg)](https://github.com/SkunkWerkx/HyperUuid/actions/workflows/ci.yml)
+[![RubyGems](https://img.shields.io/gem/v/hyperuuid.svg)](https://rubygems.org/gems/hyperuuid)
+
 **Ruby's own stdlib stops at `SecureRandom.uuid` — random v4, full stop. No v5, no v6, no v7. This gem is the whole RFC, with zero gem dependency beyond `Fiddle` (which ships with every Ruby install) — and it's faster than `SecureRandom.uuid` too.**
 
 RFC 9562 UUID v4 (random), v5 (deterministic), v6 and v7 (time-sortable) generation, with
@@ -60,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):
@@ -99,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/runtime.rb

@@ -5,7 +5,7 @@ module HyperUuid
   # C-ABI call, no runtime bridge (the same "no shim" positioning as the Go/Swift bindings'
   # purego/dlopen approach). Fiddle ships with every Ruby install; it's a plain gem
   # dependency here (see hyperuuid.gemspec) rather than a third-party one — mirroring Go's
-  # "no cgo" and Python's ctypes-only stance.
+  # "no cgo" and Python's zero-dependency PyO3 wheels.
   #
   # Unlike the Go/Swift bindings, which embed their native builds inside a single compiled
   # archive and must extract to a temp file before dlopen can see a real path, a Ruby gem's

data/lib/hyperuuid/uuid.rb

@@ -1,7 +1,8 @@
 module HyperUuid
   # A parsed 16-byte RFC 9562 UUID value. Minimal by design — this gem has no runtime
   # dependency on the `uuid` gem, the same "no extra dependency" positioning as the Go
-  # binding's purego-only/no-cgo approach and the Python binding's stdlib-ctypes-only one.
+  # binding's purego-only/no-cgo approach and the Python binding's dependency-free PyO3
+  # wheels.
   class Uuid
     include Comparable
 

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.0"
+  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.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Brian Buvinghausen
@@ -73,6 +73,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- LICENSE
 - README.md
 - lib/hyperuuid.rb
 - lib/hyperuuid/namespaces.rb
@@ -105,7 +106,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !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.