Trait IoType

pub unsafe trait IoType {
    type PointerType: TrivialType;

    const METADATA: &[u8];

    // Required methods
    fn size(&self) -> u32;
    unsafe fn size_ptr(&self) -> impl Deref<Target = NonNull<u32>>;
    unsafe fn size_mut_ptr(&mut self) -> impl DerefMut<Target = *mut u32>;
    fn capacity(&self) -> u32;
    unsafe fn capacity_ptr(&self) -> impl Deref<Target = NonNull<u32>>;
    unsafe fn set_size(&mut self, size: u32);
    unsafe fn from_ptr<'a>(
        ptr: &'a NonNull<Self::PointerType>,
        size: &'a u32,
        capacity: u32,
    ) -> impl Deref<Target = Self> + 'a;
    unsafe fn from_mut_ptr<'a>(
        ptr: &'a mut NonNull<Self::PointerType>,
        size: &'a mut *mut u32,
        capacity: u32,
    ) -> impl DerefMut<Target = Self> + 'a;
    unsafe fn as_ptr(&self) -> impl Deref<Target = NonNull<Self::PointerType>>;
    unsafe fn as_mut_ptr(
        &mut self,
    ) -> impl DerefMut<Target = NonNull<Self::PointerType>>;
}

Trait that is used for types that are crossing host/guest boundary in smart contracts.

Crucially, it is implemented for any type that implements TrivialType and for VariableBytes.

Safety

This trait is used for types with memory transmutation capabilities, it must not be relied on with untrusted data. Serializing and deserializing of types that implement this trait is simply casting of underlying memory. As a result, all the types implementing this trait must not use implicit padding, unions or anything similar that might make it unsound to access any bits of the type.

Helper functions are provided to make casting to/from bytes a bit safer than it would otherwise, but extra care is still needed.

Do not implement this trait explicitly! Use #[derive(TrivialType)] instead, which will ensure safety requirements are upheld, or use VariableBytes if more flexibility is needed.

In case of variable state size is needed, create a wrapper struct around VariableBytes and implement traits on it by forwarding everything to inner implementation.

Required Associated Constants

const METADATA: &[u8]

Data structure metadata in binary form, describing shape and types of the contents, see IoTypeMetadataKind for encoding details

Required Associated Types

type PointerType: TrivialType

Pointer with trivial type that this IoType represents

Required Methods

fn size(&self) -> u32

Number of bytes that are currently used to store data

unsafe fn size_ptr(&self) -> impl Deref<Target = NonNull<u32>>

Pointer to the number of bytes that are currently used to store data.

Safety

While calling this function is technically safe, it and allows to ignore many of its invariants, so requires extra care. In particular, no modifications must be done to the value while this returned pointer might be used and no changes must be done through the returned pointer. Also, lifetimes are only superficial here and can be easily (and incorrectly) ignored by using Copy.

unsafe fn size_mut_ptr(&mut self) -> impl DerefMut<Target = *mut u32>

An exclusive pointer to the number of bytes that are currently used to store data.

NOTE: Pointer might be null for TrivialTypes that don’t store size internally, in which case type’s capacity should be used as size.

Safety

While calling this function is technically safe, it and allows to ignore many of its invariants, so requires extra care. In particular, the value’s contents must not be read or written to while returned point might be used. Also, lifetimes are only superficial here and can be easily (and incorrectly) ignored by using Copy.

fn capacity(&self) -> u32

Number of bytes are allocated right now

unsafe fn capacity_ptr(&self) -> impl Deref<Target = NonNull<u32>>

Number of bytes are allocated right now

Safety

While calling this function is technically safe, it and allows to ignore many of its invariants, so requires extra care. In particular, no modifications must be done to the value while this returned pointer might be used and no changes must be done through the returned pointer. Also, lifetimes are only superficial here and can be easily (and incorrectly) ignored by using Copy.

unsafe fn set_size(&mut self, size: u32)

Set the number of used bytes

Safety

size must be set to number of properly initialized bytes

unsafe fn from_ptr<'a>( ptr: &'a NonNull<Self::PointerType>, size: &'a u32, capacity: u32, ) -> impl Deref<Target = Self> + 'a

Create a reference to a type, which is represented by provided memory.

Memory must be correctly aligned and sufficient in size, but padding beyond the size of the type is allowed. Memory behind a pointer must not be written to in the meantime either.

Only size are guaranteed to be allocated for types that can store variable amount of data due to read-only nature of read-only access here.

Panics

Panics if size is a null pointer in case of non-TrivialType

Safety

Input bytes must be previously produced by taking underlying bytes of the same type.

unsafe fn from_mut_ptr<'a>( ptr: &'a mut NonNull<Self::PointerType>, size: &'a mut *mut u32, capacity: u32, ) -> impl DerefMut<Target = Self> + 'a

Create a mutable reference to a type, which is represented by provided memory.

Memory must be correctly aligned and sufficient in size or else None will be returned, but padding beyond the size of the type is allowed. Memory behind pointer must not be read or written to in the meantime either.

size indicates how many bytes are used within larger allocation for types that can store variable amount of data.

Panics

Panics if size is a null pointer in case of non-TrivialType

Safety

Input bytes must be previously produced by taking underlying bytes of the same type.

unsafe fn as_ptr(&self) -> impl Deref<Target = NonNull<Self::PointerType>>

Get a raw pointer to the underlying data with no checks.

Safety

While calling this function is technically safe, it and allows to ignore many of its invariants, so requires extra care. In particular, no modifications must be done to the value while this returned pointer might be used and no changes must be done through the returned pointer. Also, lifetimes are only superficial here and can be easily (and incorrectly) ignored by using Copy.

unsafe fn as_mut_ptr( &mut self, ) -> impl DerefMut<Target = NonNull<Self::PointerType>>

Get an exclusive raw pointer to the underlying data with no checks.

Safety

While calling this function is technically safe, it and allows to ignore many of its invariants, so requires extra care. In particular, the value’s contents must not be read or written to while returned point might be used. Also, lifetimes are only superficial here and can be easily (and incorrectly) ignored by using Copy.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl<Data> IoType for MaybeData<Data>

where Data: TrivialType,

const METADATA: &[u8] = Data::METADATA

type PointerType = Data

impl<T> IoType for T

where T: TrivialType,

const METADATA: &[u8] = T::METADATA

type PointerType = T

impl<const RECOMMENDED_ALLOCATION: u32> IoType for VariableBytes<RECOMMENDED_ALLOCATION>

const METADATA: &[u8]

type PointerType = u8