Struct Memo

pub struct Memo<T>
where
    T: 'static,
{ /* private fields */ }

Memos are the result of computing a value from use_memo.

You may have noticed that this struct doesn’t have many methods. Most methods for Memo are defined on the Readable and Writable traits.

Reading a Memo

You can use the methods on the Readable trait to read a memo:

fn app() -> Element {
    let mut count = use_signal(|| 0);
    // The memo will rerun any time we write to the count signal
    let halved = use_memo(move || count() / 2);

    rsx! {
        // When we read the value of memo, the current component will subscribe to the result of the memo. It will only rerun when the result of the memo changes.
        "{halved}"
        button {
            onclick: move |_| {
                count += 1;
            },
            "Increment"
        }
    }
}

Memo also includes helper methods just like Signals to make it easier to use. Calling a memo like a function will clone the inner value:

fn app() -> Element {
    let mut count = use_signal(|| 0);
    // The memo will rerun any time we write to the count signal
    let halved = use_memo(move || count() / 2);
    // This will rerun any time the halved value changes
    let doubled = use_memo(move || 2 * halved());

    rsx! {
        "{doubled}"
        button {
            onclick: move |_| {
                count += 1;
            },
            "Increment"
        }
    }
}

For a full list of all the helpers available, check out the Readable, [ReadableVecExt], and [ReadableOptionExt] traits.

Memos with Async

Because Memos check borrows at runtime, you need to be careful when reading memos inside of async code. If you hold a read of a memo over an await point, that read may still be open when the memo reruns which will cause a panic:

async fn double_me_async(value: &u32) -> u32 {
    sleep(100).await;
    *value * 2
}
let mut signal = use_signal(|| 0);
let halved = use_memo(move || signal() / 2);

let doubled = use_resource(move || async move {
    // Don't hold reads over await points
    let halved = halved.read();
    // While the future is waiting for the async work to finish, the read will be open
    double_me_async(&halved).await
});

rsx!{
    "{doubled:?}"
    button {
        onclick: move |_| {
            // When you write to signal, it will cause the memo to rerun which may panic because you are holding a read of the memo over an await point
            signal += 1;
        },
        "Increment"
    }
};

Instead of holding a read over an await point, you can clone whatever values you need out of your memo:

async fn double_me_async(value: u32) -> u32 {
    sleep(100).await;
    value * 2
}
let mut signal = use_signal(|| 0);
let halved = use_memo(move || signal() / 2);

let doubled = use_resource(move || async move {
    // Calling the memo will clone the inner value
    let halved = halved();
    double_me_async(halved).await;
});

rsx!{
    "{doubled:?}"
    button {
        onclick: move |_| {
            signal += 1;
        },
        "Increment"
    }
};

Memo lifecycle

Memos are implemented with generational-box which makes all values Copy even if the inner value is not Copy.

This is incredibly convenient for UI development, but it does come with some tradeoffs. The lifetime of the memo is tied to the lifetime of the component it was created in. If you drop the component that created the memo, the memo will be dropped as well. You might run into this if you try to pass a memo from a child component to a parent component and drop the child component. To avoid this you can create your memo higher up in your component tree, or use global memos.

TLDR Don’t pass memos up in the component tree. It will cause issues:

fn MyComponent() -> Element {
    let child_signal = use_signal(|| None);

    rsx! {
        IncrementButton {
            child_signal
        }
    }
}

#[component]
fn IncrementButton(mut child_signal: Signal<Option<Memo<i32>>>) -> Element {
    let signal_owned_by_child = use_signal(|| 0);
    let memo_owned_by_child = use_memo(move || signal_owned_by_child() * 2);
    // Don't do this: it may cause issues if you drop the child component
    child_signal.set(Some(memo_owned_by_child));

    todo!()
}

Implementations

impl<T> Memo<T>

where T: 'static,

