pub struct GuestPtr<T: ?Sized + Pointee> { /* private fields */ }
Expand description
A guest pointer.
This type represents a pointer from the guest that points into host memory.
Internally a GuestPtr
the offset into the memory that the pointer is
pointing at. At this time this is always a 32-bit offset so this is not
suitable for bindings where wasm has 64-bit addresses.
Presence of a GuestPtr
does not imply any form of validity. Pointers can
be out-of-bounds, misaligned, etc. It is safe to construct a GuestPtr
with
any offset at any time. Consider a GuestPtr<T>
roughly equivalent to *mut T
.
§Slices and Strings
Note that the type parameter does not need to implement the Sized
trait,
so you can implement types such as this:
GuestPtr<str>
- a pointer to a guest string.GuestPtr<[T]>
- a pointer to a guest array.
Note that generated bindings won’t use these types so you’ll have to
otherwise construct the types with .cast()
or .as_array()
. Unsized types
track both the pointer and length in guest memory.
§Type parameter and pointee
The T
type parameter is largely intended for more static safety in Rust as
well as having a better handle on what we’re pointing to. A GuestPtr<T>
,
however, does not necessarily literally imply a guest pointer pointing to
type T
. Instead the GuestType
trait is a layer of abstraction where
GuestPtr<T>
may actually be a pointer to U
in guest memory, but you can
construct a T
from a U
.
For example GuestPtr<GuestPtr<T>>
is a valid type, but this is actually
more equivalent to GuestPtr<u32>
because guest pointers are always
32-bits. That being said you can create a GuestPtr<T>
from a u32
.
Additionally GuestPtr<MyEnum>
will actually delegate, typically, to and
implementation which loads the underlying data as GuestPtr<u8>
(or
similar) and then the bytes loaded are validated to fit within the
definition of MyEnum
before MyEnum
is returned.
For more information see the GuestMemory::read
and
GuestMemory::write
methods. In general though be extremely careful about
writing unsafe
code when working with a GuestPtr
if you’re not using one
of the already-attached helper methods.
Implementations§
Source§impl<T: ?Sized + Pointee> GuestPtr<T>
impl<T: ?Sized + Pointee> GuestPtr<T>
Sourcepub fn new(pointer: T::Pointer) -> GuestPtr<T>
pub fn new(pointer: T::Pointer) -> GuestPtr<T>
Creates a new GuestPtr
from the given mem
and pointer
values.
Note that for sized types like u32
, GuestPtr<T>
, etc, the pointer
value is a u32
offset into guest memory. For slices and strings,
pointer
is a (u32, u32)
offset/length pair.
Sourcepub fn offset(&self) -> T::Pointer
pub fn offset(&self) -> T::Pointer
Returns the offset of this pointer in guest memory.
Note that for sized types this returns a u32
, but for slices and
strings it returns a (u32, u32)
pointer/length pair.
Sourcepub fn cast<U>(&self) -> GuestPtr<U>
pub fn cast<U>(&self) -> GuestPtr<U>
Casts this GuestPtr
type to a different type.
This is a safe method which is useful for simply reinterpreting the type
parameter on this GuestPtr
. Note that this is a safe method, where
again there’s no guarantees about alignment, validity, in-bounds-ness,
etc of the returned pointer.
Source§impl<T> GuestPtr<[T]>
impl<T> GuestPtr<[T]>
Sourcepub fn offset_base(&self) -> u32
pub fn offset_base(&self) -> u32
For slices, specifically returns the relative pointer to the base of the array.
This is similar to <[T]>::as_ptr()
Sourcepub fn iter(
&self,
) -> impl ExactSizeIterator<Item = Result<GuestPtr<T>, GuestError>> + '_where
T: GuestType,
pub fn iter(
&self,
) -> impl ExactSizeIterator<Item = Result<GuestPtr<T>, GuestError>> + '_where
T: GuestType,
Returns an iterator over interior pointers.
Each item is a Result
indicating whether it overflowed past the end of
the address space or not.
Sourcepub fn as_ptr(&self) -> GuestPtr<T>
pub fn as_ptr(&self) -> GuestPtr<T>
Returns a GuestPtr
pointing to the base of the array for the interior
type T
.
pub fn get(&self, index: u32) -> Option<GuestPtr<T>>where
T: GuestType,
pub fn get_range(&self, r: Range<u32>) -> Option<GuestPtr<[T]>>where
T: GuestType,
Trait Implementations§
Source§impl<T> GuestType for GuestPtr<[T]>where
T: GuestType,
impl<T> GuestType for GuestPtr<[T]>where
T: GuestType,
Source§fn guest_size() -> u32
fn guest_size() -> u32
Source§fn guest_align() -> usize
fn guest_align() -> usize
Source§fn read(mem: &GuestMemory<'_>, ptr: GuestPtr<Self>) -> Result<Self, GuestError>
fn read(mem: &GuestMemory<'_>, ptr: GuestPtr<Self>) -> Result<Self, GuestError>
ptr
. Read moreSource§fn write(
mem: &mut GuestMemory<'_>,
ptr: GuestPtr<Self>,
val: Self,
) -> Result<(), GuestError>
fn write( mem: &mut GuestMemory<'_>, ptr: GuestPtr<Self>, val: Self, ) -> Result<(), GuestError>
Source§impl<T> GuestType for GuestPtr<T>
impl<T> GuestType for GuestPtr<T>
Source§fn guest_size() -> u32
fn guest_size() -> u32
Source§fn guest_align() -> usize
fn guest_align() -> usize
Source§fn read(mem: &GuestMemory<'_>, ptr: GuestPtr<Self>) -> Result<Self, GuestError>
fn read(mem: &GuestMemory<'_>, ptr: GuestPtr<Self>) -> Result<Self, GuestError>
ptr
. Read moreSource§fn write(
mem: &mut GuestMemory<'_>,
ptr: GuestPtr<Self>,
val: Self,
) -> Result<(), GuestError>
fn write( mem: &mut GuestMemory<'_>, ptr: GuestPtr<Self>, val: Self, ) -> Result<(), GuestError>
impl<T: ?Sized + Pointee> Copy for GuestPtr<T>
Auto Trait Implementations§
impl<T> Freeze for GuestPtr<T>
impl<T> RefUnwindSafe for GuestPtr<T>
impl<T> Send for GuestPtr<T>
impl<T> Sync for GuestPtr<T>
impl<T> Unpin for GuestPtr<T>
impl<T> UnwindSafe for GuestPtr<T>
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
Source§impl<T> Instrument for T
impl<T> Instrument for T
Source§fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
Source§fn in_current_span(self) -> Instrumented<Self> ⓘ
fn in_current_span(self) -> Instrumented<Self> ⓘ
Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
self
into a Left
variant of Either<Self, Self>
if into_left
is true
.
Converts self
into a Right
variant of Either<Self, Self>
otherwise. Read moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
self
into a Left
variant of Either<Self, Self>
if into_left(&self)
returns true
.
Converts self
into a Right
variant of Either<Self, Self>
otherwise. Read more