wasmtime/runtime/gc.rs
1#[cfg(feature = "gc")]
2mod enabled;
3#[cfg(feature = "gc")]
4pub use enabled::*;
5
6#[cfg(not(feature = "gc"))]
7mod disabled;
8#[cfg(not(feature = "gc"))]
9pub use disabled::*;
10
11mod maybe_rooted;
12pub use maybe_rooted::MaybeRooted;
13
14mod noextern;
15pub use noextern::NoExtern;
16
17mod none_ref;
18pub use none_ref::NoneRef;
19
20use core::fmt;
21use core::ops::Deref;
22
23/// A common trait implemented by all garbage-collected reference types.
24///
25/// This is a sealed trait, and may not be implemented for any types outside of
26/// the `wasmtime` crate.
27pub trait GcRef: GcRefImpl {}
28
29impl<T> GcRef for T where T: GcRefImpl {}
30
31/// A trait implemented for GC references that are guaranteed to be rooted:
32///
33/// * [`Rooted<T>`][crate::Rooted]
34/// * [`OwnedRooted<T>`][crate::OwnedRooted]
35///
36/// You can use this to abstract over the different kinds of rooted GC
37/// references. Note that `Deref<Target = T>` is a supertrait for
38/// `RootedGcRef<T>`, so all rooted GC references deref to their underlying `T`,
39/// allowing you to call its methods.
40///
41/// This is a sealed trait, and may not be implemented for any types outside of
42/// the `wasmtime` crate.
43pub trait RootedGcRef<T>: RootedGcRefImpl<T> + Deref<Target = T>
44where
45 T: GcRef,
46{
47}
48
49impl<T, U> RootedGcRef<T> for U
50where
51 T: GcRef,
52 U: RootedGcRefImpl<T> + Deref<Target = T>,
53{
54}
55
56/// An error returned when attempting to allocate a GC-managed object, but the
57/// GC heap is out of memory.
58///
59/// This error wraps an inner `T` value -- which is the host value, if any, that
60/// was passed to [`ExternRef::new`][crate::ExternRef::new] -- and you can
61/// recover this value via the
62/// [`into_inner`][crate::GcHeapOutOfMemory::into_inner] method. This lets you
63/// try to allocate the `externref` again, after performing a GC to hopefully
64/// free up space in the heap, or otherwise do whatever you want with the inner
65/// value.
66///
67/// For errors that occur when attempting to allocate non-`externref` objects
68/// when the GC heap is at capacity, the `T` type parameter is just the unit
69/// type `()`.
70pub struct GcHeapOutOfMemory<T> {
71 inner: T,
72 bytes_needed: u64,
73}
74
75impl<T> fmt::Debug for GcHeapOutOfMemory<T> {
76 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
77 fmt::Display::fmt(self, f)
78 }
79}
80
81impl<T> fmt::Display for GcHeapOutOfMemory<T> {
82 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
83 write!(
84 f,
85 "GC heap out of memory: no capacity for allocation of {} bytes",
86 self.bytes_needed
87 )
88 }
89}
90
91impl<T> core::error::Error for GcHeapOutOfMemory<T> {}
92
93impl<T> GcHeapOutOfMemory<T> {
94 pub(crate) fn new(inner: T, bytes_needed: u64) -> Self {
95 Self {
96 inner,
97 bytes_needed,
98 }
99 }
100
101 #[cfg(feature = "gc")]
102 pub(crate) fn bytes_needed(&self) -> u64 {
103 self.bytes_needed
104 }
105
106 #[cfg(feature = "gc")]
107 pub(crate) fn map_inner<U>(self, f: impl FnOnce(T) -> U) -> GcHeapOutOfMemory<U> {
108 GcHeapOutOfMemory {
109 inner: f(self.inner),
110 bytes_needed: self.bytes_needed,
111 }
112 }
113
114 /// Recover this error's inner host value.
115 pub fn into_inner(self) -> T {
116 self.inner
117 }
118
119 /// Take this error's inner host value, but also retain this
120 /// `GcHeapOutOfMemory` with `T` replaced with `()`.
121 ///
122 /// This allows you to both extract the inner `T` if necessary, and also
123 /// pass the `GcHeapOutOfMemory` error to [`Store::gc`][crate::Store::gc]
124 /// calls.
125 pub fn take_inner(self) -> (T, GcHeapOutOfMemory<()>) {
126 (self.inner, GcHeapOutOfMemory::new((), self.bytes_needed))
127 }
128}