Struct ic_stable_memory::primitive::s_box::SBox

pub struct SBox<T: AsDynSizeBytes + StableType> { /* private fields */ }

Smart-pointer that allows storing any dynamic sized data on stable memory.

T should implement both StableType and AsDynSizeBytes. SBox itself implements StableType, so it will be stable-dropped automatically, when it is no longer needed. SBox also implements AsFixedSizeBytes, so you can put it in any other stable structure (e.g. SVec).

It is eager on writes, but lazy on reads. When you create or update it, the underlying value gets immediately serialized and written to stable memory, but when you read it after it was stored in some other stable data structure, it’s underlying value gets read and deserialized only when you access it.

You can access the underlying data by dereferencing it, for immutable access. For mutable access you have to use SBox::with method (similar to thread_local!’s with() method).

Examples

{
    let mut boxed_string = SBox::new(String::from("Test string"))
        .expect("Out of memory");

    assert_eq!(&*boxed_string, "Test string");

    boxed_string.with(|it| {
        *it = String::from("Much much longer test string");
    }).expect("Out of memory");

    assert_eq!(&*boxed_string, "Much much longer test string");
} // <- gets stable-dropped here automatically

Implementations

impl<T: AsDynSizeBytes + StableType> SBox<T>

pub fn new(it: T) -> Result<Self, T>

Stores dynamic sized data on stable memory, immediately serializing and allocating.

Returns Err and the data, if the canister is OutOfMemory.

pub fn as_ptr(&self) -> u64

Returns a pointer to the underlying SSlice of stable memory.

See also SBox::from_ptr.

pub fn into_inner(self) -> T

Returns the underlying data, releasing occupied stable memory.

pub unsafe fn from_ptr(ptr: u64) -> Self

Creates SBox from a pointer to the underlying SSlice of stable memory.

See also SBox::as_ptr.

Panics

Panics if the pointer points to an invalid (or free) block of stable memory.

Safety

This method basically allows you to clone the smart-pointer, which breaks ownership and stable-drop rules. Always make sure you restore stable-drop rules manually. Always destroy other copies of the same SBox before mutating it or the underlying data.

Example

let mut b = SBox::new(10u64).expect("Out of memory");
unsafe { b.stable_drop_flag_off() };

b = unsafe { SBox::from_ptr(b.as_ptr()) };

pub fn with<R, F: FnOnce(&mut T) -> R>( &mut self, func: F ) -> Result<R, OutOfMemory>

Provides mutable access to the underlying data, by accepting a lambda function.

Returns OutOfMemory error if it was impossible to reallocate the underlying SSlice to make it bugger.

Example

#[derive(CandidType, Deserialize, CandidAsDynSizeBytes, StableType, Debug)]
struct A {
    name: String,
    id: u64,
}

let it = A { name: String::from("Sasha"), id: 1 };
let mut b = SBox::new(it).expect("Out of memory");

b.with(|it| it.id += 1).unwrap();

Trait Implementations

impl<T: AsDynSizeBytes + StableType> AsFixedSizeBytes for SBox<T>

const SIZE: usize = 8usize

Size of self when encoded

type Buf = [u8; 8]

Buffer that is used to encode this value into

fn as_fixed_size_bytes(&self, buf: &mut [u8])

Encodes itself into a slice of bytes.

fn from_fixed_size_bytes(arr: &[u8]) -> Self

Decodes itself from a slice of bytes.

fn as_new_fixed_size_bytes(&self) -> Self::Buf

Encodes itself into a new Self::Buf of size == Self::SIZE

impl<T: AsHashTree + AsDynSizeBytes + StableType> AsHashTree for SBox<T>

fn root_hash(&self) -> Hash

Returns the root hash of the tree without constructing it. Must be equivalent to [HashTree::reconstruct].

fn hash_tree(&self) -> HashTree

Returns a [HashTree] of this value. Must be equivalent to AsHashTree::root_hash.

impl<T: AsDynSizeBytes + StableType> Borrow<T> for SBox<T>

fn borrow(&self) -> &T

Immutably borrows from an owned value.

impl<T: Debug + AsDynSizeBytes + StableType> Debug for SBox<T>

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

Formats the value using the given formatter.

impl<T: AsDynSizeBytes + StableType> Deref for SBox<T>

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<T: AsDynSizeBytes + StableType> Drop for SBox<T>

fn drop(&mut self)

Executes the destructor for this type.

impl<T: Hash + AsDynSizeBytes + StableType> Hash for SBox<T>

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<T: Ord + PartialOrd + AsDynSizeBytes + StableType> Ord for SBox<T>

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Selfwhere Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Selfwhere Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Selfwhere Self: Sized + PartialOrd<Self>,

Restrict a value to a certain interval.

impl<T: PartialEq + AsDynSizeBytes + StableType> PartialEq<SBox<T>> for SBox<T>

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

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T: PartialOrd + AsDynSizeBytes + StableType> PartialOrd<SBox<T>> for SBox<T>

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

This method tests less than (for self and other) and is used by the < operator.

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

This method tests less than or equal to (for self and other) and is used by the <= operator.

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

This method tests greater than (for self and other) and is used by the > operator.

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

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<T: AsDynSizeBytes + StableType> StableType for SBox<T>

fn should_stable_drop(&self) -> bool

Should return the value of the stable drop flag

unsafe fn stable_drop_flag_off(&mut self)

Sets stable drop flag to off position, if it is applicable

unsafe fn stable_drop_flag_on(&mut self)

Should set stable drop flag to on position, if it is applicable

unsafe fn stable_drop(&mut self)

Performs stable drop, releasing all underlying stable memory of this data structure

impl<T: AsHashableBytes + AsDynSizeBytes + StableType> AsHashableBytes for SBox<T>

impl<T: Eq + PartialEq + AsDynSizeBytes + StableType> Eq for SBox<T>