Enum wiggle::wasmtime_crate::HeapType

pub enum HeapType {
    Extern,
    NoExtern,
    Func,
    ConcreteFunc(FuncType),
    NoFunc,
    Any,
    Eq,
    I31,
    Array,
    ConcreteArray(ArrayType),
    Struct,
    ConcreteStruct(StructType),
    None,
}

The heap types that can Wasm can have references to.

Subtyping Hierarchy

Wasm has three different heap type hierarchies:

1. Function types
2. External types
3. Internal types

Each hierarchy has a top type (the common supertype of which everything else in its hierarchy is a subtype of) and a bottom type (the common subtype of which everything else in its hierarchy is supertype of).

Function Types Hierarchy

The top of the function types hierarchy is func; the bottom is nofunc. In between are all the concrete function types.

                         func
                      /  /  \  \
     ,----------------  /    \  -------------------------.
    /                  /      \                           \
   |              ,----        -----------.                |
   |              |                       |                |
   |              |                       |                |
(func)    (func (param i32))    (func (param i32 i32))    ...
   |              |                       |                |
   |              |                       |                |
   |              `---.        ,----------'                |
    \                  \      /                           /
     `---------------.  \    /  ,------------------------'
                      \  \  /  /
                        nofunc

Additionally, some concrete function types are sub- or supertypes of other concrete function types. For simplicity, this isn’t depicted in the diagram above. Specifically, this is based on their parameter and result types, and whether those types are in a subtyping relationship:

• Parameters are contravariant: (func (param $a) (result $c)) is a subtype of (func (param $b) (result $c)) when $b is a subtype of $a.

  For example, we can substitute (func (param $cat)) with (func (param $animal)) because $cat is a subtype of $animal and so the new function is still prepared to accept all $cat arguments that any caller might pass in.

  We can’t do the opposite and replace (func (param $animal)) with (func (param $cat)). What would the new function do when given a $dog? It is invalid.

• Results are covariant: (func (result $a)) is a subtype of (func (result $b)) when $a is a subtype of $b.

  For example, we can substitute a (func (result $animal)) with a (func (result $cat)) because callers expect to be returned an $animal and all $cats are $animals.

  We cannot do the opposite and substitute a (func (result $cat)) with a (func (result $animal)), since callers expect a $cat but the new function could return a $dog.

As always, Wikipedia is also helpful: https:///en.wikipedia.org/wiki/Covariance_and_contravariance_(computer_science)

External

The top of the external types hierarchy is extern; the bottom is noextern. There are no concrete types in this hierarchy.

 extern
   |
noextern

Internal

The top of the internal types hierarchy is any; the bottom is none. The eq type is the common supertype of all types that can be compared for equality. The struct and array types are the common supertypes of all concrete struct and array types respectively. The i31 type represents unboxed 31-bit integers.

                                  any
                                 / | \
   ,----------------------------'  |  `--------------------------.
  /                                |                              \
 |                        .--------'                               |
 |                        |                                        |
 |                      struct                                   array
 |                     /  |   \                                 /  |   \
