1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
use std::fmt::Debug;
use std::hash::{Hash, Hasher};
use std::num::NonZeroU32;
use crate::zalsa::Zalsa;
/// The `Id` of a salsa struct in the database [`Table`](`crate::table::Table`).
///
/// The high-order bits of an `Id` store a 32-bit generation counter, while
/// the low-order bits pack a [`PageIndex`](`crate::table::PageIndex`) and
/// [`SlotIndex`](`crate::table::SlotIndex`) within the page.
///
/// The low-order bits of `Id` are a `u32` ranging from `0..Id::MAX_U32`.
/// The maximum range is smaller than a standard `u32` to leave
/// room for niches; currently there is only one niche, so that
/// `Option<Id>` is the same size as an `Id`.
///
/// As an end-user of `Salsa` you will generally not use `Id` directly,
/// it is wrapped in new types.
#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub struct Id {
index: NonZeroU32,
generation: u32,
}
impl Id {
pub const MAX_U32: u32 = u32::MAX - 0xFF;
pub const MAX_USIZE: usize = Self::MAX_U32 as usize;
/// Create a `salsa::Id` from a u32 value, without a generation. This
/// value should be less than [`Self::MAX_U32`].
///
/// In general, you should not need to create salsa ids yourself,
/// but it can be useful if you are using the type as a general
/// purpose "identifier" internally.
///
/// # Safety
///
/// The supplied value must be less than [`Self::MAX_U32`].
#[doc(hidden)]
#[track_caller]
#[inline]
pub const unsafe fn from_index(index: u32) -> Self {
debug_assert!(index < Self::MAX_U32);
Id {
// SAFETY: Caller obligation.
index: unsafe { NonZeroU32::new_unchecked(index + 1) },
generation: 0,
}
}
/// Create a `salsa::Id` from a `u64` value.
///
/// This should only be used to recreate an `Id` together with `Id::as_u64`.
///
/// # Safety
///
/// The data bits of the supplied value must represent a valid `Id` returned
/// by `Id::as_u64`.
#[doc(hidden)]
#[track_caller]
#[inline]
pub const unsafe fn from_bits_unchecked(bits: u64) -> Self {
// SAFETY: Caller obligation.
let index = unsafe { NonZeroU32::new_unchecked(bits as u32) };
let generation = (bits >> 32) as u32;
Id { index, generation }
}
/// Create a `salsa::Id` from a `u64` value.
///
/// This should only be used to recreate an `Id` together with `Id::as_u64`,
/// and may panic if the `Id` is invalid.
#[inline]
#[doc(hidden)]
pub const fn from_bits(bits: u64) -> Self {
let index = NonZeroU32::new(bits as u32).expect("attempted to create invalid `Id`");
let generation = (bits >> 32) as u32;
Id { index, generation }
}
/// Return a `u64` representation of this `Id`.
#[inline]
pub fn as_bits(self) -> u64 {
u64::from(self.index.get()) | (u64::from(self.generation) << 32)
}
/// Returns a new `Id` with same index, but the generation incremented by one.
///
/// Returns `None` if the generation would overflow, i.e. the current generation
/// is `u32::MAX`.
#[inline]
pub fn next_generation(self) -> Option<Id> {
self.generation()
.checked_add(1)
.map(|generation| self.with_generation(generation))
}
/// Mark the `Id` with a generation.
///
/// This `Id` will refer to the same page and slot in the database,
/// but will differ from other identifiers of the slot based on the
/// provided generation.
#[inline]
pub const fn with_generation(self, generation: u32) -> Id {
Id {
index: self.index,
generation,
}
}
/// Return the index portion of this `Id`.
#[inline]
pub const fn index(self) -> u32 {
self.index.get() - 1
}
/// Return the generation of this `Id`.
#[inline]
pub const fn generation(self) -> u32 {
self.generation
}
}
impl Hash for Id {
fn hash<H: Hasher>(&self, state: &mut H) {
// Convert to a `u64` to avoid dispatching multiple calls to `H::write`.
state.write_u64(self.as_bits());
}
}
#[cfg(feature = "persistence")]
impl serde::Serialize for Id {
fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
where
S: serde::Serializer,
{
serde::Serialize::serialize(&self.as_bits(), serializer)
}
}
#[cfg(feature = "persistence")]
impl<'de> serde::Deserialize<'de> for Id {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: serde::Deserializer<'de>,
{
serde::Deserialize::deserialize(deserializer).map(Self::from_bits)
}
}
impl Debug for Id {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
if self.generation() == 0 {
write!(f, "Id({:x})", self.index())
} else {
write!(f, "Id({:x}g{:x})", self.index(), self.generation())
}
}
}
/// Internal salsa trait for types that can be represented as a salsa id.
pub trait AsId: Sized {
fn as_id(&self) -> Id;
}
/// Internal Salsa trait for types that are just a newtype'd [`Id`][].
pub trait FromId {
fn from_id(id: Id) -> Self;
}
impl AsId for Id {
#[inline]
fn as_id(&self) -> Id {
*self
}
}
impl FromId for Id {
#[inline]
fn from_id(id: Id) -> Self {
id
}
}
/// Enums cannot use [`FromId`] because they need access to the DB to tell the `TypeId` of the variant,
/// so they use this trait instead, that has a blanket implementation for `FromId`.
pub trait FromIdWithDb {
fn from_id(id: Id, zalsa: &Zalsa) -> Self;
}
impl<T: FromId> FromIdWithDb for T {
#[inline]
fn from_id(id: Id, _zalsa: &Zalsa) -> Self {
FromId::from_id(id)
}
}