Struct Action

pub struct Action<I, O> {
    inner: ArenaItem<ArcAction<I, O>>,
}

An action runs some asynchronous code when you dispatch a new value to it, and gives you reactive access to the result.

Actions are intended for mutating or updating data, not for loading data. If you find yourself creating an action and immediately dispatching a value to it, this is probably the wrong primitive.

The reference-counted, Clone (but not Copy version of an Action is an ArcAction.

async fn send_new_todo_to_api(task: String) -> usize {
    // do something...
    // return a task id
    42
}
let save_data = Action::new(|task: &String| {
  // `task` is given as `&String` because its value is available in `input`
  send_new_todo_to_api(task.clone())
});

// the argument currently running
let input = save_data.input();
// the most recent returned result
let result_of_call = save_data.value();
// whether the call is pending
let pending = save_data.pending();
// how many times the action has run
// useful for reactively updating something else in response to a `dispatch` and response
let version = save_data.version();

// before we do anything
assert_eq!(input.get(), None); // no argument yet
assert_eq!(pending.get(), false); // isn't pending a response
assert_eq!(result_of_call.get(), None); // there's no "last value"
assert_eq!(version.get(), 0);

// dispatch the action
save_data.dispatch("My todo".to_string());

// when we're making the call
assert_eq!(input.get(), Some("My todo".to_string()));
assert_eq!(pending.get(), true); // is pending
assert_eq!(result_of_call.get(), None); // has not yet gotten a response


// after call has resolved
assert_eq!(input.get(), None); // input clears out after resolved
assert_eq!(pending.get(), false); // no longer pending
assert_eq!(result_of_call.get(), Some(42));
assert_eq!(version.get(), 1);

The input to the async function should always be a single value, but it can be of any type. The argument is always passed by reference to the function, because it is stored in Action::input as well.

// if there's a single argument, just use that
let action1 = Action::new(|input: &String| {
    let input = input.clone();
    async move { todo!() }
});

// if there are no arguments, use the unit type `()`
let action2 = Action::new(|input: &()| async { todo!() });

// if there are multiple arguments, use a tuple
let action3 = Action::new(|input: &(usize, String)| async { todo!() });

Fields

inner: ArenaItem<ArcAction<I, O>>

Implementations

impl<I, O> Action<I, O>

where I: Send + Sync + 'static, O: Send + Sync + 'static,

pub fn new<F, Fu>(action_fn: F) -> Action<I, O>

where F: Fn(&I) -> Fu + Send + Sync + 'static, Fu: Future<Output = O> + Send + 'static,

Creates a new action. This is lazy: it does not run the action function until some value is dispatched.

The constructor takes a function which will create a new Future from some input data. When the action is dispatched, this action_fn will run, and the Future it returns will be spawned.

The action_fn must be Send + Sync so that the ArcAction is Send + Sync. The Future must be Send so that it can be moved across threads by the async executor as needed. In order to be stored in the Copy arena, the input and output types should also be Send + Sync.

let act = Action::new(|n: &u8| {
    let n = n.to_owned();
    async move { n * 2 }
});

act.dispatch(3);
assert_eq!(act.input().get(), Some(3));

// Remember that async functions already return a future if they are
// not `await`ed. You can save keystrokes by leaving out the `async move`

let act2 = Action::new(|n: &String| yell(n.to_owned()));
act2.dispatch(String::from("i'm in a doctest"));

// after it resolves
assert_eq!(act2.value().get(), Some("I'M IN A DOCTEST".to_string()));

async fn yell(n: String) -> String {
    n.to_uppercase()
}

pub fn new_with_value<F, Fu>(value: Option<O>, action_fn: F) -> Action<I, O>

where F: Fn(&I) -> Fu + Send + Sync + 'static, Fu: Future<Output = O> + Send + 'static,

Creates a new action, initializing it with the given value.

This is lazy: it does not run the action function until some value is dispatched.

The constructor takes a function which will create a new Future from some input data. When the action is dispatched, this action_fn will run, and the Future it returns will be spawned.

The action_fn must be Send + Sync so that the ArcAction is Send + Sync. The Future must be Send so that it can be moved across threads by the async executor as needed. In order to be stored in the Copy arena, the input and output types should also be Send + Sync.

impl<I, O> Action<I, O>

where I: 'static, O: 'static,

pub fn clear(&self)

Clears the value of the action, setting its current value to None.

This has no other effect: i.e., it will not cancel in-flight actions, set the input, etc.

impl<I, O> Action<I, O>

where I: 'static, O: 'static,

pub fn new_local<F, Fu>(action_fn: F) -> Action<I, O>

where F: Fn(&I) -> Fu + 'static, Fu: Future<Output = O> + 'static,

Creates a new action, which does not require its inputs or outputs to be Send. In all other ways, this is the same as Action::new. If this action is accessed from outside the thread on which it was created, it panics.

pub fn new_local_with_value<F, Fu>( value: Option<O>, action_fn: F, ) -> Action<I, O>

where F: Fn(&I) -> Fu + 'static, Fu: Future<Output = O> + Send + 'static,

Creates a new action with the initial value, which does not require its inputs or outputs to be Send. In all other ways, this is the same as Action::new_with_value. If this action is accessed from outside the thread on which it was created, it panics.

impl<I, O> Action<I, O>

where I: 'static, O: 'static,

pub fn version(&self) -> RwSignal<usize>

The number of times the action has successfully completed.

let act = Action::new(|n: &u8| {
    let n = n.to_owned();
    async move { n * 2 }
});

let version = act.version();
act.dispatch(3);
assert_eq!(version.get(), 0);

// after it resolves
assert_eq!(version.get(), 1);

pub fn pending(&self) -> Memo<bool>

Whether the action has been dispatched and is currently waiting to resolve.

let act = Action::new(|n: &u8| {
    let n = n.to_owned();
    async move { n * 2 }
});

let pending = act.pending();
assert_eq!(pending.get(), false);
act.dispatch(3);
assert_eq!(pending.get(), true);

// after it resolves
assert_eq!(pending.get(), false);

impl<I, O> Action<I, O>

where I: 'static, O: 'static,

pub fn input(&self) -> MappedSignal<Option<I>>

The current argument that was dispatched to the async function. This value will be Some while we are waiting for it to resolve, and None after it has resolved.

let act = Action::new(|n: &u8| {
    let n = n.to_owned();
    async move { n * 2 }
});

let input = act.input();
assert_eq!(input.get(), None);
act.dispatch(3);
assert_eq!(input.get(), Some(3));

// after it resolves
assert_eq!(input.get(), None);

pub fn input_local(&self) -> MappedSignal<Option<I>>

👎Deprecated: You can now use .input() for any value, whether it’s thread-safe or not.

The current argument that was dispatched to the async function. This value will be Some while we are waiting for it to resolve, and None after it has resolved.

Returns a thread-local signal using [LocalStorage].

impl<I, O> Action<I, O>

where I: 'static, O: 'static,

pub fn value(&self) -> MappedSignal<Option<O>>

The most recent return value of the async function. This will be None before the action has ever run successfully, and subsequently will always be Some(_), holding the old value until a new value has been received.

let act = Action::new(|n: &u8| {
    let n = n.to_owned();
    async move { n * 2 }
});

let value = act.value();
assert_eq!(value.get(), None);
act.dispatch(3);
assert_eq!(value.get(), None);

// after it resolves
assert_eq!(value.get(), Some(6));
// dispatch another value, and it still holds the old value
act.dispatch(3);
assert_eq!(value.get(), Some(6));

pub fn value_local(&self) -> MappedSignal<Option<O>>

where O: Send + Sync,

👎Deprecated: You can now use .value() for any value, whether it’s thread-safe or not.

The most recent return value of the async function. This will be None before the action has ever run successfully, and subsequently will always be Some(_), holding the old value until a new value has been received.

Returns a thread-local signal using [LocalStorage].

impl<I, O> Action<I, O>

where I: Send + Sync + 'static, O: Send + Sync + 'static,

pub fn dispatch(&self, input: I) -> ActionAbortHandle

Calls the async function with a reference to the input type as its argument.

impl<I, O> Action<I, O>

where I: 'static, O: 'static,

pub fn dispatch_local(&self, input: I) -> ActionAbortHandle

Calls the async function with a reference to the input type as its argument.

impl<I, O> Action<I, O>

where I: Send + Sync + 'static, O: Send + Sync + 'static,

pub fn new_unsync<F, Fu>(action_fn: F) -> Action<I, O>

where F: Fn(&I) -> Fu + 'static, Fu: Future<Output = O> + 'static,

Creates a new action, which does not require the action itself to be Send, but will run it on the same thread it was created on.

In all other ways, this is identical to Action::new.

pub fn new_unsync_with_value<F, Fu>( value: Option<O>, action_fn: F, ) -> Action<I, O>

where F: Fn(&I) -> Fu + 'static, Fu: Future<Output = O> + 'static,

Creates a new action, which does not require the action itself to be Send, but will run it on the same thread it was created on, and gives an initial value.

In all other ways, this is identical to Action::new.

impl<I, O> Action<I, O>

where I: 'static, O: 'static,

pub fn new_unsync_local<F, Fu>(action_fn: F) -> Action<I, O>

where F: Fn(&I) -> Fu + 'static, Fu: Future<Output = O> + 'static,

Creates a new action, which neither requires the action itself nor the value it returns to be Send. If this action is accessed from outside the thread on which it was created, it panics.

This combines the features of Action::new_local and Action::new_unsync.

pub fn new_unsync_local_with_value<F, Fu>( value: Option<O>, action_fn: F, ) -> Action<I, O>

where F: Fn(&I) -> Fu + 'static, Fu: Future<Output = O> + 'static,

Creates a new action, which neither requires the action itself nor the value it returns to be Send, and provides it with an initial value. If this action is accessed from outside the thread on which it was created, it panics.

This combines the features of Action::new_local_with_value and Action::new_unsync_with_value.

Trait Implementations

impl<I, O> Clone for Action<I, O>

fn clone(&self) -> Action<I, O>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<I, O> DefinedAt for Action<I, O>

fn defined_at(&self) -> Option<&'static Location<'static>>

Returns the location at which the signal was defined. This is usually simply None in release mode.

impl<I, O> Dispose for Action<I, O>

fn dispose(self)

Disposes of the signal. This:

impl<S> From<ServerAction<S>> for Action<S, Result<<S as ServerFn>::Output, <S as ServerFn>::Error>>

where S: ServerFn + 'static, <S as ServerFn>::Output: 'static,

fn from( value: ServerAction<S>, ) -> Action<S, Result<<S as ServerFn>::Output, <S as ServerFn>::Error>>

Converts to this type from the input type.

impl<I, O> Copy for Action<I, O>