Struct freya::prelude::Resource

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

A handle to a reactive future spawned with use_resource that can be used to modify or read the result of the future.

Example

Reading the result of a resource:

fn App() -> Element {
    let mut revision = use_signal(|| "1d03b42");
    let mut resource = use_resource(move || async move {
        // This will run every time the revision signal changes because we read the count inside the future
        reqwest::get(format!("https://github.com/DioxusLabs/awesome-dioxus/blob/{revision}/awesome.json")).await
    });

    // Since our resource may not be ready yet, the value is an Option. Our request may also fail, so the get function returns a Result
    // The complete type we need to match is `Option<Result<String, reqwest::Error>>`
    // We can use `read_unchecked` to keep our matching code in one statement while avoiding a temporary variable error (this is still completely safe because dioxus checks the borrows at runtime)
    match &*resource.read_unchecked() {
        Some(Ok(value)) => rsx! { "{value:?}" },
        Some(Err(err)) => rsx! { "Error: {err}" },
        None => rsx! { "Loading..." },
    }
}

Implementations

impl<T> Resource<T>

pub fn restart(&mut self)

Restart the resource’s future.

This will cancel the current future and start a new one.

Example

fn App() -> Element {
    let mut revision = use_signal(|| "1d03b42");
    let mut resource = use_resource(move || async move {
        // This will run every time the revision signal changes because we read the count inside the future
        reqwest::get(format!("https://github.com/DioxusLabs/awesome-dioxus/blob/{revision}/awesome.json")).await
    });

    rsx! {
        button {
            // We can get a signal with the value of the resource with the `value` method
            onclick: move |_| resource.restart(),
            "Restart resource"
        }
        "{resource:?}"
    }
}

pub fn cancel(&mut self)

Forcefully cancel the resource’s future.

Example

fn App() -> Element {
    let mut revision = use_signal(|| "1d03b42");
    let mut resource = use_resource(move || async move {
        reqwest::get(format!("https://github.com/DioxusLabs/awesome-dioxus/blob/{revision}/awesome.json")).await
    });

    rsx! {
        button {
            // We can cancel the resource before it finishes with the `cancel` method
            onclick: move |_| resource.cancel(),
            "Cancel resource"
        }
        "{resource:?}"
    }
}

pub fn pause(&mut self)

Pause the resource’s future.

Example

fn App() -> Element {
    let mut revision = use_signal(|| "1d03b42");
    let mut resource = use_resource(move || async move {
        // This will run every time the revision signal changes because we read the count inside the future
        reqwest::get(format!("https://github.com/DioxusLabs/awesome-dioxus/blob/{revision}/awesome.json")).await
    });

    rsx! {
        button {
            // We can pause the future with the `pause` method
            onclick: move |_| resource.pause(),
            "Pause"
        }
        button {
            // And resume it with the `resume` method
            onclick: move |_| resource.resume(),
            "Resume"
        }
        "{resource:?}"
    }
}

pub fn resume(&mut self)

Resume the resource’s future.

Example

fn App() -> Element {
    let mut revision = use_signal(|| "1d03b42");
    let mut resource = use_resource(move || async move {
        // This will run every time the revision signal changes because we read the count inside the future
        reqwest::get(format!("https://github.com/DioxusLabs/awesome-dioxus/blob/{revision}/awesome.json")).await
    });

    rsx! {
        button {
            // We can pause the future with the `pause` method
            onclick: move |_| resource.pause(),
            "Pause"
        }
        button {
            // And resume it with the `resume` method
            onclick: move |_| resource.resume(),
            "Resume"
        }
        "{resource:?}"
    }
}

pub fn clear(&mut self)

Clear the resource’s value. This will just reset the value. It will not modify any running tasks.

Example

fn App() -> Element {
    let mut revision = use_signal(|| "1d03b42");
    let mut resource = use_resource(move || async move {
        // This will run every time the revision signal changes because we read the count inside the future
        reqwest::get(format!("https://github.com/DioxusLabs/awesome-dioxus/blob/{revision}/awesome.json")).await
    });

    rsx! {
        button {
            // We clear the value without modifying any running tasks with the `clear` method
            onclick: move |_| resource.clear(),
            "Clear"
        }
        "{resource:?}"
    }
}

pub fn task(&self) -> Task

Get a handle to the inner task backing this resource Modify the task through this handle will cause inconsistent state

pub fn finished(&self) -> bool

Is the resource’s future currently finished running?

