Skip to content

A lightweight WebAssembly runtime that is fast, secure, and standards-compliant

Add a public method to grow the per-store GC heap (#14341)

Alex Crichton358ee7665bff
diff --git a/crates/wasmtime/src/runtime/store/async_.rs b/crates/wasmtime/src/runtime/store/async_.rs
index 09a98b24c5..dd7cccfff4 100644
--- a/crates/wasmtime/src/runtime/store/async_.rs
+++ b/crates/wasmtime/src/runtime/store/async_.rs
@@ -104,6 +104,16 @@ impl<T> Store<T> {
StoreContextMut(&mut self.inner).gc_async(why).await
}
+ /// Manually grow the GC heap by at least `bytes` bytes.
+ ///
+ /// For more information, see the documentation of [`Store::gc_heap_grow`].
+ #[cfg(feature = "gc")]
+ pub async fn gc_heap_grow_async(&mut self, bytes: u64) -> Result<()> {
+ StoreContextMut(&mut self.inner)
+ .gc_heap_grow_async(bytes)
+ .await
+ }
+
/// Configures epoch-deadline expiration to yield to the async
/// caller and the update the deadline.
///
@@ -156,6 +166,17 @@ impl<'a, T> StoreContextMut<'a, T> {
Ok(())
}
+ /// Manually grow the GC heap by at least `bytes` bytes.
+ ///
+ /// For more information, see the documentation of [`Store::gc_heap_grow`].
+ #[cfg(feature = "gc")]
+ pub async fn gc_heap_grow_async(&mut self, bytes: u64) -> Result<()> {
+ let (mut limiter, store) = self.0.resource_limiter_and_store_opaque();
+ store
+ .grow_gc_heap(limiter.as_mut(), bytes, crate::store::Asyncness::Yes)
+ .await
+ }
+
/// Configures epoch-deadline expiration to yield to the async
/// caller and the update the deadline.
///
diff --git a/crates/wasmtime/src/runtime/store/gc.rs b/crates/wasmtime/src/runtime/store/gc.rs
index 364249346c..5c84a41807 100644
--- a/crates/wasmtime/src/runtime/store/gc.rs
+++ b/crates/wasmtime/src/runtime/store/gc.rs
@@ -95,6 +95,36 @@ impl<T> Store<T> {
self.inner.gc_heap_capacity()
}
+ /// Manually grow the GC heap by at least `bytes` bytes.
+ ///
+ /// This method will attempt to increase the size of the GC heap used for GC
+ /// objects by at least `bytes` bytes. The current capacity of the GC heap
+ /// can be determined by looking at [`Store::gc_heap_capacity`].
+ ///
+ /// This method can be useful, for example, to pre-allocate space in the GC
+ /// heap for guests that are known to have GC-heavy workloads. This can help
+ /// amortize startup costs in some situations.
+ ///
+ /// Note that GC heap capacity does not mean that an `(array i8)` of size
+ /// equal to the heap's capacity will succeed. Wasmtime's GC implementations
+ /// are responsible for how the heap is used and divvy'd up. As a result
+ /// the growth here does not have a precise semantic meaning and instead
+ /// it's recommended to primarily use this for performance tuning.
+ ///
+ /// # Errors
+ ///
+ /// GC heap growth is a resource-consuming operation that can fail for a
+ /// number of reasons:
+ ///
+ /// * The OS might reject growth of the GC heap.
+ /// * The GC heap's configuration may not allow it to grow further.
+ /// * The store's resource limiter might reject the growth.
+ /// * This method was used when the [`Store::gc_heap_grow_async`] method
+ /// must be used instead.
+ pub fn gc_heap_grow(&mut self, bytes: u64) -> Result<()> {
+ StoreContextMut(&mut self.inner).gc_heap_grow(bytes)
+ }
+
/// Set an exception as the currently pending exception, and
/// return an error that propagates the throw.
///
@@ -166,6 +196,14 @@ impl<'a, T> StoreContextMut<'a, T> {
Ok(())
}
+ /// Manually grow the GC heap by at least `bytes` bytes.
+ ///
+ /// For more information, see the documentation of [`Store::gc_heap_grow`].
+ pub fn gc_heap_grow(&mut self, bytes: u64) -> Result<()> {
+ let (mut limiter, store) = self.0.validate_sync_resource_limiter_and_store_opaque()?;
+ vm::assert_ready(store.grow_gc_heap(limiter.as_mut(), bytes, crate::store::Asyncness::No))
+ }
+
/// Set an exception as the currently pending exception, and
/// return an error that propagates the throw.
///
@@ -275,7 +313,7 @@ impl StoreOpaque {
/// Returns an error if growing the GC heap fails.
pub(crate) async fn grow_gc_heap(
&mut self,
- limiter: Option<&mut StoreResourceLimiter<'_>>,
+ mut limiter: Option<&mut StoreResourceLimiter<'_>>,
bytes_needed: u64,
asyncness: Asyncness,
) -> Result<()> {
@@ -302,6 +340,9 @@ impl StoreOpaque {
);
}
+ // Make sure the GC heap is actually allocated to get grown.
+ self.ensure_gc_store(limiter.as_deref_mut()).await?;
+
let page_size = self.engine().tunables().gc_heap_memory_type().page_size();
// Take the GC heap's underlying memory out of the GC heap, attempt to
diff --git a/tests/all/gc.rs b/tests/all/gc.rs
index 97c224cc2a..65359fe1c8 100644
--- a/tests/all/gc.rs
+++ b/tests/all/gc.rs
@@ -4249,3 +4249,17 @@ fn table_fill_null_barriers_ok() -> Result<()> {
Ok(())
}
+
+#[tokio::test]
+async fn manually_grow_gc_heap() -> Result<()> {
+ let engine = Engine::default();
+ let mut store = Store::new(&engine, ());
+ assert_eq!(store.gc_heap_capacity(), 0);
+ store.gc_heap_grow(1)?;
+ assert_eq!(store.gc_heap_capacity(), 1 << 16);
+ store.gc_heap_grow(1)?;
+ assert_eq!(store.gc_heap_capacity(), 2 << 16);
+ store.gc_heap_grow_async(1).await?;
+ assert_eq!(store.gc_heap_capacity(), 4 << 16);
+ Ok(())
+}