wasmtime/runtime/gc/maybe_rooted.rs
1//! GC references held in [`Val`](crate::Val)s and [`Ref`](crate::Ref)s.
2
3use crate::runtime::vm::VMGcRef;
4use crate::store::{AutoAssertNoGc, StoreOpaque};
5use crate::{
6 AnyRef, ArrayRef, AsContext, AsContextMut, EqRef, GcRef, HeapType, OwnedRooted, Result, Rooted,
7 StructRef, Unrooted, prelude::*,
8};
9use core::fmt;
10
11/// A reference to a GC object of type `T`, as held in a [`Val`](crate::Val)
12/// or [`Ref`](crate::Ref): either rooted or unrooted.
13///
14/// A [`MaybeRooted::Rooted`] reference keeps its object alive until the
15/// current LIFO rooting scope exits; see [`Rooted`]. A
16/// [`MaybeRooted::Unrooted`] reference is cheaper to create and needs only
17/// shared access to the store, but is valid only until the store's GC heap
18/// next changes; see [`Unrooted`].
19///
20/// APIs that read GC values, such as [`Global::get`](crate::Global::get),
21/// [`StructRef::field`](crate::StructRef::field), or the results of
22/// [`Func::call`](crate::Func::call), return unrooted references, so that
23/// rooting is always opt-in: the caller can choose to root them, and how
24/// (with [`MaybeRooted::to_rooted`], [`MaybeRooted::to_owned_rooted`], or
25/// [`Val::ensure_all_rooted`](crate::Val::ensure_all_rooted) for several at
26/// once), or to keep them unrooted.
27///
28/// APIs that take GC values to store or pass along, such as
29/// [`Global::set`](crate::Global::set),
30/// [`StructRef::new`](crate::StructRef::new), or the arguments of
31/// [`Func::call`](crate::Func::call), mutate the store, which invalidates
32/// unrooted references, and so they require rooted references, and return an
33/// error for unrooted ones; root them first.
34pub enum MaybeRooted<T: GcRef> {
35 /// A reference rooted in the current LIFO rooting scope; see [`Rooted`].
36 Rooted(Rooted<T>),
37
38 /// A reference that is not rooted, and is valid only until the store's GC
39 /// heap next changes; see [`Unrooted`].
40 Unrooted(Unrooted<T>),
41}
42
43impl<T: GcRef> Clone for MaybeRooted<T> {
44 fn clone(&self) -> Self {
45 *self
46 }
47}
48
49impl<T: GcRef> Copy for MaybeRooted<T> {}
50
51impl<T: GcRef> fmt::Debug for MaybeRooted<T> {
52 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
53 match self {
54 MaybeRooted::Rooted(r) => f.debug_tuple("Rooted").field(r).finish(),
55 MaybeRooted::Unrooted(r) => f.debug_tuple("Unrooted").field(r).finish(),
56 }
57 }
58}
59
60impl<T: GcRef> From<Rooted<T>> for MaybeRooted<T> {
61 #[inline]
62 fn from(r: Rooted<T>) -> Self {
63 MaybeRooted::Rooted(r)
64 }
65}
66
67impl<T: GcRef> From<Unrooted<T>> for MaybeRooted<T> {
68 #[inline]
69 fn from(r: Unrooted<T>) -> Self {
70 MaybeRooted::Unrooted(r)
71 }
72}
73
74macro_rules! upcasts {
75 ($($from:ty => $to:ty;)*) => {$(
76 impl From<MaybeRooted<$from>> for MaybeRooted<$to> {
77 #[inline]
78 fn from(r: MaybeRooted<$from>) -> Self {
79 match r {
80 MaybeRooted::Rooted(r) => MaybeRooted::Rooted(r.into()),
81 MaybeRooted::Unrooted(r) => MaybeRooted::Unrooted(r.into()),
82 }
83 }
84 }
85
86 impl From<Rooted<$from>> for MaybeRooted<$to> {
87 #[inline]
88 fn from(r: Rooted<$from>) -> Self {
89 MaybeRooted::Rooted(r.into())
90 }
91 }
92
93 impl From<Unrooted<$from>> for MaybeRooted<$to> {
94 #[inline]
95 fn from(r: Unrooted<$from>) -> Self {
96 MaybeRooted::Unrooted(r.into())
97 }
98 }
99 )*};
100}
101
102upcasts! {
103 EqRef => AnyRef;
104 StructRef => AnyRef;
105 ArrayRef => AnyRef;
106}
107
108impl<T: GcRef> MaybeRooted<T> {
109 /// Is this a rooted reference?
110 #[inline]
111 pub fn is_rooted(&self) -> bool {
112 matches!(self, MaybeRooted::Rooted(_))
113 }
114
115 /// Is this an unrooted reference?
116 #[inline]
117 pub fn is_unrooted(&self) -> bool {
118 matches!(self, MaybeRooted::Unrooted(_))
119 }
120
121 /// Get this reference as a [`Rooted<T>`], if it is rooted.
122 #[inline]
123 pub fn as_rooted(&self) -> Option<Rooted<T>> {
124 match self {
125 MaybeRooted::Rooted(r) => Some(*r),
126 MaybeRooted::Unrooted(_) => None,
127 }
128 }
129
130 /// Get this reference as a [`Rooted<T>`], panicking if it is not rooted.
131 ///
132 /// # Panics
133 ///
134 /// Panics if this reference is not rooted.
135 #[inline]
136 #[track_caller]
137 pub fn unwrap_rooted(&self) -> Rooted<T> {
138 self.as_rooted()
139 .expect("MaybeRooted::unwrap_rooted on a reference that is not rooted")
140 }
141
142 /// Get this reference as an [`Unrooted<T>`], if it is unrooted.
143 #[inline]
144 pub fn as_unrooted(&self) -> Option<Unrooted<T>> {
145 match self {
146 MaybeRooted::Rooted(_) => None,
147 MaybeRooted::Unrooted(r) => Some(*r),
148 }
149 }
150
151 /// Get this reference as an [`Unrooted<T>`], panicking if it is not
152 /// unrooted.
153 ///
154 /// # Panics
155 ///
156 /// Panics if this reference is not unrooted.
157 #[inline]
158 #[track_caller]
159 pub fn unwrap_unrooted(&self) -> Unrooted<T> {
160 self.as_unrooted()
161 .expect("MaybeRooted::unwrap_unrooted on a reference that is not unrooted")
162 }
163
164 /// Get this reference as a [`Rooted<T>`], or return an error if it is not
165 /// rooted.
166 ///
167 /// APIs that take GC values to store or pass along, such as
168 /// [`StructRef::new`](crate::StructRef::new), use this to check that their
169 /// values are rooted.
170 ///
171 /// # Errors
172 ///
173 /// Returns an error if this reference is not rooted.
174 pub fn validate_rooted(&self) -> Result<Rooted<T>> {
175 match self {
176 MaybeRooted::Rooted(r) => Ok(*r),
177 MaybeRooted::Unrooted(_) => bail!(
178 "expected a rooted GC reference, found an unrooted one; root it \
179 first with `MaybeRooted::ensure_rooted` or `Val::ensure_rooted`"
180 ),
181 }
182 }
183
184 /// Root this reference in place, if it is not rooted already, in the
185 /// current LIFO rooting scope, and return it as a [`Rooted<T>`].
186 ///
187 /// Rooting a reference invalidates every other unrooted reference into the
188 /// store's GC heap; use [`Rooted::to_all_rooted`] or
189 /// [`Val::ensure_all_rooted`](crate::Val::ensure_all_rooted) to root
190 /// several references at once.
191 ///
192 /// # Errors
193 ///
194 /// Returns an error if this reference is unrooted and no longer valid.
195 ///
196 /// # Panics
197 ///
198 /// Panics if this reference is associated with a different store.
199 pub fn ensure_rooted(&mut self, mut store: impl AsContextMut) -> Result<Rooted<T>> {
200 self.ensure_rooted_(store.as_context_mut().0)
201 }
202
203 pub(crate) fn ensure_rooted_(&mut self, store: &mut StoreOpaque) -> Result<Rooted<T>> {
204 let rooted = self.to_rooted_(store)?;
205 *self = MaybeRooted::Rooted(rooted);
206 Ok(rooted)
207 }
208
209 /// Get a [`Rooted<T>`] referencing the same GC object as this reference:
210 /// this reference itself if it is rooted, or a new root in the current
211 /// LIFO rooting scope if it is unrooted.
212 ///
213 /// Rooting a reference invalidates every other unrooted reference into the
214 /// store's GC heap; use [`Rooted::to_all_rooted`] or
215 /// [`Val::ensure_all_rooted`](crate::Val::ensure_all_rooted) to root
216 /// several references at once.
217 ///
218 /// # Errors
219 ///
220 /// Returns an error if this reference is unrooted and no longer valid.
221 ///
222 /// # Panics
223 ///
224 /// Panics if this reference is associated with a different store.
225 pub fn to_rooted(&self, mut store: impl AsContextMut) -> Result<Rooted<T>> {
226 self.to_rooted_(store.as_context_mut().0)
227 }
228
229 pub(crate) fn to_rooted_(&self, store: &mut StoreOpaque) -> Result<Rooted<T>> {
230 match self {
231 MaybeRooted::Rooted(r) => {
232 assert!(
233 r.comes_from_same_store(store),
234 "object used with wrong store"
235 );
236 Ok(*r)
237 }
238 MaybeRooted::Unrooted(r) => r.to_rooted_(store),
239 }
240 }
241
242 /// Get an [`Unrooted<T>`] referencing the same GC object as this
243 /// reference.
244 ///
245 /// # Errors
246 ///
247 /// Returns an error if this reference is no longer valid: if it is rooted
248 /// and has since been unrooted, or if it is unrooted and the store's GC
249 /// heap has since changed.
250 ///
251 /// # Panics
252 ///
253 /// Panics if this reference is associated with a different store.
254 pub fn to_unrooted(&self, store: impl AsContext) -> Result<Unrooted<T>> {
255 self.to_unrooted_(store.as_context().0)
256 }
257
258 pub(crate) fn to_unrooted_(&self, store: &StoreOpaque) -> Result<Unrooted<T>> {
259 match self {
260 MaybeRooted::Rooted(r) => r.to_unrooted_(store),
261 MaybeRooted::Unrooted(r) => {
262 r.gc_ref(store)?;
263 Ok(*r)
264 }
265 }
266 }
267
268 /// Create an [`OwnedRooted<T>`] holding onto the same GC object as this
269 /// reference.
270 ///
271 /// # Errors
272 ///
273 /// Returns an error if this reference is no longer valid.
274 ///
275 /// This function will return an [`OutOfMemory`](crate::OutOfMemory)
276 /// error when memory allocation fails. See the `OutOfMemory` type's
277 /// documentation for details on Wasmtime's out-of-memory handling.
278 ///
279 /// # Panics
280 ///
281 /// Panics if this reference is associated with a different store.
282 pub fn to_owned_rooted(&self, mut store: impl AsContextMut) -> Result<OwnedRooted<T>> {
283 match self {
284 MaybeRooted::Rooted(r) => r.to_owned_rooted(store),
285 MaybeRooted::Unrooted(r) => r.to_owned_rooted_(store.as_context_mut().0),
286 }
287 }
288
289 pub(crate) fn comes_from_same_store(&self, store: &StoreOpaque) -> bool {
290 match self {
291 MaybeRooted::Rooted(r) => r.comes_from_same_store(store),
292 MaybeRooted::Unrooted(r) => r.comes_from_same_store(store),
293 }
294 }
295
296 /// The referenced object, if this reference is still valid.
297 ///
298 /// The result borrows `store`, so nothing can collect garbage or
299 /// otherwise mutate the GC heap while it is in use.
300 ///
301 /// # Panics
302 ///
303 /// Panics if this reference is associated with a different store.
304 pub(crate) fn try_gc_ref<'a>(&'a self, store: &'a StoreOpaque) -> Result<&'a VMGcRef> {
305 match self {
306 MaybeRooted::Rooted(r) => r.try_gc_ref(store),
307 MaybeRooted::Unrooted(r) => r.gc_ref(store),
308 }
309 }
310
311 /// Root this reference in place, if it is unrooted, after the caller has
312 /// checked that it is valid (with `try_gc_ref`), as part of rooting several
313 /// references at once; see `Unrooted::unchecked_gc_ref` for the
314 /// conditions.
315 pub(crate) fn ensure_rooted_unchecked(&mut self, store: &mut AutoAssertNoGc<'_>) {
316 if let MaybeRooted::Unrooted(r) = self {
317 *self = MaybeRooted::Rooted(r.to_rooted_unchecked(store));
318 }
319 }
320
321 /// The referenced object, cloned for storing it somewhere, if this
322 /// reference is rooted and still valid.
323 ///
324 /// Storing a reference mutates the store, so this is an error for an
325 /// unrooted reference.
326 ///
327 /// # Panics
328 ///
329 /// Panics if this reference is associated with a different store.
330 pub(crate) fn try_clone_gc_ref(&self, store: &mut AutoAssertNoGc<'_>) -> Result<VMGcRef> {
331 self.validate_rooted()?.try_clone_gc_ref(store)
332 }
333
334 /// The raw bits of this reference, exposed to Wasm, if this reference is
335 /// rooted and still valid.
336 ///
337 /// Exposing a reference to Wasm mutates the store, so this is an error for
338 /// an unrooted reference.
339 ///
340 /// # Panics
341 ///
342 /// Panics if this reference is associated with a different store.
343 pub(crate) fn to_raw_(&self, store: &mut AutoAssertNoGc<'_>) -> Result<u32> {
344 let gc_ref = self.try_clone_gc_ref(store)?;
345 let raw = match store.optional_gc_store_mut() {
346 Some(s) => s.expose_gc_ref_to_wasm(gc_ref)?,
347 None => {
348 // NB: do not force the allocation of a GC heap just because the
349 // program is using `i31ref`s.
350 debug_assert!(gc_ref.is_i31());
351 gc_ref.as_raw_non_zero_u32()
352 }
353 };
354 Ok(raw.get())
355 }
356
357 /// The raw bits of the optional reference `this`, exposed to Wasm; zero
358 /// for null.
359 pub(crate) fn option_to_raw(
360 this: Option<&Self>,
361 store: &mut AutoAssertNoGc<'_>,
362 ) -> Result<u32> {
363 match this {
364 Some(r) => r.to_raw_(store),
365 None => Ok(0),
366 }
367 }
368}
369
370impl MaybeRooted<AnyRef> {
371 /// The type of the referenced object; see [`AnyRef::ty`].
372 pub(crate) fn ty_(&self, store: &StoreOpaque) -> Result<HeapType> {
373 AnyRef::ty_of_(store, self.try_gc_ref(store)?)
374 }
375}