Reading this does not subscribe to the future’s state

Example

fn App() -> Element {
    let mut revision = use_signal(|| "1d03b42");
    let mut resource = use_resource(move || async move {
        // This will run every time the revision signal changes because we read the count inside the future
        reqwest::get(format!("https://github.com/DioxusLabs/awesome-dioxus/blob/{revision}/awesome.json")).await
    });

    // We can use the `finished` method to check if the future is finished
    if resource.finished() {
        rsx! {
            "The resource is finished"
        }
    } else {
        rsx! {
            "The resource is still running"
        }
    }
}

pub fn state(&self) -> ReadOnlySignal<UseResourceState>

Get the current state of the resource’s future. This method returns a ReadOnlySignal which can be read to get the current state of the resource or passed to other hooks and components.

Example

fn App() -> Element {
    let mut revision = use_signal(|| "1d03b42");
    let mut resource = use_resource(move || async move {
        // This will run every time the revision signal changes because we read the count inside the future
        reqwest::get(format!("https://github.com/DioxusLabs/awesome-dioxus/blob/{revision}/awesome.json")).await
    });

    // We can read the current state of the future with the `state` method
    match resource.state().cloned() {
        UseResourceState::Pending => rsx! {
            "The resource is still pending"
        },
        UseResourceState::Paused => rsx! {
            "The resource has been paused"
        },
        UseResourceState::Stopped => rsx! {
            "The resource has been stopped"
        },
        UseResourceState::Ready => rsx! {
            "The resource is ready!"
        },
    }
}

pub fn value(&self) -> ReadOnlySignal<Option<T>>

Get the current value of the resource’s future. This method returns a ReadOnlySignal which can be read to get the current value of the resource or passed to other hooks and components.

Example

fn App() -> Element {
    let mut revision = use_signal(|| "1d03b42");
    let mut resource = use_resource(move || async move {
        // This will run every time the revision signal changes because we read the count inside the future
        reqwest::get(format!("https://github.com/DioxusLabs/awesome-dioxus/blob/{revision}/awesome.json")).await
    });

    // We can get a signal with the value of the resource with the `value` method
    let value = resource.value();

    // Since our resource may not be ready yet, the value is an Option. Our request may also fail, so the get function returns a Result
    // The complete type we need to match is `Option<Result<String, reqwest::Error>>`
    // We can use `read_unchecked` to keep our matching code in one statement while avoiding a temporary variable error (this is still completely safe because dioxus checks the borrows at runtime)
    match &*value.read_unchecked() {
        Some(Ok(value)) => rsx! { "{value:?}" },
        Some(Err(err)) => rsx! { "Error: {err}" },
        None => rsx! { "Loading..." },
    }
}

pub fn suspend(&self) -> Result<MappedSignal<T>, RenderError>

Suspend the resource’s future and only continue rendering when the future is ready

Trait Implementations

impl<T> Clone for Resource<T>

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

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T> Debug for Resource<T>

where T: Debug + 'static,

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

Formats the value using the given formatter.

impl<T> Deref for Resource<T>

where T: Clone,

Allow calling a signal with signal() syntax

Currently only limited to copy types, though could probably specialize for string/arc/rc

type Target = dyn Fn() -> Option<T>

The resulting type after dereferencing.

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

Dereferences the value.

impl<T> From<Resource<T>> for ReadOnlySignal<Option<T>>

fn from(val: Resource<T>) -> ReadOnlySignal<Option<T>>

Converts to this type from the input type.

impl<T> IntoAttributeValue for Resource<T>

where T: Clone + IntoAttributeValue,

fn into_value(self) -> AttributeValue

Convert into an attribute value

impl<T> IntoDynNode for Resource<T>

where T: Clone + IntoDynNode,

fn into_dyn_node(self) -> DynamicNode

Consume this item and produce a DynamicNode

impl<T> PartialEq for Resource<T>

fn eq(&self, other: &Resource<T>) -> 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> Readable for Resource<T>

type Target = Option<T>

The target type of the reference.

type Storage = UnsyncStorage

The type of the storage this readable uses.

fn try_read_unchecked( &self ) -> Result<<<Resource<T> as Readable>::Storage as AnyStorage>::Ref<'static, <Resource<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 try_peek_unchecked( &self ) -> Result<<<Resource<T> as Readable>::Storage as AnyStorage>::Ref<'static, <Resource<T> as Readable>::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 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 Resource<T>