Struct wasmtime_runtime::VMExternRef

#[repr(transparent)]
pub struct VMExternRef(_);

An external reference to some opaque data.

VMExternRefs dereference to their underlying opaque data as dyn Any.

Unlike the externref in the Wasm spec, VMExternRefs are non-nullable, and always point to a valid value. You may use Option<VMExternRef> to represent nullable references, and Option<VMExternRef> is guaranteed to have the same size and alignment as a raw pointer, with None represented with the null pointer.

VMExternRefs are reference counted, so cloning is a cheap, shallow operation. It also means they are inherently shared, so you may not get a mutable, exclusive reference to their inner contents, only a shared, immutable reference. You may use interior mutability with RefCell or Mutex to work around this restriction, if necessary.

VMExternRefs have pointer-equality semantics, not structural-equality semantics. Given two VMExternRefs a and b, a == b only if a and b point to the same allocation. a and b are considered not equal, even if a and b are two different identical copies of the same data, if they are in two different allocations. The hashing and ordering implementations also only operate on the pointer.

Example

use std::cell::RefCell;
use wasmtime_runtime::VMExternRef;

// Open a file. Wasm doesn't know about files, but we can let Wasm instances
// work with files via opaque `externref` handles.
let file = std::fs::File::create("some/file/path")?;

// Wrap the file up as an `VMExternRef` that can be passed to Wasm.
let extern_ref_to_file = VMExternRef::new(RefCell::new(file));

// `VMExternRef`s dereference to `dyn Any`, so you can use `Any` methods to
// perform runtime type checks and downcasts.

assert!(extern_ref_to_file.is::<RefCell<std::fs::File>>());
assert!(!extern_ref_to_file.is::<String>());

if let Some(file) = extern_ref_to_file.downcast_ref::<RefCell<std::fs::File>>() {
    use std::io::Write;
    let mut file = file.borrow_mut();
    writeln!(&mut file, "Hello, `VMExternRef`!")?;
}

Implementations

impl VMExternRef

pub fn new<T>(value: T) -> VMExternRef where
    T: 'static + Any, 

Wrap the given value inside an VMExternRef.

pub fn new_with<T>(make_value: impl FnOnce() -> T) -> VMExternRef where
    T: 'static + Any, 

Construct a new VMExternRef in place by invoking make_value.

pub fn as_raw(&self) -> *mut u8

Turn this VMExternRef into a raw, untyped pointer.

Unlike into_raw, this does not consume and forget self. It is not safe to use from_raw on pointers returned from this method; only use clone_from_raw!

Nor does this method increment the reference count. You must ensure that self (or some other clone of self) stays alive until clone_from_raw is called.

pub unsafe fn into_raw(self) -> *mut u8

Consume this VMExternRef into a raw, untyped pointer.

Safety

This method forgets self, so it is possible to create a leak of the underlying reference counted data if not used carefully.

Use from_raw to recreate the VMExternRef.

pub unsafe fn from_raw(ptr: *mut u8) -> Self

Recreate a VMExternRef from a pointer returned from a previous call to as_raw.

Safety

Unlike clone_from_raw, this does not increment the reference count of the underlying data. It is not safe to continue to use the pointer passed to this function.

pub unsafe fn clone_from_raw(ptr: *mut u8) -> Self

Recreate a VMExternRef from a pointer returned from a previous call to as_raw.

Safety

Wildly unsafe to use with anything other than the result of a previous as_raw call!

Additionally, it is your responsibility to ensure that this raw VMExternRef’s reference count has not dropped to zero. Failure to do so will result in use after free!

pub fn strong_count(&self) -> usize

Get the strong reference count for this VMExternRef.

impl VMExternRef

Methods that would normally be trait implementations, but aren’t to avoid potential footguns around VMExternRef’s pointer-equality semantics.

Note that none of these methods are on &self, they all require a fully-qualified VMExternRef::foo(my_ref) invocation.

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

Check whether two VMExternRefs point to the same inner allocation.

Note that this uses pointer-equality semantics, not structural-equality semantics, and so only pointers are compared, and doesn’t use any Eq or PartialEq implementation of the pointed-to values.

pub fn hash<H>(externref: &Self, hasher: &mut H) where
    H: Hasher, 

Hash a given VMExternRef.

Note that this just hashes the pointer to the inner value, it does not use the inner value’s Hash implementation (if any).

pub fn cmp(a: &Self, b: &Self) -> Ordering

Compare two VMExternRefs.

Note that this uses pointer-equality semantics, not structural-equality semantics, and so only pointers are compared, and doesn’t use any Cmp or PartialCmp implementation of the pointed-to values.

Methods from Deref<Target = dyn Any>

pub fn is<T>(&self) -> bool where
    T: Any, 

Returns true if the boxed type is the same as T.

Examples

use std::any::Any;

fn is_string(s: &dyn Any) {
    if s.is::<String>() {
        println!("It's a string!");
    } else {
        println!("Not a string...");
    }
}

is_string(&0);
is_string(&"cookie monster".to_string());

pub fn downcast_ref<T>(&self) -> Option<&T> where
    T: Any, 

Returns some reference to the boxed value if it is of type T, or None if it isn’t.

Examples

use std::any::Any;

fn print_if_string(s: &dyn Any) {
    if let Some(string) = s.downcast_ref::<String>() {
        println!("It's a string({}): '{}'", string.len(), string);
    } else {
        println!("Not a string...");
    }
}

print_if_string(&0);
print_if_string(&"cookie monster".to_string());

pub fn is<T>(&self) -> bool where
    T: Any, 

Forwards to the method defined on the type Any.

Examples

use std::any::Any;

fn is_string(s: &(dyn Any + Send)) {
    if s.is::<String>() {
        println!("It's a string!");
    } else {
        println!("Not a string...");
    }
}

is_string(&0);
is_string(&"cookie monster".to_string());

pub fn downcast_ref<T>(&self) -> Option<&T> where
    T: Any, 

Forwards to the method defined on the type Any.

Examples

use std::any::Any;

fn print_if_string(s: &(dyn Any + Send)) {
    if let Some(string) = s.downcast_ref::<String>() {
        println!("It's a string({}): '{}'", string.len(), string);
    } else {
        println!("Not a string...");
    }
}

print_if_string(&0);
print_if_string(&"cookie monster".to_string());

pub fn is<T>(&self) -> bool where
    T: Any, 

Forwards to the method defined on the type Any.

Examples

use std::any::Any;

fn is_string(s: &(dyn Any + Send + Sync)) {
    if s.is::<String>() {
        println!("It's a string!");
    } else {
        println!("Not a string...");
    }
}

is_string(&0);
is_string(&"cookie monster".to_string());

pub fn downcast_ref<T>(&self) -> Option<&T> where
    T: Any, 

Forwards to the method defined on the type Any.

Examples

use std::any::Any;

fn print_if_string(s: &(dyn Any + Send + Sync)) {
    if let Some(string) = s.downcast_ref::<String>() {
        println!("It's a string({}): '{}'", string.len(), string);
    } else {
        println!("Not a string...");
    }
}

print_if_string(&0);
print_if_string(&"cookie monster".to_string());

Trait Implementations

impl Clone for VMExternRef

fn clone(&self) -> VMExternRef

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for VMExternRef

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

Formats the value using the given formatter.

impl Deref for VMExternRef

type Target = dyn Any

The resulting type after dereferencing.

fn deref(&self) -> &dyn Any

Dereferences the value.

impl Drop for VMExternRef

fn drop(&mut self)

Executes the destructor for this type.

impl From<VMExternRef> for TableElement

fn from(x: VMExternRef) -> TableElement

Performs the conversion.