wiggle

Struct GuestPtr

Source
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>

Source

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.

Source

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.

Source

pub fn cast<U>(&self) -> GuestPtr<U>
where U: Pointee<Pointer = T::Pointer> + ?Sized,

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

pub fn add(&self, amt: u32) -> Result<GuestPtr<T>, GuestError>
where T: GuestType + Pointee<Pointer = u32>,

Performs pointer arithmetic on this pointer, moving the pointer forward amt slots.

This will either return the resulting pointer or Err if the pointer arithmetic calculation would overflow around the end of the address space.

Source

pub fn as_array(&self, elems: u32) -> GuestPtr<[T]>
where T: GuestType + Pointee<Pointer = u32>,

Returns a GuestPtr for an array of Ts using this pointer as the base.

Source§

impl<T> GuestPtr<[T]>

Source

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()

Source

pub fn len(&self) -> u32

For slices, returns the length of the slice, in elements.

Source

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.

Source

pub fn as_ptr(&self) -> GuestPtr<T>

Returns a GuestPtr pointing to the base of the array for the interior type T.

Source

pub fn get(&self, index: u32) -> Option<GuestPtr<T>>
where T: GuestType,

Source

pub fn get_range(&self, r: Range<u32>) -> Option<GuestPtr<[T]>>
where T: GuestType,

Source§

impl GuestPtr<str>

Source

pub fn offset_base(&self) -> u32

For strings, returns the relative pointer to the base of the string allocation.

Source

pub fn len(&self) -> u32

Returns the length, in bytes, of the string.

Source

pub fn as_bytes(&self) -> GuestPtr<[u8]>

Returns a raw pointer for the underlying slice of bytes that this pointer points to.

Trait Implementations§

Source§

impl<T: ?Sized + Pointee> Clone for GuestPtr<T>

Source§

fn clone(&self) -> Self

Returns a copy of the value. Read more
1.0.0 · Source§

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

Performs copy-assignment from source. Read more
Source§

impl<T: ?Sized + Pointee> Debug for GuestPtr<T>

Source§

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

Formats the value using the given formatter. Read more
Source§

impl<T> GuestType for GuestPtr<[T]>
where T: GuestType,

Source§

fn guest_size() -> u32

Returns the size, in bytes, of this type in the guest memory.
Source§

fn guest_align() -> usize

Returns the required alignment of this type, in bytes, for both guest and host memory.
Source§

fn read(mem: &GuestMemory<'_>, ptr: GuestPtr<Self>) -> Result<Self, GuestError>

Reads this value from the provided ptr. Read more
Source§

fn write( mem: &mut GuestMemory<'_>, ptr: GuestPtr<Self>, val: Self, ) -> Result<(), GuestError>

Writes a value to ptr after verifying that ptr is indeed valid to store val. Read more
Source§

impl<T> GuestType for GuestPtr<T>

Source§

fn guest_size() -> u32

Returns the size, in bytes, of this type in the guest memory.
Source§

fn guest_align() -> usize

Returns the required alignment of this type, in bytes, for both guest and host memory.
Source§

fn read(mem: &GuestMemory<'_>, ptr: GuestPtr<Self>) -> Result<Self, GuestError>

Reads this value from the provided ptr. Read more
Source§

fn write( mem: &mut GuestMemory<'_>, ptr: GuestPtr<Self>, val: Self, ) -> Result<(), GuestError>

Writes a value to ptr after verifying that ptr is indeed valid to store val. Read more
Source§

impl<T: ?Sized + Pointee> PartialEq for GuestPtr<T>

Source§

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.
1.0.0 · Source§

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
Source§

impl<T: ?Sized + Pointee> Copy for GuestPtr<T>

Auto Trait Implementations§

§

impl<T> Freeze for GuestPtr<T>
where <T as Pointee>::Pointer: Freeze, T: ?Sized,

§

impl<T> RefUnwindSafe for GuestPtr<T>
where <T as Pointee>::Pointer: RefUnwindSafe, T: ?Sized,

§

impl<T> Send for GuestPtr<T>
where <T as Pointee>::Pointer: Send, T: ?Sized,

§

impl<T> Sync for GuestPtr<T>
where <T as Pointee>::Pointer: Sync, T: ?Sized,

§

impl<T> Unpin for GuestPtr<T>
where <T as Pointee>::Pointer: Unpin, T: ?Sized,

§

impl<T> UnwindSafe for GuestPtr<T>
where <T as Pointee>::Pointer: UnwindSafe, T: ?Sized,

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dst: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> IntoEither for T

Source§

fn into_either(self, into_left: bool) -> Either<Self, Self>

Converts 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 more
Source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
where F: FnOnce(&Self) -> bool,

Converts 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
§

impl<T> Pointable for T

§

const ALIGN: usize = _

The alignment of pointer.
§

type Init = T

The type for initializers.
§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
Source§

impl<T> Pointee for T

Source§

type Pointer = u32

Source§

fn debug( pointer: <T as Pointee>::Pointer, f: &mut Formatter<'_>, ) -> Result<(), Error>

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more