i31             ,-----'   |    '-----.                   ,-----'   |    `-----.
 |             /          |           \                 /          |           \
 |            |           |            |               |           |            |
 |        (struct)    (struct i32)    ...        (array i32)    (array i64)    ...
 |            |           |            |               |           |            |
 |             \          |           /                 \          |           /
  \             `-----.   |    ,-----'                   `-----.   |    ,-----'
   \                   \  |   /                                 \  |   /
    \                   \ |  /                                   \ |  /
     \                   \| /                                     \| /
      \                   |/                                       |/
       \                  |                                        |
        \                 |                                       /
         \                '--------.                             /
          \                        |                            /
           `--------------------.  |   ,-----------------------'
                                 \ |  /
                                  none

Additionally, concrete struct and array types can be subtypes of other concrete struct and array types respectively. Once again, this is omitted from the above diagram for simplicity. Specifically:

• Array types are covariant with their element type: (array $a) is a subtype of (array $b) if $a is a subtype of $b. For example, (array $cat) is a subtype of (array $animal).

• Struct types are covariant with their field types, and subtypes may additionally have appended fields that do not appear in the supertype. For example, (struct $cat $dog) is a subtype of (struct $animal).

Subtyping and Equality

HeapType does not implement Eq, because heap types have a subtyping relationship, and so 99.99% of the time you actually want to check whether one type matches (i.e. is a subtype of) another type. You can use the HeapType::matches method to perform these types of checks. If, however, you are in that 0.01% scenario where you need to check precise equality between types, you can use the HeapType::eq method.

Variants

Extern

The abstract extern heap type represents external host data.

This is the top type for the external type hierarchy, and therefore is the common supertype of all external reference types.

NoExtern

The abstract noextern heap type represents the null external reference.

This is the bottom type for the external type hierarchy, and therefore is the common subtype of all external reference types.

Func

The abstract func heap type represents a reference to any kind of function.

This is the top type for the function references type hierarchy, and is therefore a supertype of every function reference.

ConcreteFunc(FuncType)

A reference to a function of a specific, concrete type.

These are subtypes of func and supertypes of nofunc.

NoFunc

The abstract nofunc heap type represents the null function reference.

This is the bottom type for the function references type hierarchy, and therefore nofunc is a subtype of all function reference types.

Any

The abstract any heap type represents all internal Wasm data.

This is the top type of the internal type hierarchy, and is therefore a supertype of all internal types (such as eq, i31, structs, and arrays).

Eq

The abstract eq heap type represenets all internal Wasm references that can be compared for equality.

This is a subtype of any and a supertype of i31, array, struct, and none heap types.

I31

The i31 heap type represents unboxed 31-bit integers.

This is a subtype of any and eq, and a supertype of none.

Array

The abstract array heap type represents a reference to any kind of array.

This is a subtype of any and eq, and a supertype of all concrete array types, as well as a supertype of the abstract none heap type.

ConcreteArray(ArrayType)

A reference to an array of a specific, concrete type.

These are subtypes of the array heap type (therefore also a subtype of any and eq) and supertypes of the none heap type.

Struct

The abstract struct heap type represents a reference to any kind of struct.

This is a subtype of any and eq, and a supertype of all concrete struct types, as well as a supertype of the abstract none heap type.

ConcreteStruct(StructType)

A reference to an struct of a specific, concrete type.

These are subtypes of the struct heap type (therefore also a subtype of any and eq) and supertypes of the none heap type.

None

The abstract none heap type represents the null internal reference.

This is the bottom type for the internal type hierarchy, and therefore none is a subtype of internal types.

Implementations

impl HeapType

pub fn is_extern(&self) -> bool

Is this the abstract extern heap type?

pub fn is_func(&self) -> bool

Is this the abstract func heap type?

pub fn is_no_func(&self) -> bool

Is this the abstract nofunc heap type?

pub fn is_any(&self) -> bool

Is this the abstract any heap type?

pub fn is_i31(&self) -> bool

Is this the abstract i31 heap type?

pub fn is_none(&self) -> bool

Is this the abstract none heap type?

pub fn is_abstract(&self) -> bool

Is this an abstract type?

Types that are not abstract are concrete, user-defined types.

pub fn is_concrete(&self) -> bool

Is this a concrete, user-defined heap type?

Types that are not concrete, user-defined types are abstract types.

pub fn is_concrete_func(&self) -> bool

Is this a concrete, user-defined function type?

pub fn as_concrete_func(&self) -> Option<&FuncType>

Get the underlying concrete, user-defined function type, if any.

Returns None if this is not a concrete function type.

pub fn unwrap_concrete_func(&self) -> &FuncType

Get the underlying concrete, user-defined type, panicking if this is not a concrete function type.

pub fn is_concrete_array(&self) -> bool

Is this a concrete, user-defined array type?

pub fn as_concrete_array(&self) -> Option<&ArrayType>

Get the underlying concrete, user-defined array type, if any.

Returns None for if this is not a concrete array type.

pub fn unwrap_concrete_array(&self) -> &ArrayType

Get the underlying concrete, user-defined type, panicking if this is not a concrete array type.

pub fn top(&self) -> HeapType

Get the top type of this heap type’s type hierarchy.

The returned heap type is a supertype of all types in this heap type’s type hierarchy.

pub fn is_top(&self) -> bool

Is this the top type within its type hierarchy?

pub fn bottom(&self) -> HeapType

Get the bottom type of this heap type’s type hierarchy.

The returned heap type is a subtype of all types in this heap type’s type hierarchy.

pub fn is_bottom(&self) -> bool

Is this the bottom type within its type hierarchy?

pub fn matches(&self, other: &HeapType) -> bool

Does this heap type match the other heap type?

That is, is this heap type a subtype of the other?

Panics

Panics if either type is associated with a different engine from the other.

pub fn eq(a: &HeapType, b: &HeapType) -> bool

Is heap type a precisely equal to heap type b?

Returns false even if a is a subtype of b or vice versa, if they are not exactly the same heap type.

Panics

Panics if either type is associated with a different engine from the other.

Trait Implementations

impl Clone for HeapType

fn clone(&self) -> HeapType

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for HeapType

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Display for HeapType

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl From<ArrayType> for HeapType

fn from(a: ArrayType) -> HeapType

Converts to this type from the input type.

impl From<FuncType> for HeapType

fn from(f: FuncType) -> HeapType

Converts to this type from the input type.

impl Hash for HeapType

fn hash<__H>(&self, state: &mut __H)

where __H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.