Struct wasmtime_runtime::VMExternRef [−][src]
#[repr(transparent)]pub struct VMExternRef(_);
Expand description
An external reference to some opaque data.
VMExternRef
s dereference to their underlying opaque data as dyn Any
.
Unlike the externref
in the Wasm spec, VMExternRef
s 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.
VMExternRef
s 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.
VMExternRef
s have pointer-equality semantics, not structural-equality
semantics. Given two VMExternRef
s 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(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::<std::fs::File>());
assert!(!extern_ref_to_file.is::<String>());
if let Some(mut file) = extern_ref_to_file.downcast_ref::<std::fs::File>() {
use std::io::Write;
writeln!(&mut file, "Hello, `VMExternRef`!")?;
}
Implementations
Wrap the given value inside an VMExternRef
.
Construct a new VMExternRef
in place by invoking make_value
.
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.
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
.
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.
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!
Get the strong reference count for this VMExternRef
.
Note that this loads with a SeqCst
ordering to synchronize with other
threads.
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.
Check whether two VMExternRef
s 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.
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).
Trait Implementations
Performs the conversion.
Auto Trait Implementations
Blanket Implementations
Mutably borrows from an owned value. Read more