Module: HyperUuid::Runtime

Defined in:
lib/hyperuuid/runtime.rb

Overview

Fiddle plumbing for the native libhyperuuid shared library — dlopen/dlsym plus a raw 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.

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 files are already plain files on disk once installed — native/rid/lib can be dlopen'd directly, no extraction step needed.

Defined Under Namespace

Classes: RandomSourceError, TimestampOutOfRangeError

Constant Summary collapse

NATIVE_DIR = 
File.join(__dir__, "native")

Class Method Summary collapse

Class Method Details

.new_v4 ⇒ Object

Raises:



24
25
26
27
28
29
 
# File 'lib/hyperuuid/runtime.rb', line 24

def new_v4
  out = scratch
  rc = functions[:new_v4].call(out)
  raise RandomSourceError, "uuid_new_v4 failed with code #{rc}" unless rc.zero?
  out[0, 16]
end

.new_v5(namespace_bytes, name_bytes) ⇒ Object

Raises:



31
32
33
34
35
36
37
38
39
 
# File 'lib/hyperuuid/runtime.rb', line 31

def new_v5(namespace_bytes, name_bytes)
  out = scratch
  # Fiddle passes a String's bytes for void* directly (read-only) — no Pointer
  # wrapper, no copy — the same zero-copy crossing every other input here uses.
  name = name_bytes.empty? ? nil : name_bytes
  rc = functions[:new_v5].call(namespace_bytes, name, name_bytes.bytesize, out)
  raise RandomSourceError, "uuid_new_v5 failed with code #{rc}" unless rc.zero?
  out[0, 16]
end

.new_v6(unix_millis) ⇒ Object 



41
42
43
44
45
46
47
48
49
 
# File 'lib/hyperuuid/runtime.rb', line 41

def new_v6(unix_millis)
  out = scratch
  rc = functions[:new_v6].call(unix_millis, out)
  case rc
  when 0 then out[0, 16]
  when 2 then raise TimestampOutOfRangeError, "unix_millis does not fit the 60-bit v6 timestamp field"
  else raise RandomSourceError, "uuid_new_v6 failed with code #{rc}"
  end
end

.new_v6_batch(count, unix_millis) ⇒ Object 



55
56
57
58
59
60
61
62
63
64
 
# File 'lib/hyperuuid/runtime.rb', line 55

def new_v6_batch(count, unix_millis)
  return "" if count.zero?
  out = Fiddle::Pointer.malloc(count * 16, Fiddle::RUBY_FREE)
  rc = functions[:new_v6_batch].call(unix_millis, count, out)
  case rc
  when 0 then out[0, count * 16]
  when 2 then raise TimestampOutOfRangeError, "unix_millis does not fit the 60-bit v6 timestamp field"
  else raise RandomSourceError, "uuid_new_v6_batch failed with code #{rc}"
  end
end

.new_v7(unix_millis) ⇒ Object 



66
67
68
69
70
71
72
73
74
 
# File 'lib/hyperuuid/runtime.rb', line 66

def new_v7(unix_millis)
  out = scratch
  rc = functions[:new_v7].call(unix_millis, out)
  case rc
  when 0 then out[0, 16]
  when 2 then raise TimestampOutOfRangeError, "unix_millis must fit within the RFC 9562 48-bit field"
  else raise RandomSourceError, "uuid_new_v7 failed with code #{rc}"
  end
end

.new_v7_batch(count, unix_millis) ⇒ Object 



80
81
82
83
84
85
86
87
88
89
 
# File 'lib/hyperuuid/runtime.rb', line 80

def new_v7_batch(count, unix_millis)
  return "" if count.zero?
  out = Fiddle::Pointer.malloc(count * 16, Fiddle::RUBY_FREE)
  rc = functions[:new_v7_batch].call(unix_millis, count, out)
  case rc
  when 0 then out[0, count * 16]
  when 2 then raise TimestampOutOfRangeError, "unix_millis must fit within the RFC 9562 48-bit field"
  else raise RandomSourceError, "uuid_new_v7_batch failed with code #{rc}"
  end
end

.v6_to_rfc_order(bytes) ⇒ Object 



103
104
105
 
# File 'lib/hyperuuid/runtime.rb', line 103

def v6_to_rfc_order(bytes)
  rewrite(:v6_to_rfc_order, bytes)
end

.v6_to_sql_order(bytes) ⇒ Object 



99
100
101
 
# File 'lib/hyperuuid/runtime.rb', line 99

def v6_to_sql_order(bytes)
  rewrite(:v6_to_sql_order, bytes)
end

.v6_unix_millis(bytes) ⇒ Object 



51
52
53
 
# File 'lib/hyperuuid/runtime.rb', line 51

def v6_unix_millis(bytes)
  functions[:v6_unix_millis].call(bytes)
end

.v7_to_rfc_order(bytes) ⇒ Object 



95
96
97
 
# File 'lib/hyperuuid/runtime.rb', line 95

def v7_to_rfc_order(bytes)
  rewrite(:v7_to_rfc_order, bytes)
end

.v7_to_sql_order(bytes) ⇒ Object 



91
92
93
 
# File 'lib/hyperuuid/runtime.rb', line 91

def v7_to_sql_order(bytes)
  rewrite(:v7_to_sql_order, bytes)
end

.v7_unix_millis(bytes) ⇒ Object 



76
77
78
 
# File 'lib/hyperuuid/runtime.rb', line 76

def v7_unix_millis(bytes)
  functions[:v7_unix_millis].call(bytes)
end