hyperuuid 0.1.0-aarch64-linux → 0.2.0-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2892b5a876b4e3cad50f46aad3f4a778f89b6d72e4c523b6c711979c6c87ef30
-  data.tar.gz: 61ca11315cb9a92e2221dfa9a752eb83ce9c8c276b4dcf292bf5ce425c66fc55
+  metadata.gz: 44f92576d6f75d47a6711d276468afa53fcb3d7743855f5f2e2ece727506f0d4
+  data.tar.gz: 7a7094cd8935b92d47e9b13e7ed6c564f21c0d06a6bc569d4922d47c2a305da5
 SHA512:
-  metadata.gz: a8e44ec99f418bf148a9611952c64872d933ca2786a760cbb228cfe118c1635a87d7b13d0c2c491b14d0a7f22d68dad482c0f2ef33e73cc952bd2b7ff66e8eda
-  data.tar.gz: 59e0a033d956900a43f010765a00a3edd79def7863c29b01e9cfbbe8c45339e72afe4dec9c544db26057359011a76b5cc22ac2a22bcae7f4f51bf0ca4f201c67
+  metadata.gz: 668531aaaf63a38bafda71ee55daf8782de3dfc43c663e56dad7f2528e6662ca3935ed5b3302b4b42fb62d0bddaf1f7b8b992cb75c60f356303a72d57c78641e
+  data.tar.gz: 6ad655d628c646e4bcd0efd3879f6f56e304c62e958074b3b9c9e179ad1ba898f64261e9eb6114adb0bbaab7c3f14bce0bee069ddccd61fab85d5d01cdea6f7e

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: aarch64-linux
 authors:
 - Brian Buvinghausen
@@ -73,8 +73,11 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 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
@@ -86,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
@@ -99,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.