Skip to main content

wasmtime/runtime/gc/enabled/
arrayref.rs

1//! Working with GC `array` objects.
2
3use crate::runtime::vm::VMGcRef;
4use crate::store::{Asyncness, StoreId, StoreResourceLimiter};
5#[cfg(feature = "async")]
6use crate::vm::VMStore;
7use crate::vm::{self, VMArrayRef, VMGcHeader};
8use crate::{AnyRef, FieldType};
9use crate::{
10    ArrayType, AsContext, AsContextMut, EqRef, GcHeapOutOfMemory, GcRefImpl, GcRootIndex, HeapType,
11    OwnedRooted, RefType, Rooted, Val, ValRaw, ValType, WasmTy, bail_bug,
12    prelude::*,
13    store::{AutoAssertNoGc, StoreContext, StoreOpaque},
14};
15use core::mem::{self, MaybeUninit};
16use wasmtime_environ::{GcArrayLayout, VMGcKind, VMSharedTypeIndex};
17
18/// An allocator for a particular Wasm GC array type.
19///
20/// Every `ArrayRefPre` is associated with a particular [`Store`][crate::Store]
21/// and a particular [`ArrayType`][crate::ArrayType].
22///
23/// Reusing an allocator across many allocations amortizes some per-type runtime
24/// overheads inside Wasmtime. An `ArrayRefPre` is to `ArrayRef`s as an
25/// `InstancePre` is to `Instance`s.
26///
27/// # Example
28///
29/// ```
30/// use wasmtime::*;
31///
32/// # fn foo() -> Result<()> {
33/// let mut config = Config::new();
34/// config.wasm_function_references(true);
35/// config.wasm_gc(true);
36///
37/// let engine = Engine::new(&config)?;
38/// let mut store = Store::new(&engine, ());
39///
40/// // Define an array type.
41/// let array_ty = ArrayType::new(
42///    store.engine(),
43///    FieldType::new(Mutability::Var, ValType::I32.into()),
44/// );
45///
46/// // Create an allocator for the array type.
47/// let allocator = ArrayRefPre::new(&mut store, array_ty);
48///
49/// {
50///     let mut scope = RootScope::new(&mut store);
51///
52///     // Allocate a bunch of instances of our array type using the same
53///     // allocator! This is faster than creating a new allocator for each
54///     // instance we want to allocate.
55///     for i in 0..10 {
56///         let len = 42;
57///         let elem = Val::I32(36);
58///         ArrayRef::new(&mut scope, &allocator, &elem, len)?;
59///     }
60/// }
61/// # Ok(())
62/// # }
63/// # let _ = foo();
64/// ```
65pub struct ArrayRefPre {
66    store_id: StoreId,
67    ty: ArrayType,
68}
69
70impl ArrayRefPre {
71    /// Create a new `ArrayRefPre` that is associated with the given store
72    /// and type.
73    ///
74    /// # Panics
75    ///
76    /// Panics if `ty` was not created with the same
77    /// [`Engine`](crate::Engine) as `store`.
78    pub fn new(mut store: impl AsContextMut, ty: ArrayType) -> Self {
79        Self::_new(store.as_context_mut().0, ty)
80    }
81
82    pub(crate) fn _new(store: &mut StoreOpaque, ty: ArrayType) -> Self {
83        store.insert_gc_host_alloc_type(ty.registered_type().clone());
84        let store_id = store.id();
85        ArrayRefPre { store_id, ty }
86    }
87
88    pub(crate) fn layout(&self) -> &GcArrayLayout {
89        self.ty
90            .registered_type()
91            .layout()
92            .expect("array types have a layout")
93            .unwrap_array()
94    }
95
96    pub(crate) fn type_index(&self) -> VMSharedTypeIndex {
97        self.ty.registered_type().index()
98    }
99}
100
101/// A reference to a GC-managed `array` instance.
102///
103/// WebAssembly `array`s are a sequence of elements of some homogeneous
104/// type. The elements length is determined at allocation time — two instances
105/// of the same array type may have different lengths — but, once allocated, an
106/// array's length can never be resized. An array's elements are mutable or
107/// constant, depending on the array's type. This determines whether any array
108/// element can be assigned a new value or not. Each element is either an
109/// unpacked [`Val`][crate::Val] or a packed 8-/16-bit integer. Array elements
110/// are dynamically accessed via indexing; out-of-bounds accesses result in
111/// traps.
112///
113/// Like all WebAssembly references, these are opaque and unforgeable to Wasm:
114/// they cannot be faked and Wasm cannot, for example, cast the integer
115/// `0x12345678` into a reference, pretend it is a valid `arrayref`, and trick
116/// the host into dereferencing it and segfaulting or worse.
117///
118/// Note that you can also use `Rooted<ArrayRef>` and `OwnedRooted<ArrayRef>`
119/// as a type parameter with [`Func::typed`][crate::Func::typed]- and
120/// [`Func::wrap`][crate::Func::wrap]-style APIs.
121///
122/// # Example
123///
124/// ```
125/// use wasmtime::*;
126///
127/// # fn foo() -> Result<()> {
128/// let mut config = Config::new();
129/// config.wasm_function_references(true);
130/// config.wasm_gc(true);
131///
132/// let engine = Engine::new(&config)?;
133/// let mut store = Store::new(&engine, ());
134///
135/// // Define the type for an array of `i32`s.
136/// let array_ty = ArrayType::new(
137///    store.engine(),
138///    FieldType::new(Mutability::Var, ValType::I32.into()),
139/// );
140///
141/// // Create an allocator for the array type.
142/// let allocator = ArrayRefPre::new(&mut store, array_ty);
143///
144/// {
145///     let mut scope = RootScope::new(&mut store);
146///
147///     // Allocate an instance of the array type.
148///     let len = 36;
149///     let elem = Val::I32(42);
150///     let my_array = match ArrayRef::new(&mut scope, &allocator, &elem, len) {
151///         Ok(s) => s,
152///         Err(e) => match e.downcast::<GcHeapOutOfMemory<()>>() {
153///             // If the heap is out of memory, then do a GC to free up some
154///             // space and try again.
155///             Ok(oom) => {
156///                 // Do a GC! Note: in an async context, you'd want to do
157///                 // `scope.as_context_mut().gc_async().await`.
158///                 scope.as_context_mut().gc(Some(&oom))?;
159///
160///                 // Try again. If the GC heap is still out of memory, then we
161///                 // weren't able to free up resources for this allocation, so
162///                 // propagate the error.
163///                 ArrayRef::new(&mut scope, &allocator, &elem, len)?
164///             }
165///             // Propagate any other kind of error.
166///             Err(e) => return Err(e),
167///         }
168///     };
169///
170///     // That instance's elements should have the initial value.
171///     for i in 0..len {
172///         let val = my_array.get(&mut scope, i)?.unwrap_i32();
173///         assert_eq!(val, 42);
174///     }
175///
176///     // We can set an element to a new value because the type was defined with
177///     // mutable elements (as opposed to const).
178///     my_array.set(&mut scope, 3, Val::I32(1234))?;
179///     let new_val = my_array.get(&mut scope, 3)?.unwrap_i32();
180///     assert_eq!(new_val, 1234);
181/// }
182/// # Ok(())
183/// # }
184/// # foo().unwrap();
185/// ```
186#[derive(Debug)]
187#[repr(transparent)]
188pub struct ArrayRef {
189    pub(super) inner: GcRootIndex,
190}
191
192unsafe impl GcRefImpl for ArrayRef {
193    fn transmute_ref(index: &GcRootIndex) -> &Self {
194        // Safety: `ArrayRef` is a newtype of a `GcRootIndex`.
195        let me: &Self = unsafe { mem::transmute(index) };
196
197        // Assert we really are just a newtype of a `GcRootIndex`.
198        assert!(matches!(
199            me,
200            Self {
201                inner: GcRootIndex { .. },
202            }
203        ));
204
205        me
206    }
207}
208
209impl Rooted<ArrayRef> {
210    /// Upcast this `arrayref` into an `anyref`.
211    #[inline]
212    pub fn to_anyref(self) -> Rooted<AnyRef> {
213        self.unchecked_cast()
214    }
215
216    /// Upcast this `arrayref` into an `eqref`.
217    #[inline]
218    pub fn to_eqref(self) -> Rooted<EqRef> {
219        self.unchecked_cast()
220    }
221}
222
223impl OwnedRooted<ArrayRef> {
224    /// Upcast this `arrayref` into an `anyref`.
225    #[inline]
226    pub fn to_anyref(self) -> OwnedRooted<AnyRef> {
227        self.unchecked_cast()
228    }
229
230    /// Upcast this `arrayref` into an `eqref`.
231    #[inline]
232    pub fn to_eqref(self) -> OwnedRooted<EqRef> {
233        self.unchecked_cast()
234    }
235}
236
237/// An iterator for elements in `ArrayRef::new[_async].
238///
239/// NB: We can't use `iter::repeat(elem).take(len)` because that doesn't
240/// implement `ExactSizeIterator`.
241#[derive(Clone)]
242struct RepeatN<'a>(&'a Val, u32);
243
244impl<'a> Iterator for RepeatN<'a> {
245    type Item = &'a Val;
246
247    fn next(&mut self) -> Option<Self::Item> {
248        if self.1 == 0 {
249            None
250        } else {
251            self.1 -= 1;
252            Some(self.0)
253        }
254    }
255
256    fn size_hint(&self) -> (usize, Option<usize>) {
257        let len = self.len();
258        (len, Some(len))
259    }
260}
261
262impl ExactSizeIterator for RepeatN<'_> {
263    fn len(&self) -> usize {
264        usize::try_from(self.1).unwrap()
265    }
266}
267
268impl ArrayRef {
269    /// Allocate a new `array` of the given length, with every element
270    /// initialized to `elem`.
271    ///
272    /// For example, `ArrayRef::new(ctx, pre, &Val::I64(9), 3)` allocates the
273    /// array `[9, 9, 9]`.
274    ///
275    /// This is similar to the `array.new` instruction.
276    ///
277    /// # Automatic Garbage Collection
278    ///
279    /// If the GC heap is at capacity, and there isn't room for allocating this
280    /// new array, then this method will automatically trigger a synchronous
281    /// collection in an attempt to free up space in the GC heap.
282    ///
283    /// # Errors
284    ///
285    /// If the given `elem` value's type does not match the `allocator`'s array
286    /// type's element type, an error is returned.
287    ///
288    /// If the `elem` value holds a GC reference that is not rooted, an error is
289    /// returned, since allocating may collect garbage; see
290    /// [`Val::ensure_rooted`].
291    ///
292    /// If the allocation cannot be satisfied because the GC heap is currently
293    /// out of memory, then a [`GcHeapOutOfMemory<()>`][crate::GcHeapOutOfMemory]
294    /// error is returned. The allocation might succeed on a second attempt if
295    /// you drop some rooted GC references and try again.
296    ///
297    /// If `store` is configured with a
298    /// [`ResourceLimiterAsync`](crate::ResourceLimiterAsync) then an error will
299    /// be returned because [`ArrayRef::new_async`] should be used instead.
300    ///
301    /// # Panics
302    ///
303    /// Panics if either the allocator or the `elem` value is not associated
304    /// with the given store.
305    pub fn new(
306        mut store: impl AsContextMut,
307        allocator: &ArrayRefPre,
308        elem: &Val,
309        len: u32,
310    ) -> Result<Rooted<ArrayRef>> {
311        let (mut limiter, store) = store
312            .as_context_mut()
313            .0
314            .validate_sync_resource_limiter_and_store_opaque()?;
315        vm::assert_ready(Self::_new_async(
316            store,
317            limiter.as_mut(),
318            allocator,
319            elem,
320            len,
321            Asyncness::No,
322        ))
323    }
324
325    /// Asynchronously allocate a new `array` of the given length, with every
326    /// element initialized to `elem`.
327    ///
328    /// For example, `ArrayRef::new(ctx, pre, &Val::I64(9), 3)` allocates the
329    /// array `[9, 9, 9]`.
330    ///
331    /// This is similar to the `array.new` instruction.
332    ///
333    /// # Automatic Garbage Collection
334    ///
335    /// If the GC heap is at capacity, and there isn't room for allocating this
336    /// new array, then this method will automatically trigger a asynchronous
337    /// collection in an attempt to free up space in the GC heap.
338    ///
339    /// # Errors
340    ///
341    /// If the given `elem` value's type does not match the `allocator`'s array
342    /// type's element type, an error is returned.
343    ///
344    /// If the `elem` value holds a GC reference that is not rooted, an error is
345    /// returned, since allocating may collect garbage; see
346    /// [`Val::ensure_rooted`].
347    ///
348    /// If the allocation cannot be satisfied because the GC heap is currently
349    /// out of memory, then a [`GcHeapOutOfMemory<()>`][crate::GcHeapOutOfMemory]
350    /// error is returned. The allocation might succeed on a second attempt if
351    /// you drop some rooted GC references and try again.
352    ///
353    /// # Panics
354    ///
355    /// Panics if your engine is not configured for async; use
356    /// [`ArrayRef::new_async`][crate::ArrayRef::new_async] to perform
357    /// synchronous allocation instead.
358    ///
359    /// Panics if either the allocator or the `elem` value is not associated
360    /// with the given store.
361    #[cfg(feature = "async")]
362    pub async fn new_async(
363        mut store: impl AsContextMut,
364        allocator: &ArrayRefPre,
365        elem: &Val,
366        len: u32,
367    ) -> Result<Rooted<ArrayRef>> {
368        let (mut limiter, store) = store.as_context_mut().0.resource_limiter_and_store_opaque();
369        Self::_new_async(
370            store,
371            limiter.as_mut(),
372            allocator,
373            elem,
374            len,
375            Asyncness::Yes,
376        )
377        .await
378    }
379
380    pub(crate) async fn _new_async(
381        store: &mut StoreOpaque,
382        limiter: Option<&mut StoreResourceLimiter<'_>>,
383        allocator: &ArrayRefPre,
384        elem: &Val,
385        len: u32,
386        asyncness: Asyncness,
387    ) -> Result<Rooted<ArrayRef>> {
388        // Allocation may collect garbage, so the element must be rooted.
389        elem.validate_rooted().context("unrooted element value")?;
390        store
391            .retry_after_gc_async(limiter, (), asyncness, |store, ()| {
392                Self::new_from_iter(store, allocator, RepeatN(elem, len))
393            })
394            .await
395    }
396
397    /// Allocate a new array of the given elements.
398    ///
399    /// Does not attempt a GC on OOM; leaves that to callers.
400    fn new_from_iter<'a>(
401        store: &mut StoreOpaque,
402        allocator: &ArrayRefPre,
403        elems: impl Clone + ExactSizeIterator<Item = &'a Val>,
404    ) -> Result<Rooted<ArrayRef>> {
405        assert_eq!(
406            store.id(),
407            allocator.store_id,
408            "attempted to use a `ArrayRefPre` with the wrong store"
409        );
410
411        let len = u32::try_from(elems.len())?;
412
413        // Allocate the array.
414        let arrayref = store
415            .require_gc_store_mut()?
416            .alloc_uninit_array(allocator.type_index(), len, allocator.layout())
417            .context("unrecoverable error when allocating new `arrayref`")?
418            .map_err(|n| GcHeapOutOfMemory::new((), n))?;
419
420        // From this point on, if we get any errors, then the array is not
421        // fully initialized, so we need to eagerly deallocate it before the
422        // next GC where the collector might try to interpret one of the
423        // uninitialized fields as a GC reference.
424        let mut store = AutoAssertNoGc::new(store);
425        match (|| {
426            // Type check the elements here, rather than before allocating, so
427            // that oversized arrays fail without visiting every element.
428            for elem in elems.clone() {
429                elem.ensure_matches_ty(&store, allocator.ty.element_type().unpack())
430                    .context("element type mismatch")?;
431            }
432
433            let elem_ty = allocator.ty.element_type();
434            for (i, elem) in elems.enumerate() {
435                let i = u32::try_from(i)?;
436                debug_assert!(i < len);
437                arrayref.initialize_elem(&mut store, allocator.layout(), &elem_ty, i, *elem)?;
438            }
439            Ok(())
440        })() {
441            Ok(()) => Ok(Rooted::new(&mut store, arrayref.into())),
442            Err(e) => {
443                store
444                    .require_gc_store_mut()?
445                    .dealloc_uninit_array(arrayref)?;
446                Err(e)
447            }
448        }
449    }
450
451    /// Synchronously allocate a new `array` containing the given elements.
452    ///
453    /// For example, `ArrayRef::new_fixed(ctx, pre, &[Val::I64(4), Val::I64(5),
454    /// Val::I64(6)])` allocates the array `[4, 5, 6]`.
455    ///
456    /// This is similar to the `array.new_fixed` instruction.
457    ///
458    /// # Automatic Garbage Collection
459    ///
460    /// If the GC heap is at capacity, and there isn't room for allocating this
461    /// new array, then this method will automatically trigger a synchronous
462    /// collection in an attempt to free up space in the GC heap.
463    ///
464    /// # Errors
465    ///
466    /// If any of the `elems` values' type does not match the `allocator`'s
467    /// array type's element type, an error is returned.
468    ///
469    /// If any of the `elems` values holds a GC reference that is not rooted, an error is
470    /// returned, since allocating may collect garbage; see
471    /// [`Val::ensure_rooted`].
472    ///
473    /// If the allocation cannot be satisfied because the GC heap is currently
474    /// out of memory, then a [`GcHeapOutOfMemory<()>`][crate::GcHeapOutOfMemory]
475    /// error is returned. The allocation might succeed on a second attempt if
476    /// you drop some rooted GC references and try again.
477    ///
478    /// If `store` is configured with a
479    /// [`ResourceLimiterAsync`](crate::ResourceLimiterAsync) then an error
480    /// will be returned because [`ArrayRef::new_fixed_async`] should be used
481    /// instead.
482    ///
483    /// # Panics
484    ///
485    /// Panics if the allocator or any of the `elems` values are not associated
486    /// with the given store.
487    pub fn new_fixed(
488        mut store: impl AsContextMut,
489        allocator: &ArrayRefPre,
490        elems: &[Val],
491    ) -> Result<Rooted<ArrayRef>> {
492        let (mut limiter, store) = store
493            .as_context_mut()
494            .0
495            .validate_sync_resource_limiter_and_store_opaque()?;
496        vm::assert_ready(Self::_new_fixed_async(
497            store,
498            limiter.as_mut(),
499            allocator,
500            elems,
501            Asyncness::No,
502        ))
503    }
504
505    /// Asynchronously allocate a new `array` containing the given elements.
506    ///
507    /// For example, `ArrayRef::new_fixed_async(ctx, pre, &[Val::I64(4),
508    /// Val::I64(5), Val::I64(6)])` allocates the array `[4, 5, 6]`.
509    ///
510    /// This is similar to the `array.new_fixed` instruction.
511    ///
512    /// If your engine is not configured for async, use
513    /// [`ArrayRef::new_fixed`][crate::ArrayRef::new_fixed] to perform
514    /// synchronous allocation.
515    ///
516    /// # Automatic Garbage Collection
517    ///
518    /// If the GC heap is at capacity, and there isn't room for allocating this
519    /// new array, then this method will automatically trigger a synchronous
520    /// collection in an attempt to free up space in the GC heap.
521    ///
522    /// # Errors
523    ///
524    /// If any of the `elems` values' type does not match the `allocator`'s
525    /// array type's element type, an error is returned.
526    ///
527    /// If any of the `elems` values holds a GC reference that is not rooted, an error is
528    /// returned, since allocating may collect garbage; see
529    /// [`Val::ensure_rooted`].
530    ///
531    /// If the allocation cannot be satisfied because the GC heap is currently
532    /// out of memory, then a [`GcHeapOutOfMemory<()>`][crate::GcHeapOutOfMemory]
533    /// error is returned. The allocation might succeed on a second attempt if
534    /// you drop some rooted GC references and try again.
535    ///
536    /// # Panics
537    ///
538    /// Panics if the `store` is not configured for async; use
539    /// [`ArrayRef::new_fixed`][crate::ArrayRef::new_fixed] to perform
540    /// synchronous allocation instead.
541    ///
542    /// Panics if the allocator or any of the `elems` values are not associated
543    /// with the given store.
544    #[cfg(feature = "async")]
545    pub async fn new_fixed_async(
546        mut store: impl AsContextMut,
547        allocator: &ArrayRefPre,
548        elems: &[Val],
549    ) -> Result<Rooted<ArrayRef>> {
550        let (mut limiter, store) = store.as_context_mut().0.resource_limiter_and_store_opaque();
551        Self::_new_fixed_async(store, limiter.as_mut(), allocator, elems, Asyncness::Yes).await
552    }
553
554    pub(crate) async fn _new_fixed_async(
555        store: &mut StoreOpaque,
556        limiter: Option<&mut StoreResourceLimiter<'_>>,
557        allocator: &ArrayRefPre,
558        elems: &[Val],
559        asyncness: Asyncness,
560    ) -> Result<Rooted<ArrayRef>> {
561        // Allocation may collect garbage, so the elements must be rooted.
562        for elem in elems {
563            elem.validate_rooted().context("unrooted element value")?;
564        }
565        store
566            .retry_after_gc_async(limiter, (), asyncness, |store, ()| {
567                Self::new_from_iter(store, allocator, elems.iter())
568            })
569            .await
570    }
571
572    /// Synchronously allocate a new `i8` array initialized from the given bytes.
573    ///
574    /// Unlike [`ArrayRef::new_fixed`], which initializes the array one [`Val`]
575    /// at a time, the element body is filled with a single `memcpy`. The bytes
576    /// are passed as `u8`; their signedness is only observed at read time (e.g.
577    /// `array.get_s` vs `array.get_u`).
578    ///
579    /// # Automatic Garbage Collection
580    ///
581    /// If the GC heap is at capacity, and there isn't room for allocating this
582    /// new array, then this method will automatically trigger a synchronous
583    /// collection in an attempt to free up space in the GC heap.
584    ///
585    /// # Errors
586    ///
587    /// If the `allocator`'s array type does not have `i8` elements, an error is
588    /// returned.
589    ///
590    /// If the allocation cannot be satisfied because the GC heap is currently
591    /// out of memory, then a [`GcHeapOutOfMemory<()>`][crate::GcHeapOutOfMemory]
592    /// error is returned. The allocation might succeed on a second attempt if
593    /// you drop some rooted GC references and try again.
594    ///
595    /// If `store` is configured with a
596    /// [`ResourceLimiterAsync`](crate::ResourceLimiterAsync) then an error will
597    /// be returned because [`ArrayRef::new_from_i8_slice_async`] should be used
598    /// instead.
599    ///
600    /// # Panics
601    ///
602    /// Panics if the allocator is not associated with the given store.
603    pub fn new_from_i8_slice(
604        mut store: impl AsContextMut,
605        allocator: &ArrayRefPre,
606        elems: &[u8],
607    ) -> Result<Rooted<ArrayRef>> {
608        let (mut limiter, store) = store
609            .as_context_mut()
610            .0
611            .validate_sync_resource_limiter_and_store_opaque()?;
612        vm::assert_ready(Self::_new_from_i8_slice_async(
613            store,
614            limiter.as_mut(),
615            allocator,
616            elems,
617            Asyncness::No,
618        ))
619    }
620
621    /// Asynchronously allocate a new `i8` array initialized from the given
622    /// bytes.
623    ///
624    /// This is the `async` equivalent of [`ArrayRef::new_from_i8_slice`]; see
625    /// that method for details. If your engine is not configured for async, use
626    /// [`ArrayRef::new_from_i8_slice`] to perform synchronous allocation.
627    ///
628    /// # Automatic Garbage Collection
629    ///
630    /// If the GC heap is at capacity, and there isn't room for allocating this
631    /// new array, then this method will automatically trigger an asynchronous
632    /// collection in an attempt to free up space in the GC heap.
633    ///
634    /// # Errors
635    ///
636    /// If the `allocator`'s array type does not have `i8` elements, an error is
637    /// returned.
638    ///
639    /// If the allocation cannot be satisfied because the GC heap is currently
640    /// out of memory, then a [`GcHeapOutOfMemory<()>`][crate::GcHeapOutOfMemory]
641    /// error is returned. The allocation might succeed on a second attempt if
642    /// you drop some rooted GC references and try again.
643    ///
644    /// # Panics
645    ///
646    /// Panics if the `store` is not configured for async; use
647    /// [`ArrayRef::new_from_i8_slice`] to perform synchronous allocation
648    /// instead.
649    ///
650    /// Panics if the allocator is not associated with the given store.
651    #[cfg(feature = "async")]
652    pub async fn new_from_i8_slice_async(
653        mut store: impl AsContextMut,
654        allocator: &ArrayRefPre,
655        elems: &[u8],
656    ) -> Result<Rooted<ArrayRef>> {
657        let (mut limiter, store) = store.as_context_mut().0.resource_limiter_and_store_opaque();
658        Self::_new_from_i8_slice_async(store, limiter.as_mut(), allocator, elems, Asyncness::Yes)
659            .await
660    }
661
662    pub(crate) async fn _new_from_i8_slice_async(
663        store: &mut StoreOpaque,
664        limiter: Option<&mut StoreResourceLimiter<'_>>,
665        allocator: &ArrayRefPre,
666        elems: &[u8],
667        asyncness: Asyncness,
668    ) -> Result<Rooted<ArrayRef>> {
669        store
670            .retry_after_gc_async(limiter, (), asyncness, |store, ()| {
671                Self::new_from_i8_slice_inner(store, allocator, elems)
672            })
673            .await
674    }
675
676    /// Allocate a new array initialized from a slice of `i8` bytes.
677    ///
678    /// Does not attempt a GC on OOM; leaves that to callers.
679    fn new_from_i8_slice_inner(
680        store: &mut StoreOpaque,
681        allocator: &ArrayRefPre,
682        elems: &[u8],
683    ) -> Result<Rooted<ArrayRef>> {
684        assert_eq!(
685            store.id(),
686            allocator.store_id,
687            "attempted to use a `ArrayRefPre` with the wrong store"
688        );
689
690        let elem_ty = allocator.ty.element_type();
691        ensure!(
692            elem_ty.is_i8(),
693            "element type mismatch: cannot initialize an array of `{elem_ty}` elements from a slice of `i8`s"
694        );
695
696        let len = u32::try_from(elems.len())?;
697        let layout = allocator.layout();
698
699        let arrayref = store
700            .require_gc_store_mut()?
701            .alloc_uninit_array(allocator.type_index(), len, layout)
702            .context("unrecoverable error when allocating new `arrayref`")?
703            .map_err(|n| GcHeapOutOfMemory::new((), n))?;
704
705        // If the copy failed then the array is not fully initialized, so we
706        // must eagerly deallocate it before the next GC.
707        let mut store = AutoAssertNoGc::new(store);
708        match (|| {
709            store
710                .require_gc_store_mut()?
711                .gc_object_data_mut(arrayref.as_gc_ref())?
712                .copy_from_slice(layout.base_size, elems)
713        })() {
714            Ok(()) => Ok(Rooted::new(&mut store, arrayref.into())),
715            Err(e) => {
716                store
717                    .require_gc_store_mut()?
718                    .dealloc_uninit_array(arrayref)?;
719                Err(e)
720            }
721        }
722    }
723
724    /// Copy this `i8` array's elements into the given byte slice.
725    ///
726    /// Unlike [`ArrayRef::get`], which decodes each element through a [`Val`],
727    /// the whole element body is copied into `dst` with a single `memcpy`. The
728    /// `i8` elements are read out as raw `u8` bytes.
729    ///
730    /// # Errors
731    ///
732    /// If this array does not have `i8` elements, an error is returned.
733    ///
734    /// If `dst`'s length does not equal this array's length, an error is
735    /// returned.
736    ///
737    /// Returns an error if this reference has been unrooted.
738    ///
739    /// # Panics
740    ///
741    /// Panics if this reference is associated with a different store.
742    pub fn copy_to_i8_slice(&self, mut store: impl AsContextMut, dst: &mut [u8]) -> Result<()> {
743        let mut store = AutoAssertNoGc::new(store.as_context_mut().0);
744        assert!(
745            self.comes_from_same_store(&store),
746            "attempted to use an array with the wrong store",
747        );
748
749        let field_ty = self.field_ty(&store)?;
750        let elem_ty = field_ty.element_type();
751        ensure!(
752            elem_ty.is_i8(),
753            "element type mismatch: cannot read an array of `{elem_ty}` elements into a slice of `i8`s"
754        );
755
756        let layout = self.layout(&store)?;
757        let arrayref = self.arrayref(&store)?.unchecked_copy();
758        let len = arrayref.len(&store)?;
759
760        let dst_len = u32::try_from(dst.len())?;
761        ensure!(
762            dst_len == len,
763            "destination slice length is {dst_len} but the array length is {len}",
764        );
765
766        let data = store
767            .require_gc_store_mut()?
768            .gc_object_data(arrayref.as_gc_ref())?;
769        let bytes = data.slice(layout.base_size, len)?;
770        dst.copy_from_slice(bytes);
771        Ok(())
772    }
773
774    #[inline]
775    pub(crate) fn comes_from_same_store(&self, store: &StoreOpaque) -> bool {
776        self.inner.comes_from_same_store(store)
777    }
778
779    /// Get this `arrayref`'s type.
780    ///
781    /// # Errors
782    ///
783    /// Return an error if this reference has been unrooted.
784    ///
785    /// # Panics
786    ///
787    /// Panics if this reference is associated with a different store.
788    pub fn ty(&self, store: impl AsContext) -> Result<ArrayType> {
789        self._ty(store.as_context().0)
790    }
791
792    pub(crate) fn _ty(&self, store: &StoreOpaque) -> Result<ArrayType> {
793        assert!(self.comes_from_same_store(store));
794        let index = self.type_index(store)?;
795        match ArrayType::from_shared_type_index(store.engine(), index) {
796            Some(ty) => Ok(ty),
797            None => bail_bug!("invalid array type index"),
798        }
799    }
800
801    /// Does this `arrayref` match the given type?
802    ///
803    /// That is, is this array's type a subtype of the given type?
804    ///
805    /// # Errors
806    ///
807    /// Return an error if this reference has been unrooted.
808    ///
809    /// # Panics
810    ///
811    /// Panics if this reference is associated with a different store or if the
812    /// type is not associated with the store's engine.
813    pub fn matches_ty(&self, store: impl AsContext, ty: &ArrayType) -> Result<bool> {
814        self._matches_ty(store.as_context().0, ty)
815    }
816
817    pub(crate) fn _matches_ty(&self, store: &StoreOpaque, ty: &ArrayType) -> Result<bool> {
818        assert!(self.comes_from_same_store(store));
819        Ok(self._ty(store)?.matches(ty))
820    }
821
822    pub(crate) fn ensure_matches_ty(&self, store: &StoreOpaque, ty: &ArrayType) -> Result<()> {
823        if !self.comes_from_same_store(store) {
824            bail!("function used with wrong store");
825        }
826        if self._matches_ty(store, ty)? {
827            Ok(())
828        } else {
829            let actual_ty = self._ty(store)?;
830            bail!("type mismatch: expected `(ref {ty})`, found `(ref {actual_ty})`")
831        }
832    }
833
834    /// Get the length of this array.
835    ///
836    /// # Errors
837    ///
838    /// Return an error if this reference has been unrooted.
839    ///
840    /// # Panics
841    ///
842    /// Panics if this reference is associated with a different store.
843    pub fn len(&self, store: impl AsContext) -> Result<u32> {
844        self._len(store.as_context().0)
845    }
846
847    pub(crate) fn _len(&self, store: &StoreOpaque) -> Result<u32> {
848        assert!(self.comes_from_same_store(store));
849        let gc_ref = self.inner.try_gc_ref(store)?;
850        debug_assert!({
851            let header = store.require_gc_store()?.header(gc_ref)?;
852            header.matches_kind(VMGcKind::ArrayRef)
853        });
854        let arrayref = gc_ref.as_arrayref_unchecked();
855        arrayref.len(store)
856    }
857
858    /// Get the values of this array's elements.
859    ///
860    /// Note that `i8` and `i16` element values are zero-extended into
861    /// `Val::I32(_)`s.
862    ///
863    /// GC references are returned as unrooted references
864    /// ([`MaybeRooted::Unrooted`](crate::MaybeRooted::Unrooted)), valid until
865    /// the store's GC heap next changes; root them with
866    /// [`Val::ensure_rooted`] or [`Val::ensure_all_rooted`] to keep them for
867    /// longer.
868    ///
869    /// # Errors
870    ///
871    /// Return an error if this reference has been unrooted.
872    ///
873    /// # Panics
874    ///
875    /// Panics if this reference is associated with a different store.
876    pub fn elems<'a, T: 'static>(
877        &'a self,
878        store: impl Into<StoreContext<'a, T>>,
879    ) -> Result<impl ExactSizeIterator<Item = Val> + 'a> {
880        self._elems(store.into().0)
881    }
882
883    pub(crate) fn _elems<'a>(
884        &'a self,
885        store: &'a StoreOpaque,
886    ) -> Result<impl ExactSizeIterator<Item = Val> + 'a> {
887        assert!(self.comes_from_same_store(store));
888
889        let gc_ref = self.inner.try_gc_ref(store)?;
890        let header = store.require_gc_store()?.header(gc_ref)?;
891        debug_assert!(header.matches_kind(VMGcKind::ArrayRef));
892
893        let len = self._len(store)?;
894
895        return Ok(Elems {
896            arrayref: self,
897            store,
898            index: 0,
899            len,
900        });
901
902        struct Elems<'a> {
903            arrayref: &'a ArrayRef,
904            store: &'a StoreOpaque,
905            index: u32,
906            len: u32,
907        }
908
909        impl Iterator for Elems<'_> {
910            type Item = Val;
911
912            #[inline]
913            fn next(&mut self) -> Option<Self::Item> {
914                let i = self.index;
915                debug_assert!(i <= self.len);
916                if i >= self.len {
917                    return None;
918                }
919                self.index += 1;
920                self.arrayref._get(self.store, i).ok()
921            }
922
923            #[inline]
924            fn size_hint(&self) -> (usize, Option<usize>) {
925                let len = self.len - self.index;
926                let len = usize::try_from(len).unwrap();
927                (len, Some(len))
928            }
929        }
930
931        impl ExactSizeIterator for Elems<'_> {
932            #[inline]
933            fn len(&self) -> usize {
934                let len = self.len - self.index;
935                usize::try_from(len).unwrap()
936            }
937        }
938    }
939
940    fn header<'a>(&self, store: &'a StoreOpaque) -> Result<&'a VMGcHeader> {
941        assert!(self.comes_from_same_store(&store));
942        let gc_ref = self.inner.try_gc_ref(store)?;
943        Ok(store.require_gc_store()?.header(gc_ref)?)
944    }
945
946    fn arrayref<'a>(&self, store: &'a StoreOpaque) -> Result<&'a VMArrayRef> {
947        assert!(self.comes_from_same_store(&store));
948        let gc_ref = self.inner.try_gc_ref(store)?;
949        debug_assert!(self.header(store)?.matches_kind(VMGcKind::ArrayRef));
950        Ok(gc_ref.as_arrayref_unchecked())
951    }
952
953    pub(crate) fn layout(&self, store: &StoreOpaque) -> Result<GcArrayLayout> {
954        assert!(self.comes_from_same_store(&store));
955        let type_index = self.type_index(store)?;
956        super::gc_array_layout(store.engine(), type_index)
957    }
958
959    fn field_ty(&self, store: &StoreOpaque) -> Result<FieldType> {
960        let ty = self._ty(store)?;
961        Ok(ty.field_type())
962    }
963
964    /// Get this array's `index`th element.
965    ///
966    /// Note that `i8` and `i16` field values are zero-extended into
967    /// `Val::I32(_)`s.
968    ///
969    /// GC references are returned as unrooted references
970    /// ([`MaybeRooted::Unrooted`](crate::MaybeRooted::Unrooted)), valid until
971    /// the store's GC heap next changes; root them with
972    /// [`Val::ensure_rooted`] or [`Val::ensure_all_rooted`] to keep them for
973    /// longer.
974    ///
975    /// # Errors
976    ///
977    /// Returns an `Err(_)` if the index is out of bounds or this reference has
978    /// been unrooted.
979    ///
980    /// # Panics
981    ///
982    /// Panics if this reference is associated with a different store.
983    pub fn get(&self, store: impl AsContext, index: u32) -> Result<Val> {
984        self._get(store.as_context().0, index)
985    }
986
987    pub(crate) fn _get(&self, store: &StoreOpaque, index: u32) -> Result<Val> {
988        assert!(
989            self.comes_from_same_store(store),
990            "attempted to use an array with the wrong store",
991        );
992        let arrayref = self.arrayref(store)?;
993        let field_ty = self.field_ty(store)?;
994        let layout = self.layout(store)?;
995        let len = arrayref.len(store)?;
996        ensure!(
997            index < len,
998            "index out of bounds: the length is {len} but the index is {index}"
999        );
1000        arrayref.read_elem(store, &layout, field_ty.element_type(), index)
1001    }
1002
1003    /// Set this array's `index`th element.
1004    ///
1005    /// # Errors
1006    ///
1007    /// Returns an error in the following scenarios:
1008    ///
1009    /// * When given a value of the wrong type, such as trying to write an `f32`
1010    ///   value into an array of `i64` elements.
1011    ///
1012    /// * When the array elements are not mutable.
1013    ///
1014    /// * When `index` is not within the range `0..self.len(ctx)`.
1015    ///
1016    /// * When `value` is a GC reference that has since been unrooted.
1017    ///
1018    /// # Panics
1019    ///
1020    /// Panics if either this reference or the given `value` is associated with
1021    /// a different store.
1022    pub fn set(&self, mut store: impl AsContextMut, index: u32, value: Val) -> Result<()> {
1023        self._set(store.as_context_mut().0, index, value)
1024    }
1025
1026    pub(crate) fn _set(&self, store: &mut StoreOpaque, index: u32, value: Val) -> Result<()> {
1027        assert!(
1028            self.comes_from_same_store(store),
1029            "attempted to use an array with the wrong store",
1030        );
1031        assert!(
1032            value.comes_from_same_store(store),
1033            "attempted to use a value with the wrong store",
1034        );
1035        value
1036            .validate_rooted()
1037            .with_context(|| format!("cannot set element {index}: unrooted value"))?;
1038
1039        let mut store = AutoAssertNoGc::new(store);
1040
1041        let field_ty = self.field_ty(&store)?;
1042        ensure!(
1043            field_ty.mutability().is_var(),
1044            "cannot set element {index}: array elements are not mutable"
1045        );
1046
1047        value
1048            .ensure_matches_ty(&store, &field_ty.element_type().unpack())
1049            .with_context(|| format!("cannot set element {index}: type mismatch"))?;
1050
1051        let layout = self.layout(&store)?;
1052        let arrayref = self.arrayref(&store)?.unchecked_copy();
1053
1054        let len = arrayref.len(&store)?;
1055        ensure!(
1056            index < len,
1057            "index out of bounds: the length is {len} but the index is {index}"
1058        );
1059
1060        arrayref.write_elem(&mut store, &layout, field_ty.element_type(), index, value)
1061    }
1062
1063    pub(crate) fn type_index(&self, store: &StoreOpaque) -> Result<VMSharedTypeIndex> {
1064        let gc_ref = self.inner.try_gc_ref(store)?;
1065        let header = store.require_gc_store()?.header(gc_ref)?;
1066        debug_assert!(header.matches_kind(VMGcKind::ArrayRef));
1067        match header.ty() {
1068            Some(ty) => Ok(ty),
1069            None => bail_bug!("arrayrefs should have concrete types"),
1070        }
1071    }
1072
1073    /// Create a new `Rooted<ArrayRef>` from the given GC reference.
1074    ///
1075    /// `gc_ref` should point to a valid `arrayref` and should belong to the
1076    /// store's GC heap. Failure to uphold these invariants is memory safe but
1077    /// will lead to general incorrectness such as panics or wrong results.
1078    pub(crate) fn from_cloned_gc_ref(
1079        store: &mut AutoAssertNoGc<'_>,
1080        gc_ref: VMGcRef,
1081    ) -> Rooted<Self> {
1082        debug_assert!(gc_ref.is_arrayref(&**store.unwrap_gc_store().gc_heap.get()));
1083        Rooted::new(store, gc_ref)
1084    }
1085}
1086
1087unsafe impl WasmTy for Rooted<ArrayRef> {
1088    #[inline]
1089    fn valtype() -> ValType {
1090        ValType::Ref(RefType::new(false, HeapType::Array))
1091    }
1092
1093    #[inline]
1094    fn compatible_with_store(&self, store: &StoreOpaque) -> bool {
1095        self.comes_from_same_store(store)
1096    }
1097
1098    #[inline]
1099    fn dynamic_concrete_type_check(
1100        &self,
1101        store: &StoreOpaque,
1102        _nullable: bool,
1103        ty: &HeapType,
1104    ) -> Result<()> {
1105        match ty {
1106            HeapType::Any | HeapType::Eq | HeapType::Array => Ok(()),
1107            HeapType::ConcreteArray(ty) => self.ensure_matches_ty(store, ty),
1108
1109            HeapType::Extern
1110            | HeapType::NoExtern
1111            | HeapType::Func
1112            | HeapType::ConcreteFunc(_)
1113            | HeapType::NoFunc
1114            | HeapType::I31
1115            | HeapType::Struct
1116            | HeapType::ConcreteStruct(_)
1117            | HeapType::Cont
1118            | HeapType::NoCont
1119            | HeapType::ConcreteCont(_)
1120            | HeapType::Exn
1121            | HeapType::NoExn
1122            | HeapType::None => bail!(
1123                "type mismatch: expected `(ref {ty})`, got `(ref {})`",
1124                self._ty(store)?,
1125            ),
1126        }
1127    }
1128
1129    fn store(self, store: &mut AutoAssertNoGc<'_>, ptr: &mut MaybeUninit<ValRaw>) -> Result<()> {
1130        self.wasm_ty_store(store, ptr, ValRaw::anyref)
1131    }
1132
1133    unsafe fn load(store: &mut AutoAssertNoGc<'_>, ptr: &ValRaw) -> Self {
1134        Self::wasm_ty_load(store, ptr.get_anyref(), ArrayRef::from_cloned_gc_ref)
1135    }
1136}
1137
1138unsafe impl WasmTy for Option<Rooted<ArrayRef>> {
1139    #[inline]
1140    fn valtype() -> ValType {
1141        ValType::ARRAYREF
1142    }
1143
1144    #[inline]
1145    fn compatible_with_store(&self, store: &StoreOpaque) -> bool {
1146        self.map_or(true, |x| x.comes_from_same_store(store))
1147    }
1148
1149    #[inline]
1150    fn dynamic_concrete_type_check(
1151        &self,
1152        store: &StoreOpaque,
1153        nullable: bool,
1154        ty: &HeapType,
1155    ) -> Result<()> {
1156        match self {
1157            Some(s) => Rooted::<ArrayRef>::dynamic_concrete_type_check(s, store, nullable, ty),
1158            None => {
1159                ensure!(
1160                    nullable,
1161                    "expected a non-null reference, but found a null reference"
1162                );
1163                Ok(())
1164            }
1165        }
1166    }
1167
1168    #[inline]
1169    fn is_vmgcref_and_points_to_object(&self) -> bool {
1170        self.is_some()
1171    }
1172
1173    fn store(self, store: &mut AutoAssertNoGc<'_>, ptr: &mut MaybeUninit<ValRaw>) -> Result<()> {
1174        <Rooted<ArrayRef>>::wasm_ty_option_store(self, store, ptr, ValRaw::anyref)
1175    }
1176
1177    unsafe fn load(store: &mut AutoAssertNoGc<'_>, ptr: &ValRaw) -> Self {
1178        <Rooted<ArrayRef>>::wasm_ty_option_load(
1179            store,
1180            ptr.get_anyref(),
1181            ArrayRef::from_cloned_gc_ref,
1182        )
1183    }
1184}
1185
1186unsafe impl WasmTy for OwnedRooted<ArrayRef> {
1187    #[inline]
1188    fn valtype() -> ValType {
1189        ValType::Ref(RefType::new(false, HeapType::Array))
1190    }
1191
1192    #[inline]
1193    fn compatible_with_store(&self, store: &StoreOpaque) -> bool {
1194        self.comes_from_same_store(store)
1195    }
1196
1197    #[inline]
1198    fn dynamic_concrete_type_check(
1199        &self,
1200        store: &StoreOpaque,
1201        _: bool,
1202        ty: &HeapType,
1203    ) -> Result<()> {
1204        match ty {
1205            HeapType::Any | HeapType::Eq | HeapType::Array => Ok(()),
1206            HeapType::ConcreteArray(ty) => self.ensure_matches_ty(store, ty),
1207
1208            HeapType::Extern
1209            | HeapType::NoExtern
1210            | HeapType::Func
1211            | HeapType::ConcreteFunc(_)
1212            | HeapType::NoFunc
1213            | HeapType::I31
1214            | HeapType::Struct
1215            | HeapType::ConcreteStruct(_)
1216            | HeapType::Cont
1217            | HeapType::NoCont
1218            | HeapType::ConcreteCont(_)
1219            | HeapType::Exn
1220            | HeapType::NoExn
1221            | HeapType::None => bail!(
1222                "type mismatch: expected `(ref {ty})`, got `(ref {})`",
1223                self._ty(store)?,
1224            ),
1225        }
1226    }
1227
1228    fn store(self, store: &mut AutoAssertNoGc<'_>, ptr: &mut MaybeUninit<ValRaw>) -> Result<()> {
1229        self.wasm_ty_store(store, ptr, ValRaw::anyref)
1230    }
1231
1232    unsafe fn load(store: &mut AutoAssertNoGc<'_>, ptr: &ValRaw) -> Self {
1233        Self::wasm_ty_load(store, ptr.get_anyref(), ArrayRef::from_cloned_gc_ref)
1234    }
1235}
1236
1237unsafe impl WasmTy for Option<OwnedRooted<ArrayRef>> {
1238    #[inline]
1239    fn valtype() -> ValType {
1240        ValType::ARRAYREF
1241    }
1242
1243    #[inline]
1244    fn compatible_with_store(&self, store: &StoreOpaque) -> bool {
1245        self.as_ref()
1246            .map_or(true, |x| x.comes_from_same_store(store))
1247    }
1248
1249    #[inline]
1250    fn dynamic_concrete_type_check(
1251        &self,
1252        store: &StoreOpaque,
1253        nullable: bool,
1254        ty: &HeapType,
1255    ) -> Result<()> {
1256        match self {
1257            Some(s) => OwnedRooted::<ArrayRef>::dynamic_concrete_type_check(s, store, nullable, ty),
1258            None => {
1259                ensure!(
1260                    nullable,
1261                    "expected a non-null reference, but found a null reference"
1262                );
1263                Ok(())
1264            }
1265        }
1266    }
1267
1268    #[inline]
1269    fn is_vmgcref_and_points_to_object(&self) -> bool {
1270        self.is_some()
1271    }
1272
1273    fn store(self, store: &mut AutoAssertNoGc<'_>, ptr: &mut MaybeUninit<ValRaw>) -> Result<()> {
1274        <OwnedRooted<ArrayRef>>::wasm_ty_option_store(self, store, ptr, ValRaw::anyref)
1275    }
1276
1277    unsafe fn load(store: &mut AutoAssertNoGc<'_>, ptr: &ValRaw) -> Self {
1278        <OwnedRooted<ArrayRef>>::wasm_ty_option_load(
1279            store,
1280            ptr.get_anyref(),
1281            ArrayRef::from_cloned_gc_ref,
1282        )
1283    }
1284}