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}