Skip to content

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

Add a tunable knob for the GC heap initial size (#13841)

Alex Crichtonb62ac14e665c
diff --git a/crates/cli-flags/src/lib.rs b/crates/cli-flags/src/lib.rs
index 35c309b60a..9333c256cd 100644
--- a/crates/cli-flags/src/lib.rs
+++ b/crates/cli-flags/src/lib.rs
@@ -86,6 +86,9 @@ wasmtime_option_group! {
/// Size, in bytes, of guard pages for the GC heap.
pub gc_heap_guard_size: Option<u64>,
+ /// Initial allocated size for the GC heap.
+ pub gc_heap_initial_size: Option<u64>,
+
/// Indicates whether an unmapped region of memory is placed before all
/// linear memories.
pub guard_before_linear_memory: Option<bool>,
@@ -977,6 +980,11 @@ impl CommonOptions {
if let Some(size) = self.opts.gc_heap_reservation_for_growth {
config.gc_heap_reservation_for_growth(size);
}
+
+ if let Some(size) = self.opts.gc_heap_initial_size {
+ config.gc_heap_initial_size(size);
+ }
+
if let Some(enable) = self.opts.table_lazy_init {
config.table_lazy_init(enable);
}
@@ -1329,6 +1337,7 @@ impl CommonOptions {
gc_heap_reservation: Some(engine.get_gc_heap_reservation()),
gc_heap_reservation_for_growth: Some(engine.get_gc_heap_reservation_for_growth()),
gc_heap_guard_size: Some(engine.get_gc_heap_guard_size()),
+ gc_heap_initial_size: Some(engine.get_gc_heap_initial_size()),
guard_before_linear_memory: Some(engine.get_guard_before_linear_memory()),
table_lazy_init: Some(engine.get_table_lazy_init()),
memory_init_cow: Some(engine.get_memory_init_cow()),
diff --git a/crates/environ/src/tunables.rs b/crates/environ/src/tunables.rs
index d67f59fbcc..37efb27a0c 100644
--- a/crates/environ/src/tunables.rs
+++ b/crates/environ/src/tunables.rs
@@ -179,6 +179,9 @@ define_tunables! {
/// heaps.
pub gc_heap_reservation_for_growth: u64,
+ /// The size, in bytes, to set as the minimum for GC heaps.
+ pub gc_heap_initial_size: u64,
+
/// Whether or not GC heaps are allowed to be reallocated after initial
/// allocation at runtime.
///
@@ -279,6 +282,7 @@ impl Tunables {
gc_heap_guard_size: 0,
gc_heap_reservation_for_growth: 0,
gc_heap_may_move: true,
+ gc_heap_initial_size: 0,
metadata_for_internal_asserts: false,
metadata_for_gc_heap_corruption: true,
branch_hinting: false,
@@ -341,15 +345,17 @@ impl Tunables {
/// Get the GC heap's memory type, given our configured tunables.
pub fn gc_heap_memory_type(&self) -> Memory {
+ // We *could* try to match the target architecture's page size, but that
+ // would require exercising a page size for memories that we don't
+ // otherwise support for Wasm; we conservatively avoid that, and just
+ // use the default Wasm page size, for now.
+ let page_size_log2 = 16;
+ let min = self.gc_heap_initial_size.div_ceil(1 << page_size_log2);
Memory {
idx_type: IndexType::I32,
- limits: Limits { min: 0, max: None },
+ limits: Limits { min, max: None },
shared: false,
- // We *could* try to match the target architecture's page size, but that
- // would require exercising a page size for memories that we don't
- // otherwise support for Wasm; we conservatively avoid that, and just
- // use the default Wasm page size, for now.
- page_size_log2: 16,
+ page_size_log2,
}
}
}
diff --git a/crates/fuzzing/src/generators/config.rs b/crates/fuzzing/src/generators/config.rs
index d91715640c..32e52e1144 100644
--- a/crates/fuzzing/src/generators/config.rs
+++ b/crates/fuzzing/src/generators/config.rs
@@ -862,7 +862,7 @@ impl WasmtimeConfig {
// When using the pooling allocator, GC heap tunables must match memory
// tunables.
- if let InstanceAllocationStrategy::Pooling(_) = &self.strategy {
+ if let InstanceAllocationStrategy::Pooling(pcfg) = &self.strategy {
let reservation = mcfg.gc_heap_reservation.max(mcfg.memory_reservation);
mcfg.gc_heap_reservation = reservation;
mcfg.memory_reservation = reservation;
@@ -880,6 +880,12 @@ impl WasmtimeConfig {
// memory_may_move is not in MemoryConfig, but gc_heap_may_move
// must not conflict. Set it to None so the default matches.
mcfg.gc_heap_may_move = None;
+
+ // Don't let the initial size of a GC heap exceed the maximum
+ // allowed by the pooling allocator.
+ if let Some(amt) = mcfg.gc_heap_initial_size {
+ mcfg.gc_heap_initial_size = Some(amt.min(pcfg.max_memory_size as u64));
+ }
}
if !self.debug_symbols {
diff --git a/crates/fuzzing/src/generators/memory.rs b/crates/fuzzing/src/generators/memory.rs
index ea36ad3011..11c1de0401 100644
--- a/crates/fuzzing/src/generators/memory.rs
+++ b/crates/fuzzing/src/generators/memory.rs
@@ -128,6 +128,7 @@ pub struct MemoryConfig {
pub gc_heap_guard_size: Option<u64>,
pub gc_heap_reservation_for_growth: Option<u64>,
pub gc_heap_may_move: Option<bool>,
+ pub gc_heap_initial_size: Option<u64>,
}
impl<'a> Arbitrary<'a> for MemoryConfig {
@@ -152,6 +153,7 @@ impl<'a> Arbitrary<'a> for MemoryConfig {
gc_heap_guard_size: interesting_virtual_memory_size(u, 32)?,
gc_heap_reservation_for_growth: interesting_virtual_memory_size(u, 30)?,
gc_heap_may_move: u.arbitrary()?,
+ gc_heap_initial_size: interesting_virtual_memory_size(u, 22)?,
})
}
}
@@ -195,6 +197,7 @@ impl MemoryConfig {
cfg.opts.gc_heap_guard_size = self.gc_heap_guard_size;
cfg.opts.gc_heap_reservation_for_growth = self.gc_heap_reservation_for_growth;
cfg.opts.gc_heap_may_move = self.gc_heap_may_move;
+ cfg.opts.gc_heap_initial_size = self.gc_heap_initial_size;
if let Some(enable) = self.cranelift_enable_heap_access_spectre_mitigations {
cfg.codegen.cranelift.push((
diff --git a/crates/wasmtime/src/config.rs b/crates/wasmtime/src/config.rs
index 9b0bca8e25..9c39590b9f 100644
--- a/crates/wasmtime/src/config.rs
+++ b/crates/wasmtime/src/config.rs
@@ -1414,6 +1414,38 @@ impl Config {
self
}
+ /// Configures the initial size, in bytes, of each store's GC heap.
+ ///
+ /// By default all GC heaps start out at 0 bytes in size and must grow
+ /// upwards from there. Growth happens incrementally as GC pressure happens
+ /// and memory runs out. The amount being grown by is additionally a
+ /// heuristic of the size of the failed allocation. By providing an initial
+ /// size of a store's GC heap embedders can more tightly control initial
+ /// parameters to optimize workloads that might have a predictable pattern.
+ /// For example if workloads frequently have less than a certain threshold
+ /// of size then that could be configured as the initial size here to avoid
+ /// growths happening over time.
+ ///
+ /// Note that like WebAssembly linear memories the GC heap does not start
+ /// with committed memory equal to this size. Instead memory is reserved,
+ /// but then lazily allocated by the OS on access. In other words it should
+ /// be relatively cheap to increase this value to help amortize initial
+ /// startup cost of wasm modules.
+ ///
+ /// The `bytes` size is rounded up to the GC heap's page size.
+ ///
+ /// This only configures the initially-allocated size of the GC heap; the
+ /// heap can still grow beyond it on demand. It is separate from
+ /// [`Config::gc_heap_reservation`], which configures the size of the
+ /// virtual-memory reservation (and therefore how far the heap can grow
+ /// in place).
+ ///
+ /// The default value for this is 0.
+ pub fn gc_heap_initial_size(&mut self, bytes: u64) -> &mut Self {
+ self.tunables.gc_heap_initial_size = Some(bytes);
+ self
+ }
+
/// Creates a default profiler based on the profiling strategy chosen.
///
/// Profiler creation calls the type's default initializer where the purpose is
@@ -4757,6 +4789,11 @@ impl Engine {
self.tunables().gc_heap_reservation
}
+ /// Returns the configured [`Config::gc_heap_initial_size`] value.
+ pub fn get_gc_heap_initial_size(&self) -> u64 {
+ self.tunables().gc_heap_initial_size
+ }
+
/// Returns the configured [`Config::gc_heap_reservation_for_growth`] value.
pub fn get_gc_heap_reservation_for_growth(&self) -> u64 {
self.tunables().gc_heap_reservation_for_growth
diff --git a/crates/wasmtime/src/engine/serialization.rs b/crates/wasmtime/src/engine/serialization.rs
index ceb9b154a0..cc91db370f 100644
--- a/crates/wasmtime/src/engine/serialization.rs
+++ b/crates/wasmtime/src/engine/serialization.rs
@@ -334,6 +334,7 @@ impl Metadata<'_> {
gc_heap_reservation,
gc_heap_guard_size,
gc_heap_may_move,
+ gc_heap_initial_size,
// This doesn't affect compilation, it's just a runtime setting.
gc_heap_reservation_for_growth: _,
@@ -433,6 +434,11 @@ impl Metadata<'_> {
other.gc_heap_guard_size,
"GC heap guard size",
)?;
+ Self::check_int(
+ gc_heap_initial_size,
+ other.gc_heap_initial_size,
+ "GC heap initial size",
+ )?;
Self::check_bool(gc_heap_may_move, other.gc_heap_may_move, "GC heap may move")?;
Ok(())
diff --git a/crates/wasmtime/src/runtime/store.rs b/crates/wasmtime/src/runtime/store.rs
index 368d466440..78c46017b6 100644
--- a/crates/wasmtime/src/runtime/store.rs
+++ b/crates/wasmtime/src/runtime/store.rs
@@ -1842,6 +1842,7 @@ impl StoreOpaque {
let engine = store.engine();
let mem_ty = engine.tunables().gc_heap_memory_type();
+
ensure!(
engine.features().gc_types(),
"cannot allocate a GC store when GC is disabled at configuration time"
diff --git a/crates/wasmtime/src/runtime/store/gc.rs b/crates/wasmtime/src/runtime/store/gc.rs
index 88916704c5..419face962 100644
--- a/crates/wasmtime/src/runtime/store/gc.rs
+++ b/crates/wasmtime/src/runtime/store/gc.rs
@@ -929,6 +929,7 @@ fn should_collect_first(
#[cfg(test)]
mod tests {
use super::should_collect_first;
+ use crate::{AsContextMut, Config, Engine, ExternRef, Result, Store};
#[test]
fn test_should_collect_first() {
@@ -966,4 +967,17 @@ mod tests {
// grow first.
assert_eq!(should_collect_first(16, 1024, 512), false);
}
+
+ #[test]
+ fn gc_heap_initial_size() -> Result<()> {
+ let mut config = Config::new();
+ config.gc_heap_initial_size(1 << 20);
+ let engine = Engine::new(&config)?;
+ let mut store = Store::new(&engine, ());
+ ExternRef::new(&mut store, 1)?;
+
+ let gc_store = store.as_context_mut().0.unwrap_gc_store();
+ assert_eq!(gc_store.gc_heap_capacity(), 1 << 20);
+ Ok(())
+ }
}
diff --git a/tests/all/gc.rs b/tests/all/gc.rs
index 28b6b8880a..3058855e33 100644
--- a/tests/all/gc.rs
+++ b/tests/all/gc.rs
@@ -3774,3 +3774,17 @@ fn pooling_gc_heap_failure_does_not_leak_memory_slot() -> Result<()> {
Ok(())
}
+
+#[test]
+fn initial_size_larger_than_reservation() -> Result<()> {
+ // This shouldn't panic/corrupt/etc, it should just allocate a larger heap.
+ let mut config = Config::new();
+ config.gc_heap_initial_size(4096 * 20);
+ config.gc_heap_reservation(4096);
+ let engine = Engine::new(&config)?;
+
+ let mut store = Store::new(&engine, ());
+ ExternRef::new(&mut store, 1)?;
+
+ Ok(())
+}