pub fn new(f: impl FnMut() -> T + 'static) -> Memo<T>

where T: PartialEq,

Create a new memo

pub fn new_with_location( f: impl FnMut() -> T + 'static, location: &'static Location<'static>, ) -> Memo<T>

where T: PartialEq,

Create a new memo with an explicit location

pub const fn global(constructor: fn() -> T) -> Global<Memo<T>, T>

where T: PartialEq,

Creates a new GlobalMemo that can be used anywhere inside your dioxus app. This memo will automatically be created once per app the first time you use it.

Example

static SIGNAL: GlobalSignal<i32> = Signal::global(|| 0);
// Create a new global memo that can be used anywhere in your app
static DOUBLED: GlobalMemo<i32> = Memo::global(|| SIGNAL() * 2);

fn App() -> Element {
    rsx! {
        button {
            // When SIGNAL changes, the memo will update because the SIGNAL is read inside DOUBLED
            onclick: move |_| *SIGNAL.write() += 1,
            "{DOUBLED}"
        }
    }
}

Global memos are generally not recommended for use in libraries because it makes it more difficult to allow multiple instances of components you define in your library.

pub fn origin_scope(&self) -> ScopeId

Get the scope that the signal was created in.

pub fn id(&self) -> GenerationalBoxId

Get the id of the signal.

Trait Implementations

impl<T> Clone for Memo<T>

where T: 'static,

fn clone(&self) -> Memo<T>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T> Debug for Memo<T>

where T: Debug + 'static + PartialEq,

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

Formats the value using the given formatter.

impl<T> Deref for Memo<T>

where T: Clone + PartialEq,

type Target = dyn Fn() -> T

The resulting type after dereferencing.

fn deref(&self) -> &<Memo<T> as Deref>::Target

Dereferences the value.

impl<T> Display for Memo<T>

where T: Display + 'static + PartialEq,

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

Formats the value using the given formatter.

impl<T> From<Memo<T>> for ReadOnlySignal<T>

where T: PartialEq,

fn from(val: Memo<T>) -> ReadOnlySignal<T>

Converts to this type from the input type.

impl<T> InitializeFromFunction<T> for Memo<T>

where T: PartialEq,

fn initialize_from_function(f: fn() -> T) -> Memo<T>

Create an instance of this type from an initialization function

impl<T> IntoAttributeValue for Memo<T>

where T: Clone + IntoAttributeValue + PartialEq,

fn into_value(self) -> AttributeValue

Convert into an attribute value

impl<T> IntoDynNode for Memo<T>

where T: Clone + IntoDynNode + PartialEq,

fn into_dyn_node(self) -> DynamicNode

Consume this item and produce a DynamicNode

impl<T> PartialEq<T> for Memo<T>

where T: PartialEq + 'static,

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

Tests for self and other values to be equal, and is used by ==.

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

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

impl<T> PartialEq for Memo<T>

where T: 'static,

fn eq(&self, other: &Memo<T>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

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

impl<T> Readable for Memo<T>

where T: PartialEq,

fn try_peek_unchecked( &self, ) -> Result<<<Memo<T> as Readable>::Storage as AnyStorage>::Ref<'static, <Memo<T> as Readable>::Target>, BorrowError>

Get the current value of the signal. Unlike read, this will not subscribe the current scope to the signal which can cause parts of your UI to not update.

If the signal has been dropped, this will panic.

type Target = T

The target type of the reference.

type Storage = UnsyncStorage

The type of the storage this readable uses.

fn try_read_unchecked( &self, ) -> Result<<<Memo<T> as Readable>::Storage as AnyStorage>::Ref<'static, <Memo<T> as Readable>::Target>, BorrowError>

Try to get a reference to the value without checking the lifetime. This will subscribe the current scope to the signal.

fn map<O>( self, f: impl Fn(&Self::Target) -> &O + 'static, ) -> MappedSignal<O, Self::Storage>

where Self: Sized + Clone + 'static,

Map the readable type to a new type. This lets you provide a view into a readable type without needing to clone the inner value.

fn read(&self) -> <Self::Storage as AnyStorage>::Ref<'_, Self::Target>

Get the current value of the state. If this is a signal, this will subscribe the current scope to the signal. If the value has been dropped, this will panic. Calling this on a Signal is the same as using the signal() syntax to read and subscribe to its value

fn try_read( &self, ) -> Result<<Self::Storage as AnyStorage>::Ref<'_, Self::Target>, BorrowError>

Try to get the current value of the state. If this is a signal, this will subscribe the current scope to the signal.

fn read_unchecked( &self, ) -> <Self::Storage as AnyStorage>::Ref<'static, Self::Target>

Get a reference to the value without checking the lifetime. This will subscribe the current scope to the signal.

fn peek(&self) -> <Self::Storage as AnyStorage>::Ref<'_, Self::Target>

Get the current value of the state without subscribing to updates. If the value has been dropped, this will panic.

fn try_peek( &self, ) -> Result<<Self::Storage as AnyStorage>::Ref<'_, Self::Target>, BorrowError>

Try to peek the current value of the signal without subscribing to updates. If the value has been dropped, this will return an error.

fn peek_unchecked( &self, ) -> <Self::Storage as AnyStorage>::Ref<'static, Self::Target>

Get the current value of the signal without checking the lifetime. Unlike read, this will not subscribe the current scope to the signal which can cause parts of your UI to not update.

fn with<O>(&self, f: impl FnOnce(&Self::Target) -> O) -> O

Run a function with a reference to the value. If the value has been dropped, this will panic.

fn with_peek<O>(&self, f: impl FnOnce(&Self::Target) -> O) -> O

Run a function with a reference to the value. If the value has been dropped, this will panic.

fn index<I>( &self, index: I, ) -> <Self::Storage as AnyStorage>::Ref<'_, <Self::Target as Index<I>>::Output>

where Self::Target: Index<I>,

Index into the inner value and return a reference to the result. If the value has been dropped or the index is invalid, this will panic.

impl<T> Copy for Memo<T>

where T: 'static,