1#[derive(Clone, Copy, Debug, PartialEq, Eq)]
8pub enum Tag {
9 Int,
11 Bool,
13 Str,
15 Model,
18 Persistent,
20 Transient,
22 Empty,
24}
25
26const TAG_BITS: u32 = 3;
27const TAG_MASK: u64 = 0b111;
28const T_INT: u64 = 0;
29const T_BOOL: u64 = 1;
30const T_STR: u64 = 2;
31const T_MODEL: u64 = 3;
32const T_PERSISTENT: u64 = 4;
34const T_TRANSIENT: u64 = 5;
35const T_EMPTY: u64 = 7;
36
37const SHARD_BITS: u32 = 8;
38const CLASS_BITS: u32 = 2;
39pub(crate) const CLASSES: usize = 4;
41pub(crate) const LAZY_CLASS: u8 = 3;
43pub(crate) const MAX_CLASS_INDEX: u64 = (1 << 29) - 1;
45
46pub const INT_MAX: i64 = (1 << 60) - 1;
48pub const INT_MIN: i64 = -(1 << 60);
50
51#[derive(Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
54pub struct Handle(pub(crate) u64);
55
56impl std::fmt::Debug for Handle {
57 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
58 match self.tag() {
59 Tag::Int => write!(f, "Int({})", self.int_unchecked()),
60 Tag::Bool => write!(f, "Bool({})", self.0 >> TAG_BITS != 0),
61 Tag::Str => write!(f, "Str#{}", self.0 >> TAG_BITS),
62 Tag::Model => write!(f, "Model#{}", self.0 >> TAG_BITS),
63 Tag::Persistent => {
64 let (s, c, i) = self.persistent_parts();
65 write!(f, "P{s}:{c}:{i}")
66 }
67 Tag::Transient => {
68 let (e, i) = self.transient_parts();
69 write!(f, "T{e}:{i}")
70 }
71 Tag::Empty => write!(f, "Empty"),
72 }
73 }
74}
75
76impl Handle {
77 pub const EMPTY: Self = Self(T_EMPTY);
79 pub const TRUE: Self = Self((1 << TAG_BITS) | T_BOOL);
81 pub const FALSE: Self = Self(T_BOOL);
83
84 #[must_use]
86 pub const fn bits(self) -> u64 {
87 self.0
88 }
89
90 #[must_use]
92 pub const fn tag(self) -> Tag {
93 match self.0 & TAG_MASK {
94 T_INT => Tag::Int,
95 T_BOOL => Tag::Bool,
96 T_STR => Tag::Str,
97 T_MODEL => Tag::Model,
98 T_PERSISTENT => Tag::Persistent,
99 T_TRANSIENT => Tag::Transient,
100 _ => Tag::Empty,
101 }
102 }
103
104 #[must_use]
106 pub const fn int(v: i64) -> Option<Self> {
107 if v < INT_MIN || v > INT_MAX {
108 None
109 } else {
110 #[allow(clippy::cast_sign_loss, reason = "two's complement packing")]
111 Some(Self(((v << TAG_BITS) as u64) | T_INT))
112 }
113 }
114
115 #[must_use]
117 pub const fn bool(b: bool) -> Self {
118 if b { Self::TRUE } else { Self::FALSE }
119 }
120
121 #[must_use]
123 pub const fn string(id: u32) -> Self {
124 Self(((id as u64) << TAG_BITS) | T_STR)
125 }
126
127 #[must_use]
129 pub const fn model(id: u32) -> Self {
130 Self(((id as u64) << TAG_BITS) | T_MODEL)
131 }
132
133 pub(crate) const fn persistent(shard: u8, class: u8, index: u64) -> Self {
134 Self(
135 (((index << (SHARD_BITS + CLASS_BITS))
136 | ((class as u64) << SHARD_BITS)
137 | shard as u64)
138 << TAG_BITS)
139 | T_PERSISTENT,
140 )
141 }
142
143 pub(crate) const fn transient(epoch: u32, index: u32) -> Self {
144 Self(((((epoch as u64) << 32) | index as u64) << TAG_BITS) | T_TRANSIENT)
145 }
146
147 #[must_use]
149 pub const fn as_int(self) -> Option<i64> {
150 if self.0 & TAG_MASK == T_INT {
151 Some(self.int_unchecked())
152 } else {
153 None
154 }
155 }
156
157 #[allow(clippy::cast_possible_wrap, reason = "two's complement unpacking")]
158 const fn int_unchecked(self) -> i64 {
159 (self.0 as i64) >> TAG_BITS
160 }
161
162 #[must_use]
164 pub const fn as_bool(self) -> Option<bool> {
165 if self.0 & TAG_MASK == T_BOOL {
166 Some(self.0 >> TAG_BITS != 0)
167 } else {
168 None
169 }
170 }
171
172 #[must_use]
174 pub const fn as_str_id(self) -> Option<u32> {
175 if self.0 & TAG_MASK == T_STR {
176 #[allow(clippy::cast_possible_truncation, reason = "ids are 32-bit")]
177 Some((self.0 >> TAG_BITS) as u32)
178 } else {
179 None
180 }
181 }
182
183 #[must_use]
185 pub const fn as_model_id(self) -> Option<u32> {
186 if self.0 & TAG_MASK == T_MODEL {
187 #[allow(clippy::cast_possible_truncation, reason = "ids are 32-bit")]
188 Some((self.0 >> TAG_BITS) as u32)
189 } else {
190 None
191 }
192 }
193
194 #[must_use]
196 pub const fn is_compound(self) -> bool {
197 matches!(self.0 & TAG_MASK, T_PERSISTENT | T_TRANSIENT)
198 }
199
200 #[must_use]
202 pub const fn is_transient(self) -> bool {
203 self.0 & TAG_MASK == T_TRANSIENT
204 }
205
206 #[must_use]
208 pub const fn is_persistent(self) -> bool {
209 self.0 & TAG_MASK == T_PERSISTENT
210 }
211
212 #[must_use]
215 pub const fn is_lazy_persistent(self) -> bool {
219 self.is_persistent() && self.persistent_parts().1 == LAZY_CLASS
220 }
221
222 #[must_use]
224 pub const fn is_empty(self) -> bool {
225 self.0 & TAG_MASK == T_EMPTY
226 }
227
228 #[allow(clippy::cast_possible_truncation, reason = "packed fields")]
230 #[inline]
231 pub(crate) const fn persistent_parts(self) -> (u8, u8, u64) {
232 let p = self.0 >> TAG_BITS;
233 (
234 (p & 0xff) as u8,
235 ((p >> SHARD_BITS) & ((1 << CLASS_BITS) - 1)) as u8,
236 p >> (SHARD_BITS + CLASS_BITS),
237 )
238 }
239
240 #[allow(clippy::cast_possible_truncation, reason = "packed fields")]
241 pub(crate) const fn transient_parts(self) -> (u32, u32) {
242 let p = self.0 >> TAG_BITS;
243 ((p >> 32) as u32, p as u32)
244 }
245}
246
247#[must_use]
249#[inline]
250pub const fn mix64(mut z: u64) -> u64 {
251 z = (z ^ (z >> 30)).wrapping_mul(0xbf58_476d_1ce4_e5b9);
252 z = (z ^ (z >> 27)).wrapping_mul(0x94d0_49bb_1331_11eb);
253 z ^ (z >> 31)
254}
255
256#[must_use]
258#[inline]
259pub const fn mix2(a: u64, b: u64) -> u64 {
260 mix64(a ^ b.rotate_left(29).wrapping_mul(0x9e37_79b9_7f4a_7c15))
261}
262
263pub(crate) const K_BOOL: u64 = 0x1f83_d9ab_fb41_bd6b;
264pub(crate) const K_INT: u64 = 0x5be0_cd19_137e_2179;
265pub(crate) const K_STR: u64 = 0x6a09_e667_f3bc_c908;
266pub(crate) const K_SET: u64 = 0x3c6e_f372_fe94_f82b;
267pub(crate) const K_FCN: u64 = 0xa54f_f53a_5f1d_36f1;
268pub(crate) const K_SYM: u64 = 0x510e_527f_ade6_82d1;
269pub(crate) const K_MODEL: u64 = 0x1f83_d9ab_5be0_cd19;
270pub const K_STATE: u64 = 0x9b05_688c_2b3e_6c1f;
272
273#[must_use]
275#[inline]
276pub const fn fin(k: u64, len: u64, sum: u64) -> u64 {
277 mix64(sum ^ mix64(k.wrapping_add(len.wrapping_mul(0x9e37_79b9_7f4a_7c15))))
278}
279
280#[must_use]
282#[inline]
283pub const fn scalar_hash(h: Handle) -> Option<u64> {
284 match h.0 & TAG_MASK {
285 T_INT => Some(int_hash(h.int_unchecked())),
286 T_BOOL => Some(mix64(K_BOOL ^ (h.0 >> TAG_BITS))),
287 T_STR => Some(mix64(K_STR ^ (h.0 >> TAG_BITS))),
288 T_MODEL => Some(mix64(K_MODEL ^ (h.0 >> TAG_BITS))),
289 _ => None,
290 }
291}
292
293#[must_use]
295#[inline]
296pub const fn int_hash(v: i64) -> u64 {
297 #[allow(clippy::cast_sign_loss, reason = "bit reinterpretation for hashing")]
298 mix64((v as u64) ^ K_INT)
299}
300
301#[must_use]
303#[inline]
304pub const fn state_term(i: usize, h: u64) -> u64 {
305 mix2(mix64(K_STATE ^ i as u64), h)
306}
307
308#[cfg(test)]
309mod tests {
310 use super::*;
311
312 #[test]
313 fn integers_round_trip_at_the_bounds() {
314 for v in [0, 1, -1, INT_MAX, INT_MIN, 12345, -9876] {
315 let h = Handle::int(v).unwrap_or(Handle::EMPTY);
316 assert_eq!(h.as_int(), Some(v));
317 assert_eq!(h.tag(), Tag::Int);
318 }
319 assert!(Handle::int(INT_MAX + 1).is_none());
320 assert!(Handle::int(INT_MIN - 1).is_none());
321 }
322
323 #[test]
324 fn compound_parts_round_trip() {
325 let p = Handle::persistent(200, 2, (1 << 40) + 7);
326 assert_eq!(p.persistent_parts(), (200, 2, (1 << 40) + 7));
327 assert!(p.is_persistent());
328 let t = Handle::transient(0x1fff_ffff, 0xffff_fff0);
329 assert_eq!(t.transient_parts(), (0x1fff_ffff, 0xffff_fff0));
330 assert!(t.is_transient());
331 assert_eq!(Handle::TRUE.as_bool(), Some(true));
332 assert_eq!(Handle::FALSE.as_bool(), Some(false));
333 assert_eq!(Handle::string(9).as_str_id(), Some(9));
334 assert!(Handle::EMPTY.is_empty());
335 }
336}